Ghostwriter v4.2

Ghostwriter v4.2: Project Documents & Reporting Enhancements

After April’s massive Ghostwriter v4.1 release, we received some great feedback and ideas. We got a little carried away working on these and created a release so big we had to call it v4.2. This release contains some fantastic changes and additions to the features introduced in April’s release. Let’s get to the highlights!

Improving Customizable Fields

Ghostwriter v4.1 introduced custom fields, and seeing the community use them so creatively was awesome. What we saw gave us some ideas for a few big improvements.

The rich text fields support the Jinja2 templating language, so loops quickly became a talking point. Looping over project objectives, findings, hosts, and other things to create dynamic lists, table rows, or sections is incredibly powerful, so we had to do it.

You can now use Jinja2-style expressions with the new li, tr, and p tags to create list items, table rows, and text sections. Here is an example of building a dynamic list inside Ghostwriter’s WYSIWYG editor.

Jinja2-style Loop in the WYSIWYG Editor

This screenshot includes examples of a few notable features. We’re using the new li tag with a for loop to create a bulleted list of findings. We have access to Jinja2 filters, including Ghostwriter’s custom filters, so we use the filter_severity filter to limit the loop to findings with a severity rating matching critical, high, or medium. The first and last bullets won’t be in the list in the final Word document.

The middle bullet will repeat for each finding to create our list. It includes the title and severity and uses the regex_search filter to pull the first sentence of the finding’s description. The use of severity_rt here is also worth a call-out. Some community members asked about nesting rich text fields inside of other rich text fields, like the pre-formatted severity_rt text for a finding. Not only can we use severity_rt inside this field, but we can also add formatting, like changing the text to bold.

Here is the above list rendered in a Word document. The pre-formatted finding.severity_rt appears with the proper color formatting and the bold formatting added in the WYSIWYG editor.

Output of the Jinja2 Loop in Microsoft Word

These additions introduced some complexity. A typo or syntax mistake could break the Jinja2 templating and prevent a report from generating, and the resulting error message wasn’t always helpful for tracking down the offending line of text. To help with this, Ghostwriter v4.2 validates your Jinja2 when you save your work, so you don’t need to worry about accidentally saving any invalid Jinja2 and causing a headache later on.

Validating the Jinja2 didn’t cover every possible issue, though. Even valid Jinja2 can fail to render if the report data causes an error (e.g., trying to divide by zero or referencing a non-existent value). To help with that, we significantly improved error handling to catch Jinja2 syntax and template errors at render time and surface more helpful information about them. When content prevents a report from generating, error messages point to the report’s section containing the problem.

In this example, a field called exec_summ contains this Jinja2 statement: {{ 100/0 }}. That’s valid Jinja2, but you can’t actually divide by zero, so rendering will always fail. With Ghostwriter v4.2’s error handling enhancements, the error message will direct us to the field name and include information we can use to track down the problem.

New Explicit Error Message for a Failed Report

More Reporting Improvements

Ghostwriter v4.2 also includes enhancements to the reporting engine. The most significant change is the introduction of project documents. You don’t always need to generate a full report with findings. You may need to generate other project-related documents before or after the assessment is done, like rules of engagement, statement of work, or attestation of testing documents. You could technically do this with older versions of Ghostwriter by generating a report with a different template, but that was not intuitive.

The project dashboard’s Reports tab is now called Reporting and contains an option to generate JSON, docx, or pptx reports with your project’s data. This works like the reports you’re familiar with but uses only the project data (e.g., no findings or report-specific values).

New Project Document Generation Under the Project Dashboard

We wanted to make it easier to generate project documents like this because custom fields open up many possibilities. For example, at SpecterOps, we provide clients with daily status reports after each day of testing. We can accomplish this task with a Daily Status Report field added to projects and the new project reporting feature. Consultants can now easily collaborate on updates to the daily status and then generate their daily status document from the same dashboard.

That’s not all, though. We realized one globally configured report filename would never apply to every possible document or report you might want to generate, so we made some changes. The biggest change is that your filename can now be configured using Jinja2-style templating with access to your project data, familiar filters, and a few additional values (e.g., `now` to include the current date and time). That means you can configure a filename like this that dynamically includes information about your project, client, and more:

{{now|format_datetime(“Y-m-d”)}} {{company_name}} — {{}} {{project.project_type}} Report

That template would produce a filename like 2024–06–05 Acme Corp — SpecterOps Red Team Report.docx. That’s great for a default, but you’d probably be renaming documents often as you expanded the types of documents generated with Ghostwriter. To help with that, we made it possible to configure separate global defaults for reports and project documents.

Jinja2 Templating for Default Filenames for Report Downloads

We also added the option to override the filename per template! To revisit the daily status report example, your Word template for such a report can override the global filename template with a filename template like {{now|format_datetime(“Y-m-d”)}} {{company_name}} Daily Status Report.

Another enhancement for this feature is a third template type, Project DOCX. You can use this to flag Microsoft Word templates that are intended only for project documents. Templates flagged with this type will only appear in the dropdown menu on the project dashboard. This will keep them out of the list of templates for your reports.

Finally, Ghostwriter v4.2 also includes a feature proposed by community member Dominic Whewell, support for templating the document properties in your Word templates. If you set values like the document title, author(s), and company, you can now do that in your templates and let Ghostwriter fill in that information for you.

Jinja2 Templating in Document Properties

Background Tasks with Cron

Ghostwriter v4.2 also contains various bug fixes and quality-of-life improvements. There are too many details here, but one worth mentioning is support for cron expressions with scheduled background tasks. Previously, you could schedule tasks to run at certain time intervals, but you couldn’t control some of the finer points, like the day of the week.

You can now use cron to schedule a task on a more refined schedule, like only on a specific day of the week or weekdays. When scheduling a task, select Cron for the Schedule Type and provide a cron expression–e.g., 00 12 * * 1–5 to run the task every weekday at 12:00.

Using Cron to Schedule a Background Task

Check out the full CHANGELOG for all the details on this release.

Release Ghostwriter v4.2.0 · GhostManager/Ghostwriter

Ghostwriter v4.2 was originally published in Posts By SpecterOps Team Members on Medium, where people are continuing the conversation by highlighting and responding to this story.

Article Link: Ghostwriter v4.2: Project Documents & Reporting Enhancements | by Christopher Maddalena | Jun, 2024 | Posts By SpecterOps Team Members