From e1df094fd537e395abf2db9f01b019e866df6d23 Mon Sep 17 00:00:00 2001 From: Thorsten Sick Date: Wed, 9 Jun 2021 13:46:33 +0200 Subject: [PATCH] Documentation upgrade --- README.md | 59 ++++++++++++++----- .../{kali_plugins.rst => attack_plugins.rst} | 15 +++-- doc/source/index.rst | 2 +- 3 files changed, 55 insertions(+), 21 deletions(-) rename doc/source/extending/{kali_plugins.rst => attack_plugins.rst} (80%) diff --git a/README.md b/README.md index 849bf13..5eed7ae 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,62 @@ -# Creates vulnerable systems +# 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 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. Documentation is using sphinx diff --git a/doc/source/extending/kali_plugins.rst b/doc/source/extending/attack_plugins.rst similarity index 80% rename from doc/source/extending/kali_plugins.rst rename to doc/source/extending/attack_plugins.rst index 7668989..6478792 100644 --- a/doc/source/extending/kali_plugins.rst +++ b/doc/source/extending/attack_plugins.rst @@ -1,8 +1,11 @@ -************ -Kali plugins -************ +************** +Attack plugins +************** -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 The plugin class ================ -.. autoclass:: plugins.base.kali.KaliPlugin +.. autoclass:: plugins.base.attack.AttackPlugin :members: \ No newline at end of file diff --git a/doc/source/index.rst b/doc/source/index.rst index f648363..80f921c 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -27,7 +27,7 @@ Welcome to the Purple Dome documentation! extending/vulnerability_plugins.rst - extending/kali_plugins + extending/attack_plugins extending/sensor_plugins