# PurpleDome creates simulated systems which hack each other
Uses vagrant to set up vulnerable systems. Sensors and maybe attack agents will be installed as well.
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.
Will use vagrant config. It is quite likely that it we will need some parameters to create similar but not identical systems.
The goal is to test sensors and detection logic on the targets and in the network and improve them.
## Testing
The system is at the same time reproducible and quite flexible (target system wise, vulnerabilities on the targets, attacks).
*Prerequisites:*
## Installation
Install python environment, e.g. using `conda`:
```
conda create -n purpledome python=3.8
conda activate purpledome
```
Setting up the python environment:
Then install the required dependencies in the crated python environment:
```
pip install -r requirements.txt
./init.sh
```
*Call test suite:*
The typical local use case is to create the machines using Vagrant and running them in VirtualBox:
...
sudo apt install vagrant virtualbox
...
You will have to switch into the python environment to run it
Before using any PurpleDome commands switch into the python environment:
...
source venv/bin/activate
...
(this will contain the libraries in the required versions)
## Testing
Basic code and unit tests can be run by
```
make test
```
## Documentation
That way you can also see if your env is set up properly
## Running the basic commands
All command line tools have a help included. You can access it by the "--help" parameter
...
python3 ./experiment_control.py -v run
...
* -v is verbosity. To spam stdout use -vvv
* run is the default command
* --configfile <filename> 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
## The real documentation
This README is just a short overview. In depth documentation can be found in the *doc* folder.
Kali attacks can be extended using a plugin system. An example plugin is in the file *hydra_plugin.py*. It contains a plugin class that **MUST** be based on the *KaliPlugin* class.
Attack features of PurpleDome can be extended using a plugin system. Those attack plugins can start Caldera ttacks, run Kali command line tools ir use Metasploit.
An example plugin is in the file *hydra_plugin.py*. It contains a plugin class that **MUST** be based on the *AttackPlugin* class.
::
@ -16,7 +19,7 @@ Kali attacks can be extended using a plugin system. An example plugin is in the
Usage
=====
To create a new plugin, start a sub-folder in plugins. The python file in there must contain a class that inherits from *KaliPlugin*.
To create a new plugin, start a sub-folder in plugins. The python file in there must contain a class that inherits from *AttackPlugin*.
There is an example plugin *hydra.py* that you can use as template.
@ -59,5 +62,5 @@ If you are using the plugin, you **must** have a config section for this kali pl
There are three command line tools that offer a simple interface to PurpleDome.
Experiment control
------------------
Experiment control is the core tool to run an experiment. It accepts a yaml config file and runs the experiments in there. The configuration file defines the system to be used (together with a Vagrant file being referenced there) and the attacks to run.
The central one is Experiment control where you start your experiments:
Experiment control is the core tool to run an experiment. It accepts a yaml config file and runs the experiments in there. The configuration file defines the system to be used (together with a Vagrant file being referenced there) and the attacks to run.
Thorsten Sick
3 years ago
committed by