pentest-report

When to use

Trigger on any of:

• "Write the pentest report from these findings."
• "Turn security-audit's output into a deliverable for the customer."
• "Prepare the Q3 security assessment document."
• End of an internal red-team engagement that already has a findings list.

Do not use to perform the assessment. This skill only assembles the report from evidence already collected.

Inputs

• AUDIT_DIR — directory containing scanner outputs (the OUT_DIR from security-audit typically). Required.
• MANUAL_NOTES — optional path to a markdown file with findings the tester documented by hand.
• ENGAGEMENT_META — YAML with engagement name, client, tester(s), dates, scope list, methodology notes.
• OUT_FILE (default: ./pentest-report.md).

Example ENGAGEMENT_META:

engagement: "Q3 2026 External Web App Assessment"
client: "Acme Corp"
testers:
  - "Taylor Reyes <[email protected]>"
window:
  start: "2026-04-05"
  end:   "2026-04-12"
scope:
  in:
    - https://app.acme.example
    - https://api.acme.example
  out:
    - https://blog.acme.example
methodology:
  - "OWASP WSTG v4.2"
  - "PTES Technical Guidelines"

Outputs

• $OUT_FILE — markdown report matching references/report-template.md.
• pentest-report.findings.json — machine-readable finding list used during assembly (kept for regeneration / re-export to DOCX/PDF).
• pentest-report.risk-matrix.csv — risk matrix data.

Tool dependencies

• jq to read scanner outputs.
• pandoc (optional) to convert $OUT_FILE to DOCX/PDF for client delivery.
• cvss-cli (optional) to recompute vectors when raw vectors are present.

Procedure

1. Load ENGAGEMENT_META and validate required fields (client, window, scope, testers).
2. Collect findings:
   • From $AUDIT_DIR/findings.normalized.json (security-audit output).
   • From $AUDIT_DIR/secrets.deduped.json (secret-scanner output).
   • From $AUDIT_DIR/dep-audit.normalized.json (dependency-audit output).
   • From $MANUAL_NOTES (parsed: each H3 becomes a finding).
3. Normalize each finding into the report schema:

   { title, severity, cvss_score, cvss_vector, cwe, description,
     evidence (markdown block with code fences + image refs),
     impact, remediation, references[], status }
   

4. Deduplicate across sources by (cwe, affected_asset) — if two scanners found the same issue, merge evidence blocks and keep the higher CVSS.
5. Assign each finding a stable ID: FIND-<YEAR>-<0-padded-index>.
6. Assemble the document per references/report-template.md:
   • Title page + engagement metadata.
   • Executive Summary (non-technical; counts per severity; business impact paragraph; 3 headline recommendations).
   • Scope (in/out, test windows, test accounts used).
   • Methodology (tools, frameworks cited from meta).
   • Findings (ordered by severity desc, then CVSS desc).
   • Risk Matrix (Impact x Likelihood 5x5, each cell lists finding IDs).
   • Recommendations (strategic, beyond per-finding fixes).
   • Appendix A: Raw evidence pointers (relative paths into $AUDIT_DIR).
   • Appendix B: Tool versions.
7. Emit pentest-report.risk-matrix.csv: finding_id,likelihood(1-5),impact(1-5),risk(likelihood*impact).
8. Optionally convert: pandoc $OUT_FILE -o pentest-report.docx --reference-doc=corp-template.docx.