NightVision

View saved version →

---
name: api-discovery
description: Guide for agents to help users extract OpenAPI specs from source code using NightVision API Discovery. Use when running swagger extract, identifying framework support, troubleshooting extraction, handling unresolved variables, comparing API specs, or understanding Code Traceback.
allowed-tools: Bash
---

# NightVision API Discovery

Use this skill when helping users generate OpenAPI specifications from their source code using `nightvision swagger extract`. API Discovery performs static analysis — no running application or compilation needed — and annotates the spec with source file paths and line numbers (Code Traceback) so that vulnerabilities found during DAST scans trace back to exact code locations.

## Agent workflow

When a user asks to extract or document their API:

1. **Check prerequisites** — verify the NightVision CLI is available (`nightvision --help`)
2. **Examine the repo** — identify the backend language and web framework to determine the `--lang` flag and whether the framework is supported (see [references/framework-support.md](references/framework-support.md))
3. **Run extraction** — execute `nightvision swagger extract` with the appropriate flags. On success, the CLI prints `"Swagger file extracted successfully."` and writes the spec to the output path (default: `openapi-spec.yml`)
4. **Review the output** — read the generated spec to check completeness. Handle unresolved variables if `nv.config` was created alongside the spec
5. **Compare coverage** — if the user has an existing spec, run `nightvision swagger diff` to show what was discovered vs. what was documented
6. **Upload to target** — attach the spec to a NightVision target for scanning

**Related skills:** Use `scan-configuration` for target/auth setup, `ci-cd-integration` for pipeline integration, `scan-triage` for interpreting scan results.

## Language flags

| Language | Flag | Frameworks |
|----------|------|------------|
| Python | `--lang python` | Django, DRF, Flask, Flask-RESTful, FastAPI |
| Java | `--lang java` | Spring Boot, JAX-RS/Jersey, Micronaut, Java EE/Jakarta EE |
| JavaScript | `--lang js` | Express, NestJS, Fastify |
| C# | `--lang dotnet` | ASP.NET Core (controllers, minimal APIs) |
| Go | `--lang go` | Gin, httprouter, net/http (experimental) |
| Ruby | `--lang ruby` | Rails, Grape |

See [references/framework-support.md](references/framework-support.md) for detailed component coverage per framework.

## Running extraction

```bash
# Basic extraction (output defaults to openapi-spec.yml)
nightvision swagger extract . --lang python

# Specify output file and format
nightvision swagger extract . --lang java -o api-spec.json --file-format json

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

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

# Scan multiple source directories
nightvision swagger extract ./service-a ./service-b --lang python

# Extend an existing spec (add discovered endpoints to it)
nightvision swagger extract . --lang python --extend existing-spec.yml

# Exclude directories from analysis
nightvision swagger extract . --lang python --exclude vendor,generated

# Include code snippets in the spec (useful for debugging)
nightvision swagger extract . --lang python --dump-code
```

### Extraction fallback for CI

Extraction can fail if language detection fails or the framework isn't supported. Always guard against this in pipelines:

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

## Handling unresolved variables

When static analysis can't resolve a variable (e.g., an API prefix read from an environment variable), it appears as a literal placeholder in the spec. NightVision generates an `nv.config` file to fix this.

