CI CD Integration

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 API Discovery (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 API Discovery)
   • 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 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, api-discovery 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)
6. Upload to CI platform (GitHub Security, GitLab SAST, 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:

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:

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:

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:

# 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)

# 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

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.

API Discovery (spec extraction from source code)

For API targets, extract OpenAPI specs via static analysis. Supports Go, Python, Java, Ruby, C#, JavaScript.

# Extract and upload to a target
nightvision swagger extract . -t my-api -p my-project --lang python

# Extract locally without uploading
nightvision swagger extract . -o openapi-spec.yml --lang java --no-upload

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

Important CI pattern — extraction fallback: Extraction can fail if language detection fails. Always use:

nightvision swagger extract . -t $TARGET --lang java || true
if [ ! -e openapi-spec.yml ]; then cp backup-openapi-spec.yml openapi-spec.yml; fi

Code Traceback

When API Discovery generates the spec, it annotates endpoints with file paths and line numbers. Vulnerabilities found during scanning trace back to exact source locations. This powers the file/line links in GitHub Security Alerts, Azure Boards work items, and similar CI integrations.

Running scans

# Basic scan
nightvision scan my-target -p my-project

# Authenticated scan
nightvision scan my-target -p my-project --auth my-auth

# Unauthenticated (explicit, skip any stored credentials)
nightvision scan my-target -p my-project --no-auth

# Extended duration (default 30 min, max 480 min / 8 hours)
nightvision scan my-target -p my-project --max-duration-minutes 120

# Engine selection
nightvision scan my-target -p my-project --no-nuclei   # ZAP only
nightvision scan my-target -p my-project --no-zap      # Nuclei only

# Verbose logging (recommended for CI debugging)
nightvision scan my-target -p my-project --verbose

Capturing the scan ID

In CI (non-interactive), the CLI prints the scan ID as the first line of stdout. Use this pattern:

nightvision scan $TARGET --auth $AUTH > scan-results.txt
SCAN_ID=$(head -n 1 scan-results.txt)

Exit codes

Exit code 0 does not mean "no vulnerabilities." Use export commands to inspect findings.

On failure (exit code 1), the CLI prints a status-specific error message:

• TIMED_OUT — includes the configured --max-duration-minutes value and suggests increasing it
• ABORTED — indicates the scan was aborted (by user or system)
• FAILED — includes a link to the dashboard for investigation

When the API provides a failure reason, it is included in the error message and displayed in the TUI dashboard.

Private / internal targets (Smart Proxy)

NightVision's Smart Proxy automatically tunnels scan traffic through the CLI when the target is not publicly reachable (localhost, Docker, Kubernetes, corporate networks). No configuration needed — it's built into the CLI.

Use --force-private-scan to force tunneling when the target appears publicly accessible but isn't from the scanner's perspective.

Exporting results

# SARIF with Code Traceback (API targets — provide the spec used for the scan)
nightvision export sarif -s "$SCAN_ID" --swagger-file openapi-spec.yml -o results.sarif

# SARIF without Code Traceback (WEB targets, or when no spec is available)
nightvision export sarif -s "$SCAN_ID" -o results.sarif

# CSV (for reports, spreadsheets, custom processing)
nightvision export csv -s "$SCAN_ID" -o results.csv

--swagger-file is optional. When provided, SARIF output includes Code Traceback source annotations (file paths and line numbers linking findings to source code). When omitted, the SARIF is still valid but won't contain source locations. Always provide --swagger-file for API targets when the spec is available.

CI platform quick reference

See references/ci-platforms.md for complete, copy-pasteable pipeline configs.

Troubleshooting

Source: nvsecurity/nightvision-skills — distributed by TomeVault.