ci-cd-integration

What this skill does

# 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](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:
```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.

## API Discovery (spec extraction from source code)

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

```bash
# 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:
```bash
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

```bash
# 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:

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

### Exit codes

| Code | Meaning |
|------|---------|
| 0 | Scan completed successfully (`SUCCEEDED`). Vulnerabilities may still have been found. |
| 1 | Scan failed (`FAILED`, `ABORTED`, `TIMED_OUT`), or other error. |

**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

```bash
# SARIF with Code Traceback (API targets — provide the spec used for the s