**Steps:**
1. Run extraction — if unresolved variables exist, `nv.config` is created alongside the spec (in the first source directory passed to the command)
2. Open `nv.config` — find the `replacements` object with `null` values
3. Replace `null` with the actual values (check the app's config files, environment vars, etc.)
4. Re-run extraction — the tool reads `nv.config` and substitutes the values. You can also use `-c` / `--config` to explicitly specify the config file path: `nightvision swagger extract . --lang python -c path/to/nv.config`

```json
// nv.config example
{
  "replacements": {
    "Microsoft.AspNetCore.Builder.WebApplication.Services...ApiPrefix": null
  }
}
```

The agent should help the user find the actual value by searching their config files (`appsettings.json`, `.env`, `settings.py`, etc.) and updating `nv.config`.

## Comparing API specs

Use `swagger diff` to measure coverage or detect breaking changes:

```bash
# Summary diff (paths and schemas counts)
nightvision swagger diff original-spec.yml discovered-spec.yml

# Show only path-level changes (endpoints added/removed/modified)
nightvision swagger diff original-spec.yml discovered-spec.yml --paths

# Show only schema changes
nightvision swagger diff original-spec.yml discovered-spec.yml --schemas

# Show the full diff (paths and schemas together, with details)
nightvision swagger diff original-spec.yml discovered-spec.yml --full-diff

# Save diff output to file
nightvision swagger diff original-spec.yml discovered-spec.yml -o diff-report.txt
```

Common use cases:
- **Coverage analysis** — compare a hand-written spec against the discovered one to find undocumented shadow APIs
- **PR checks** — diff specs from the base branch vs. PR branch to detect breaking API changes
- **Audit** — verify that all endpoints are documented

## Detecting existing specs

Search the codebase for existing OpenAPI/Swagger files. The `detect` command takes no positional arguments — use `-p` to specify the root folder:

```bash
# Detect project roots in the current directory
nightvision swagger detect

# Detect in a specific directory
nightvision swagger detect -p ./path/to/code

# Save detection results as JSON
nightvision swagger detect -o detection-results.json
```

## Code Traceback

The generated spec includes `x-source` annotations on each endpoint with the file path and line number where the route is declared. When this spec is used for DAST scanning:

- Vulnerabilities found by NightVision link directly to the source code
- GitHub Security Alerts, Azure Boards work items, and Jenkins Warnings show the exact file and line
- Developers see where to fix, not just what to fix

This is why using NightVision-generated specs (vs. hand-written ones) significantly improves the triage experience.

## Troubleshooting

| Issue | Cause | Fix |
|-------|-------|-----|
| No endpoints found | Wrong `--lang` flag, or unsupported framework | Verify the framework is supported, check `--lang` value |
| Unresolved variables in paths | Config values read from env vars without defaults | Fill in `nv.config` replacements and re-run |
| Incomplete routes | Custom routing, non-standard framework usage | NightVision relies on standard framework patterns; custom routing may not be detected |
| Extraction fails entirely | Syntax errors in source, missing files | Use `--diagnostics` to get language-level error details |
| Spec missing sub-routes | Code in subdirectories not scanned | Pass multiple paths: `nightvision swagger extract ./src ./lib` |

For unsupported frameworks or components, contact support@nightviz.ai.

Referenced files: 1

View saved version →

---
name: ci-cd-integration
description: Guide for agents to help users integrate NightVision DAST scanning into CI/CD pipelines. Use when setting up security scans in GitHub Actions, GitLab CI, Azure DevOps, Jenkins, BitBucket, or JFrog pipelines, configuring NightVision tokens, creating targets, running scans, exporting results as SARIF/CSV, or detecting API breaking changes.
allowed-tools: Bash
---

# 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 / 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.

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

# GitLab DAST report (for the GitLab Vulnerability dashboard)
nightvision export gitlab -s "$SCAN_ID" --swagger-file openapi-spec.yml -o gl-dast-report.json

# Jira tickets (one per finding; severity sets priority; status changes sync back to findings)
# --jira-token is a classic user API token. For an Atlassian service-account token
# (always scoped), pass --jira-cloud-id <id> instead of --base-url (scopes: read:jira-work, write:jira-work).
nightvision export jira -s "$SCAN_ID" --project-key SEC \
  --base-url https://your-org.atlassian.net --user-email you@example.com --jira-token "$JIRA_TOKEN"
```

`--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](references/ci-platforms.md) for complete, copy-pasteable pipeline configs.

| Platform | Results surface | Upload mechanism |
|----------|----------------|-----------------|
| GitHub Actions | Security tab (Code Scanning) | `github/codeql-action/upload-sarif@v3` (needs `permissions: contents: read, security-events: write`) |
| GitLab CI | Vulnerability dashboard | `nightvision export gitlab`, `artifacts.reports.dast` |
| Azure DevOps | Azure Boards work items | `sarif-manager azure create-work-items` |
| Jenkins | Warnings Next Generation | `recordIssues tool: sarif(pattern: 'results.sarif')` |
| BitBucket | Pipeline artifacts | SARIF as artifact |
| JFrog | Evidence on Docker packages | `jf evd create` with SARIF predicate |

## Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| "login authentication token has expired" | Token expired or invalid | `nightvision token create`, update CI secret |
| "API is unreachable" | Network/firewall issue | Check `NIGHTVISION_API_URL`, network connectivity |
| "SSL certificate error" | TLS verification failed | Fix certs, or `--skip-tls-verify` (not for production) |
| Scan `TIMED_OUT` | Exceeded max duration | CLI error message shows the current limit; increase `--max-duration-minutes` (up to 480) |
| Scan `ABORTED` | Scan was cancelled by user or system | Check the failure reason in the CLI output or dashboard |
| Scan `FAILED` | Engine error or target unreachable | CLI error includes a dashboard link; also use `--verbose` and verify target is up |
| 401 Unauthorized during scan | Auth credentials expired | Re-record authentication locally |
| "Repository not found" in checkout | `permissions` block missing `contents: read` | Add `contents: read` alongside `security-events: write` in the workflow permissions |

Referenced files: 1

View saved version →

---
name: scan-configuration
description: Guide for agents to help users configure NightVision DAST scans. Use when creating targets, setting up authentication (Playwright, headers, cookies), recording HTTP traffic, managing projects, configuring scope exclusions, or preparing private network scans.
allowed-tools: Bash
---

# NightVision Scan Configuration

Use this skill when helping users set up everything needed before running a NightVision DAST scan — targets, authentication, traffic recordings, projects, and scope control.

## Agent workflow

When a user asks to configure a scan:

1. **Check prerequisites** — verify the NightVision CLI is available (`nightvision --help`). Check if `NIGHTVISION_TOKEN` is set.
2. **Determine what exists** — ask if they have a NightVision account, project, and token already. Use `nightvision project list` and `nightvision target list -p <project>` to see current state (output defaults to text; use `--format json` for structured parsing)
3. **Create the project** (if needed) — projects organize targets, scans, and auth resources
4. **Create the target** — web app or API, with the correct URL and spec
5. **Set up authentication** (if needed) — determine the method and guide the user through it
6. **Record traffic** (if needed) — for apps with complex workflows or dynamic identifiers
7. **Configure scope** — set exclusions to avoid scanning health checks, admin endpoints, etc.
8. **Verify readiness** — confirm the target is reachable and the auth works

**Related skills:** Use `ci-cd-integration` for pipeline setup, `api-discovery` for spec extraction, `scan-triage` for interpreting results.

## Projects

Projects are organizational containers for targets, scans, and auth resources. They can be shared with team members.

```bash
# Create a project
nightvision project create -n my-project

# List projects
nightvision project list

# Set default project (used when -p flag is omitted)
nightvision project set -p my-project

# Share — done through the web UI at app.nightvision.net
```

## Targets

Two types: **Web** (URL only) and **API** (URL + OpenAPI/Postman spec).

### Creating targets

```bash
# Web target
nightvision target create my-web-app https://staging.example.com \
  --type WEB -p my-project

# API target with local spec file (.json, .yml, .yaml, .swagger, .postman)
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/openapi.json

# Idempotent create-or-update (useful in automation)
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
```

### Updating targets

```bash
# Update the spec file
nightvision target update my-api -p my-project --spec-file new-spec.yml

# Update the target URL
nightvision target update my-api -p my-project -u https://new-staging.example.com

# List targets in a project
nightvision target list -p my-project
```

### API spec sources

For API targets, the spec can come from:
- **Local file** (`--spec-file`) — JSON or YAML OpenAPI/Swagger or Postman collection
- **Remote URL** (`--spec-url`) — publicly accessible spec endpoint
- **API Discovery** (`nightvision swagger extract`) — extracted from source code (see the `api-discovery` skill)
- **Postman conversion** — convert Postman collections to OpenAPI with `p2o` (npm: `postman-to-openapi`)

## Authentication

NightVision supports three auth methods. The agent should help the user choose the right one.

