scan-configuration

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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, `source-intelligence` 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
- **Source Intelligence** (`nightvision openapi extract`) — extracted from source code (see the `source-intelligence` 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"

From nvsecurity/nightvision-skills, Apache-2.0.

More from nvsecurity/nightvision-skills