WriteHat (Tool)

WriteHat is a reporting tool which removes Microsoft Word (and many hours of suffering) from the reporting process. Markdown –> HTML –> PDF.

Introducting WriteHat, a reporting tool written by pentesters, for pentesters.

Table of Contents:

  1. Purpose
  2. Features
  3. Terminology
  4. Extensible, Open Source
  5. Roadmap
  6. Demos

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


Here at Black Lantern, 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. Black Lantern is releasing it to the public so that others may be freed from the chains of Microsoft Word.


  • 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


WriteHat contains common terminology Black Lantern uses internally and is outlined below.


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


  • A Report is a modular, hierachical 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.


  • 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/)
  • A HTML Template (/writehat/templates/componentTemplates/)
  • CSS file (/writehat/static/css/component/) (Optional)

Refer to the Github Readme page for more information on writing custom components!


Black Lantern has a roadmap with features we are working on. Currently, the short list contains the following:

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

Black Lantern loves feedback and actively looks for Pull Requests!

You can deploy WriteHat today with a one liner (git clone https://github.com/blacklanternsecurity/writehat && cd writehat && docker-compose up) or view the Github page for a comprehensive production deployment!

View the github page to start writing reports!


Creating a new engagement and adding a templated finding:

Creating a new report for an engagement:

Creating a new report using a template report:

Creating a customer, adding a proactive findings group:

Happy Report Writing!

© 2020 | All rights reserved | 1834 Summerville Avenue | Suite 250 | North Charleston, SC | 29405 | 843.991.4612