| Method | Use when | Agent can help? |
|--------|----------|----------------|
| Playwright (interactive login) | Form-based logins, OAuth flows, MFA | No — requires user's browser |
| Headers | API keys, bearer tokens, static auth headers | Yes — agent can construct the command |
| Cookies | Session cookies from a logged-in browser | Partially — user provides cookie values |

### Playwright authentication (user must run locally)

Records a browser-based login flow that NightVision replays during scans. This requires an interactive browser session — instruct the user to run this themselves.

```bash
# Create — opens Chrome, user logs in, closes window to finish
nightvision auth playwright create my-auth https://myapp.example.com

# Update an existing recording
nightvision auth playwright update my-auth https://myapp.example.com
```

NightVision stores the recording securely and replays it before each scan. Screenshots and video are captured to verify login success.

### Header authentication

For APIs using static auth headers (API keys, bearer tokens). The agent can help build this command.

```bash
# Single header
nightvision auth headers create my-auth \
  -H "Authorization: Bearer eyJhbGciOi..."

# Multiple headers
nightvision auth headers create my-auth \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "X-API-Key: abc123"

# Update headers on existing auth
nightvision auth headers update my-auth \
  -H "Authorization: Bearer new-token..."
```

### Cookie authentication

```bash
nightvision auth cookies create my-auth \
  --cookie "session_id=abc123; Path=/; HttpOnly"
```

### Managing auth resources

```bash
# List all auth credentials
nightvision auth list -p my-project

# Delete auth credentials
nightvision auth delete my-auth -p my-project
```

### Using auth in scans

```bash
# By name
nightvision scan my-target -p my-project --auth my-auth

# By UUID
nightvision scan my-target -p my-project -C <credentials-uuid>

# Explicitly skip auth
nightvision scan my-target -p my-project --no-auth
```

## HTTP traffic recording

Recording HTTP traffic (HAR files) improves scan coverage for apps with:
- Pages behind complex business logic workflows
- Endpoints requiring valid UUIDs or dynamic identifiers not in the API spec

The HAR file is recorded once and replayed in all subsequent scans on that target.

```bash
# Record traffic — opens Chrome, user interacts with the app, then closes
nightvision traffic record my-recording https://myapp.example.com/workflow \
  --target my-target --output traffic.har

# Upload an existing HAR file
nightvision traffic upload traffic.har --target my-target

# List recorded traffic for a target
nightvision traffic list --target my-target

# Download a recording
nightvision traffic download my-recording --output traffic.har
```

Traffic recording requires a browser — instruct the user to run this locally.

## Scope control

Control which URLs and elements are included or excluded from scans.

```bash
# Exclude URL patterns (regex, comma-separated)
nightvision target update my-target -p my-project \
  --exclude-url "/health,/metrics,/admin.*,/api/internal.*"

# Exclude elements by XPath (for web targets)
nightvision target update my-target -p my-project \
  --exclude-xpath "//button[@id='delete'],//a[@class='logout']"

# Clear all exclusions
nightvision target update my-target -p my-project --exclude-url ""
nightvision target update my-target -p my-project --exclude-xpath ""
```

Common exclusion patterns:
- `/health`, `/healthz`, `/ready` — health check endpoints
- `/metrics`, `/prometheus` — monitoring endpoints
- `/admin.*` — admin panels (if not in scope)
- Logout buttons/links — prevents the scanner from logging itself out

## Private networks (Smart Proxy)

NightVision can scan targets that are not publicly accessible. The Smart Proxy is built into the CLI and activates automatically when the target is unreachable from the internet.

Supported environments: localhost, Docker containers, Kubernetes clusters, staging servers, corporate data centers.

```bash
# Smart Proxy activates automatically for private targets
nightvision scan my-target -p my-project

# Force Smart Proxy even if the target appears public
nightvision scan my-target -p my-project --force-private-scan
```

### Firewall whitelisting

If the target is behind a corporate firewall, whitelist these NightVision AWS NAT Gateway IPs:
- 44.210.184.14
- 3.210.133.44
- 18.210.3.10
- 52.207.103.176
- 52.201.44.112
- 50.17.248.188

## Listing scans

View scan history and status across projects.

```bash
# List scans in the current (or set) project
nightvision scan list

# Filter by one or more projects
nightvision scan list -p my-project
nightvision scan list -p project-a -p project-b

# List scans across all projects
nightvision scan list --all
```

