GHOSTS NPC Framework

Realistic User Behavior Modeling and Simulation for Cyber/Cognitive Training, Exercises, and Research

Quick Start • Documentation • Issues • Demo Video

Status: GHOSTS 9 is released but under active development. The API, domain models, and Docker Compose stack are stable and used in production exercises. Individual client handlers and newer features (Scenario Builder, n8n integration) are evolving. Expect changes in minor releases until 10.0. See the v9 announcement for details.

Overview

GHOSTS is an NPC (or agent) orchestration framework that models and simulates realistic users on all types of computer systems, generating human-like activity across applications, networks, and workflows. Beyond simple automation, it can dynamically reason, chat, and create content via integrated LLMs, enabling adaptive, context-aware behavior. Designed for cyber training, research, and simulation, it produces realistic network traffic, supports complex multi-agent scenarios, and leaves behind realistic artifacts. Its modular architecture allows the addition of new agents, behaviors, and lightweight clients, making it a flexible platform for high-fidelity simulations.

Watch a quick demo: 3-minute introduction on YouTube

Quick Start

There are two supported ways to get GHOSTS running: the Dev Container (best for contributors who want to build and debug the source) and standard Docker Compose (best for standing up the published stack quickly).

1. Dev Container

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.

Prerequisites: Docker and VS Code with the Dev Containers extension (or any editor that supports the Dev Container spec).

Clone the repository and open it in VS Code:

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

