scan-triage

What this skill does

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