WriteHat

A Reporting Tool Written by Pentesters, for Pentesters

WriteHat is a reporting tool geared toward removing Microsoft Word from the reporting chain. WriteHat strives to use simple, streamlined writing of reports focused on Markdown -> HTML -> PDF export. The reporting tool uses Django (Python) and Markdown to accomplish elegant components to present beautiful reports for penetration/red/blue/purple team engagements. WriteHat is only limited by your imagination, by supporting extensible components and templates.

Purpose

Here at Black Lantern Security (BLS), we’ve experienced the pain of having to pass around multiple document versions which end up with a variety of edits and version numbering schemes (e.g., v001, v005, v006_FINAL, v009_REAL_FINAL, etc.). WriteHat strives to be a reporting tool geared towards a collaborative and central platform for all your engagement writing needs. Currently WriteHat is in beta, with our internal team using it for over a year. BLS is releasing it to the public so that others may be freed from the chains of Microsoft Word.

Features

• Effortlessly generate beautiful pentest reports

• On-the-fly drag-and-drop report builder

• Markdown support - including code blocks, tables, etc.

• Crop, annotate, caption, and upload images

• Customizable report background / footer

• Assign operators and track statuses for individual report sections

• Ability to clone and template reports

• Findings database

• Supports multiple scoring types (CVSS 3.1, DREAD)

• Can easily generate multiple reports from the same set of findings

• Extensible design enables power users to craft highly-customized report sections

• LDAP integration

Terminology

WriteHat contains common terminology BLS uses internally and is outlined below.

Engagements

• An Engagement is where content is created for a customer. This is the overarching container that will hold Reports and findings.

Report

• A Report is a modular, hierarchical arrangement of Components which can be easily updated via a drag-and-drop interface, which is then rendered into HTML/PDF. An Engagement can have multiple Reports. Page Templates can be used to customize the background and footer of your Reports. Reports can also be based off (or converted into) a Report Template.

Component

• A Component is a section or module of the report that can be dragged/dropped into place inside the Report creator. Examples of Components are: Title Page, Markdown, Findings, etc. These are built-in Components, but users can create their own custom components. Custom components are comprised of HTML/CSS and Python.

Report Template

• A Report Template is a starting point for a Report. They are a saved compilation of Components in a Report to give report authors a head start to writing their content.

Page Template

• A Page Template lets a company/author customize report background images and footers. You can set a global default Page Template. This default can be overridden at the Engagement/Report level.

Extensible, Open Source

Content creators can write custom components to their liking using the extensible project. A custom component is composed of three elements:

• Python Code

  /writehat/components/

• HTML Template

  /writehat/templates/componentTemplates/

• Optional: CSS file

  /writehat/static/css/component/

Refer to the GitHub README.md page for more information on writing custom components.

Roadmap

BLS has a roadmap with features we are working on. Currently, the short list contains the following in-progress features:

• Change tracking and revisions

• More in-depth review/feedback functionality

• Collaborative multi-user editing similar to Google Docs

• JSON export feature

• Presentation slide generation

• More advanced table creator with CSV upload feature

• More granular permissions / ACLs (beyond just user + admin roles)

BLS love feedback and actively looks for Pull Requests.

You can deploy WriteHat now with a one liner:

git clone https://github.com/blacklanternsecurity/writehat && cd writehat && docker-compose up

View the GitHub page for a comprehensive production deployment, or to start writing reports using WriteHat!

Demos

Creating a New Engagement and Adding a Templated Finding

Creating a New Report from an Engagement

Creating a New Report Using a Template Report

Creating a Customer, Adding a Proactive Findings Group

Happy Report Writing!