report-writing

Report Writing — Professional Vulnerability Disclosure

When to Use

• /report command invoked
• Validator has issued a CONFIRMED verdict
• Director decides to submit a finding
• Need to draft a follow-up or clarification to a maintainer

Writing Principles

Sound Human, Not AI

Reports go to real maintainers. They can spot AI-generated text instantly and will take your report less seriously.

Avoid:

• Starting sentences with "It is worth noting that..." or "It should be noted..."
• "This vulnerability allows an attacker to..." (every single sentence)
• Bullet-point-only reports with no narrative flow
• Overly formal language ("hereby", "aforementioned", "thus")
• Repeating the same sentence structure back to back
• Hedging everything ("potentially", "could possibly", "might theoretically")
• Filler phrases ("in order to", "it is important to", "as a matter of fact")
• Numbered lists for everything — use prose where it reads better

Do:

• Write like a competent engineer explaining a bug to a colleague
• Vary sentence length — mix short punchy sentences with longer explanations
• Use active voice: "The parser accepts..." not "It can be observed that the parser..."
• Be direct about impact: "This crashes the process" not "This may potentially lead to a denial of service condition"
• Use contractions naturally: "doesn't", "won't", "can't" — especially in emails
• Start paragraphs differently — not every paragraph should begin the same way
• Include one specific detail that shows you actually tested it (Node version, OS, exact error message)

Tone by Channel

Channel	Tone	Length	Format
GHSA	Professional, structured	Medium (300-500 words)	Markdown with headers
HackerOne	Concise, impact-focused	Short-medium (200-400 words)	Their template format
Email (first contact)	Friendly, brief	Short (100-150 words)	Plain text, no attachments
Email (full report)	Professional, thorough	Medium (300-500 words)	Plain text or markdown
Follow-up / clarification	Conversational, helpful	Short (50-150 words)	Plain text

Process

Step 1: Gather Inputs

Read these files from the target directory:

• findings.md — Hunter's technical details
• verdict.md — Validator's confirmed verdict with CVSS
• poc_*.py or poc_*.js — Working PoC code
• brief.md — Target metadata (version, repo URL, maintainer contacts)

Step 2: Determine Channel

Does the project have a HackerOne program?
  YES -> HackerOne report
  NO  -> Does the project have SECURITY.md with email?
    YES -> Email first, then GHSA if no response in 7 days
    NO  -> Does the repo have Security Advisories enabled?
      YES -> GHSA
      NO  -> Find maintainer email from package.json/GitHub profile -> Email

Step 3: Calculate CVSS

Use CVSS 3.1 calculator logic:

Factor	Question	Values
AV (Attack Vector)	How does attacker reach it?	N=network, A=adjacent, L=local, P=physical
AC (Attack Complexity)	Special conditions needed?	L=no special conditions, H=race/specific config
PR (Privileges Required)	Auth needed?	N=none, L=low user, H=admin
UI (User Interaction)	Victim must do something?	N=no, R=yes (click link, open file)
S (Scope)	Breaks out of component?	U=no, C=yes (sandbox escape, affects other users)
C (Confidentiality)	Data exposed?	N=none, L=limited, H=all data
I (Integrity)	Data modified?	N=none, L=limited, H=full control
A (Availability)	Service disrupted?	N=none, L=degraded, H=full DoS

Common patterns:

• Unauthenticated RCE: AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H = 9.8 CRITICAL
• Auth required RCE: AV:N/AC:L/PR:L/UI:N/S:U/C:H/I:H/A:H = 8.8 HIGH
• Unauthenticated DoS (crash): AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H = 7.5 HIGH
• Unauthenticated DoS (catchable): AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:L = 5.3 MEDIUM
• Stored XSS: AV:N/AC:L/PR:L/UI:R/S:C/C:L/I:L/A:N = 5.4 MEDIUM
• Path traversal read: AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:N/A:N = 7.5 HIGH
• Path traversal write: AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:H/A:H = 9.1 CRITICAL
• SSRF to metadata: AV:N/AC:L/PR:L/UI:N/S:C/C:H/I:N/A:N = 7.7 HIGH

Step 4: Write the Report

Select the appropriate template from templates/ and fill it in. Then apply these rewrites:

Humanization pass:

1. Read the draft aloud in your head — does it sound like a person wrote it?
2. Replace any "It is important to note that X" with just "X"
3. Replace "This vulnerability allows an attacker to" with varied openers: "An attacker can...", "Parsing untrusted input...", "When processing...", "The [function] doesn't..."
4. Remove duplicate information — don't say the same thing in Summary and Description
5. Check that the PoC section is copy-pasteable (exact commands, exact version)
6. Add one human touch — a note about what you tested on, or a brief suggestion for the fix

Structure check:

1. Summary is one sentence, max two
2. Impact section answers "so what?" for a non-security person
3. PoC has exact reproduction steps a developer can follow in 2 minutes
4. Suggested fix is actionable (not just "validate input" — say HOW)

Step 5: Write Subject Line (for email)

Format: [Security] [SEVERITY] vulnerability in [PROJECT] [VERSION]

Good: [Security] HIGH severity path traversal in archiver v5.3.1 Bad: Security Vulnerability Found In Your Project Bad: URGENT: Critical Security Issue Detected

Follow-Up Templates

No response after 7 days

Hi [name],

Just following up on my security report from [date]. I understand you may be busy — happy to provide any additional details or clarify anything about the finding.

If you'd prefer I submit this through a different channel (GitHub Security Advisory, etc.), I'm happy to do that instead.

Best,
[name]

Maintainer asks for more info

Sure — here's the additional detail:

[answer their specific question concisely]

The key thing is [restate the core issue in one sentence]. Happy to jump on a call if that would be easier.

Maintainer disputes severity

Thanks for looking at this. I see your point about [their argument].

My reasoning for [SEVERITY] was [brief CVSS justification]. But I'm happy to adjust — the important thing is getting it fixed. Would [LOWER_SEVERITY] work better for you?

Maintainer says "won't fix"

I understand — thanks for taking the time to review it.

Would you be open to adding a note in the README about [the risk] so users handling untrusted input are aware? That way the behavior is documented and users can make an informed decision.

Either way, thanks for your time.

Recommended: Humanizer Skill

Install blader/humanizer — a Claude Code skill that automatically removes signs of AI-generated writing. Run it as a final pass on any report before submitting.

# Install the humanizer skill
git clone https://github.com/blader/humanizer.git .claude/skills/humanizer

After drafting a report, invoke /humanizer to clean up AI patterns automatically. This catches things the manual humanization pass might miss.

References

• Humanization Guide — Detailed patterns for natural writing
• CVSS Quick Reference — Common vectors and score calculation
• Channel Selection — How to find the right disclosure channel