Simulation environment for attacks on computer networks
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Go to file
Thorsten Sick ff8622b3b8
Merge pull request #47 from avast/polishing2
1 year ago
.github/workflows Workflows can be manually triggered 2 years ago
app fix 2 years ago
doc Vale fix for docs 2 years ago
docs Added Hs Alb-sig to homepage 2 years ago
plugins Requirements update and fixes 2 years ago
presentations Britta changes 1 year ago
systems Fixing Hydra vs. filebeat. Issues fixed: Kali linux updated. Hydra dependency fixed. Filebeat fully moved to plugin (no Vagrant setup left). 2 years ago
templates Adding line numbers and file names to metasploit attacks 2 years ago
tests More MyPy enforcements 2 years ago
tools shipit extended to accept deeper nested files. Especially in plugin resource folders 2 years ago
.gitignore some git cleanup 2 years ago
CONTRIBUTING.txt Documentation upgrade improved contributing.txt 2 years ago
CONTRIBUTORS.txt Basic contribution files added 2 years ago
LICENSE.txt Cleanup and adding a starter pack (hello_world, license, readme) 2 years ago
Makefile Requirements update and fixes 2 years ago AFK message added 1 year ago Basic doc upgrade 2 years ago
caldera_subset_classic.txt Caldera experiments can be independently controlled by files. Those will overwrite the caldera attacks in the experiment files. Good for batch processing 2 years ago Requirements update and fixes 2 years ago Basic doc upgrade 2 years ago Requirements update and fixes 2 years ago
hello_world.yaml removed confusing stuff 2 years ago Added argcomplete to command line tools 2 years ago Requirements update and fixes 2 years ago pylinting round 4 2 years ago
mypy.ini More MyPy enforcements 2 years ago Basic doc upgrade 2 years ago Requirements update and fixes 2 years ago
pylint.rc Made pylint happy 2 years ago
requirements.txt Requirements update 1 year ago
requirements_dev.txt Documentation can be built now 2 years ago Requirements update and fixes 2 years ago
template.yaml Cleanup and adding a starter pack (hello_world, license, readme) 2 years ago
tox.ini Activating pylint for code checks 2 years ago

main branch test develop branch test

Important: During the next months the main developer is mostly AFK. There are fallback maintainers, but you can expect reduced response time. Please plan accordingly, fork and cooperate. Thanks

PurpleDome creates simulated systems which hack each other

It creates several virtual machines to simulate a target network. A Kali attacker will be spawned and use configured attacks to blast at the targets. Those attacks can be Kali command line tools, Caldera abilities or Metasploit tools.

The goal is to test sensors and detection logic on the targets and in the network and improve them.

The system is at the same time reproducible and quite flexible (target system wise, vulnerabilities on the targets, attacks).


On a current Ubuntu 21.10 system, just execute the to install the required packages and set up the virtual env.

You need python 3.9 (which is part of this Ubuntu)

And it will not run properly in a VM as it spawns its own VMs ... unless VT-x is available. We confirmed it is working in VirtualBox. Please reserve enough disk space. The simple hello_world will already download a kali and an ubuntu image. They must be stored on your VM.


Default vm will be vagrant and virtualbox

Before using any PurpleDome commands switch into the python environment:

source venv/bin/activate

My first experiment

Run and be very patient. The first time it runs it will build target and attacker VMs which is time consuming and will need some bandwidth.

python3 ./ -vvv  run --configfile hello_world.yaml

This will:

  • Use vagrant to generate attacker and target
  • run them
  • run several attacks from the attacker to the target
  • zip sensor logs and attack logs together

Building the machines from vagrant will take some time ont he first run. Please be patient.

After the experiment ran, open the zip file with the attack log and all the sensor logs:

file-roller loot/2021_11_11___12_13_14/

or jump directly into the human readable attack log

evince tools/human_readable_documentation/build/latex/purpledomesimulation.pdf

(which is included in the zip as well)

Potential issues here

The vagrant configuration file systems/Vagrantfile defines a bridged network shared between the VirtualBox VMs. If you do not have one or yours has a different name, please create one and change the config. Currently every machine uses: "public_network", bridge: "enp4s0"

Fixing issues

Machine creation

One of the big steps is creation of attacker and target machines. If this fails, you can do the step manually and check why it fails.

cd systems
vagrant up attacker
vagrant up target3
vagrant ssh attacker
# do someting
vagrant ssh target
# do something
vagrant destroy target3
vagrant destroy attacker

Caldera issues

The caldera server is running on the attacker. It will be contacted by the implants installed on the client and remote controlled by PurpleDome using a REST Api. This can be tested using curl:

curl -H 'KEY: ADMIN123' http://attacker:8888/api/rest -H 'Content-Type: application/json' -d '{"index":"adversaries"}'

If there are errors, connect to the attacker using ssh and monitor the server while contacting it. Maybe kill it first.

cd caldera
python3 --insecure

Running the basic commands

All command line tools have a help included. You can access it by the "--help" parameter

python3 ./ -v  run
  • -v is verbosity. To spam stdout use -vvv
  • run is the default command
  • --configfile is optional. If not supplied it will take experiment.yaml

Most of the configuration is done in the yaml config file. For more details check out the full documentation


Basic code and unit tests can be run by

make test

That way you can also see if your env is set up properly.

It will also check the plugins you write for compatibility.

the tool


is not included in the make test. But you can use it manually to verify your yaml config files. As they tend to become quite complex this is a time safer.

More documentation

This README is just a short overview. In depth documentation can be found in the doc folder.

Documentation is using sphinx. To compile it, go into this folder and call

make html

Use your browser to open build/html/index.html and start reading.


The code is stored in Feel free to fork it and create a pull request.

Development happens in feature branches branched of from develop branch. And all PRs go back there. The branch release is a temporary branch from develop and will be used for bug fixing before a PR to main creates a new release. Commits in main will be marked with tags and the changelog.txt file in human readable form describe the new features.


  • As a user, the main branch is relevant for you
  • Start a feature branch from develop
  • When doing a hotfix, branch from main


Branching your own feature branch

$ git checkout development
$ git pull --rebase=preserve
$ git checkout -b my_feature

Do some coding, commit.

Rebase before pushing

$ git checkout development
$ git pull --rebase=preserve
$ git checkout my_feature
$ git rebase development

Code review will be happening on github. If everything is nice, you should squash the several commits you made into one (so one commit = one feature). This will make code management and debugging a lot simpler when you commit is added to develop and main branches

git rebase --interactive
git push --force


Is a argparse extension that registers the command line arguments for bash. It requires a command line command to register it globally. This is added to

The configuration will be set in /etc/bash_completion.d/ . Keep in mind: It will require a shell restart to be activated


When doing scientific research using Purple Dome, please use this BibTeX snippet in your paper:

author = {Thorsten Sick and Fabrizio Biondi},
title = {GitHub - avast/PurpleDome: Simulation environment for attacks on computer networks},
note = {(visited on 09.02.2022)},
howpublished = "\url{}",