# Vulnerability Reports

> A pentest vulnerability report documents the findings of a penetration test, detailing identified security weaknesses, their potential impact, and remediation steps. It is critical for informing stakeholders about the security posture of their systems, prioritizing vulnerabilities, and guiding mitigation efforts. Effective reports enhance overall security by providing actionable insights to prevent exploitation.

## Tools

Tools to help you collaborate and generate your reports.

* [GhostManager/Ghostwriter](https://github.com/GhostManager/Ghostwriter) - The SpecterOps project management and reporting engine
* [pwndoc/pwndoc](https://github.com/pwndoc/pwndoc) - Pentest Report Generator

List of penetration test reports and templates.

* [reconmap/pentest-reports](https://github.com/reconmap/pentest-reports) - Collection of penetration test reports and pentest report templates.
* [juliocesarfort/public-pentesting-reports](https://github.com/juliocesarfort/public-pentesting-reports) - A list of public penetration test reports published by several consulting firms and academic security groups.
* [xanhacks/web-pentest-reports](https://gitlab.com/xanhacks/web-pentest-reports) - List of template vulnerability reports for web pentesting.
* [noraj/OSCP-Exam-Report-Template-Markdown](https://github.com/noraj/OSCP-Exam-Report-Template-Markdown) - Markdown Templates for Offensive Security OSCP, OSWE, OSCE, OSEE, OSWP exam report.

## Vulnerability Report Structure

* Executive Summary
* Security Findings and Recommendations
* Vulnerabilities (sorted by severity)
* Appendix (optional)

## Vulnerability Details Structure

* **Summary**: a concise introduction to the vulnerability, providing a snapshot of the issue and its potential reach..
* **Impact**: detailed insights into the potential business ramifications that could arise from exploiting this vulnerability.
* **Reproductions Steps**: a comprehensive, step-by-step walkthrough on how to replicate the issue,, complete with screenshots, HTTP requests or Proof of Concept code snippets.
* **Recommendations**: suggestions and best practices for addressing and resolving the highlighted issue.
* **References**: links to external content, documentation, and security guidelines, including resources like OWASP.
* **Severity**: Include a severity score like CVSS.

## General Guidelines

* Use a **Passive Voice Form**.
* **Obfuscate** the secrets and Personal Identifiable Information: `passwords`, `token`, Identity cards, Pictures ...
* Include **captions** for all figures and images.
* Apply **shadows** to images to enhance their visual appeal.
* Customize the report for technical and non-technical stakeholders, ensuring clarity and comprehensibility for all readers.
* Explain the **business impact** and context of vulnerabilities to help prioritize remediation efforts effectively.
* Include **positive security practices** and areas of improvement to provide a balanced view.

## Common Mistakes

* **Edit the pictures** before importing them in the document:
    * A cropped picture can be `uncropped` inside the Word document
    * Word drawings added on top of the image can be removed, and the image is still present unobfuscated inside the Word archive
    * Most of the time you don't `blur` enough the picture, it is always better to **add a dark/red square** on top of the data you want to obfuscate.

* Unreadable screenshots
    * Keep only the necessary elements in the screenshot
    * Texts in the screenshot should be readable: not too long, not too small
    * Avoid dark mode screenshots: people prints reports
    * Don't use a transparent shell
    * Highlight the important parts of the screenshot: [flameshot-org/flameshot](https://github.com/flameshot-org/flameshot), [greenshot/greenshot](https://github.com/greenshot/greenshot)
    * Include the command string in the screenshot: `./exploit.py argument1 -verbose`
    * Consider narrowing down the shell/browser windows for the screenshot: it will be inserted in "portrait mode" document (PDF).

* Always **distribute a PDF** file to your customer, not a Word, LaTeX or Markdown file
    * Word is an archive file, you can rename it as .zip to explore the content
    * For sensitive files, you might want to **add a password** on the file

* Sending data on a uncontrolled LLM
    * Using a **LOCAL** Large Language Model to help you is fine. For example, you can use `ollama` + `openwebui` + `llama3` model on an on-premise machine disconnected from Internet
    * Never send customer data or sensitive information on ChatGPT, Mistral AI, Gemini, etc, you don't know how the data will be processed and stored.

* Neglecting **Proof of Concepts** (PoCs)
    * Failing to include PoCs or detailed reproduction steps can hinder the remediation process.
    * If the PoC is small, like a `curl` command, add it inside the Reproductions Steps. Otherwise add it to the Appendix and reference it inside the Reproductions Steps.

* Bad writing
    * Typos/Mispellings: use a writing aid
    * Poor grammar
    * Too much jargon
    * Convoluted sentences
    * No clear narrative, the report should tell a story.
    * Avoid emotionally loaded terms: awful, bad, good, etc.
    * Specify and quantify whenever possible, e.g: replace "several" by the amount of affected systems.

* Lists
    * Lists should be sorted alphabetically, numerically, by octet or by domain
    * De-duping your list

## Template Improvement

* Use headings to format the document
* Create and use templates, custom styles:
    * One custom style for inline code: `./myprogram -debug`
    * One custom style for code block, including syntax highlighting and darker background.

        ```java
        // Your First Program
        class HelloWorld {
            public static void main(String[] args) {
                System.out.println("Hello, World!"); 
            }
        }
        ```

## References

* [Best Practices for Writing Quality Vulnerability Reports - Krzysztof Pranczk](https://itnext.io/best-practices-for-writing-quality-vulnerability-reports-119882422a27)
* [Overview of technical writing courses - Google Technical Writing](https://developers.google.com/tech-writing/overview)
* [Part 1 - Things NOT to Do in Pentest Reports: Tips, Tricks, & Traps in Report Writing - Bronwen Aker- Feb 6, 2023](https://youtu.be/eWNqaFf60fg)
* [Part 2 - Things NOT to Do in Pentest Reports: Tips, Tricks, & Traps in Report Writing - Bronwen Aker- Feb 7, 2023](https://www.youtube.com/watch?v=2Op9Q2CY2lA)
* [Part 3 - Things NOT to Do in Pentest Reports: Tips, Tricks, & Traps in Report Writing - Bronwen Aker- Feb 7, 2023](https://www.youtube.com/watch?v=mZom07etvSk)
* [Part 1 - Professional Pentest Reporting - A Model for Clear Communication - Brian (BB) King - May 16, 2023](https://youtu.be/rM-MVSe4MiA)
* [Part 2 - Professional Pentest Reporting - A Model for Clear Communication - Brian (BB) King - May 17, 2023](https://www.youtube.com/watch?v=Uu3pardnHiI)
* [BHIS | Hack for Show, Report For Dough: Part 2 w/ BB King (1-Hour) - Brian (BB) King - Oct 28, 2021](https://youtu.be/bJ4gJVXPAS0)
* [Sort Your Lists - Penetration Test Reporting Tips - Bronwen Aker - Aug 15, 2022](https://br0nw3n.com/2022/08/sort-your-lists-penetration-test-reporting-tips/)
* [Things NOT to Do in Your Pentest Report | Offensive Con 2023 - Bronwen Aker - Aug 17, 2023](https://youtu.be/o2MOuM4JF4U)
