How to Submit Bug Reports That Get Paid

At Immunefi, we have a simple catchphrase: excellent bug reports lead to excellent payouts.

It’s a completely serious catchphrase.

Immunefi has facilitated the world’s largest bug bounty payouts ($10 million, $6 million, $2.2 million, and many more), because the funds at risk are orders of magnitude larger in web3, compared to web2. This means the payouts must be higher to incentivize responsible disclosure.

But it also means the bug reports must be excellent to earn those excellent payouts, and it’s important for whitehats using Immunefi for the first time to know the differences between submitting reports on Immunefi, as opposed to other bounty platforms.

In this post, we outline exactly what to do when submitting reports, what to avoid, and what good and bad bug reports look like. This will reduce uncertainty and help whitehats on Immunefi maximize their chances of getting massive wins.

The reality is stark: bugs you find could seriously damage or destroy projects. If you’ve found a bug, you need to take the situation extremely seriously.

This means there are some basic principles to follow when bug hunting on Immunefi:

Don’t submit a three-line report. It will be completely ignored and closed, anyway. Low-quality reports can also get you banned on Immunefi.Be as thorough, deliberated and detailed as you need to be in pursuit of a big bug bounty. Treat bug report writing as an expression of craftsmanship.Articulate exactly how much economic damage would result from the exploit. If you don’t include this information, it will slow down the bug-reporting process and could result in a lower payout — or no payout.Submit a complete and runnable PoC. Make things easier for the project to determine that the bug is real, and you make things easier for yourself. As Algernon Sydney said in his seminal 1698 work Discourses Concerning Government, “God helps those who help themselves.”For Proofs of Concept (PoCs), it’s ideal to optimize your attack parameters, so you can determine the maximum economic damage that could result from a successful exploit. This is highly correlated to the scope and severity of your submitted bug, and will likely affect the final payout.PoCs should be tested on a local network, like a mainnet fork, not on mainnet or even public testnet. If exploits are tested on mainnet or public testnet, this not only constitutes a malicious attack, but will earn you an immediate and permanent ban from Immunefi.

Immunefi has numerous articles on how to craft such exploit PoCs, such as How to PoC your bug leads and a tutorial on how to PoC with Foundry (part 1 and part 2). Besides those, our continuous series on Hack Analyses provides real examples of PoCs for vulnerabilities that led to serious exploits.

To help increase the likelihood of your submissions being accepted, we have created a bug report template to guide you through the process of writing a high-quality bug report.

If you’ve ever wondered what a top-notch bug report actually looks like, this part is for you.

We’ll briefly explain each section that should be included in your bug report on Immunefi. If you’d like to skip to some examples of good (and bad) reports, check out our Help Center article, which dives deeper into the template details.

Title

The bug report title is the first thing that the project reads before any other section. The title should be descriptive enough to include some sort of vulnerability classification and the impact it creates. A good example would be something like, “Reentrancy in withdraw function leads to total loss of funds”, “Lack of access control in update function leads to griefing”, “Arithmetic error in calculateTotalRewards can temporarily freeze unclaimed yield”.

After reading the title, the project should have a basic understanding of what the rest of the bug report is about.

Bug Description

The bug description should be clear and concise, but being clear is the most important part. You should put yourself in the shoes of the project team and ask yourself: am I describing the vulnerability and its impact clearly, accurately, and without any unnecessary assumptions?

Brief/Intro

A very short and concise (one paragraph) statement on what the problem is, and what the consequences would be if the bug were exploited in the wild.

Details

A detailed explanation of the vulnerability itself. Do not leave out any relevant information. Code snippets should be supplied whenever helpful, as long as they don’t overcrowd the report with unnecessary details. This section should make it obvious that the whitehat understands exactly what they’re talking about, and more importantly, it should be clear by this point that such a vulnerability does exist.

Impact

This section is where you provide a detailed breakdown of possible losses from an exploit, especially if there are funds at risk. This illustrates the severity of the vulnerability, but it also provides the best possible case for you to be paid your fair share. Make sure that the selected impact is within the project’s list of in-scope impacts. You can check that on the project’s bug bounty program page on Immunefi.

Risk Breakdown

You should assess how difficult it is to exploit the disclosed vulnerability. The NIST’s Common Vulnerability Scoring System Calculator can help with such an assessment, especially if the report is addressing a Web/App or Blockchain/DLT bug.

Recommendation

You should include a recommendation on how to fix the bug (or mitigate the impact) in this section. Once again, this actually helps make the case for a good payout, as it illustrates your expertise and further explains the underlying vulnerability.

References

In this section, you are welcome to add any relevant links to documentation or smart contracts.

Proof of Concept

