# GHOSTS and the case for simulating users instead of scripting them

> GHOSTS is a CMU Software Engineering Institute framework that orchestrates non-player characters on real machines to generate human-like traffic, artifacts and activity for cyber training, exercises and research. Its realism comes from personas and timelines rather than from attack payloads, and its cost is a stack with a database, a dashboard and three client flavours.

**cmu-sei/GHOSTS** — GHOSTS (General Human-Oriented Synthetic Teammates and Systems) is a realistic user simulation framework for cyber experimentation, simulation, training, and exercise

- Repository: https://github.com/cmu-sei/GHOSTS
- Website: https://cmu-sei.github.io/GHOSTS/
- Stars: 733 · Forks: 100
- Language: C#
- License: NOASSERTION
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/cmu-sei-ghosts

## The unit of simulation is a person, not a script

GHOSTS stands for General Human-Oriented Synthetic Teammates and Systems, and the framework describes itself as a realistic user simulation platform for cyber experimentation, simulation, training and exercise. Its subject is not traffic. It is people.

The overview calls it an NPC orchestration framework that models and simulates realistic users on all types of computer systems, generating human-like activity across applications, networks and workflows. Where a load generator replays recorded HTTP requests, GHOSTS drives real client software through a timeline of activities, which is what makes the resulting traffic and artifacts useful for training a detection analyst or a SOC.

The claim goes further than replay. The framework can dynamically reason, chat and create content through integrated LLMs, which is meant to produce adaptive, context-aware behaviour rather than a fixed script. That is the interesting design bet, and also the part a defender should treat with care, since the same reasoning and content generation could produce artifacts that look authored.

The output is described as realistic network traffic, support for complex multi-agent scenarios, and realistic artifacts left behind on the machine.

## Personas and timelines are the two models the whole system runs on

The supporting services section names the two pieces that make behaviour non-trivial, and they are separate components rather than fields on a machine record.

Ghosts.Animator is the NPC persona generation engine, described as producing names, careers, social networks and beliefs. Ghosts.Pandora is a dynamic content generation server for realistic web content, blog posts and documents. Between them, a simulated user has an identity with a plausible history and a reason to produce content that fits it.

The other half is the timeline. The API component handles NPC orchestration and scenario management, the frontend manages machines, groups, timelines, NPCs, scenarios and workflow automation, and Grafana provides real-time dashboards for NPC activity, health metrics and timeline execution. So a run is a set of timelines executed against a set of personas, and the dashboards exist to let an operator watch whether that is happening the way it was planned.

Ghosts.Domain is the shared library that carries the timeline models, handler base classes and client configuration, and it is what keeps the timeline concept consistent across the API, the clients and the console.

## Three client flavours for three different machines

The client side is where a simulation actually touches hardware, and GHOSTS ships three versions with a clear division of purpose.

Ghosts.Client.Windows is the full-featured one, built on .NET Framework 4.6.2, with Office automation, browser control, SSH, RDP and 27 or more activity handlers. Ghosts.Client.Universal is the cross-platform build for Linux and Windows on .NET 9, with 38 or more handlers. Ghosts.Client.Lite is the lightweight .NET 8 build for resource-constrained environments.

The handler count is the meaningful number. An activity handler is the unit of behaviour, so a client with 38 handlers can do more kinds of things on a Linux box than the Windows client manages to do with 27, because the two have different capabilities underneath. This is also why the framework is not limited to browsers: Office automation on the Windows client is what allows a simulated user to create and edit documents that leave artifacts behind.

Installation is per machine. You install a client on each machine you want to simulate and point it at the API host on port 5000, so the scale of a scenario is bounded by how many machines you are willing to enrol.

## Standing up the stack with Docker Compose

There are two supported ways to run GHOSTS, and the guide is explicit about which is for whom. The Dev Container is for contributors who want to build and debug the source, and standard Docker Compose is for standing up the published stack quickly.

The Compose route needs nothing but Docker. You fetch the compose file and start it:

```bash
mkdir ghosts && cd ghosts
curl -O https://raw.githubusercontent.com/cmu-sei/GHOSTS/master/src/Ghosts.Api/docker-compose.yml
docker compose up -d
```

One setup step is mandatory. You copy .env.example to .env and set POSTGRES_PASSWORD before starting, and the guide points at src/Ghosts.Api/.env.example for the full list of variables. Skipping that step is the most common way a first run fails, because the database container has no password to work with.

The published services and their ports are laid out in a table in the guide: the Angular management UI on port 4200, the REST API on port 5000 with Swagger at /swagger, Grafana on port 3000 for activity dashboards, n8n on port 5678 for workflow automation, and PostgreSQL on port 5432.

For the source-building path there is also a .NET Aspire application host, which orchestrates locally without Compose:

```bash
   cd src/apphost
   dotnet run
```

Under Aspire the frontend moves to port 4222, which is worth knowing before you paste a URL from a colleague's setup.

## The Dev Container bundles the whole toolchain

For contributors, the repository ships a fully configured Dev Container with the .NET 10 SDK, Node.js, Python and Docker-in-Docker preinstalled, so you can build and run every component without setting up a local toolchain. The prerequisites are Docker and VS Code with the Dev Containers extension, or any editor that supports the Dev Container spec.

The clone and open step is short:

```bash
   git clone https://github.com/cmu-sei/GHOSTS.git
   cd GHOSTS
   code .
```