Output includes scan ID, target name, status, start time, duration, and issue count.

## Scan engine options

```bash
# Disable Nuclei (ZAP only)
nightvision scan my-target -p my-project --no-nuclei

# Disable ZAP (Nuclei only)
nightvision scan my-target -p my-project --no-zap

# Disable specific ZAP alert IDs
nightvision scan my-target -p my-project --disable-zap-active-alerts 40012,40014

# Disable specific Nuclei template folders
nightvision scan my-target -p my-project --disable-nuclei-folders cves/2021

# Set max scan duration (default 30 min, max 480 min)
nightvision scan my-target -p my-project --max-duration-minutes 120
```

## Verification checklist

Before running a scan, verify:

1. **Token** — `NIGHTVISION_TOKEN` is set (or user is logged in)
2. **Target** — exists and URL is correct (`nightvision target list -p my-project`)
3. **Spec** (API targets) — uploaded and processing complete (CLI auto-retries if not ready)
4. **Auth** (if needed) — recorded and associated with the project (`nightvision auth list -p my-project`)
5. **Reachability** — target is accessible from the machine running the scan (or Smart Proxy will handle it)

View saved version →

---
name: scan-triage
description: Guide for agents to help users interpret and act on NightVision DAST scan results. Use when reading SARIF/CSV findings, explaining vulnerabilities, locating vulnerable code, validating findings with curl, prioritizing by severity, suggesting remediations, or marking false positives.
allowed-tools: Bash, Read, Grep
---

# NightVision Scan Triage

Use this skill when helping users understand and act on NightVision scan results. NightVision produces findings from two scanning engines — ZAP (active and passive rules) and Nuclei (CVE and misconfiguration templates) — and exports them as SARIF or CSV.

## Agent workflow

When a user asks for help with scan results:

1. **Check prerequisites** — verify the NightVision CLI is available (`nightvision --help`) if you need to export results
2. **Locate the results** — look for `results.sarif` or `results.csv` in the repo, or ask the user for the scan ID to export them
3. **Read and parse the findings** — use the Read tool for SARIF (JSON) files; CSV is tabular (see formats below)
4. **Explain each finding** — for each, present: severity, finding name, affected endpoint (method + path), one-line explanation, and suggested remediation
5. **Locate the vulnerable code** — use Code Traceback annotations in SARIF to find the exact file and line, then use Read/Grep to show the code in context
6. **Help the user validate** — construct curl commands to reproduce the finding
7. **Suggest remediation** — provide concrete fix patterns for the vulnerability class (see [references/vulnerability-guide.md](references/vulnerability-guide.md))
8. **Help prioritize** — triage by severity and exploitability

**Related skills:** Use `scan-configuration` for setting up scans, `ci-cd-integration` for pipeline setup, `api-discovery` for spec extraction.

## Exporting results

If the user doesn't know their scan ID, list recent scans to find it:

```bash
nightvision scan list -p my-project
```

If the user has a scan ID but no exported file:

```bash
# 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 (flat, good for quick overview)
nightvision export csv -s "$SCAN_ID" -o results.csv
```

`--swagger-file` is optional. When provided, SARIF output includes Code Traceback source annotations (file/line mappings). When omitted, the SARIF is still valid but won't contain source code locations.

## Reading SARIF files

SARIF (Static Analysis Results Interchange Format) is JSON. Key structure:

```
runs[0].tool.driver.rules[]     — vulnerability type definitions
runs[0].results[]               — individual finding instances
  .ruleId                       — maps to rules[] for description
  .level                        — "error" (high), "warning" (medium), "note" (low/info)
  .message.text                 — human-readable finding summary
  .locations[].physicalLocation — file path and line (Code Traceback)
  .properties                   — NightVision-specific metadata
```

The agent should read the SARIF JSON, iterate over `results[]`, and explain each finding using the corresponding `rules[]` entry.

### Code Traceback in SARIF

When API Discovery generated the OpenAPI spec, it annotated endpoints with source file paths and line numbers. These appear in SARIF as `physicalLocation` entries, letting the agent navigate directly to the vulnerable code:

