Introducing Ghostwriter
For the past year the SpecterOps team has been working on a problem: project management. It is not the most glamorous topic; however, it is essential to smooth business operations and ensuring quality deliverables. Starting a project plan without the requisite information or resource management is like rushing into a home improvement project without a design plan. You may have built that porch you’ve always wanted, but it’s also likely you had a shortage of materials, made several additional trips to hardware stores, and cut a few boards too short in the process.
SpecterOps is excited to publicly release the product of our research and development efforts:
Ghostwriter is a part of our team. It helps us 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 is available now on GitHub:
By turning a critical eye to each piece of our workflow we continuously identified opportunities to “grease the wheels” and make adjustments to our project management. We wanted a solution that would be easy to learn, use, and — most importantly — be a complete platform we actually wanted to use.
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 tasks.py.
Speaking of automation, the entire platform can be deployed with a single Docker command for local development/debugging and production use.
Read on for a closer look at these features and the decision process behind their design and creation.
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 their projects, like which projects they are attached to and notifications related to their active infrastructure (e.g. domains and servers).
Ghostwriter uses django-allauth for authentication. The default authentication method is a username and password, but you can enable SSO with a wide variety of services, including many your team may already be using (e.g. GitHub, Bitbucket, Box, Slack, Trello). Django can also be configured to use LDAP, ADFS, 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 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 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.
A new project’s page 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.
You can also provide a Slack channel for the project. 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. Ghostwriter contains a completely rewritten version of Shepherd with all new features and improved functionality.
In brief, Shepherd assists teams with the 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 as scheduled 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 domain name 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 shows everyone the 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 similar to the domain tracking. IP addresses tracked in Ghostwriter will be your static IP addresses used for things like Cobalt Strike and Covenant 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 Ghostwritre’s infrastructure manager. 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 from 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 and .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 (default is 90 days) 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.
Wrap Up
We are excited to finally discuss this project publicly and we hope other teams will find it useful. Project management and report writing does not have to be a slog! Ghostwriter can’t make you enjoy writing reports, but it can round the sharp edges and remove some friction to make report writing a more enjoyable experience.
It was a long road to define the features required for a 1.0 release; however, this is not the end! Ghostwriter will be under active development for the foreseeable future. Some features we have planned include:
- Management and generation of Alerting and Detection Strategies documents
- Full activity log tracking with timestamps, output, and evidence tracking for offensive engagements
- Addition of other reporting formats, such as PDF, and more direct editing within Ghostwriter to support those formats
- Enhanced report editing capabilities for building more pieces of a report within Ghostwriter
If you’ll be at Black Hat 2019, come by Arsenal Station 6 onWednesday, August 7 between 2:30pm-3:50pm to see demos and talk Ghostwriter!
