scan-triage

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.
user-invocable	true
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)
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:

nightvision scan list -p my-project

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

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

"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:

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