```json
"locations": [{
  "physicalLocation": {
    "artifactLocation": { "uri": "src/main/java/api/UserController.java" },
    "region": { "startLine": 42 }
  }
}]
```

The agent should read that file and show the user the vulnerable code in context.

## Reading CSV files

CSV columns: `finding_name`, `kind_id`, `id`, `url`, `path`, `method`, `parameter`, `payload`, `evidence`, `severity`, `ai_explanation`

Key fields for triage:
- **finding_name** + **severity** — what it is and how serious
- **url** + **path** + **method** — which endpoint was vulnerable
- **parameter** + **payload** — how NightVision exploited it
- **evidence** — proof from the server response
- **ai_explanation** — NightVision's AI-generated explanation

## Severity levels

| Severity | Meaning | Agent action |
|----------|---------|-------------|
| High | Exploitable, significant impact (data breach, RCE, auth bypass) | Fix immediately, explain the attack scenario |
| Medium | Exploitable but lower impact, or requires specific conditions | Fix soon, explain the risk |
| Low | Minor issues, information leaks, best practice violations | Fix when convenient, explain the hygiene benefit |
| Informational | Observations, not directly exploitable | Mention if relevant, don't alarm |

## Validating findings with curl

NightVision's web UI provides a "Validate with curl" button. The agent can construct equivalent curl commands from the SARIF/CSV data:

```bash
# From CSV fields: method, url, parameter, payload
curl -X POST "https://api.example.com/login" \
  -d "username=admin' OR '1'='1&password=test" \
  -v
```

The response should contain the evidence that confirms the vulnerability. Show the user the relevant part of the response.

## Common vulnerability types and remediations

See [references/vulnerability-guide.md](references/vulnerability-guide.md) for a reference of common finding types, what they mean, and how to fix them.

### Quick reference for the most frequent findings

**SQL Injection** (CWE-89) — User input reaches a SQL query without parameterization.
- Fix: Use parameterized queries / prepared statements. Never concatenate user input into SQL.

**Cross-Site Scripting / XSS** (CWE-79) — User input is reflected in HTML without encoding.
- Fix: Encode output for the context (HTML entity encoding, JavaScript escaping). Use framework auto-escaping.

**Server-Side Request Forgery / SSRF** (CWE-918) — User input controls a server-side HTTP request target.
- Fix: Validate and allowlist target URLs. Block internal/private IP ranges.

**Remote Code Execution / RCE** (CWE-94) — User input is executed as code on the server.
- Fix: Never pass user input to eval, exec, or system commands. Use allowlists for permitted operations.

**Path Traversal** (CWE-22) — User input accesses files outside intended directories.
- Fix: Canonicalize paths, validate against an allowlist, use chroot or sandboxed file access.

**Broken Authentication** (CWE-287) — Authentication mechanisms can be bypassed or exploited.
- Fix: Use established auth libraries. Enforce strong password policies, MFA, and session management.

## Helping the user decide: real vs. false positive

Guide the user through this decision:

1. **Validate with curl** — does the attack actually work when replayed?
2. **Check the evidence** — does the server response confirm exploitation?
3. **Review the code** — is the vulnerable pattern actually reachable in production?
4. **Consider the context** — is this a test endpoint, internal-only, or behind additional access controls?

If the finding is a false positive, the user can mark it in the NightVision web UI (app.nightvision.net) under the scan results. Status options: **Open**, **False Positive**, **Resolved**.

## NightVision scanning engines

**ZAP Active Rules** — Sends attack payloads to test for exploitable vulnerabilities. Covers SQL injection variants, XSS types, RCE, SSTI, Log4Shell, JWT attacks, directory traversal, and more.

**ZAP Passive Rules** — Analyzes responses without attacking. Detects missing security headers, cookie misconfigurations, information leaks, CSRF token absence, credential exposure.

**Nuclei Templates** — Template-based detection of known CVEs and misconfigurations.

Specific rules can be disabled per scan with `--disable-zap-active-alerts <ids>` or `--disable-nuclei-folders <paths>`, or entire engines with `--no-zap` / `--no-nuclei`.

Referenced files: 1