You then choose Reopen in Container, and the first build takes a few minutes while the image and features are provisioned. Once the container is ready you open a terminal and start the stack, and because Docker-in-Docker is enabled the same Compose stack runs from inside the container:

```bash
   cd src/Ghosts.Api
   cp .env.example .env   # set POSTGRES_PASSWORD
   docker compose up -d
```

That last point is the reason for the DinD setup. The services are published on the same ports as the plain Compose route and are forwarded to your host automatically, so a developer running inside the container reaches the same URLs as everyone else, with no port remapping in the middle.

The repository also ships a .devcontainer directory at the top level, along with an .aspire directory and an aspire.config.json for the Aspire path.

## n8n and SignalR are how the framework stays alive during a scenario

Two integration points are worth understanding before you design an exercise.

The API is described as a central command-and-control server with a REST API, a SignalR WebSocket hub, NPC orchestration and scenario management. The SignalR hub is what keeps a running exercise live, since a long scenario needs push updates rather than polling, and the frontend consumes it to show machine, group and timeline state.

n8n is the workflow automation platform, and the guide notes that the GHOSTS API can schedule and trigger n8n workflows via webhook. That is the extension seam for an exercise: an operator can wire an external tool to react to what happens in the simulation without touching C# code.

The remaining supporting service is Grafana, running as a Docker container, for real-time dashboards of NPC activity, health metrics and timeline execution. PostgreSQL 16 is the primary data store for everything: machines, timelines, NPCs, activities and survey data.

The repository layout also shows directories worth knowing: configuration/, schemas/, scripts/, docs/, experimental/ and assets/ at the root, plus an .aspire/ directory and a GHOSTS.sln solution file.

## A framework under active development, with a licence that needs reading

The status note at the top of the guide is unusually informative and should be the first thing an evaluator reads. GHOSTS 9 is released but under active development. The API, domain models and Docker Compose stack are stable and used in production exercises, while individual client handlers and newer features, specifically the Scenario Builder and the n8n integration, are evolving. Changes are expected in minor releases until 10.0.

So the stability is uneven by layer. The server side and the data model are the parts other people depend on in production, while the client handlers and the newest features can move under you. That is a reasonable place for a research framework to be, but it means a client handler you depend on may need updating in a minor release.

The release history shows the pace: v9.3.0 on 2026-08-06 with the note that cyber, social and cognitive simulation continued development, v9.0.0 on 2026-06-03, and v8.3.1 on 2025-05-29. The last push to the repository was on 2026-10-15, so the work is current.

The licence is the one place to look carefully. The repository is classified under a custom licence that GitHub cannot categorise, with a LICENSE.md file in the root, and the project is from the CMU Software Engineering Institute. A badge in the guide reads MIT, but a badge is not the licence text, and a team planning to use GHOSTS in a commercial training offering should read LICENSE.md rather than the badge.

## Conclusion

GHOSTS suits a red team or training group that needs believable human activity on a network rather than noisy scripted traffic, and it suits researchers who need agent behaviour that changes over time, since timelines and personas are the core of the model rather than an afterthought. It does not suit a small team that just needs a load generator, because the stack brings a .NET API, an Angular console, Grafana, n8n and PostgreSQL, and it does not suit anyone who wants a stable release, because the project states that GHOSTS 9 is under active development with changes expected in minor releases until 10.0. Before deploying it, read the status note, confirm you can run the published Compose stack, and point a client at the API host on port 5000 only after setting POSTGRES_PASSWORD in the .env file.

## FAQ

### What is the GHOSTS framework used for?

GHOSTS is a CMU SEI framework for simulating realistic users on real computer systems for cyber training, exercises and research. It produces human-like network traffic, supports multi-agent scenarios, and leaves realistic artifacts behind on the simulated machines.

### How do I run GHOSTS for the first time?

Use the Docker Compose route. Fetch the published compose file with curl from the raw GitHub URL, copy .env.example to .env and set POSTGRES_PASSWORD, then run docker compose up -d. The API is then on port 5000, the Angular UI on 4200, Grafana on 3000 and n8n on 5678.

### Which GHOSTS client should I install on a simulated machine?

Ghosts.Client.Windows is the full-featured build on .NET Framework 4.6.2 with Office automation, browser control, SSH and RDP plus 27 or more handlers. Ghosts.Client.Universal covers Linux and Windows on .NET 9 with 38 or more handlers, and Ghosts.Client.Lite is the lightweight .NET 8 build for constrained machines.

### How does GHOSTS generate believable user behaviour?

Through Ghosts.Animator, which generates NPC personas with names, careers, social networks and beliefs, and Ghosts.Pandora, which generates dynamic web content, blog posts and documents. Behaviour is then executed along timelines whose progress is visible in the Grafana dashboards.

### Is GHOSTS production ready for training exercises?

Partly. The guide states that GHOSTS 9 is released but under active development, with the API, domain models and Docker Compose stack stable and used in production exercises, while client handlers and newer features such as the Scenario Builder and n8n integration are still evolving. Changes are expected in minor releases until 10.0.

## Sources

- [cmu-sei/GHOSTS on GitHub](https://github.com/cmu-sei/GHOSTS)
- [Issues](https://github.com/cmu-sei/GHOSTS/issues)
- [Project website](https://cmu-sei.github.io/GHOSTS/)
- [README](https://github.com/cmu-sei/GHOSTS/blob/master/README.md)
- [Releases](https://github.com/cmu-sei/GHOSTS/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cmu-sei-ghosts