A Hacker's Guide to Documentation

You’ve just finished a penetration test, identified vulnerabilities, and uncovered risks. If you do not document the findings clearly, the work may not lead to meaningful security improvements. A well-written penetration-testing report turns technical discoveries into actionable insights for the client.

This guide covers how to write a report that is clear, professional, and useful to its readers.

Why the penetration-testing report matters

A strong report:

• Translates technical findings into business risks for executives and IT teams.
• Provides a remediation roadmap and helps organizations prioritize fixes.
• Serves as a record of the assessment and the organization’s due diligence.
• Demonstrates the quality and care of the assessment.

A poor report can undermine even a thorough penetration test. The goal is to make the findings understandable and actionable.

Key components of a penetration-testing report

A well-structured report typically includes the following sections.

1. Executive summary (for non-technical stakeholders)

The executive summary gives decision-makers a high-level overview without unnecessary technical detail. Include:

• Objective: Why the test was conducted, such as compliance, risk assessment, or a pre-deployment review.
• Scope: The systems tested and the types of assessment performed.
• Overall risk posture: A concise summary of the security state observed.
• Key findings: The most significant issues and their potential impact.
• Recommendations: Broad next steps, such as patching or improving security policies.

Tip: Use clear language, avoid unexplained acronyms, and leave deep technical details for the findings section.

2. Technical summary (for IT and security teams)

This section provides a concise, technical overview for the teams responsible for remediation. Include:

• Testing methodology: The tools and approach used, such as black-box, gray-box, or white-box testing.
• Vulnerability statistics: Counts by severity, when useful and supported by the assessment.
• Attack-path analysis: How findings could be chained to reach a larger impact.

3. Detailed findings

This is the core of the report. Document each vulnerability with enough evidence and context for the client to reproduce, understand, and remediate it.

For each finding, include:

• Vulnerability title: A concise description, such as “SQL Injection in Login Form.”
• Risk rating: Critical, High, Medium, or Low; use CVSS when applicable and explain relevant assumptions.
• Affected system or URL: Where the issue exists, while respecting any restrictions on sensitive data.
• Description: What the vulnerability is and why it matters.
• Proof of concept: Safe, reproducible steps, with screenshots, sanitized code snippets, or proxy logs where helpful.
• Impact: What an attacker could achieve, such as unauthorized data access or system compromise.
• Remediation steps: Specific actions, such as a patch, configuration change, or code review.

Tips:

• Use screenshots or network diagrams to clarify complex issues.
• Prioritize findings so the most serious risks are easy to identify.
• Sanitize secrets, personal information, and unrelated customer data from evidence.
• Keep proof-of-concept steps within the approved scope and avoid unnecessary destructive actions.

4. Conclusion and recommendations

Summarize the overall security posture and provide prioritized recommendations. For example, a conclusion could note that external systems showed strong defenses while internal services still exposed a privilege-escalation risk.

Include:

• Overall assessment: The main themes and risks observed during testing.
• Strategic recommendations: Longer-term improvements, such as regular patch management or security training.
• Next steps: Practical milestones, such as retesting after remediation.

5. Appendices (optional but useful)

Appendices can provide supporting detail without interrupting the main report. Consider including:

• Full scan outputs, such as Nmap, Nessus, or Burp logs, where appropriate.
• A list of tools used.
• A glossary defining terms for less technical readers.

References

• Penetration Test Reports
• OffSec PWK Example Report (PDF)

---

Originally published on Medium.