Writing Better Reports Faster

If you are you looking for tips on how to make your submission report looks pretty and professional, you found the right article!

Let me share here with you some tips and tools you can use from today to enhance the readability and appearance of your report.

This isn't a post about writing good, but fancy reports, that is why I will only talk about the form and not the substance of the report.

Using the right template

First let's start with the obvious. Either you're participating in Code4rena, Sherlock, CodeHawks, Immunefi, or any other competitive platform, you must respect the template. This is important as judges will review hundreds of submissions, you easily understand how this can help them to go faster.

#L/M/H-00 - Description

## Vulnerability details

## Impact

## Proof of Concept

## Tools Used

Manual review

## Recommended Mitigation Steps

A great title to begin your report will help the judge to grasp the core idea, here's an example of good title:
"[actors] can [impact] by [condition]"

The title must be short or it will simply lose its purpose.

Copy With Line Number

If you're using VSCode this is a must have for your reports. This allow you to get code snippets along with the line numbers, and file relative path in a click! Check my previous post for more informations: https://twitter.com/InfectedCrypto/status/1803420953512206600

Also, you might be interested by the quick mod I've done to the Copy With Line Number extension to lose even less time

WeAudit

This extension developed by @trailofbits is also a must have for every SR. Among all its functionalities, there is one very practical for reports: you can seamlessly get a link to a specific part of the code!

More informations here: weAudit Vscode Extension

Diff blocks

The recommendation part of the report usually contains a diff of the modification compared to base implementation. By reading a lot of reports, I've noticed a lot of people don't seem to know this exist in the first place. By using wrapping your code inside a ```diff ... ``` code block you'll get these really practical colors:

If you want to make even better diffs, like the one in the screenshot below, you can diff your updated code with the original contest repo by following next steps:

Adds the contest remote repository named 'original' (or the name you prefer) with its URL.

git remote add original https://github.com/project/contest-repo.git

Downloads objects and refs from the remote repository

git fetch original

print the diff between original file and your modifications

git diff original/main -- src/contract.sol

Adding images

You can also add images to your submission, to do so, you can use a simple trick. Adding an image to a comment/text field in github generate a link to the image (image is hosted on github servers) that you can then use in your submission.

Github enhanced comments

Finally, to use with moderation as this can make "too much" sometimes, you can try the special github markdown "Alerts" which can highly enhance the readability sometimes!

Well that's the end. Go write your report now, I bet you have something cooking that might profit from a bit of seasoning 🍜🧂