writehat: pentest reporting tool written in Python


WriteHat is a pentest reporting tool that removes Microsoft Word (and many hours of suffering) from the reporting process. Markdown –> HTML –> PDF. Created by penetration testers, for penetration testers – but can be used to generate any kind of report. Written in Django (Python 3).


  • 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



Here are basic explanations for some WriteHat terms which may not be obvious.


├─ Customer
├─ Finding Group 1
│ ├─ Finding
│ └─ Finding
├─ Finding Group 2
│ ├─ Finding
│ └─ Finding
├─ Report 1
└─ Report 2
└─ Page Template



An Engagement is where content is created for the customer. This is where the work happens – creating reports and entering findings.


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

Report Component

A report Component is a section or module of the report that can be dragged/dropped into place inside the report creator. Examples include “Title Page”, “Markdown”, “Findings”, etc. There are plenty of built-in components, but you can make your own as well. (They’re just HTML/CSS + Python, so it’s pretty easy. See the guide below)

Report Template

Report Template can be used as a starting point for a Report (in an Engagement). Reports can also be converted to Report Templates.

Finding Group

Finding Group is a collection of findings that are scored in the same way (e.g. CVSS or DREAD). You can create multiple finding groups per engagement (e.g. “Technical Findings” and “Treasury Findings”). When inserting the findings into the Report (via the “Findings” Component, for example), you need to select which Finding Group you want to populate that Component.

Page Template

Page Template lets you customize report background images and footers. You can set one Page Template as the default, and it will be applied globally unless overridden at the Engagement or Report level.

Writing Custom Report Components

Each report component is made up of the following:

  1. A Python file in writehat/components/
  2. An HTML template in writehat/templates/componentTemplates/
  3. A CSS file in writehat/static/css/component/ (optional)

We recommend referencing the existing files in these directories; they work well as starting points/examples.


Copyright (C) 2020 blacklanternsecurity