Skip to content
Christopher Maddalena edited this page Jul 29, 2019 · 1 revision



Ghostwriter is a part of your team. It helps you manage clients, projects, reports, and infrastructure in one application. It does not replace some of the more common or traditional project management tools, such as CRMs, but it does consolidate all relevant project information in a way for users to easily curate every aspect of their projects.

Ghostwriter’s key features are:

  • Client Management

    • Ghostwriter tracks clients and related information to provide a hub of knowledge for each client and their related projects.
  • Project Management

    • Projects are created and attached to clients for organization of project tasks, where a record of project tasks can be created and viewed.
  • Infrastructure Tracking and Management

    • Track and manage domain names and servers.
    • Automatically monitor these assets for any problems, such as ports left open to the internet and negative domain category changes.
  • Reporting Engine

    • The reporting engine is capable of outputting reports with information for clients, projects, infrastructure usage, findings, and more.
  • The current reporting formats are JSON and Office docx, xlsx, and pptx documents.

  • Automation

    • Ghostwriter can be extended to run arbitrary tasks in the background, on demand or on schedule. Some tasks include: sending Slack messages via a WebHook, DNS and domain categorization updates, releasing domains and servers when projects end, and archiving reports after projects are closed, all of which are customizable in

Feature Highlights

Ghostwriter is a feature rich application, and as such it would be difficult to detail each feature thoroughly here. Instead, we'll focus on highlights, advantages, and the general workflow Ghostwriter provides.

User Dashboard

To begin, each user has their own account. This is necessary for tracking user actions and assigned project-related tasks. When a user logs in they are presented with an overview of the current state of the user's projects, like which projects they are attached to and notifications related to their active infrastructure (e.g. domains and servers).

Ghostwriter uses Django's built-in support for username and password authentication, but Django can be configured to use LDAP, ADFS, SSO, and other authentication methods.

Client Manager

When new work comes in, users should enroll a new client into the Client Manager application - the Rolodex.

When a user adds a new client they only need to enter a name and a "short name" (an abbreviation that may be used for reporting later). Once the client is created, Ghostwriter will generate and assign a unique codename. The codename is handy for referring to projects in public and can be re-rolled if you do not like the one generated by Ghostwriter.

Users can add points of contact and notes to the new client as required. The client manager may feel like a small piece of Ghostwriter at first; however, it will slowly become a valuable hub of information.

Over time, notes and project history collected on the client page will make it simple to look back at the team's history with that client, review old projects, and see which consultants have worked with the client and in what capacity. Even better, this information lives in the same place as everything else so there is less jumping between data sources.

Project Manager

New projects are created are created and attached to clients when viewing the client's page.. These projects are automatically associated with the client and are categorized by type (e.g. Penetration Test, Web Assessment). Projects also have required start and end dates (which can be edited at any time) with the option for providing a Slack channel name. Providing a Slack channel (either globally or for an individual project) allows GhostWriter to send Slack messages to the designated channel.

The scheduled task that generated the notificationA new project's page is similar to a new client page; it will look barren at first. The first step (optional, but recommended) involves adding a team to this new project. Team members are selected from Ghostwriter's list of users and are assigned project roles (e.g. Assessment Lead, Project Manager). You can, of course, add or edit roles as needed.

Provide a Slack channel (either globally or for an individual project) and Ghostwriter can be configured to send Slack messages to the designated channel via a Slack WebHook. It's easy to add new background tasks to Ghostwriter to perform actions like sending reminders to the project team before the start date or announcing problems with the infrastructure associated with the project (more on that below).

With a client and a project setup it's time to get to work with infrastructure.

Infrastructure Manager

To those who closely followed the Shepherd project, the infrastructure manager may look familiar. I previously released it as a standalone application named Shepherd. Ghostwriter contains a completely rewritten version of Shepherd with all new features and improved functionality.

In brief, Shepherd assists teams with management of domain names and servers before, during, and after operations. The post introducing Shepherd already takes a deep dive into the design and workflow, so please refer to that post for a dose of early Ghostwriter design (circa January 2019) and Shepherd details. The following will be a briefer summary.

On the domain name side of things, Shepherd tracks all available domains with their associated data (e.g. the registrar, purchase date, expiration date, the domain’s age, etc.), and enriches that data with category information collected from sources such as Bluecoat, McAfee, and VirusTotal. The categorization checks can be run upon request or automated and run as background tasks. All domains can be updated at once or one at a time based on the team’s needs. A similar process also exists for updating current DNS records.

If a domain appears in VirusTotal (e.g. malware download hit) or is tagged with a bad category (e.g. Phishing, Suspicious, Scam), Ghostwriter updates the domain's "Health Status" to "Burned." This is a clear indicator to the team that the domain should no longer be used for covert infrastructure. You can request these checks for individual domains or all domains and configure automatic checks on a schedule.

