Realistic User Behavior Simulation for Cyber Training, Exercises, and Research
GHOSTS is an agent orchestration framework that 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
- 🌐 Web browsing with realistic navigation patterns
- 📝 Document creation and editing (Word, Excel, PowerPoint, Notepad)
- 📧 Email communication (Outlook, sending/receiving)
- 💬 Chat and messaging (Pidgin, social interactions)
- 🖥️ Terminal commands and system operations
- 🔄 File operations (FTP, SFTP, downloads, uploads)
- 🖱️ UI interactions (clicks, mouse movements)
- 🔐 Remote access (RDP, SSH)
- 🤖 AI-powered content generation (LLM integrations)
- 📊 Activity monitoring and analytics via Grafana dashboards
The fastest way to get started is using Docker Compose:
# Clone the repository
git clone https://github.com/cmu-sei/GHOSTS.git
cd GHOSTS
# Start the GHOSTS API and supporting services
docker-compose up -dFor detailed installation instructions, platform-specific builds, and configuration options, see the Quick Start Guide.
- Deploy the API Server - Use Docker Compose or deploy to your infrastructure
- Install Clients - Deploy GHOSTS clients on Windows or Linux machines
- Configure Timelines - Define activities through the UI or API
- Monitor Activity - View real-time NPC behavior through Grafana dashboards
See the full documentation for detailed configuration and usage examples.
GHOSTS consists of several integrated components that work together to create a realistic simulation environment:
| Component | Description | Documentation |
|---|---|---|
| GHOSTS Client | Cross-platform agent (Windows/Linux) that executes simulated user activities | Client Docs |
| GHOSTS API | Central server managing clients, timelines, and activity orchestration via REST and WebSocket | API Docs |
| GHOSTS UI | Web-based interface for managing machines, groups, and deploying timelines | UI Docs |
| GHOSTS Lite | Lightweight client version for resource-constrained environments | Lite Docs |
| Service | Description | Documentation |
|---|---|---|
| Animator | Generates realistic NPC personas with attributes, relationships, and social networks | Animator Docs |
| Pandora | Content generation server providing dynamic web content and responses | Pandora Docs |
| Socializer | Simulated social media platform for realistic social interactions | Socializer Docs |
| Grafana Integration | Real-time monitoring and visualization of NPC activities | Grafana Docs |
GHOSTS is designed for various cybersecurity and training scenarios:
- 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
- Cyber Range Development - Build immersive environments with autonomous NPCs
- Simulation & Modeling - Generate realistic network behavior patterns for analysis
- New UI - Web-based interface for managing machines, groups, and timelines
- GHOSTS Lite - Lightweight client for resource-constrained environments
- LLM Integration - AI-powered content generation (migrate to RangerAI for latest AI features)
- Bug Fixes - Resolved GUID issues (#385), client path bugs (#384), and animation cancellation issues
- Documentation Updates - Enhanced animation documentation
⚠️ Breaking Changes: Version 8.0 introduced breaking changes requiring a fresh installation. No upgrade path from previous versions.
Key Updates:
- Merged ANIMATOR and SPECTRE into core platform (both now archived)
- Migrated from MongoDB to PostgreSQL for better performance
- WebSocket support for real-time NPC connectivity
- Simplified Docker Compose deployment
- Reorganized API endpoints
- Enhanced timeline configuration with random delays
View Version 8.1 Changes
- GHOSTS LITE beta release
- API cleanup for machine updates and groups
- Simplified JSON object structures
- Improved machine group management
- Enhanced timeline delivery system
For complete version history, see the releases page.
Comprehensive documentation is available at cmu-sei.github.io/GHOSTS
Key Documentation Sections:
- Installation Guide
- Client Configuration
- Handler Reference - Available activities and configurations
- Timeline Management
- Animator NPCs
- Advanced Features
We welcome contributions from the community! Whether it's bug reports, feature requests, documentation improvements, or code contributions, your input helps make GHOSTS better.
- Report Issues - Use the GitHub issue tracker for bugs and feature requests
- Submit Pull Requests - Fork the repository, create a feature branch, and submit a PR
- Improve Documentation - Help enhance guides, examples, and API documentation
- Share Use Cases - Tell us how you're using GHOSTS in your environment
Please ensure your contributions align with our project goals and maintain code quality standards.
- Documentation: https://cmu-sei.github.io/GHOSTS/
- Issues: GitHub Issue Tracker
- Contact: Email [email protected] for questions and support
- RangerAI - Advanced AI integration for GHOSTS (successor to Shadows)
- ANIMATOR - Now integrated into GHOSTS core (archived)
- SPECTRE - Now integrated into GHOSTS core (archived)
GHOSTS is developed by the Software Engineering Institute (SEI) at Carnegie Mellon University and funded by the Department of Defense.
This project is licensed under the MIT License. See LICENSE.md for full details.
Distribution Statement: [DISTRIBUTION STATEMENT A] This material has been approved for public release and unlimited distribution.
Copyright 2017-2025 Carnegie Mellon University. All Rights Reserved.
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
