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

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

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

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

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

Preview of the first 4,000 characters. Read full instructions →

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

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.