How to Write a Better Vulnerability Report
Security teams are humans too. (1337 5p34k not included.)
An essential skill for a security researcher is the ability to write concise and clear vulnerability reports. A well-written vulnerability report will help the security team reproduce and fix the issue faster and minimize the possibility of exploitation. In this post, we are going to go into the components of a good vulnerability report and some tips and tricks I’ve learned along the way.
Step 1 of Writing a Good Report: Craft a Descriptive Title and Summary
The first parts of a great vulnerability report would always be a descriptive title and a clear summary.
What is the vulnerability that you have found? Does it correspond to an OWASP top 10? Where is it found on the target? Ideally, the title of the report should be descriptive to the point that it allows the security team you are working with to immediately get an idea of what it is that you are reporting and its potential criticality. For example, instead of saying
Report Title:
IDOR on a critical endpointyour report title should instead be:
Report Title:
IDOR on "https://example.com/change_password" leads to account takeover for all usersIn the first two seconds of reading your report, the security engineer already has a good idea of what is to come in the rest of the report. And in the subsequent summary section, include any additional details that you weren’t able to include in the title, like the post parameters used for the attack, how you found it, and so on.
Report Summary:
The "https://example.com/change_password" endpoint takes two POST body parameters: "user_id" and "new_password". A POST request to this endpoint would change the password of user "user_id" to "new_password". This endpoint is not validating the "user_id" parameter and as a result, any user can change anyone else's password by manipulating the "user_id" parameter.Step 2: Include a Severity Assessment
It is often helpful to include an honest assessment of the severity of the issue in your report. In addition to working with you to fix vulnerabilities, security teams have other responsibilities to tend to as well. Including an honest assessment of severity will help them prioritize which vulnerabilities to fix first, and ensure that critical vulnerabilities are taken care of right away.
Study the CVSS scale for a general idea of how critical each type of vulnerability is. Then, figure out what your client company cares about and which vulnerabilities would present the biggest business impact. Always customize your assessment to fit into the client’s business priorities. For example, some companies may consider a user’s birth date leak as a big issue and others might not. While leaks of users’ credit card information are almost always considered an urgent issue.
Provide an accurate assessment of severity in your report based on the type of vulnerability and business impact. This will help make everyone’s lives easier and contribute to a positive relationship between you and the security team.
Severity of the issue: HighStep 3: Give Clear Steps to Reproduce
Provide step-by-step instructions on how to reproduce the vulnerability and include all the relevant details that you can think of. It’s best to assume that engineer on the other side of the report does not have any knowledge of the vulnerability and does not know how the application works in detail. For example, this is the “steps to reproduce” section of an okay report:
Steps to reproduce:Log onto the site and visit “https://example.com/change_password". Click on the “Change password” button.Intercept the request, and change the “user_id” parameter to another user’s ID.
And this is the “steps to reproduce” section of a good report:
Steps to reproduce:Make two accounts on “example.com”, user A and user B.Log onto “example.com” as account A and visit “https://example.com/change_password".Fill in the desired new password in the "new password" field located on the top left of the page.Click on the “Change password” button located on the top right of the page. Intercept the POST request to "https://example.com/change_password" and change the user_id POST parameter to the user ID of account B.You can now log into account B using the new password that you have chosen.
Although the first report will probably still be understood by the security team, the second report is a lot more specific. This avoids any ambiguity and misunderstanding and speeds up the vulnerability mitigation process.
Step 4: Provide a Proof of Concept
For simple vulnerabilities, the steps to reproduce that you have provided often serves as the PoC as well. But for vulnerabilities that are more complex in nature, it is helpful to include a video or photo “proof” of the vulnerability. You can also include any crafted URLs, scripts or upload files that you have used when validating the vulnerability. For example, for a CSRF vulnerability, include the HTML file with the CSRF payload, and for an XXE, include the crafted XML file that you used during the attack. PoC scripts like these save the security team time as they won’t have to prepare the attack payload themselves.
Step 5: Describe Impact and Attack Scenarios
Include a plausible way of how a vulnerability can be exploited. Think about how a malicious attacker would do with the vulnerability that you have found. Try to escalate the impact of the vulnerability as much as possible and give the client company a realistic sense of how the bug can be exploited if it is found by a malicious attacker. This will help the company prioritize the fix internally and determine if additional steps and internal investigations are necessary.
Step 6: Recommend Possible Mitigations
If you can, recommend possible mitigations in your report. This will save the team’s time used to research mitigations for that vulnerability. You should only do this if you have a good idea about the root cause of the issue. Often, you as the security researcher who discovered the vulnerability would be the most familiar with the particular behavior of an application feature and thus would be in the best position to come up with a comprehensive fix.
Don’t Assume Anything
Don’t assume that the security team would be able to understand everything in your report. Remember, you might have been staring at this endpoint for a week, but to the engineers that you are communicating with, this is all new information. They have a whole host of other responsibilities on their plates and often aren’t as familiar with the feature as you. Help them understand what you have discovered.
Be as verbose as possible and include all the details that you can think of, even ones that you find it unnecessary. Think about the potential consequences of being unnecessarily verbose versus the consequences of leaving out essential details: the worst thing that can happen if you are too wordy is that your report will take two extra minutes to read. But if you leave out important details, the remediation of the vulnerability might get delayed, and the bug might be exploited by a malicious attacker!
Remember: Security Teams are Humans too
Make your report as easy to read as possible. Write in a conversational tone and include links to references for obscure security knowledge. Don’t use 1337 5p34k, slang or abbreviations, as these make the text harder to read and will add to the annoyance of your reader.
Communicate with the security engineer with respect and professionalism. Provide follow-ups and clarifications patiently and promptly.
And remember, we all make mistakes. If the person handling your report makes a mistake or mishandles the issue, communicate and explain your thought process, and elaborate on the technical details of the vulnerability. If that still does not resolve the issue, escalate the issue through the bug platform or other security engineers on the team. And if you are the one that makes a mistake during the process, communicate that to the security team as soon as possible with all the relevant details.
Miscommunication issues will inevitably happen, but remember that as the security researcher, you have the power to minimize that possibility by providing a clear and comprehensive vulnerability report. By honing your communication skills in addition to hacking skills, you will save everyone’s time and maximize your value as a hacker!
