SlipItIn/.github/skills/security-specialist/steering/reporting.md

Steering: Generate Scan Report

Produce the final deliverable: a structured report of all findings from a scan, in both machine-readable (JSON) and human-readable (Markdown) formats.

Step 1: Load All Findings

Pull the complete findings set from the scan database:

python3 scripts/scan_db.py list --scan-dir <dir> --format json > /tmp/findings_raw.json

Verify the data includes:

• All triaged findings (confirmed + false-positive + needs-more-info)
• Validated severity for each
• Status (open, fixed, tracked, false-positive)
• Location, category, evidence, and triage rationale

If any findings lack triage data, go back to the triage workflow first. Don't report un-triaged findings.

Step 2: Compute Statistics

Calculate:

By severity:

• Critical: count
• High: count
• Medium: count
• Low: count
• Informational: count
• False positives excluded from totals

By category:

• Group by CWE or vulnerability class (injection, XSS, auth, crypto, etc.)
• Show count per category

By location:

• Which files/directories have the most findings
• Hotspots (files with 3+ findings)

By status:

• Open (unresolved)
• Fixed (remediated and verified)
• Tracked (exported to issue tracker)
• False positive (dismissed with rationale)

Step 3: Generate JSON Report

Structure:

{
  "scan_metadata": {
    "scan_id": "<uuid>",
    "timestamp": "<ISO 8601>",
    "target": "<repository or directory scanned>",
    "tools_used": ["semgrep", "trufflehog", ...],
    "scan_duration_seconds": <int>
  },
  "summary": {
    "total_findings": <int>,
    "by_severity": {"critical": 0, "high": 0, "medium": 0, "low": 0, "informational": 0},
    "by_status": {"open": 0, "fixed": 0, "tracked": 0, "false_positive": 0},
    "by_category": {"CWE-79": 3, "CWE-89": 1, ...}
  },
  "findings": [
    {
      "id": "<finding-id>",
      "title": "<short description>",
      "severity": "<validated severity>",
      "category": "<CWE-XXX>",
      "location": {"file": "<path>", "line": <int>, "function": "<name>"},
      "status": "<open|fixed|tracked|false_positive>",
      "evidence": "<code snippet or trace>",
      "rationale": "<triage reasoning>",
      "tracking_url": "<url if tracked, null otherwise>"
    }
  ]
}

Write to: <scan-dir>/report.json

Step 4: Generate HTML Report

The human-readable report is a self-contained HTML file (security-report.html). Follow the template in references/report-format.md exactly — it is a prescriptive spec, not a suggestion.

Key features:

• Dark theme, color-coded severity badges
• Collapsible evidence and remediation sections
• Interactive filter buttons (filter by severity)
• CVE analysis table with exploitability cross-reference
• Pentest results with all tests numbered (P1, P2...)
• Negative results table (what was tested and passed)
• Footer with skill attribution (mandatory — see template)
• Zero external dependencies — opens offline

Build the HTML by replacing {{placeholders}} in the template with actual data. Repeat blocks for each finding/CVE/test.

After generating the HTML, run the Report Compliance Checklist from SKILL.md against your output. If any element is missing, fix it before proceeding.

Write to: <scan-dir>/security-report.html (and also repo root for easy access)

Step 5: Structured Output (Full-Scan Only)

Se este report vem de um full-scan com pipeline de 6 fases, produza também o findings.json estruturado:

1. Leia references/report-schema.json — siga exatamente
2. Para cada finding confirmado, popule todos required fields incluindo trace, conditions, execution, confidence
3. Valide: node scripts/validate-findings.cjs <scan-dir>/findings.json
4. Fix erros antes de prosseguir

Para workflows não-pipeline (discovery, diff-review, pentest), o format simples do SQLite é suficiente.

Step 6: Finalize

Run the finalization script to seal both reports and compute integrity hashes:

python3 scripts/finalize.py --scan-dir <dir>

This script:

• Validates both report files exist and are well-formed (JSON valid, HTML parseable)
• Computes SHA-256 hashes of report.json and security-report.html
• Writes a manifest.json with file hashes and completion timestamp
• Marks the scan as complete in the database

Step 6: Present to User

Show:

• The executive summary
• The findings table
• Location of the full report files
• Any findings that still need action (open critical/high)

Principles

• Reports are for two audiences: machines (JSON) and humans (HTML). Both must be complete.
• The HTML report is self-contained, interactive, and opens offline in any browser.
• False positives go in a collapsible appendix — they prove rigor but shouldn't clutter the main findings.
• Severity in the report is the validated severity (cross-referenced against project context), not the scanner's original rating.
• Every recommendation must be specific enough that a developer can act on it without further research.
• The executive summary is for people who won't read the rest. Make it count.
• All pentest tests performed must appear in the report — positive and negative results.