ci-cd-integration

Files (2)

• SKILL.md
• ci-platforms.md · references/

SKILL.md (first lines)

# NightVision CI/CD Integration

Use this skill when helping users add NightVision security scanning to their CI/CD pipelines. NightVision is a white-box-assisted DAST tool that finds exploitable vulnerabilities in web applications and REST APIs. It combines Source Intelligence (static analysis to extract OpenAPI specs from source code) with dynamic scanning (ZAP + Nuclei engines), and traces vulnerabilities back to exact source code locations (Code Traceback).

## Agent workflow

When a user asks to set up NightVision in their pipeline:

1. **Check prerequisites** — verify the NightVision CLI is available (`nightvision --help`). If not installed, see the Installation section below.
2. **Examine the repo** — look for existing CI configs (`.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `bitbucket-pipelines.yml`, `azure-pipelines.yml`) to understand the CI platform and existing pipeline structure
3. **Ask the user** what you can't determine from the repo:
   - Target URL (staging/production endpoint to scan)
   - Target type — web app or API?
   - Does the app require authentication to scan?
   - What language is the backend? (needed for Source Intelligence)
   - Have they already created a NightVision project, target, and token?
4. **Tell the user what they must do locally** — some steps require interactive browser sessions that the agent cannot perform (see Prerequisites below)
5. **Generate the pipeline config** — adapt the patterns below and the platform-specific examples in [references/ci-platforms.md](references/ci-platforms.md) to the user's repo, substituting their target name, language, app startup method, and CI platform conventions

**Related skills:** Use `scan-configuration` for detailed target/auth setup, `source-intelligence` for spec extraction details, `scan-triage` for interpreting results.

## Pipeline structure

Every NightVision CI pipeline follows this pattern:

```
1. Install the NightVision CLI
2. Extract API spec from source code (API targets only)
3. Start the application (private/local targets only)
4. Run the scan (CLI polls until completion, ~5-15 min)
5. Export results (SARIF / CSV / GitLab DAST)
6. Upload to CI platform (GitHub Security, GitLab DAST, Azure Boards, Jenkins Warnings)
```

## Prerequisites the user must complete

These steps require interactive sessions (browser login, GUI) that the agent cannot perform. Instruct the user to run these locally before the pipeline will work.

**1. Create an API token** — requires browser-based login:
```bash
nightvision login
nightvision token create                          # no expiry
nightvision token create --expiry-date 2026-12-31 # with expiry
```
Tokens can also be created in the NightVision web UI: Profile > Settings > Tokens. The user must store the token as a CI secret named `NIGHTVISION_TOKEN`.

**2. Record authentication** (if the target requires login) — Playwright recording opens a browser:
```bash
nightvision auth playwright create my-auth https://myapp.example.com
# A Chrome window opens — user completes login, then closes the window
```
For API key / bearer token auth, the agent can help construct the command:
```bash
nightvision auth headers create my-auth \
  -H "Authorization: Bearer <token>"
```

**3. Create the target** — the agent can help with this if `NIGHTVISION_TOKEN` is available:
```bash
# Web target
nightvision target create my-web-app https://staging.example.com --type WEB -p my-project

# API target with local spec
nightvision target create my-api https://api.example.com --type API -p my-project \
  --spec-file openapi-spec.yml

# API target with remote spec URL
nightvision target create my-api https://api.example.com --type API -p my-project \
  --spec-url https://api.example.com/docs/openapi.json

# Idempotent create-or-update (useful in pipelines)
nightvision target create my-api $URL --type API -p my-project --spec-file spec.yml \
  || nightvision target update my-api -p my-project --spec-file spec.yml
```

## Installation (in the pipeline)

```bash
# Linux Intel (standard for most CI runners)
curl -L https://downloads.nightvision.net/binaries/latest/nightvision_latest_linux_amd64.tar.gz | tar -xz
sudo mv nightvision /usr/local/bin/
```

For Linux ARM runners, substitute `linux_arm64` in the URL.

## Environment variables

| Variable | Required | Purpose |
|----------|----------|---------|
| `NIGHTVISION_TOKEN` | Yes | API token (store as CI secret) |
| `NIGHTVISION_API_URL` | No | API endpoint (default: `https://api.nightvision.net/api/v1/`) |

All config keys accept env vars with the `NIGHTVISION_` prefix (hyphens become underscores).

## CLI output format

Most `list` and `get` commands default to text output. Use `--format json` (or `-F json`) for machine-parseable output, or `--format table` for tabular display.

## Source Intelligence (spec extraction from source code)

For API targets, extract OpenAPI specs via static analysis. Supports C#, Go, Java, JavaScript/TypeScript, PHP, Python and Ruby; project roots and languages are detected automatically, so `--lang` is only needed to restrict a run.

```bash
# Extract and upload to a target
nightvision openapi extract . -t my-api -p my-project

# Extract without a target (e.g. for a spec diff)
nightvision openapi extract . -o openapi-spec.yml --no-target

# Compare specs for breaking changes (useful in PR checks)
nightvision openapi diff old-spec.yml new-spec.yml
```

**Important CI pattern — extraction fallback:** Extraction exits non-zero when it finds no routes, for example on an unsupported framework, and also when the spec was written but the upload failed. Fall back to a backup spec only when no spec was written, keep `openapi-spec.diagnostics.json` as a build artifact, and print why the fallback was taken.
```bash
if ! nightvision openapi extract . -t $TARGET; then
  if [ -e openapi-spec.yml ]; then
    echo "Spec extracted but the upload failed; keeping openapi-spec.yml"
  else

From nvsecurity/nightvision-skills, Apache-2.0.

More from nvsecurity/nightvision-skills