composing-vulnerability-report

What this skill does

# Composing Vulnerability Report

## Overview

After cluster 1-4 scan skills run, each one produces a Findings
file. A typical engagement ends up with eight to twenty such files
across the different skill categories. The customer wants ONE
vulnerability report — comprehensive, deduplicated, organized by
severity, with each finding cross-referenced to its source skill
and target.

This skill consumes one or more findings files (JSONL preferred,
JSON list also accepted), deduplicates entries by the canonical
fingerprint defined in `lib/finding.py`, enriches each finding
with a CVSS v3.1 vector when one isn't present (using a deterministic
heuristic based on severity + category — explicitly noted as
"derived, not assigned by NVD" in the output), and emits a single
markdown report with per-finding sections plus a top-level
summary table.

The report has a defined structure that downstream tools (next
two skills in cluster 6) consume:

1. **Header** — engagement ID, generation timestamp, source files
2. **Summary table** — finding count by severity
3. **Per-severity sections** — CRITICAL first, then HIGH, MEDIUM,
   LOW, INFO
4. **Per-finding subsections** — title, severity, target, detail,
   remediation, evidence, references

## When the skill produces findings

| Finding | Severity | Threshold | Affected control |
|---|---|---|---|
| Source file unparseable | **HIGH** | JSON/JSONL parse fails | (operational) |
| Finding missing required field | **HIGH** | A finding record is missing title, severity, target, detail, or remediation | (operational) |
| Duplicate fingerprint across files | **INFO** | Same finding appears in N>1 sources; reported as deduplication count | (informational) |
| Source file has zero findings | **INFO** | Empty or all-info-only file; reported but not an error | (informational) |
| Report generated cleanly | **INFO** | Positive confirmation | (informational) |

## Prerequisites

- Python 3.9+
- One or more findings files in JSON or JSONL format produced by
  any cluster 1-4 scan skill (which all share `lib/finding.py`
  schema)

## Instructions

### Step 1 — Gather findings sources

By default the skill reads every file matching
`engagement/findings/*.json` and `engagement/findings/*.jsonl`.
Override with `--source FILE` (repeatable).

### Step 2 — Run the composer

```bash
python3 ./scripts/compose_report.py engagements/acme-2026-q2/
```

Options:

```
Usage: compose_report.py PATH [OPTIONS]

Options:
  --source FILE         Specific findings file (repeatable; overrides default glob)
  --report-output FILE  Write the composed report here (default:
                        PATH/reports/vulnerability-report.md)
  --engagement-id ID    Override the engagement ID (default: parse from PATH/roe.yaml)
  --output FILE         Operational findings output (this skill's own findings)
  --format FMT          json | jsonl | markdown (default: markdown)
  --min-severity SEV    Filter report to findings at or above this severity
  --include-info        Include INFO-severity findings in the report (default: omit)
```

### Step 3 — Review the report

The output report has a predictable structure. The header
identifies the engagement, the source files, and the generation
timestamp. The summary table shows finding counts by severity.
Per-severity sections follow.

Each finding subsection includes a stable anchor (the fingerprint)
so cross-references from later artifacts (executive summary,
OWASP mapping) resolve into the report cleanly.

### Step 4 — Verify against sources

```bash
python3 ./scripts/compose_report.py engagements/acme-2026-q2/ --format json --output /tmp/compose-findings.json
jq '.[] | select(.severity == "high")' /tmp/compose-findings.json
```

If the report references a finding the operator didn't expect,
trace back via the finding's `skill_id` + `target` to the source
file.

## Examples

### Example 1 — End-of-engagement report

```bash
python3 ./scripts/compose_report.py engagements/acme-2026-q2/ \
    --report-output engagements/acme-2026-q2/reports/vulnerability-report.md
```

### Example 2 — Interim report mid-engagement

```bash
python3 ./scripts/compose_report.py engagements/acme-2026-q2/ \
    --min-severity high \
    --report-output engagements/acme-2026-q2/reports/interim-2026-06-15.md
```

`--min-severity high` produces an interim report covering only
HIGH and CRITICAL findings — useful for in-engagement customer
syncs.

### Example 3 — Regenerate after OWASP mapping

```bash
python3 ./scripts/compose_report.py engagements/acme-2026-q2/ \
    --source engagements/acme-2026-q2/findings/all-findings-with-owasp.jsonl \
    --report-output engagements/acme-2026-q2/reports/vulnerability-report-v2.md
```

Re-run after `mapping-findings-to-owasp-top10` has enriched each
finding with its OWASP category; the regenerated report includes
the OWASP tag in each per-finding subsection.

## Output

JSON / JSONL / Markdown per `lib/report.py` for the skill's own
operational findings. The PRIMARY output is the composed
vulnerability report, written as standalone Markdown to the
`--report-output` path.

Each operational Finding includes:

- `id` — `compose::<issue>::<source-file>`
- `severity` — CRITICAL / HIGH / MEDIUM / INFO
- `category` — `report-composition`
- `summary` — what went wrong (or right) during composition
- `evidence` — source files, finding counts, dedup stats

## Error Handling

- **PATH missing or empty** → emits CRITICAL operational finding,
  exits 1.
- **Source file unparseable** → emits HIGH operational finding,
  skips the file, continues with remaining sources.
- **No findings files found** → emits HIGH operational finding,
  exits 1.
- **Output report path not writable** → emits HIGH operational
  finding, exits 1.
- **Finding missing required fields** → emits HIGH operational
  finding, omits that record from the report, continues.

## Resources

- `references/THEORY.md` — Vulnerability-report structure history
  (NIST SP 800-115, OWASP Testing Guide), CVSS v3.1 vector
  composition, severity scoring tradeoffs (CVSS vs intrinsic vs
  EPSS), finding-deduplication theory, why fingerprint-based dedup
  beats title-based
- `references/PLAYBOOK.md` — Report-template variants per
  audience (technical, executive, regulatory), per-finding
  remediation phrasing patterns, evidence-redaction patterns
  for distributed reports, cross-reference protocol with the
  OWASP-mapping and exec-summary skills