Customizing Reports

Customizing how your Office reports are formatted

Customizing Report Formatting

The Word and PowerPoint reports are easily customized by editing template documents to change fonts, colors, and table styles.

Some modifications will require editing code within ghostwriter/modules/reportwriter.py.

Customizing Templates

The templates live in ghostwriter/reporting/templates/reports. There are templates for the Word and PowerPoint report formats. Customize the formatting by opening the template files in Microsoft Office and editing the styles.

Customizing Word Reports

Ghostwriter uses a template.docx file as its default bae template for the Word reports. The example template includes samples that show how you can customize the template to dynamically replace words and build tables. The template uses Jinja2 template language (https://jinja.palletsprojects.com/en/2.11.x/).

Table Built Dynamically at Report Generation

The generate_word_docx function in reportwriter.py creates a "context" dictionary that is passed to the template. The entries in this dictionary directly correspond to the variables use din the report template. New variables are easily added and the list of default options will continue to grow. The list of currently available variables is below.

Variable

Description

client

Project client's full name

client_short

Project client's "short" name as defined in the client record

client_pocs

List of client points of contacts associated with the client in Ghostwriter

assessment_name

Name configured for the project

project_type

Type of project (e.g., penetration test, red team)

company

Company name configured in .envs file

company_pocs

Company points of contact / operators assigned to the project

domains

All domains checked-out and used for the project

static_servers

All "static" servers checked-out and used for the project

cloud_servers

All cloud servers used for the project

domains_and_servers

All defined domain:server associations (DNS)

findings

All findings associated with the report

findings_subdoc

A "subdocument" containing all findings

The variables retain all formatting applied to them in the template. In the above example, the {{ assessment_name }} variable would be replaced by the project's name and have the Heading 1 style applied.

This holds true for tables and other items in the report as well. In the Table 1 example, the middle row represents what each row of the dynamic table will look like. The person's name will be left aligned while their job title and email address are centered, just like the variables are in the template.

Variables can be placed in the template by surrounding the variable name in curly braces, e.g. {{ client }}. Creating tables and other objects requires slightly more work and it can be confusing at first. Reference the Jinja2 documentation and the example template.docx to build your perfect report template.

You can supply a complete report template and use the Jinja2 template language to dynamically replace words, build tables, or whole sections of your report. The rest of your template will remain untouched.

If you have a standard template, bring that content over to the Ghostwriter template and experiment.

Subdocuments

Subdocuments are like other other variables except they are pre-rendered Word documents. For example, Ghostwriter builds the findings section and passes that to the main template a the findings_subdoc variable. When a subdocument is inserted into the template, it is like copy/pasting content from one document into another. A subdocument can be a small paragraph or much larger sections.

For the findings section, Ghostwriter's template starts a new page with a page break and then inserts the subdocument.

Findings Subdocument in the Template

Subdocuments are referenced as {{p VARIABLE }}.That variable is automatically replaced with the contents of the subdocument.

Customizing Word Styles

Ghostwriter uses Word's Header, Normal, Table, and Caption styles in the template.docx. There are also several custom styles:

  • CodeBlock: Used for formatting blocks of code, terminal output, and other text evidence.

  • Code (Inline): Used for code, one-liners, and other special text inline with other text, i.e. mid-sentence.

  • Ghostwriter Table: The default style used for all tables.

To make changes to Ghostwriter Table you do need to insert a new table to access the list of styles in the ribbon.

Open template.docx and edit the styles by right-clicking the style in the ribbon and choosing the Modify option. Make the desired changes and then save the style.

Save the template! If you do not save the template, the updated style will not be saved.

Customizing PowerPoint Reports

PowerPoint styles are controlled by the slide masters. Open the template.pptx, click the View tab, and then click Slide Master.

Adjust the slide masters as desired and then save the template.

Customizing the Code

In the current version of Ghostwriter, each Office document is built from scratch for more fine grained control. If you wish to rearrange the placement of text or change how text is displayed you will need to review and edit the generate_* functions:

  • generate_word_docx()

  • generate_excel_xlsx()

  • generate_powerpoint_pptx()

Major edits will require a careful review of the code and accompanying comments; however, simpler edits, like changing colors for finding severity, can be tweaked relatively easily.

Tweaking Colors

You may want to change the colors or hues of the severity ratings and picture borders. Open ghostwriter/modules/reportwriter.py and look at the top of the Reportwriter() class.

Finding Severity Colors
# Color codes used for finding severity
# Blue
informational_color = '8eaadb'
informational_color_hex = [0x83, 0xaa, 0xdb]
# Green
low_color = 'a8d08d'
low_color_hex = [0xa8, 0xd0, 0x8d]
# Orange
medium_color = 'f4b083'
medium_color_hex = [0xf4, 0xb0, 0x83]
# Red
high_color = 'ff7e79'
high_color_hex = [0xff, 0x7e, 0x79]
# Purple
critical_color = '966FD6'
critical_color_hex = [0x96, 0x6f, 0xd6]
# Picture border color
border_color = '2d2b6b'
border_color_hex = [0x45, 0x43, 0x107]
# Picture border weight – 12700 is equal to the 1pt weight in Word
border_weight = '12700'

The different report formats all require the colors to be represented in their hex form. You need to set both a string value and a list value.

The *_color variable must be a string value like 8eaabd (hex without any 0x prefixes).

The *_color_hex variable must be a string value like [0x83, 0xaa, 0xdb] (with the 0x prefixes).