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.
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? guidelines.
In order to get YT installed, you will need to have the following installed:
python3.8+python3-pipvirtualenv
YT is designed to be OS-agnostic, and thus should work on most variations/distros of Linux, Windows, and MacOS.
python3 -m venv <name_of_venv>
source <name_of_venv>/bin/activate.\<name_of_venv>\Scripts\activatepython3 -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:
python3 -m pip install -e .[tensorflow]To install the development dependencies, postfix the command in step 3 above with the [dev] extra. Example:
python3 -m pip install -e .[dev]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:
~/
├─ .cache/
│ ├─ yawning_titan/
│ │ ├─ log/
├─ .config/
│ ├─ yawning_titan/
├─ .local/
│ ├─ share/
│ │ ├─ yawning_titan/
│ │ │ ├─ app_images/
│ │ │ ├─ db/
│ │ │ ├─ docs/
├─ yawning_titan/
│ ├─ agents/
│ ├─ game_modes/
│ ├─ images/
│ ├─ notebooks/
~/
├─ AppData/
│ ├─ yawning_titan/
│ │ ├─ app_images/
│ │ ├─ config/
│ │ ├─ db/
│ │ ├─ docs/
│ │ ├─ logs/
├─ yawning_titan/
│ ├─ agents/
│ ├─ game_modes/
│ ├─ images/
│ ├─ notebooks/
~/
├─ Library/
│ ├─ Application Support/
│ │ ├─ Logs/
│ │ │ ├─ yawning_titan/
│ │ │ │ ├─ log/
│ │ ├─ Preferences/
│ │ │ ├─ yawning_titan/
│ │ ├─ yawning_titan/
│ │ │ ├─ app_images/
│ │ │ ├─ db/
│ │ │ ├─ docs/
├─ yawning_titan/
│ ├─ agents/
│ ├─ game_modes/
│ ├─ images/
│ ├─ notebooks/
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.
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
cd docs
make htmlcd docs
.\make.bat htmlThis 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.
A collection of example notebooks have been provided. The original versions of these notebooks stored in
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:
from yawning_titan.notebooks.jupyter import reset_default_jupyter_notebooks
reset_default_jupyter_notebooks(overwrite_existing=True)If you would like to include a citation for YT in your work, please cite the paper published at the ICML 2022 ML4Cyber Workshop.
@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)}
}YAWNING-TITAN is released under MIT license. Please see LICENSE for details.
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