This section is crucial because it makes the vulnerability “real” in a way that nothing else can. Unfortunately, this is also the section that whitehats most often fail to fill out correctly. The first and most important component of a successful proof of concept (PoC) is that it should be runnable exploit code…

Not a list of steps (even though this can exist somewhere in the report)Not pseudocodeNot just the project’s smart contracts

…but an actual, runnable attack vector. A valid PoC might be an attack script (a Hardhat/Foundry test file, for example), a smart contract with functions that can trigger the exploit, or any code that manages to somehow exploit the project’s vulnerability.

See Immunefi’s Help Center article for more PoC guidelines and rules.

The whitehats who hunt on Immunefi are a special cadre of some of the best hackers in the world, finding world-changing vulnerabilities. They have the opportunity to make hundreds of thousands, or even millions, with a single bug find.

So, the demands for quality and good whitehat behavior are much higher on Immunefi.

For example, unlike other platforms, we will warn or ban users for:

Submitting AI-generated or automated reports. They aren’t accurate and waste time for all involved.Submitting lots of low-quality bug reports. We don’t allow spray-and-pray behavior on our platform. If you submit a report, make it a beautiful, high-quality report with a well-functioning Proof of Concept (PoC).Rogue behavior/harassmentRepeatedly submitting bug reports for impacts or assets that are out of scopeRepeatedly misclassifying the severity of bug reports

It’s also important to check the terms listed on every bounty page. These terms establish what type of vulnerabilities and assets are in scope. Don’t give a project any reason to disqualify your bug report. And remember that if you play fast and loose with the rules, you are essentially forfeiting your payment, as well as endangering any future prospects you might have on Immunefi.

Those are just some of the differences between Immunefi and other bug bounty platforms. To read more about the rules, check them out here.

Whitehats should be aware of their rights. First of all, whitehats should know that when projects onboard to Immunefi, they agree to a Service Level Agreement (SLA) that determines required response times for the receipt of the report, the decision on the report, and payout for valid reports.

If a project breaches the SLA, whitehats should poke them for a response or request help from Immunefi in the dashboard.

Whitehats also need to realize all the ways that projects benefit from their hard work. With an important vulnerability patched, projects can protect their brand image and keep user funds safe. User trust is often as important, if not more, than the funds being protected. Keep this in mind when negotiating. Knowing the needs and values of a project can help you find common ground and make things easier when you ask for a proper valuation of the bounty reward.

This approach is known as Tactical Empathy, a term coined by Chris Voss, the founder of business negotiation consultancy The Black Swan Group, who has years of experience leading high-stakes negotiations for the FBI.

If you listen well and align your narrative with the facts to be in your favor, then you are more likely to get the right payout amount for your bug submission.

If the negotiation doesn’t go in what you believe to be the right direction, then it’s time to ask for Immunefi’s direct intervention in the case.

There are times when you’ve submitted a bug and haven’t received word on it for weeks. Or a project may come back to you and declare that they decided to pay a much lower bounty than agreed upon. Some may try not to pay at all.

We’ve seen some less-than-healthy behavior from projects, and whitehats end up feeling like they don’t have any negotiating power and that they should be happy to just accept whatever payment they’re offered, even if it doesn’t make sense according to the terms of the project’s own bounty program!

When such things happen, you should not be passively waiting for a solution or trying to create one yourself, but instead, raise the issue to Immunefi. And don’t forget that projects have signed SLAs, as mentioned above.

If it’s only been a few hours, or a few days, it’s fine to wait. But if it’s been up to 14 days without a response on a critical bug submission, delay no further. You should reach out to the project and also the Immunefi team via the submission thread in the dashboard so that we can contact the project and check on the status of your submission.

Here are more details on when and how to request mediation.

The Immunefi mediation process is a third-party, impartial evaluation during which we review both sides’ claims from a technical perspective. At the conclusion of our review process, we will provide a Mediation Summary of our impartial analysis of the claims.

We strive for absolute impartiality in this process, to ensure the fairest outcome for all involved as determined by the bug bounty program terms.

As whitehats working in web3, you are part of an exclusive network of elite bounty hunters who target, isolate, and eliminate errors in code design and architecture in a world where less than 0.01% of people probably even fully understand what you do.

There is more to what you do than simply “making pocket money”. Your actions could determine whether the industry will continue to exist, or perish under the corruption and selfish actions of malicious actors.

And while you are here, Immunefi is here to:

Help you learn to become an elite ethical hacker.Provide you with the platform to hunt bugs and get paid.Provide help and support when you need it.

The Immunefi community is also ready to help. You can always ask for advice from other whitehats in our Discord.

Happy hunting.