Documentation & Reporting
Documentation and Reporting in IT
Strong documentation and reporting skills are important in all areas of IT, not just penetration testing. While technical expertise is valuable, the ability to effectively communicate your findings is equally important.
In penetration testing, the report is often the only part of the assessment the client sees. This report is based on our notes, tool outputs, and logs.
Being thorough and detailed in your notetaking is always beneficial.
Although there's no one-size-fits-all approach to notetaking due to the unique nature of each project, the following structure covers the essential elements and can be tailored to fit your specific needs and workflow:
Attack Path: A clear outline of the entire attack path, supported by screenshots.
Credentials: A centralized location for compromised credentials and secrets.
Findings: Create a subfolder for each finding, including detailed descriptions, evidence such as screenshots, and command outputs.
Service Enumeration & Vulnerability Scan Research: Notes on scanned items and a history of actions taken to avoid redundancy.
Web Application Research: Notes on interesting web application findings, such as subdomains and notable directories.
AD Enumeration Research: Documentation of steps taken and interesting findings related to Active Directory.
OSINT: Tracking of noteworthy OSINT findings.
Administrative Information: Details about points of contact, project managers, rules of engagement, etc.
Scoping Information: All scope-related data, including IP addresses, CIDR ranges, URLs, VPN credentials, etc.
Activity Log: High-level tracking of all assessment activities for potential event correlation.
Payload Log: Records of payloads used, including uploaded files and their hashes for future reference.
There are numerous notetaking applications available, such as CherryTree, Notion, Obsidian, and GitBook.
When choosing a notetaking application, consider whether the data is stored in the cloud or locally. While cloud storage may be suitable for CTFs or practice, it’s recommended to keep data local for actual engagements.
Logging your commands is extremely helpful when creating the report. Tools like Tmux Logging can facilitate this process.
In addition to your commands, document all artifacts such as files and accounts. Record the host’s IP address, timestamp of changes, location of changes, application or service name, and account name. Also, note whether the artifact was cleaned or if the customer needs to handle it.
Evidence
Always include evidence for each finding, such as screenshots and reproduction steps.
Storage
It’s beneficial to organize your project directory to mirror your notetaking structure. For example, using the command:
This creates a structured directory as follows:
When taking screenshots, always redact sensitive information such as credentials or PII. Consider using terminal output instead of screenshots, as this allows for easier redaction, removal of unnecessary information (using
<SNIP>), and highlighting of important details with different styling, like red or bold text.Remember, the client trusts you to protect sensitive information. For instance, if you discover a vulnerability granting access to a directory with sensitive customer data, it’s better to screenshot the directory listing rather than the files themselves.
Types of Reports
While we provided a general notetaking structure earlier, it’s adaptable. The specific format of notes and reports will vary depending on the type of assessment.
For instance, a report for an automated vulnerability scan differs from a penetration testing report, and network penetration testing reports differ from web penetration testing reports.
Retesting reports also require a unique format, focusing solely on verifying previous findings rather than assessing the entire system or new features. Some prefer updating the original report with status tags for each finding (e.g., resolved, unresolved, partial), while others issue a new report with comparison content and an updated executive summary.
Occasionally, we may discover a critical flaw necessitating immediate client notification. In such cases, a draft report may be issued, especially for directly exploitable vulnerabilities exposed to the internet. These notifications should be concise, allowing technical staff to quickly address the issue.
Every element in the report should serve a purpose, avoiding unnecessary information that could overwhelm the reader.
Report Content
Executive Summary
The Executive Summary is a critical component of the report, intended for non-technical stakeholders responsible for budgeting and decision-making. It should be concise and accessible.
Tips for the Executive Summary:
Use specific metrics rather than vague terms (e.g., use exact numbers instead of "multiple").
Keep it brief, ideally less than 1.5-2 pages.
Describe accessed resources in non-technical terms (e.g., "accessed HR documents" instead of "accessed DC").
If feasible, provide a general estimate of the effort required for remediation.
Avoid recommending specific vendors; suggest technologies instead (e.g., "install an EDR" not "install CrowdStrike EDR").
Do not use acronyms or reference technical sections of the report.
Use layman’s terms for technical concepts (e.g., "a protocol for secure remote administration" instead of "VPN" or "SSH").
Summary of Recommendations
Including a Summary of Recommendations or Remediation Summary is advisable. This section should outline short, medium, and long-term recommendations based on the findings and the client’s current environment.
Each recommendation should be linked to a specific finding and should only include actionable items related to the reported findings. For example, if a missing patch is identified, the short-term recommendation is to apply the patch, while the long-term recommendation might involve reviewing and improving patch and vulnerability management processes to prevent recurrence.
The Attack Chain
Sometimes the situation might require detailing the attack chain, such as the steps to gain initial access, move laterally, and compromise the domain. Presentation styles may vary, but an effective approach is to begin with a summary of the attack chain, followed by a step-by-step walkthrough supported by command outputs and screenshots for clarity.
Findings
Following the Executive Summary, the Findings section is paramount, providing the core content of the report. Detailed findings enable technical teams to reproduce and address issues effectively.
Each finding should include:
A description of the finding and the affected platforms.
The potential impact if the finding remains unresolved.
A list of affected systems, networks, environments, or applications.
Recommendations for remediation.
Reference links for further information on the finding and its resolution.
Steps to reproduce the issue, accompanied by collected evidence.
Tips When Writing the Findings
Consider the client’s perspective when presenting information. For web application vulnerabilities, provide payloads or code snippets that can be copied and tested, rather than just screenshots.
Ensure that evidence is irrefutable. For example, to demonstrate cleartext transmission due to basic authentication, include a screenshot of the login prompt with fake credentials and a Wireshark capture showing the cleartext credentials in the authentication request.
Recommendations should be specific and actionable. Avoid vague suggestions like "Reconfigure your registry settings to harden against X." Instead, provide detailed instructions, such as:
"To fully remediate this finding, update the following registry hives with the specified values. Exercise caution and test changes in a controlled environment before widespread implementation.
[List the full paths to the affected registry hives]
Change value X to value Y."
Include external references for each finding, preferring vendor-agnostic sources that are concise and from reputable websites. If possible, contribute your own insights through blogging or other publications.
Appendices
Certain appendices are essential for every report, while others are included based on the assessment’s specifics.
Essential Appendices:
Scope: Details the assessment’s scope, including URLs, network ranges, facilities, etc.
Methodology: Describes the consistent and thorough process followed during the assessment.
Severity Ratings: If not using standard severity scales like CVSS, define the criteria for your severity levels.
Biographies: For PCI compliance assessments, include biographies of the assessment personnel to demonstrate their qualifications.
Dynamic Appendices:
Exploitation Attempts and Payloads: Document your actions to help distinguish between your testing and potential real attacks.
Compromised Credentials: List compromised accounts if numerous, or note if all domain accounts were affected, to guide client remediation.
Configuration Changes: Itemize any changes made to the client’s environment, allowing them to revert changes and mitigate introduced risks.
Additional Affected Scope: For findings affecting numerous hosts, reference an appendix with a comprehensive list, possibly in a table format.
Information Gathering: For external penetration tests, provide data on the client’s external footprint, such as whois data, domain information, subdomains, emails, and accounts from public breach data.
Tips and Tricks
Utilize templates for each assessment type to streamline report creation.
If using Word, consider macros for automation.
Leverage reporting tools like Ghostwriter, Dradis, VECTR, WriteHat, or SysReptor to simplify the process.
Craft your report to tell a story, explaining the significance and impact of findings.
Write the report progressively during the assessment, not just at the end.
Maintain organization by keeping notes and evidence in chronological order.
Provide ample evidence without being overly verbose.
Enhance screenshots with annotations (e.g., using Greenshot) and include explanations as needed.
Redact sensitive information, including passwords, hashes, and client-sensitive data.
Edit tool outputs to remove unprofessional elements (e.g., "Pwn3d!" from CrackMapExec).
Ensure proper grammar, spelling, and consistent formatting; define acronyms upon first use.
Use clear, focused screenshots without extraneous screen elements.
Prefer raw command outputs over screenshots when possible, ensuring console screenshots are opaque and professional.
Implement a quality assurance (QA) process with at least one, preferably two, reviewers. QA should focus on minor corrections rather than major revisions.
Adhere to a style guide for consistency across reports.
Enable autosave in notetaking and word processing tools to prevent data loss.
Automate repetitive tasks where feasible.
Client Communication
At the engagement’s outset, send a start notification email containing:
Tester’s name
Engagement type and scope description
Source IP address for testing (public for external tests, internal for internal tests)
Anticipated testing dates
Primary and secondary contact information (email and phone)
Conclude each testing day with a stop notification, potentially including a high-level summary of findings to prepare the client for the final report.
Maintain open communication throughout the engagement. For example:
If additional external assets are discovered, consult the client about expanding the scope.
Upon finding critical vulnerabilities, pause testing and notify the client for guidance.
Be transparent about any issues, such as unresponsive hosts.
You should be able to provide precise documentation of your activities if questioned.
Report Review Meeting
After delivering the report, allow the client time to review it (typically a week) and schedule a meeting to discuss findings, answer questions, and gather feedback.
Last updated