Skip to content

Commit e6d6352

Browse files
sei-dupdykesei-dupdyke
committed
readme updates
1 parent 8d39a1e commit e6d6352

File tree

1 file changed

+161
-79
lines changed

1 file changed

+161
-79
lines changed

‎README.md‎

Lines changed: 161 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -1,106 +1,188 @@
1+
<div>
2+
13
# GHOSTS NPC Framework
24

3-
GHOSTS simulates user activity on a computer, like creating documents, browsing websites, and downloading files. It drives various popular applications on both Windows and Linux machines. Whether you're a friendly administrator or a cyber adversary, GHOSTS can replicate your expected behavior.
5+
**Realistic User Behavior Simulation for Cyber Training, Exercises, and Research**
6+
7+
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.md)
8+
[![.NET](https://img.shields.io/badge/.NET-9.0-purple.svg)](https://dotnet.microsoft.com/)
9+
[![Version](https://img.shields.io/badge/version-8.2-green.svg)](https://github.com/cmu-sei/GHOSTS/releases)
10+
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/cmu-sei/GHOSTS/pulls)
411

5-
GHOSTS has many use cases in cyber experimentation, training and exercise, most notably for bringing non-player characters (NPCs) to life. However, it can also be used for other purposes requiring realistic activity on a computer.
12+
[Quick Start](https://cmu-sei.github.io/GHOSTS/quickstart/) • [Documentation](https://cmu-sei.github.io/GHOSTS/) • [Issues](https://github.com/cmu-sei/GHOSTS/issues) • [Demo Video](https://www.youtube.com/watch?v=EkwK-cqwjjA)
613

7-
There is a [short demonstration video available on YouTube](https://www.youtube.com/watch?v=EkwK-cqwjjA) (3:03).
14+
</div>
815

916
---
1017

11-
## Key Links
18+
## Overview
1219

13-
- [Quick Start: Installation from distribution binaries](https://cmu-sei.github.io/GHOSTS/quickstart/)
14-
- [GHOSTS Documentation](https://cmu-sei.github.io/GHOSTS/)
15-
- [Submit issues and feature requests](https://github.com/cmu-sei/GHOSTS/issues)
20+
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.
1621

17-
---
22+
**Watch a quick demo:** [3-minute introduction on YouTube](https://www.youtube.com/watch?v=EkwK-cqwjjA)
1823

19-
**Version 8.2 is here!**
24+
### Key Capabilities
2025

21-
GHOSTS has undergone major updates, including breaking changes introduced in version 8.0. Version 8 absorbed the [ANIMATOR](https://github.com/cmu-sei/GHOSTS-ANIMATOR) and [SPECTRE](https://github.com/cmu-sei/GHOSTS-SPECTRE) modules, simplifying the installation, configuration, and administration of a GHOSTS instance, while bringing further capabilities to core agents by integrating previously segregated data. With version 8.2, more improvements and features are introduced, making it easier and more powerful to use.
26+
- 🌐 **Web browsing** with realistic navigation patterns
27+
- 📝 **Document creation and editing** (Word, Excel, PowerPoint, Notepad)
28+
- 📧 **Email communication** (Outlook, sending/receiving)
29+
- 💬 **Chat and messaging** (Pidgin, social interactions)
30+
- 🖥️ **Terminal commands** and system operations
31+
- 🔄 **File operations** (FTP, SFTP, downloads, uploads)
32+
- 🖱️ **UI interactions** (clicks, mouse movements)
33+
- 🔐 **Remote access** (RDP, SSH)
34+
- 🤖 **AI-powered content generation** (LLM integrations)
35+
- 📊 **Activity monitoring and analytics** via Grafana dashboards
2236

23-
### Breaking Changes in Version 8.0:
24-
1. Configuration file changes.
25-
2. Database changes.
26-
3. API endpoint changes.
37+
## Quick Start
2738

28-
There is no upgrade path from previous versions — a fresh install is required for version 8 and beyond.
39+
### Installation
2940

30-
---
41+
The fastest way to get started is using Docker Compose:
42+
43+
```bash
44+
# Clone the repository
45+
git clone https://github.com/cmu-sei/GHOSTS.git
46+
cd GHOSTS
47+
48+
# Start the GHOSTS API and supporting services
49+
docker-compose up -d
50+
```
3151

32-
## What's New in GHOSTS v8.2 🆕
33-
Welcome to the latest version of GHOSTS! Here’s a look at what’s new and improved in v8.2:
34-
35-
- [GHOSTS now has a UI](src/ghosts.ui) — Manage machines, machine groups, deploy new timelines, and view activities through a sleek interface. 😍
36-
- GHOSTS Shadows now integrates with large language models (LLMs) for GHOSTS agents, offering various models for activities, chat, content generation, social interactions, and more. **(Shadows is depreciated. See [RangerAI](https://github.com/cmu-sei/rangerai) for all new GHOSTS AI efforts going forward)**.
37-
- [GHOSTS LITE](src/Ghosts.Client.Lite) is a lightweight version of GHOSTS that requires fewer resources, making it ideal for training, exercises, and simulations on minimal hardware. 👀
38-
- Fixes #385: Default GUID issue with Animator NPCs.
39-
- Fixes #384: Client path bug.
40-
- Resolved various animation cancellation token bugs in chat features.
41-
- Updated documentation for Animations (with contributions from SEI's TMR team). 🤙
42-
43-
## What's New in GHOSTS v8.1:
44-
- GHOSTS LITE BETA: A lighter version designed for scenarios where participants won't directly access the machine.
45-
- API cleanup, particularly around machine updates and groups.
46-
- Simplified sample JSON objects for better understanding and easier submission.
47-
- Improved API robustness and machine group management.
48-
- Enhanced timeline delivery per machine and group.
49-
50-
## What's New in GHOSTS v8.0:
51-
### Enhancements:
52-
- Merged ANIMATOR and SPECTRE functionalities into the core GHOSTS API. Both projects are now archived.
53-
- Migrated all data from MongoDB to PostgreSQL for improved performance and management.
54-
- Cleaned up the Docker Compose setup to minimize installation and configuration issues.
55-
- Animator job management can now be handled directly through the UI.
56-
- Transitioning from HTTP requests to WebSockets: NPCs are "always connected" and no longer need to poll the server to execute activities.
57-
- Added ability to configure random delays (before or after an activity) within timelines.
58-
- Simplified configuration for both client and server systems (breaking change).
59-
- Consolidated installation into a single `docker-compose` file, streamlining the process.
60-
- Reorganized API endpoints for improved structure and accessibility.
61-
- Added a favicon for UI polish.
62-
63-
### Bug Fixes:
64-
- Grafana Docker Compose no longer uses the root user.
65-
- Ensured all Docker containers are `amd64` (not `arm`).
66-
- Fixed issues with command windows staying open after execution.
67-
- Improved RDP functionality, fixing connectivity bugs.
68-
- Resolved issues with delay values exceeding integer limits.
69-
- Added "log" level to application logs for better insight into operations.
70-
- Fixed documentation bug related to machine group timelines.
52+
For detailed installation instructions, platform-specific builds, and configuration options, see the [Quick Start Guide](https://cmu-sei.github.io/GHOSTS/quickstart/).
53+
54+
### Basic Usage
55+
56+
1. **Deploy the API Server** - Use Docker Compose or deploy to your infrastructure
57+
2. **Install Clients** - Deploy GHOSTS clients on Windows or Linux machines
58+
3. **Configure Timelines** - Define activities through the UI or API
59+
4. **Monitor Activity** - View real-time NPC behavior through Grafana dashboards
60+
61+
See the [full documentation](https://cmu-sei.github.io/GHOSTS/) for detailed configuration and usage examples.
7162

7263
---
7364

74-
## Platform Components
65+
## Architecture
7566

76-
### Ghosts Clients (Windows & Linux)
77-
GHOSTS clients simulate user-like behavior on a machine. Configurable tasks include:
78-
- Web browsing
79-
- Document creation and editing
80-
- Email sending and responding
81-
- Running terminal commands
82-
- And more.
67+
GHOSTS consists of several integrated components that work together to create a realistic simulation environment:
8368

84-
### Ghosts API Server
85-
The API server enables clients to interact with GHOSTS and provides the following functionality:
86-
- Manage clients, add/remove groups, etc.
87-
- Retrieve/manage client activity data.
88-
- Orchestrate new tasks for clients to perform.
69+
### Core Components
8970

90-
### Ghosts UI
91-
The UI offers an interface for managing machines, groups, and deploying timelines, providing an easier way to interact with the GHOSTS system.
71+
| Component | Description | Documentation |
72+
|-----------|-------------|---------------|
73+
| **GHOSTS Client** | Cross-platform agent (Windows/Linux) that executes simulated user activities | [Client Docs](https://cmu-sei.github.io/GHOSTS/core/client/) |
74+
| **GHOSTS API** | Central server managing clients, timelines, and activity orchestration via REST and WebSocket | [API Docs](https://cmu-sei.github.io/GHOSTS/core/api/) |
75+
| **GHOSTS UI** | Web-based interface for managing machines, groups, and deploying timelines | [UI Docs](https://cmu-sei.github.io/GHOSTS/core/ui/) |
76+
| **GHOSTS Lite** | Lightweight client version for resource-constrained environments | [Lite Docs](https://cmu-sei.github.io/GHOSTS/core/lite/) |
9277

93-
### Ghosts Lite
94-
A minimalistic version of the Windows GHOSTS client, suitable for running on systems with limited resources.
78+
### Supporting Services
9579

96-
### Pandora Content Server
97-
A server that provides requested content to GHOSTS clients, dynamically generating responses or serving static content for training, exercises, and red-teaming.
80+
| Service | Description | Documentation |
81+
|---------|-------------|---------------|
82+
| **Animator** | Generates realistic NPC personas with attributes, relationships, and social networks | [Animator Docs](https://cmu-sei.github.io/GHOSTS/animator/) |
83+
| **Pandora** | Content generation server providing dynamic web content and responses | [Pandora Docs](https://cmu-sei.github.io/GHOSTS/content/pandora/) |
84+
| **Socializer** | Simulated social media platform for realistic social interactions | [Socializer Docs](https://cmu-sei.github.io/GHOSTS/content/social/) |
85+
| **Grafana Integration** | Real-time monitoring and visualization of NPC activities | [Grafana Docs](https://cmu-sei.github.io/GHOSTS/core/grafana/) |
9886

99-
### Pandora Socializer Server
100-
This server allows GHOSTS clients to interact with simulated social media content, enhancing the realism of cyber scenarios.
87+
## Use Cases
10188

102-
---
89+
GHOSTS is designed for various cybersecurity and training scenarios:
90+
91+
- **Cyber Training & Exercises** - Populate training environments with realistic user activity
92+
- **Red Team Operations** - Generate believable background noise during security assessments
93+
- **Blue Team Training** - Create realistic network traffic for detection and analysis practice
94+
- **Research & Development** - Test security tools and detection algorithms with realistic data
95+
- **Cyber Range Development** - Build immersive environments with autonomous NPCs
96+
- **Simulation & Modeling** - Generate realistic network behavior patterns for analysis
97+
98+
## What's New
99+
100+
### Version 8.2 (Current)
101+
102+
- **New UI** - [Web-based interface](src/ghosts.ui) for managing machines, groups, and timelines
103+
- **GHOSTS Lite** - [Lightweight client](src/Ghosts.Client.Lite) for resource-constrained environments
104+
- **LLM Integration** - AI-powered content generation (migrate to [RangerAI](https://github.com/cmu-sei/rangerai) for latest AI features)
105+
- **Bug Fixes** - Resolved GUID issues (#385), client path bugs (#384), and animation cancellation issues
106+
- **Documentation Updates** - Enhanced animation documentation
107+
108+
### Version 8.0 Major Changes
109+
110+
> **⚠️ Breaking Changes**: Version 8.0 introduced breaking changes requiring a fresh installation. No upgrade path from previous versions.
111+
112+
**Key Updates:**
113+
- Merged ANIMATOR and SPECTRE into core platform (both now archived)
114+
- Migrated from MongoDB to PostgreSQL for better performance
115+
- WebSocket support for real-time NPC connectivity
116+
- Simplified Docker Compose deployment
117+
- Reorganized API endpoints
118+
- Enhanced timeline configuration with random delays
119+
120+
<details>
121+
<summary>View Version 8.1 Changes</summary>
122+
123+
- GHOSTS LITE beta release
124+
- API cleanup for machine updates and groups
125+
- Simplified JSON object structures
126+
- Improved machine group management
127+
- Enhanced timeline delivery system
128+
129+
</details>
130+
131+
For complete version history, see the [releases page](https://github.com/cmu-sei/GHOSTS/releases).
132+
133+
## Documentation
134+
135+
Comprehensive documentation is available at [cmu-sei.github.io/GHOSTS](https://cmu-sei.github.io/GHOSTS/)
136+
137+
**Key Documentation Sections:**
138+
- [Installation Guide](https://cmu-sei.github.io/GHOSTS/quickstart/)
139+
- [Client Configuration](https://cmu-sei.github.io/GHOSTS/core/client/)
140+
- [Handler Reference](https://cmu-sei.github.io/GHOSTS/core/handlers/) - Available activities and configurations
141+
- [Timeline Management](https://cmu-sei.github.io/GHOSTS/core/api/timelines/)
142+
- [Animator NPCs](https://cmu-sei.github.io/GHOSTS/animator/)
143+
- [Advanced Features](https://cmu-sei.github.io/GHOSTS/advanced/)
144+
145+
## Contributing
146+
147+
We welcome contributions from the community! Whether it's bug reports, feature requests, documentation improvements, or code contributions, your input helps make GHOSTS better.
148+
149+
### How to Contribute
150+
151+
1. **Report Issues** - Use the [GitHub issue tracker](https://github.com/cmu-sei/GHOSTS/issues) for bugs and feature requests
152+
2. **Submit Pull Requests** - Fork the repository, create a feature branch, and submit a PR
153+
3. **Improve Documentation** - Help enhance guides, examples, and API documentation
154+
4. **Share Use Cases** - Tell us how you're using GHOSTS in your environment
155+
156+
Please ensure your contributions align with our project goals and maintain code quality standards.
157+
158+
## Support
159+
160+
- **Documentation**: [https://cmu-sei.github.io/GHOSTS/](https://cmu-sei.github.io/GHOSTS/)
161+
- **Issues**: [GitHub Issue Tracker](https://github.com/cmu-sei/GHOSTS/issues)
162+
- **Contact**: Email [email protected] for questions and support
163+
164+
## Related Projects
165+
166+
- **[RangerAI](https://github.com/cmu-sei/rangerai)** - Advanced AI integration for GHOSTS (successor to Shadows)
167+
- **ANIMATOR** - Now integrated into GHOSTS core (archived)
168+
- **SPECTRE** - Now integrated into GHOSTS core (archived)
169+
170+
## Acknowledgments
171+
172+
GHOSTS is developed by the Software Engineering Institute (SEI) at Carnegie Mellon University and funded by the Department of Defense.
103173

104174
## License
105-
[DISTRIBUTION STATEMENT A] This material has been approved for public release and unlimited distribution.
106-
Copyright 2017 Carnegie Mellon University. All Rights Reserved. See LICENSE.md file for terms.
175+
176+
This project is licensed under the MIT License. See [LICENSE.md](LICENSE.md) for full details.
177+
178+
**Distribution Statement**: [DISTRIBUTION STATEMENT A] This material has been approved for public release and unlimited distribution.
179+
180+
Copyright 2017-2025 Carnegie Mellon University. All Rights Reserved.
181+
182+
---
183+
184+
<div>
185+
186+
[Website](https://cmu-sei.github.io/GHOSTS/) • [GitHub](https://github.com/cmu-sei/GHOSTS) • [Issues](https://github.com/cmu-sei/GHOSTS/issues) • [Releases](https://github.com/cmu-sei/GHOSTS/releases)
187+
188+
</div>

0 commit comments

Comments
 (0)