pentest-finding-writer

name

pentest-finding-writer

description

Draft a pentest finding using the standard finding template with stable framework mappings. Use when the user says "write up this finding", "create a finding for...", "draft a vulnerability writeup", "score this with CVSS", "build the finding for the report", "promote this evidence to a finding", or similar requests to convert raw evidence into a deliverable finding. Works across web/API, mobile, infra, AD, cloud, wireless, physical, IoT/OT, AI/LLM findings.

Pentest Finding Writer

Convert raw evidence into a report-ready finding using the standard template.

Library root

$PENTEST_LIBRARY — caminho absoluto deste repositório clonado (definido pelo instalador; veja INSTALL.md).

Template: templates/finding-template.md (canonical text reference).

Materializing into an engagement (always use the generator)

⛔ Anti-pattern that silently breaks the importer: writing findings with YAML frontmatter (---\nid: FIND-NNN\nseverity: Critical\n---), filenames like find-NNN-slug.md, English severity strings, or CVSS 4.0 vectors. The Piersec parser ignores all of these and falls back to Severity = Informativa, CVSS = 0 on every finding. Real engagement (Flight Class, 2026-05-26): 19 findings had to be re-migrated after the client uploaded and saw everything tagged Informativa. If the engagement already has these wrong-format files, migrate them (rename to <sev>-NNN-<slug>.md, replace frontmatter with the metadata table) before adding new findings — don't mix the two conventions.

When the user has an engagement repo with a report/findings/ directory, do not hand-roll the file — call the Piersec generator. It enforces the modular layout the importer needs (filename <sev>-NNN-<slug>.md, H1 # {ID} — {Title}, metadata table without header, PT severity, CWE with link, CVSS as score (\vector`)`):

~/.claude/skills/pentest-report-structure/scripts/new-finding.py \
    --severity {crit|high|med|low|info} \
    --slug    short-kebab-slug \
    --title   "Imperative, specific finding title" \
    --cwe     79 \
    --cwe-name "Improper Neutralization …" \
    --cvss-score 8.7 \
    --cvss-vector "AV:N/AC:L/PR:L/UI:R/S:C/C:H/I:H/A:N" \
    --target "https://target/endpoint" \
    --app   "App / component" \
    --update-index    # adds the row to report.md index table

Then edit the freshly created file to fill the {{placeholders}} in ## Descrição, ## Prova de Conceito, ## Impacto, ## Recomendação, ## Referências. The metadata table comes pre-filled from the CLI flags.

If the engagement has no report/ yet, bootstrap it via pentest-report-structure (Mode A) before drafting findings.

How to operate

1. Ask for, or extract from context, the minimum evidence set:

   • Target asset(s) — host, URL, parameter, build, account, resource ARN.
   • Reproduction request/response or command/output (copy-pasteable, sensitive data redacted).
   • Authentication state at time of test (anon, low-priv, privileged, cross-tenant).
   • Pre-conditions (what the attacker needs).
   • Observed impact (what the attacker can do).

2. Locate the matching library checklist item by stable ID (WEB-AUTHN-04, AD-KRB-02, CLD-AWS-IAM-07, IOT-FW-05, LLM-PI-03, etc.). The item supplies the canonical mappings and risk profile. Search via:

   grep -REn '^### \[' "$PENTEST_LIBRARY"/0[0-9]-* "$PENTEST_LIBRARY"/1[0-9]-*
   

3. Fill templates/finding-template.md field-by-field:

   • Title — imperative, specific (include parameter / endpoint / host / role context). Avoid generic titles like "SQL Injection".
   • Severity — set Overall + CVSS 3.1 vector + score. Use CVSS 4.0 only if the engagement requires it.
   • Affected components — table form. Include version when relevant.
   • Mappings — pull CWE, framework reference (WSTG / API:2023 / MASVS / FSTM / CIS / etc.), MITRE ATT&CK technique, regulated-framework requirement when in scope.
   • Description — 2-3 sentences: what / where / why it exists.
   • Impact — business terms; tie to threat model if available; quantify (rows, accounts, dollars).
   • Reproduction steps — numbered, copy-pasteable. Sample request/response. Sanitise tokens, PII, customer IDs.
   • Evidence — list artefacts going to the appendix; every artefact stamped with capture timestamp.
   • Remediation — actionable; reference vendor docs / config keys / patches. Note compensating controls.
   • References — vendor advisories, CVEs, framework anchors.

4. CVSS scoring rules:

   • AV/AC/PR/UI describe the attacker path, not the worst plausible scenario.
   • Use Scope=Changed only when one component's privilege boundary is crossed (e.g., SSRF reaching the metadata service).
   • High-confidence findings use CVSS Base. Use Temporal/Environmental only when client-specific or kill-chain context applies.

5. Critical findings rule — if Critical, generate a separate live-notification draft (subject + 3-bullet impact + 1-bullet immediate mitigation) for the comms plan, not just the report entry.

6. Output the filled finding back to the user as Markdown. Do NOT write a file unless asked — most engagements collate findings into the engagement repo manually.

When NOT to use

• Pure scoping / ROE drafting → engagement-management.
• Active testing without evidence yet → use the type-specific pentest-* skill first.

Quality gate before delivery

• Title passes the "could a stranger find this exact spot from the title alone" test.
• Reproduction steps reproduce in a clean session; no implicit prior state.
• All sensitive values redacted (<REDACTED> placeholders).
• Mappings include at least: CWE + one framework reference + ATT&CK (when applicable).
• Remediation is actionable, not "implement input validation".

References inside the library

• templates/finding-template.md — the canonical structure.
• 00-engagement/03-reporting.md — quality gate + clustering + narrative rules.
• frameworks/ — for citation anchors.