Shepherd also acts as a librarian for your domains. Team members can "checkout" domains for a project which removes the domain from the pool of available domains, attaches the domain to the project and client, and lets everyone see domain is in-use. Shepherd has a background task that will review checked-out domains and send a message to Slack just before a domain is about to be released (one day prior to release by default), followed by a message the day it is released. You can schedule these tasks to fire on any schedule that works best for your team.

The server tracking is the same as the domain tracking with two major differences. First, Ghostwriter tracks open ports. IP addresses tracked in Ghostwriter will be your static IP addresses used for things like Cobalt Strike team servers. These servers should not have ports and services exposed to the whole internet. Instead, the ports used for command-and-control services should be firewalled off with whitelist rules for management ranges and redirector servers coming from the internet. Ghostwriter can help you make sure that is true by running periodic scans against your infrastructure and alert you if an open port is found.

Speaking of redirectors, the second difference is Shepherd tracks two types of servers: your servers with static IP addresses and so-called "transient servers," various cloud-based servers that will come and go throughout the course of a project. You can now quickly create and attach these servers to projects to keep track of their IP addresses, uses, providers, and notes.

If your team uses cloud-based servers for everything you can still use Shepherd. The only change in workflow will be all servers will be tracked as transient servers instead of some being tracked in Ghostwriter's server library.

At the end of a project you may end up with multiple domains, several static servers, and a number of transient servers attached to your project. This history is permanently tracked so you have a living record of which domains and IP addresses have been associated with a client, when, and why.

All of this data is then included in the report to assist you with C2 infrastructure explanations and narratives. This is most useful during reviews with blue teams. Being able to quickly confirm IP addresses, domain names, and when and how they were used is incredibly helpful when reviewing what was/was not detected during an exercise. It also helps with deconfliction requests when you need to confirm if red team traffic matches something the blue team saw during the exercise.

Report Writer

The infrastructure manager is great, but Ghostwriter - as the name implies - really shines when it comes to assisting you with reporting efforts. The reporting engine manages findings, observations, reports for projects, evidence files, and report generation (docx, xlsx, pptx, and JSON).

Everything discussed so far culminates in a wealth of data becoming accessible to the reporting engine. When Ghostwriter creates a report it can call upon everything, including the client's name to the project's execution window, the infrastructure that was used, and the findings.

Report generation begins with adding a report to a project. This allows for multiple separate reports to be created for a project as needed. Then users can browse the findings database and add findings and observations to their current report.

Once a finding has been attached to a report, any edits made to that finding affect only that report. Users can feel free to add evidence and customize findings as they see fit without worrying about affecting any other reports. When it comes to editing, Ghostwriter supports various keywords that can be used for templating.

Keywords are strings inside of curly braces (e.g. {{.bulleted_list}}). Perhaps the most interesting (and coolest) keyword is the one you make yourself on the fly. Users can upload and attach evidence files to findings. Ghostwriter supports images (jpg, jpeg, png) and text (log, ps1, py, txt, md) files and will store the files on the server. This way all other users can see the evidence and collaborate. As part of this upload process the user is asked to provide a "friendly name" and a caption. This friendly name becomes a keyword that can be used inside of a finding.

For example, uploading a BloodHound graph and naming it "Attack Path 1 Graph" will create a new {{.Attack Path 1 Graph}} keyword. Wherever that is used in the finding's text, Ghostwriter will drop in the image along with the caption below it. The same is done for text evidence but it will be dropped in using Ghostwriter's "Code Block" style in the template.

The templates empower users to easily customize the reports without ever touching the code base. Details like font and colors are changed in the styles used in the template.docx/xlsx/pptx files. In this way users can manipulate all of the Office reports without needing to even understand Python. More in-depth changes will require editing code, but we have tried to make that process as simple as possible by putting all report generation functions in one well documented Python file.

For those who want to be able to do something really different, there is the straight JSON output. We have surfaced Ghostwriter's JSON output as a report type so users can take it and use it with other reporting engines or write their own scripts to easily create custom reports. The JSON report includes everything about the client, project, and assessment results.

Once a project is closed, Ghostwriter can clean up the project and its associated reports. If you configure the scheduled task, Ghostwriter will wait some number of days (90 days by default) and then archive the project. This involves generating all report types, gathering all of the evidence files, and compressing everything into a zip file. This archive is moved into a separate archive directory and associated with the client and project in its own database model. This process also deletes the evidence files and report directory so old files don't slowly accumulate on the server.

The archive files can then be downloaded and dealt with per your organization's data retention policies.