https://github.com/dstl/YAWNING-TITAN
YAWNING TITAN is an abstract, graph based cyber-security simulation environment that supports the training of intelligent agents for autonomous cyber operations.
https://github.com/dstl/YAWNING-TITAN
autonomous-agents cybersecurity openai-gym openai-gym-environment reinforcement-learning rl-environment
Last synced: about 2 months ago
JSON representation
YAWNING TITAN is an abstract, graph based cyber-security simulation environment that supports the training of intelligent agents for autonomous cyber operations.
- Host: GitHub
- URL: https://github.com/dstl/YAWNING-TITAN
- Owner: dstl
- License: mit
- Archived: true
- Created: 2021-10-06T12:01:58.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-05-21T17:37:16.000Z (about 2 years ago)
- Last Synced: 2026-02-07T15:12:28.878Z (5 months ago)
- Topics: autonomous-agents, cybersecurity, openai-gym, openai-gym-environment, reinforcement-learning, rl-environment
- Language: Python
- Homepage:
- Size: 21.6 MB
- Stars: 66
- Watchers: 7
- Forks: 21
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-ai-agents-2026 - YAWNING TITAN - based cybersecurity simulation. | (🔐 Cybersecurity Agents / Benchmarks)
README
# YAWNING-TITAN
## About The Project
YAWNING-TITAN (**YT**) is an abstract, graph based cyber-security simulation environment that supports the training of
intelligent agents for autonomous cyber operations. YAWNING-TITAN currently only supports defensive autonomous agents
who face off against probabilistic red agents.
**YT** has been designed with the following things in mind:
- Simplicity over complexity
- Minimal Hardware Requirements
- Operating System agnostic
- Support for a wide range of algorithms
- Enhanced agent/policy evaluation support
- Flexible environment and game rule configuration
- Generation of evaluation episode visualisations (gifs)
**YT** was publicly released on 20th July 2022 under MIT licence. It will continue to be developed through the Autonomous
Resilient Cyber Defence (ARCD) project, overseen by Dstl.
## Contributing to YAWNING-TITAN
Found a bug, have an idea/feature you'd like to suggest, or just want to get involved with the YT community, please read
our [How to contribute to YAWNING-TITAN?](CONTRIBUTING.md) guidelines.
## What's YAWNING-TITAN built with
- [OpenAI's Gym](https://gym.openai.com/)
- [Networkx](https://github.com/networkx/networkx)
- [Stable Baselines 3](https://github.com/DLR-RM/stable-baselines3)
- [Rllib (part of Ray)](https://github.com/ray-project/ray)
## Getting Started with YAWNING-TITAN
### Pre-Requisites
In order to get **YT** installed, you will need to have the following installed:
- `python3.8+`
- `python3-pip`
- `virtualenv`
**YT** is designed to be OS-agnostic, and thus should work on most variations/distros of Linux, Windows, and MacOS.
### Installation from source
#### 1. Navigate to the YAWNING-TITAN folder and create a new python virtual environment (venv)
```unix
python3 -m venv
```
#### 2. Activate the venv
##### Unix
```bash
source /bin/activate
```
##### Windows
```powershell
.\\Scripts\activate
```
#### 3. Install `yawning-titan` into the venv along with all of it's dependencies
```bash
python3 -m pip install -e .
```
This will install all the dependencies including algorithm libraries. These libraries
all use `torch`. If you'd like to install `tensorflow` for use with Rllib, you can do this manually
or install `tensorflow` as an optional dependency by postfixing the command in step 3 above with the `[tensorflow]` extra. Example:
```bash
python3 -m pip install -e .[tensorflow]
```
### Development Installation
To install the development dependencies, postfix the command in step 3 above with the `[dev]` extra. Example:
```bash
python3 -m pip install -e .[dev]
```
## Application Directories
Upon install, **YT** creates a set of application directories, both hidden for **YT** use, and visible for user use. The
created directory trees for Linux, Windows, and MacOS operating systems are detailed below:
##### Linux
```
~/
├─ .cache/
│ ├─ yawning_titan/
│ │ ├─ log/
├─ .config/
│ ├─ yawning_titan/
├─ .local/
│ ├─ share/
│ │ ├─ yawning_titan/
│ │ │ ├─ app_images/
│ │ │ ├─ db/
│ │ │ ├─ docs/
├─ yawning_titan/
│ ├─ agents/
│ ├─ game_modes/
│ ├─ images/
│ ├─ notebooks/
```
##### Windows
```
~/
├─ AppData/
│ ├─ yawning_titan/
│ │ ├─ app_images/
│ │ ├─ config/
│ │ ├─ db/
│ │ ├─ docs/
│ │ ├─ logs/
├─ yawning_titan/
│ ├─ agents/
│ ├─ game_modes/
│ ├─ images/
│ ├─ notebooks/
```
##### MacOS
```
~/
├─ Library/
│ ├─ Application Support/
│ │ ├─ Logs/
│ │ │ ├─ yawning_titan/
│ │ │ │ ├─ log/
│ │ ├─ Preferences/
│ │ │ ├─ yawning_titan/
│ │ ├─ yawning_titan/
│ │ │ ├─ app_images/
│ │ │ ├─ db/
│ │ │ ├─ docs/
├─ yawning_titan/
│ ├─ agents/
│ ├─ game_modes/
│ ├─ images/
│ ├─ notebooks/
```
## Documentation
**YT** comes with a full set of documentation created using the Sphinx documentation library and are hosted on GitHub
pages at [https://dstl.github.io/YAWNING-TITAN](https://dstl.github.io/YAWNING-TITAN/index.html).
These docs can also be built manually from the cloned repo by using the following commands:
> This will require the development dependencies to be installed, see [Development Installation](#development-installation)
##### Unix
```bash
cd docs
make html
```
##### Windows
```powershell
cd docs
.\make.bat html
```
This will build the documentation as a collection of HTML files which uses the Read The Docs sphinx theme. Other build
options are available but may require additional dependencies such as LaTeX and PDF. Please refer to the Sphinx documentation
for your specific output requirements.
## Example Notebooks
A collection of example notebooks have been provided. The original versions of these notebooks stored in
[`yawning_titan/notebooks/_package_data`](yawning_titan/notebooks/_package_data) and are copied over to the newly created
users notebooks application directory (`~/yawning_titan/notebooks`) at install. These are the best place to start if you
want to get a feel for **YT** before builidng the docs and exploring further. If the notebooks become corrupted in the
users notebooks application directory, they can be reset running the following commands from an interactive Python
session on your venv:
```python
from yawning_titan.notebooks.jupyter import reset_default_jupyter_notebooks
reset_default_jupyter_notebooks(overwrite_existing=True)
```
## Cite This Work
If you would like to include a citation for **YT** in your work, please cite the paper published at the ICML 2022 ML4Cyber Workshop.
```bibtex
@inproceedings{inproceedings,
author = {Andrew, Alex and Spillard, Sam and Collyer, Joshua and Dhir, Neil},
year = {2022},
month = {07},
title = {Developing Optimal Causal Cyber-Defence Agents via Cyber Security Simulation},
maintitle = {International Confernece on Machine Learning (ICML)},
booktitle = {Workshop on Machine Learning for Cybersecurity (ML4Cyber)}
}
```
# License
YAWNING-TITAN is released under MIT license. Please see [LICENSE](LICENSE) for details.
# Related Environments
You may also wish to explore the PrimAITE environment, an effective simulation capability for the purposes of training and evaluating AI in a cyber-defensive role: https://github.com/Autonomous-Resilient-Cyber-Defence/PrimAITE