How to write a bug bounty report that survives triage

What a report that lands contains

• An executed proof, with its command and output, and a control case. The control is the same test without the bug step. It shows the loss comes from the bug and not from the setup.

• A final assertion on the object the impact row names. A balance, an owner, a stored record. An event or a reverted call is not the object.

• The exact code location on a pinned revision, and a concrete fix. File, lines and commit. The fix names the lines it changes.

• A title that states mechanism and consequence in one sentence. Numbered attack steps follow it, kept separate from the test code.

• Limits and non-claims, stated by you. Name the nearest known issue and say how this one differs.

• The impact row, quoted verbatim. Copy it from the programme page. Do not paraphrase it.

• Filed within hours of reproduction. Fold the variants into one report.

A worked example, before and after

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

interface IERC20 {
    function balanceOf(address account) external view returns (uint256);
    function transfer(address to, uint256 amount) external returns (bool);
    function transferFrom(address from, address to, uint256 amount) external returns (bool);
}

/// @notice Written for the Bounty Operator report guide. Not a real protocol.
contract HarborVault {
    IERC20 public immutable asset;
    uint256 public constant DELAY = 2 days;

    uint256 public totalShares;
    mapping(address => uint256) public shares;
    mapping(address => uint256) public queued;
    mapping(address => uint256) public unlockAt;

    constructor(IERC20 asset_) {
        asset = asset_;
    }

    function deposit(uint256 assets) external returns (uint256 minted) {
        uint256 pool = asset.balanceOf(address(this));
        minted = totalShares == 0 ? assets : assets * totalShares / pool;
        shares[msg.sender] += minted;
        totalShares += minted;
        require(asset.transferFrom(msg.sender, address(this), assets), "transfer failed");
    }

    /// @dev Burns shares now and pays after DELAY, so an exit cannot be front-run.
    function requestWithdraw(uint256 shareAmount) external {
        uint256 pool = asset.balanceOf(address(this));
        uint256 owed = shareAmount * pool / totalShares;
        shares[msg.sender] -= shareAmount;
        totalShares -= shareAmount;
        queued[msg.sender] += owed;
        unlockAt[msg.sender] = block.timestamp + DELAY;
    }

    function claim() external {
        require(block.timestamp >= unlockAt[msg.sender], "locked");
        uint256 owed = queued[msg.sender];
        queued[msg.sender] = 0;
        require(asset.transfer(msg.sender, owed), "transfer failed");
    }
}

$ forge test --match-contract HarborVaultSplitTest -vv

[PASS] test_control_oneRequest() (gas: 155201)
Logs:
  alice paid 50000000
  bob paid   50000000

[PASS] test_split_twoRequests() (gas: 158023)
Logs:
  alice paid 58333333
  bob paid   41666667

# Critical: accounting bug in HarborVault lets an attacker steal funds

## Summary
The withdrawal accounting in HarborVault is wrong. An attacker can withdraw more than they put in and drain the vault. All user funds are at risk.

## Impact
Critical. Loss of all user funds.

## Proof of concept
PoC attached. Run the test to see the exploit.

## Recommendation
Fix the accounting in requestWithdraw.

# requestWithdraw prices shares against assets already queued for withdrawal, so a split exit is overpaid out of the remaining holders' assets

## Impact row
"Direct theft of user funds held by the vault."

## Location
src/HarborVault.sol:34-35 at commit 4f1c9e2, the revision the scope page lists.

## Root cause
Line 34 reads the vault's whole token balance as the pool. Assets queued at line 38 stay in that balance until claim() pays them, while the shares they belonged to were burned at line 37. Every request made while a queue exists is priced against assets that are already owed to someone.

## Attack steps
1. Alice and Bob each hold 50.000000 shares. The vault holds 100.000000 USDC.
2. Alice calls requestWithdraw(25.000000). Queued for Alice: 25.000000. Shares outstanding: 75.000000. Vault balance: still 100.000000.
3. Alice calls requestWithdraw(25.000000) again. Line 35 computes 25 × 100 / 75 = 33.333333. Queued for Alice: 58.333333.
4. After the two-day delay Alice calls claim() and receives 58.333333 USDC.
5. Bob holds the only 50.000000 shares left. The vault holds 41.666667 USDC. Bob exits and receives 41.666667 USDC.

Every step is a public call by an ordinary holder. No privileged role acts.