When prompted, choose Reopen in Container (or run Dev Containers: Reopen in Container from the command palette). The first build takes a few minutes while the image and features are provisioned.
Once the container is ready, open a terminal (Ctrl-Shift-`) and start the stack. Because Docker-in-Docker is enabled, the same Compose stack runs from inside the container:
```
cd src/Ghosts.Api
cp .env.example .env   # set POSTGRES_PASSWORD
docker compose up -d
```
Alternatively, use the .NET Aspire host for local development orchestration:
```
cd src/apphost
dotnet run
```

The services are published on the same ports as below and are forwarded to your host automatically.

2. Standard Docker Compose

If you only want to run the published stack (no source build required):

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

First run: Copy .env.example to .env and set POSTGRES_PASSWORD before starting. See src/Ghosts.Api/.env.example for all available variables.

Services

Service	URL	Notes
GHOSTS Frontend	http://localhost:4200	Angular management UI
GHOSTS API	http://localhost:5000	REST API + Swagger at `/swagger`
Grafana	http://localhost:3000	Activity dashboards
n8n	http://localhost:5678	Workflow automation
PostgreSQL	localhost:5432	Database

Then install a client on each machine you want to simulate and point it at http://YOUR-API-HOST:5000/api.

For full setup instructions see the Quick Start Guide.

Architecture

Core Components

Component	Tech	Description
Ghosts.Api	.NET 10	Central command-and-control server. REST API, SignalR WebSocket hub, NPC orchestration, scenario management.
Ghosts.Frontend	Angular 20	Web UI for managing machines, groups, timelines, NPCs, scenarios, and workflow automation.
Ghosts.Client.Windows	.NET Framework 4.6.2	Full-featured Windows client with Office automation, browser control, SSH, RDP, and 27+ activity handlers.
Ghosts.Client.Universal	.NET 9	Cross-platform client for Linux/Windows with 38+ handlers.
Ghosts.Client.Lite	.NET 8	Lightweight client for resource-constrained environments.
Ghosts.Domain	.NET Standard 2.0	Shared library: timeline models, handler base classes, client configuration.

Supporting Services

Service	Tech	Description
Ghosts.Animator	.NET Standard 2.0	NPC persona generation engine (names, careers, social networks, beliefs).
Ghosts.Pandora	.NET 10	Dynamic content generation server for realistic web content, blog posts, and documents.
n8n	Docker	Workflow automation platform. GHOSTS API can schedule and trigger n8n workflows via webhook.
Grafana	Docker	Real-time dashboards for NPC activity, health metrics, and timeline execution.

Infrastructure

Component	Description
apphost	.NET Aspire application host for local development orchestration.
PostgreSQL 16	Primary data store for all machines, timelines, NPCs, activities, and survey data.

Repository Layout

src/
├── Ghosts.Api/            # .NET 10 API server + docker-compose.yml
├── Ghosts.Domain/         # Shared domain library (netstandard2.0)
├── Ghosts.Frontend/       # Angular 20 management UI
├── Ghosts.Client.Windows/ # .NET 4.6.2 Windows client
├── Ghosts.Client.Universal/ # .NET 9 cross-platform client
├── Ghosts.Client.Lite/    # .NET 8 lightweight client
├── Ghosts.Animator/       # NPC persona generation
├── Ghosts.Pandora/        # Content generation server
├── apphost/               # .NET Aspire host
└── tools/                 # Utilities (load tester, machine adder, email generator)
scripts/
├── build_windows.ps1      # Build Windows client
├── build_universal.py     # Build Universal client
└── horde/                 # Bulk operation scripts
docs/                      # MkDocs documentation source

What's New in Version 9

🎨 Complete UI Rewrite: Angular 20 Frontend

Replaced the Next.js interface with a modern, full-featured Angular 20 management application:

Operations Dashboard — Real-time overview of connected machines, active NPC animations, and recent timeline executions
Belief Explorer — Visualize and track NPC cognitive state evolution over simulation steps
NPC Action Menu — Enhanced NPC management with improved controls for persona generation and social graph visualization
Workflow Scheduler — Schedule and monitor n8n workflows with live execution logs and real-time status updates
Enhanced Timeline Management — Streamlined creation, assignment, and deployment of timelines to machines and groups
Scenario Management — Define, execute, and track training scenarios with improved planning and execution tracking

⚡ Platform Modernization

.NET 10 Upgrade — API (Ghosts.Api) and Pandora content server migrated to .NET 10 with latest dependency updates
.NET Aspire Host — Optional application host for local development with integrated service discovery and health dashboards
Grafana Provisioning — Pre-configured dashboards for cognitive range monitoring, NPC activity, and belief systems

🤖 Enhanced Cognitive Capabilities

Belief System — NPCs now maintain belief states that evolve over time based on interactions and experiences
Knowledge Graphs — Track NPC learning and knowledge acquisition with visualization tools
Social Connections API — New endpoints for managing NPC relationships, preferences, and social networks
Improved Social Graph — Enhanced visualization and management of NPC social networks and connections

🔄 Workflow Automation

n8n Integration — Native workflow automation platform integration with:
- Cron-scheduled workflow execution
- Real-time monitoring with HTTP status and response preview
- Base workflow templates included
- Environment variable configuration for API URL and authentication

🐛 Bug Fixes & Improvements

Fixed trackables history endpoint (#581)
Improved username generation (proper formatting, removes spaces)
Resolved SVG asset build issues
Animation cancellation token improvements
NPCs can now be tied to specific scenarios
Timeline delivery improvements (by machine and by group)

Version 8.x history

Version 8.2

GHOSTS UI (Next.js) — now replaced by the Angular 20 frontend in v9.
GHOSTS Lite beta release.
LLM/Shadows integration — superseded by RangerAI.
Bug fixes: default GUID (#385), client path (#384), animation cancellation token.

Version 8.1

GHOSTS Lite beta.
API cleanup for machine updates and groups.
Simplified JSON payloads.
Timeline delivery by machine and by group.

Version 8.0 (breaking — fresh install required)

ANIMATOR and SPECTRE merged into core; both archived.
Migrated from MongoDB to PostgreSQL.
WebSocket (SignalR) support; clients are now always-connected.
Single docker-compose.yml for the full stack.
API endpoints reorganized.
Random delay support in timelines.

Use Cases

Cyber Training & Exercises — Populate training environments with realistic user activity.
Red Team Operations — Generate believable background noise during security assessments.
Blue Team Training — Create realistic network traffic for detection and analysis practice.
Research & Development — Test security tools and detection algorithms with realistic data.
Cognitive Range Development — Build immersive environments with autonomous NPCs that reason and interact.

Choosing a Client

GHOSTS ships three clients. The hope is to replace the Windows client with the Universal client in future releases, as it supports modern development practices. Until that time, pick the one that matches your environment:

Client	Runtime	OS	Best For
Windows	.NET Framework 4.6.1+	Windows 7/10/11, Server 2012+	Full application automation (Office, browsers, RDP). Use when participants observe the desktop.
Universal	.NET 9	Windows, Linux, macOS	Cross-platform with 38+ handlers. Default choice for Linux or mixed environments.
Lite	.NET 8	Windows, Linux	Lightweight network traffic generation without launching real apps. Best for high NPC density on limited hardware.

Not sure? Start with Universal. It covers the widest range of handlers and runs everywhere. Switch to Windows only if you need Office/Outlook automation, or Lite if you need hundreds of NPCs on a single host.

Security

See SECURITY.md for the vulnerability reporting process, supported versions, and scope.

Contributing

See CONTRIBUTING.md for the full guide.

Related Projects

RangerAI — AI/LLM integration layer for GHOSTS (successor to Shadows).

License

MIT License. See LICENSE.md for full details.

Distribution Statement: [DISTRIBUTION STATEMENT A] This material has been approved for public release and unlimited distribution.

Docs • GitHub • Issues • Releases

GHOSTS