/report-writing

name: report-writing
description: Bug bounty report writing for H1/Bugcrowd/Intigriti/Immunefi — report templates, human tone guidelines, impact-first writing, CVSS 3.1 scoring, title formula, impact statement formula, severity decision guide, downgrade counters, pre-submit checklist. Use after validating a finding and before submitting. Never use "could potentially" — prove it or don't report.

REPORT WRITING

Impact-first. Human tone. No theoretical language. Triagers are people.

---

THE MOST IMPORTANT RULE

> **Never use "could potentially" or "could be used to" or "may allow".** > Either it does the thing or it doesn't. If you haven't proved it, don't claim it.

BAD:  "This vulnerability could potentially allow an attacker to access user data."
GOOD: "An attacker can access any user's order history by changing the user_id
       parameter to the target user's ID. I confirmed this using two test accounts:
       attacker@test.com (ID 123) successfully retrieved victim@test.com (ID 456)
       orders, including their shipping address and payment method last 4 digits."

PERSISTENCE RULE

Every report-writing session must leave a complete finding folder on disk. Save the report draft, pre-submit checklist, references, downgrade counters, and final submission note under `findings/<target-or-program>-<bug-class>/`. Never rely on terminal or tmux scrollback for content the hunter needs later.

Minimum files:

findings/<target-or-program>-<bug-class>/
├── hackerone-report.md       # or bugcrowd-report.md / intigriti-report.md / immunefi-report.md
├── submission-notes.md       # final checklist, references, caveats, next action
└── evidence/                 # screenshots, curl output, response bodies when available

If `tools/validate.py` already wrote `submission-notes.md`, append/update it instead of creating a duplicate.

---

TITLE FORMULA

[Bug Class] in [Exact Endpoint/Feature] allows [attacker role] to [impact] [victim scope]

**Good titles (specific, impact-first):**

IDOR in /api/v2/invoices/{id} allows authenticated user to read any customer's invoice data
Missing auth on POST /api/admin/users allows unauthenticated attacker to create admin accounts
Stored XSS in profile bio field executes in admin panel — allows privilege escalation
SSRF via image import URL parameter reaches AWS EC2 metadata service
Race condition in coupon redemption allows same code to be used unlimited times

**Bad titles (vague, useless to triager):**

IDOR vulnerability found
Broken access control
XSS in user input
Security issue in API
Unauthorized access to user data

---

HACKERONE REPORT TEMPLATE

## Summary

[One paragraph: what the bug is, where it is, what an attacker can do. Be specific.
Include: endpoint, method, parameter, data exposed, required access level.]

Example: "The `/api/users/{user_id}/orders` endpoint does not verify that the
authenticated user owns the requested user_id. An attacker can enumerate any
user's order history, including PII (email, address, phone) and purchase history,
by incrementing the user_id parameter. No privileges beyond a standard free
account are required."

## Vulnerability Details

**Vulnerability Type:** IDOR / Broken Object Level Authorization
**CVSS 3.1 Score:** 6.5 (Medium) — AV:N/AC:L/PR:L/UI:N/S:U/C:H/I:N/A:N
**Affected Endpoint:** GET /api/users/{user_id}/orders

## Steps to Reproduce

**Environment:**
- Attacker account: attacker@test.com, user_id = 123
- Victim account: victim@test.com, user_id = 456
- Target: https://target.com

**Steps:**

1. Log in as attacker@test.com, obtain Bearer token

2. Send the following request:

GET /api/users/456/orders HTTP/1.1 Host: target.com Authorization: Bearer ATTACKER_TOKEN_HERE

3. Observe response:

```json
{
  "orders": [
    {"id": 789, "items": [...], "email": "victim@test.com", "address": "123 Main St..."}
  ]
}

The response contains victim's full order history and PII despite being requested by a different user.

Impact

An authenticated attacker can enumerate all user orders by iterating user_id values. This exposes: full name, email, shipping address, purchase history, and payment method (last 4). With ~100K users, this represents a mass PII breach affecting all registered users. Exploitation requires only a free account and takes minutes with a simple loop.

Recommended Fix

Add server-side ownership verification:

if order.user_id != current_user.id:
    raise Forbidden()

Supporting Materials

[Screenshot showing attacker's session returning victim's order data] [Video walkthrough if available]

---

## BUGCROWD REPORT TEMPLATE

```markdown
# [IDOR] User order history accessible without authorization via /api/users/{id}/orders

**VRT Category:** Broken Access Control > IDOR > P2

## Description

[Same impact-first paragraph as HackerOne summary]

## Steps to Reproduce

[Same structured steps — exact HTTP requests, exact responses]

## Proof of Concept

[Screenshot/video showing the actual impact]

## Expected vs Actual Behavior

**Expected:** 403 Forbidden when user_id does not match authenticated user
**Actual:** 200 OK with victim's full order data

## Severity Justification

P2 (High) — Direct read access to other users' PII. Affects all user accounts.
No user interaction required. Exploitable by any authenticated user.
Automated enumeration could exfil all [N] user records in minutes.

## Remediation

Add ownership verification: `if order.user_id != current_user.id: raise 403`

---

INTIGRITI REPORT TEMPLATE

# [Bug Class]: [Exact Impact] in [Endpoint/Feature]

## Description

[Impact-first paragraph. Start with what an attacker can do, not with how you found it.
Include: endpoint, method, parameter, data exposed, required privileges.]

## Steps to Reproduce

**Environment:**
- Attacker: email=attacker@test.com (standard account, no special role)
- Victim: email=victi