# 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

* 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.

* **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

* 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.


## 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)