Update to NightVision

{
  "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.",
  "included_files": [],
  "skill_md_contents": "---\nname: scan-configuration\ndescription: 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.\nallowed-tools: Bash\n---\n\n# NightVision Scan Configuration\n\nUse this skill when helping users set up everything needed before running a NightVision DAST scan — targets, authentication, traffic recordings, projects, and scope control.\n\n## Agent workflow\n\nWhen a user asks to configure a scan:\n\n1. **Check prerequisites** — verify the NightVision CLI is available (`nightvision --help`). Check if `NIGHTVISION_TOKEN` is set.\n2. **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)\n3. **Create the project** (if needed) — projects organize targets, scans, and auth resources\n4. **Create the target** — web app or API, with the correct URL and spec\n5. **Set up authentication** (if needed) — determine the method and guide the user through it\n6. **Record traffic** (if needed) — for apps with complex workflows or dynamic identifiers\n7. **Configure scope** — set exclusions to avoid scanning health checks, admin endpoints, etc.\n8. **Verify readiness** — confirm the target is reachable and the auth works\n\n**Related skills:** Use `ci-cd-integration` for pipeline setup, `api-discovery` for spec extraction, `scan-triage` for interpreting results.\n\n## Projects\n\nProjects are organizational containers for targets, scans, and auth resources. They can be shared with team members.\n\n```bash\n# Create a project\nnightvision project create -n my-project\n\n# List projects\nnightvision project list\n\n# Set default project (used when -p flag is omitted)\nnightvision project set -p my-project\n\n# Share — done through the web UI at app.nightvision.net\n```\n\n## Targets\n\nTwo types: **Web** (URL only) and **API** (URL + OpenAPI/Postman spec).\n\n### Creating targets\n\n```bash\n# Web target\nnightvision target create my-web-app https://staging.example.com \\\n  --type WEB -p my-project\n\n# API target with local spec file (.json, .yml, .yaml, .swagger, .postman)\nnightvision target create my-api https://api.example.com \\\n  --type API -p my-project --spec-file openapi-spec.yml\n\n# API target with remote spec URL\nnightvision target create my-api https://api.example.com \\\n  --type API -p my-project --spec-url https://api.example.com/openapi.json\n\n# Idempotent create-or-update (useful in automation)\nnightvision target create my-api $URL --type API -p my-project --spec-file spec.yml \\\n  || nightvision target update my-api -p my-project --spec-file spec.yml\n```\n\n### Updating targets\n\n```bash\n# Update the spec file\nnightvision target update my-api -p my-project --spec-file new-spec.yml\n\n# Update the target URL\nnightvision target update my-api -p my-project -u https://new-staging.example.com\n\n# List targets in a project\nnightvision target list -p my-project\n```\n\n### API spec sources\n\nFor API targets, the spec can come from:\n- **Local file** (`--spec-file`) — JSON or YAML OpenAPI/Swagger or Postman collection\n- **Remote URL** (`--spec-url`) — publicly accessible spec endpoint\n- **API Discovery** (`nightvision swagger extract`) — extracted from source code (see the `api-discovery` skill)\n- **Postman conversion** — convert Postman collections to OpenAPI with `p2o` (npm: `postman-to-openapi`)\n\n## Authentication\n\nNightVision supports three auth methods. The agent should help the user choose the right one.\n\n| Method | Use when | Agent can help? |\n|--------|----------|----------------|\n| Playwright (interactive login) | Form-based logins, OAuth flows, MFA | No — requires user's browser |\n| Headers | API keys, bearer tokens, static auth headers | Yes — agent can construct the command |\n| Cookies | Session cookies from a logged-in browser | Partially — user provides cookie values |\n\n### Playwright authentication (user must run locally)\n\nRecords a browser-based login flow that NightVision replays during scans. This requires an interactive browser session — instruct the user to run this themselves.\n\n```bash\n# Create — opens Chrome, user logs in, closes window to finish\nnightvision auth playwright create my-auth https://myapp.example.com\n\n# Update an existing recording\nnightvision auth playwright update my-auth https://myapp.example.com\n```\n\nNightVision stores the recording securely and replays it before each scan. Screenshots and video are captured to verify login success.\n\n### Header authentication\n\nFor APIs using static auth headers (API keys, bearer tokens). The agent can help build this command.\n\n```bash\n# Single header\nnightvision auth headers create my-auth \\\n  -H \"Authorization: Bearer eyJhbGciOi...\"\n\n# Multiple headers\nnightvision auth headers create my-auth \\\n  -H \"Authorization: Bearer eyJhbGciOi...\" \\\n  -H \"X-API-Key: abc123\"\n\n# Update headers on existing auth\nnightvision auth headers update my-auth \\\n  -H \"Authorization: Bearer new-token...\"\n```\n\n### Cookie authentication\n\n```bash\nnightvision auth cookies create my-auth \\\n  --cookie \"session_id=abc123; Path=/; HttpOnly\"\n```\n\n### Managing auth resources\n\n```bash\n# List all auth credentials\nnightvision auth list -p my-project\n\n# Delete auth credentials\nnightvision auth delete my-auth -p my-project\n```\n\n### Using auth in scans\n\n```bash\n# By name\nnightvision scan my-target -p my-project --auth my-auth\n\n# By UUID\nnightvision scan my-target -p my-project -C <credentials-uuid>\n\n# Explicitly skip auth\nnightvision scan my-target -p my-project --no-auth\n```\n\n## HTTP traffic recording\n\nRecording HTTP traffic (HAR files) improves scan coverage for apps with:\n- Pages behind complex business logic workflows\n- Endpoints requiring valid UUIDs or dynamic identifiers not in the API spec\n\nThe HAR file is recorded once and replayed in all subsequent scans on that target.\n\n```bash\n# Record traffic — opens Chrome, user interacts with the app, then closes\nnightvision traffic record my-recording https://myapp.example.com/workflow \\\n  --target my-target --output traffic.har\n\n# Upload an existing HAR file\nnightvision traffic upload traffic.har --target my-target\n\n# List recorded traffic for a target\nnightvision traffic list --target my-target\n\n# Download a recording\nnightvision traffic download my-recording --output traffic.har\n```\n\nTraffic recording requires a browser — instruct the user to run this locally.\n\n## Scope control\n\nControl which URLs and elements are included or excluded from scans.\n\n```bash\n# Exclude URL patterns (regex, comma-separated)\nnightvision target update my-target -p my-project \\\n  --exclude-url \"/health,/metrics,/admin.*,/api/internal.*\"\n\n# Exclude elements by XPath (for web targets)\nnightvision target update my-target -p my-project \\\n  --exclude-xpath \"//button[@id='delete'],//a[@class='logout']\"\n\n# Clear all exclusions\nnightvision target update my-target -p my-project --exclude-url \"\"\nnightvision target update my-target -p my-project --exclude-xpath \"\"\n```\n\nCommon exclusion patterns:\n- `/health`, `/healthz`, `/ready` — health check endpoints\n- `/metrics`, `/prometheus` — monitoring endpoints\n- `/admin.*` — admin panels (if not in scope)\n- Logout buttons/links — prevents the scanner from logging itself out\n\n## Private networks (Smart Proxy)\n\nNightVision 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.\n\nSupported environments: localhost, Docker containers, Kubernetes clusters, staging servers, corporate data centers.\n\n```bash\n# Smart Proxy activates automatically for private targets\nnightvision scan my-target -p my-project\n\n# Force Smart Proxy even if the target appears public\nnightvision scan my-target -p my-project --force-private-scan\n```\n\n### Firewall whitelisting\n\nIf the target is behind a corporate firewall, whitelist these NightVision AWS NAT Gateway IPs:\n- 44.210.184.14\n- 3.210.133.44\n- 18.210.3.10\n- 52.207.103.176\n- 52.201.44.112\n- 50.17.248.188\n\n## Listing scans\n\nView scan history and status across projects.\n\n```bash\n# List scans in the current (or set) project\nnightvision scan list\n\n# Filter by one or more projects\nnightvision scan list -p my-project\nnightvision scan list -p project-a -p project-b\n\n# List scans across all projects\nnightvision scan list --all\n```\n\nOutput includes scan ID, target name, status, start time, duration, and issue count.\n\n## Scan engine options\n\n```bash\n# Disable Nuclei (ZAP only)\nnightvision scan my-target -p my-project --no-nuclei\n\n# Disable ZAP (Nuclei only)\nnightvision scan my-target -p my-project --no-zap\n\n# Disable specific ZAP alert IDs\nnightvision scan my-target -p my-project --disable-zap-active-alerts 40012,40014\n\n# Disable specific Nuclei template folders\nnightvision scan my-target -p my-project --disable-nuclei-folders cves/2021\n\n# Set max scan duration (default 30 min, max 480 min)\nnightvision scan my-target -p my-project --max-duration-minutes 120\n```\n\n## Verification checklist\n\nBefore running a scan, verify:\n\n1. **Token** — `NIGHTVISION_TOKEN` is set (or user is logged in)\n2. **Target** — exists and URL is correct (`nightvision target list -p my-project`)\n3. **Spec** (API targets) — uploaded and processing complete (CLI auto-retries if not ready)\n4. **Auth** (if needed) — recorded and associated with the project (`nightvision auth list -p my-project`)\n5. **Reachability** — target is accessible from the machine running the scan (or Smart Proxy will handle it)\n"
}