For the purposes of this article, I would like to distinguish two topics:
- Vulnerability Details describing single security issue raised as a part of bigger report or bug bounty activities;
- A Formal Vulnerability Report is created as a result of security assessments and may contain more than one vulnerability.
Vulnerability details describes single security issue or a group of closely related issues. These are typically written by penetration testers and bug bounty hunters to alert the owners of vulnerabilities. Such reports may be sent through various channels, such as email or dedicated bug bounty platforms.
Writing Vulnerability Details
Vulnerability Details Structure
I recommend structuring vulnerability details into the following sections:
- Summary — This section serves as an introduction to the vulnerability, offering a brief overview of the issue and its scope.
- Impact — here, the report should elaborate on the business implications of exploiting the described vulnerability.
- Reproductions Steps — this section should provide a step-by-step guide for reproducing the issue, complete with screenshots, HTTP requests or Proof of Concept code snippets for clarity.
- Recommendations — adding this section adds value to the report, as it offers advice on how to address and remediate the identified issue.
- References — This is an optional section that could contain a list of links to external materials, documentations and security guides such as OWASP.
Include Screenshots and Proof of Concept Code Snippets
In the Reproduction Steps section, it’s worth to include as many details as possible to facilitate issue reproduction, especially for individuals who may not be familiar with the vulnerable feature. Screenshots and code snippets with proof of concept examples enhance the clarity of the report. For example, in the context of web application issues, providing HTTP requests that can be used to exploit a vulnerability simplifies the process, allowing the recipient to copy and paste the exploits.
Provide Severity Calculated with Popular Scoring System
Vulnerabilities should typically be accompanied by severity information or scoring data. The Common Vulnerability Scoring System (CVSS) is a widely adopted approach for calculating severity based on defined characteristics. Regardless of the chosen scoring system, I can recommend to include both scoring data and a human-readable representation of the score, such as “informational,” “low,” “medium,” “high,” or “critical.”
Writing Vulnerability Reports
Vulnerability Report Structure
For security assessments reports, I recommend to include the following sections:
- Executive Summary
- Security Findings and Recommendations
- Vulnerabilities (sorted by severity)
- Appendix (optional)
The Executive Summary section should contain the essential information and high level security assessment summaries, designed to be comprehensible to CISO, directors, auditors or any executive positions. In this section, I recommend to include:
- the timeframe when security assessments was performed,
- the testing scope and methodology,
- high level summary and recommendations for identified issues.
Executive Summary should not delve into each vulnerability individually but instead focus on groups of findings, along with recommendations for improving the target system’s security. Let’s consider a hypothetical scenario where a web application security assessment has identified Insecure Direct Object References (IDOR), account takeover, and vertical/horizontal privilege escalation vulnerabilities. Based on these findings, we can recommend prioritizing remediation efforts on access control mechanisms, as they were found to significantly lower the security posture of the tested application. I recommend keeping the Executive Summary section concise, not exceeding one page. Lengthy sections may not provide added value to potential readers.
Furthermore, I suggest separating the Executive Summary from the Security Findings and Recommendations section. In the latter section, you can delve more deeply into the identified security findings and provide comprehensive details about remediation actions. This section is intended for developers, the security team, product owners, or any individuals closely involved with the affected features. It makes sense to include diagrams and statistics related to the identified vulnerabilities here. Additionally, this is where you can include more in-depth information about the testing methodology, exploitation methods, and any technical aspects you would like to share.
The Vulnerabilities section typically consists of a list of vulnerabilities, structured as described in the previous chapter, and sorted by severity. If you have supplementary materials or lengthy code snippets to share with the report’s readers, you can place them in the Appendix section. This section is often empty and may be skipped, but it’s worth to separate extra materials from the main sections of the report.
General Writing Reports Advises
Use a Passive Voice Form
In formal documents such as reports, I recommend using a passive voice form instead of a first person. This form is more professional and suits better for security assessment reports delivered to your clients. Instead of writing “I found an SQL Injection vulnerability in the login form”, it is more elegant to write “During the security assessment, an SQL Injection vulnerability was identified in the login form”.
Moreover, when you write recommendations, you can use the following forms:
- It is advised to…
- It is recommended to…
- It is suggested to…
Obfuscate the Secrets
Obfuscate all of the secrets presented in the report text, code or screenshots. Secrets such as credentials, tokens or API keys shouldn’t be provided in a plain text in the report. I’m recommending to obfuscate major part of those secrets and potentially leave first few characters unobfuscated if you see a value in that. This approach ensures that sensitive data remains protected and inaccessible to unauthorized readers of the report.
Feel Like a Person Reading the Report
Last but not least, try to read the vulnerability details when it’s finished as a person who may be a potential reader such as:
- Security Engineer
- Software Developer
- Software Tester
- CISO
When you’re reading, imagine that you’re doing this for the first time, you have no context about the vulnerability and you would like to fully understand the issue. Furthermore, try to feel like people with the above roles. The reported issues might be read by developers or testers who may not be familiar with security. This is also one of the reasons why reports should be as clear as possible.
What do you think?
Show comments / Leave a comment