## Proof
```
$ forge test --match-contract HarborVaultSplitTest -vv

[PASS] test_control_oneRequest() (gas: 155201)
Logs:
  alice paid 50000000
  bob paid   50000000

[PASS] test_split_twoRequests() (gas: 158023)
Logs:
  alice paid 58333333
  bob paid   41666667
```
The control test is the same exit made with one request. The final assertion in each test reads Bob's token balance. The test deploys HarborVault unmodified and a plain six-decimal token. Nothing is mocked.

## Severity
High. The proof shows theft of part of one holder's funds: 8.333333 of Bob's 50.000000 USDC. The programme's Critical row requires loss of all funds in the vault, which this proof does not assert.

## Limits
Measured for two requests only. More requests take more; that follows from line 35 and is not measured here. deposit() reads the same balance at line 25 and is not part of this claim.

## Nearest known issue
Audit note L-03, "rounding in requestWithdraw favours the user". L-03 concerns one unit of rounding and its fix changes the rounding direction. This report concerns the unsubtracted queue and its fix is different.

## Fix
Track a totalQueued counter. Add to it at line 38, subtract it in claim(), and price shares against balanceOf(vault) - totalQueued at lines 25 and 34.

The twelve checks

1. 01

   Actor trace

   Who performs every step, and who supplies every decisive value?

   Leads to: Drop

2. 02

   Own-verdict reversal

   Which new evidence defeats each reason you recorded when you held this finding or lowered its severity?

   Leads to: Earlier verdict stands

3. 03

   Design intent and counterfactual

   Did the project mean this behaviour, and does the bug step add anything over the intended path?

   Leads to: Drop

4. 04

   Literal impact and exclusion fit

   Does an exclusion name this class, and does every clause of the impact row have an artefact behind it?

   Leads to: DropRewrite, then submit

5. 05

   Asset and version binding

   Does the cited code exist in the scoped asset, at the revision that is deployed?

   Leads to: DropProve first

6. 06

   Prior-art sweep

   Does a known issue, an audit note, a branch or a pull request cover the same function and consequence, or carry the same fix?

   Leads to: Hold: duplicate

7. 07

   Own-report family

   Stated with no file and no entry point, is the broken invariant one you have already reported on this programme?

   Leads to: Hold: duplicate

8. 08

   Executed end-state proof

   Does the final assertion read the object the impact row names, on production code, with the command and its output in the report?

   Leads to: Prove first

9. 09

   Production reachability

   Does every state the proof sets up have a route from live state by public calls?

   Leads to: Prove first

10. 10

    Severity against the written scale

    Which row of the programme’s own scale does the proof assert, after every recovery action is applied?

    Leads to: Rewrite, then submit

11. 11

    Submission integrity

    Does what the platform stored match the draft: the proof field, the severity, the impact row?

    Leads to: Rewrite, then submit

12. 12

    Private-duplicate clock

    Small fix, old code, central path, checklist class: how long before someone else files it?

    Leads to: Sets a filing deadline

The order to work in

1. Scope

   Is the code in the scoped asset at the deployed revision, is the class excluded, and does every clause of the impact row have an artefact behind it?

   Run this stage: Scope

2. Provenance

   Who performs each step, is the behaviour documented design or an audit fix, and is every precondition reachable from live state?

   Run this stage: Provenance

3. Prior art

   Same root cause or same one-line fix as a known issue, a prior audit note, a team branch, or your own earlier report?

   Run this stage: Prior art

4. Proof

   Does the proof run production code on every step and end by reading the object the impact row names, with measured numbers?

   Run this stage: Proof

5. Severity

   What is the highest row of the programme’s own scale that the proof fully asserts, after every downgrade clause?

   Run this stage: Severity

6. Triager

   What is the one sentence that closes this report in ten minutes, and is it answered in the first paragraph?

   Run this stage: Triager

7. Report

   Do the claims follow from the code, is the proof inline, do form and body agree, are the limits stated?

   Run this stage: Report

8. Verdict

   One decision, one blocker, the cheapest action that removes it, and a filing deadline.

SubmitRewrite, then submitProve firstHold: duplicateDrop

Evidence to collect before you write

• The programme’s impact list, and the row you selected

• Exclusions and trusted roles

• The severity scale, with thresholds and downgrade clauses

• The asset, the revision your proof ran on, and the deployed revision

• Known issues, audits and fix-review notes, team branches, and how deep your clone goes

• Your own earlier reports on the programme

• The actor behind each step

• The measured loss

• The proof run: command, commit, output, and anything mocked

• Fee and duplicate rules, and the date you first reproduced it

• The platform’s read-back of the stored submission