Pentest Report Generator

Automating the Creation of Pentest Reports using GitHub Actions

Writing detailed and consistent reports is important for effective penetration testing. Pentest reports not only document the vulnerabilities discovered during an assessment but also provide critical information for clients to address and mitigate identified risks. However, the process of creating and maintaining these reports can be challenging, especially when multiple team members are involved and when reports have to follow a consistent structure.

Consistent and Collaborative Reporting

For penetration testers, maintaining high-quality documentation throughout an engagement is crucial. It’s not just about discovering vulnerabilities; it’s about clearly communicating those findings in a way that clients can understand and act upon. This process becomes even more complex when multiple testers are working on the same project. Ensuring that the final report is consistent, and well-structured requires coordination and an effective workflow. The structure of the report template is inspired by Hack The Box’s report template: https://www.hackthebox.com/blog/penetration-testing-reports-template-and-guide

A GitHub-Based Penetration Testing Report Template

To address these challenges, I developed a solution that leverages the power of version control systems like Git, combined with the simplicity and flexibility of Markdown for documenting findings. The result is a GitHub repository that can be used as a template for creating pentest reports. This approach provides some benefits:

1. Version Control for Documentation: By using Git, all changes to the report are tracked, providing a clear history of what was changed, when, and by whom. This is useful for collaborative projects, as it allows team members to review each other’s contributions and roll back changes if necessary.

2. Consistent Structure Across Reports: The template ensures that all reports follow the same structure and layout, regardless of who is creating the report. This consistency is important for maintaining a professional appearance and making it easier for clients to navigate the report.

3. Easy Collaboration: With the repository set up as a GitHub template, multiple team members can work on their sections of the report simultaneously. Each tester can document their findings in individual Markdown files within the findings folder, without worrying about conflicts or inconsistencies in the final document.

4. Automated Report Generation: To simplify the process of compiling the final report, I integrated GitHub Actions to automatically generate the report. When a penetration test is completed, testers can trigger the action, which pulls together all the individual Markdown files, applies the standard structure, and produces a polished report ready for delivery to the client.

5. Ticket Creation for Findings: In addition to generating the report, another GitHub Action can be used to create tickets for each finding in a system like Jira. This integration ensures that the findings are not just documented, but also tracked and managed effectively, facilitating the remediation process.

How It Works:

1. Clone the Repository: Start by cloning the GitHub repository and adjust the templates within the BUILD folder once and never touch them again, except for when you want to change your report template. Afterward you can setup the repository within your GitHub organization as a reusable template. This ensures that your report will follow the established structure and format.

2. Use the Template and adjust config file: Use the template for each penetration test you want to perform. Make sure to adjust the pentest_config.yamlfile fear each test.

3. Document Findings: Each penetration tester on the team documents their findings in individual Markdown files within the findings folder. This decentralized approach allows testers to focus on their work without stepping on each other’s toes. Each finding should be documented within a seperate folder. Folders that start with the word example will be ignored.

4. Generate the Report: Once all findings have been documented, a GitHub Action can be triggered to compile the report. This action automatically collects all Markdown files, applies the standard formatting, and produces a complete report.

5. Create Tickets: If desired, a separate GitHub Action can be used to create tickets in Jira (or a similar system) for each finding, ensuring that all issues are tracked and addressed.

File structure of this template

Template/
├── BUILD/  # Do not touch, except for adjusting templates or ticket creation script
│   ├── TEMPLATES/  # Contains text templates
│   │   ├── approach.md
│   │   ├── executive_summary.md
│   │   ├── remediation_summary.md
│   │   ├── REPORT.md  # Main report template
│   │   └── statement_of_confidentiality.md
│   ├── create_tickets.py  # Dummy script for creating tickets for each findings
│   ├── generate_report.py  # Script for creating the final markdown report
│   ├── requirements.txt
│   └── style.css  # Stylesheet for HTML report
├── Report/  # Here 
│   ├── Appendices/  # Here pentesters can store their appendices (one folder per appendice)
│   │   └── Finding Severities/
│   │       └── appendice.md
│   ├── Findings/  # Here pentesters document their findings (one folder per finding)
│   │   ├── example bac/
│   │   │   ├── finding.md
│   │   │   └── finding.yaml
│   │   ├── example sqli/
│   │   │   ├── finding.md
│   │   │   └── finding.yaml
│   │   └── example xss/
│   │       ├── finding.md
│   │       └── finding.yaml
│   └── Output/  # Here you can find the final report, after generating
│       └── output.md
└── pentest_config.yaml  # Individual settings and metadata for each pentest needs to be configured here

Conclusion

By combining the advantages of Git for version control with the simplicity of Markdown and the automation capabilities of GitHub Actions, this solution provides an efficient way to create penetration testing reports. It improves collaboration, ensures consistency, and simplifies the process of generating reports. This approach not only saves time but also improves the quality and reliability of the documentation, ultimately helping penetration testers deliver more value to their clients.

Whether you’re working on a solo project or collaborating with a team, this GitHub-driven workflow can help you manage your penetration testing reports more effectively and with greater confidence.

Built with:

Python

HTML

CSS

markdown

git