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

1. Per-finding subsections — title, severity, target, detail,

remediation, evidence, references

When the skill produces findings

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

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

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

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

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

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