The command line tools are the way you will interact with Purple Dome. Those are described in the *CLI* chapter.
The command line tools are the way you will interact with Purple Dome. Find more in the *CLI* chapter.
The experiments are configured in YAML files, the format is described in the *configuration* chapter. You will also want to create some target VMs. You can do this manually or use Vagrant. Vagrant makes it simple to create Linux targets. Windows targets (with some start configuration) are harder and have an own chapter.
You can configure the experiments in YAML files, the *configuration* chapter describes the format. Next you will also want to create some target VMs. This can be done manually or by using Vagrant. Vagrant makes it simple to create Linux targets. Windows targets (with some start configuration) are harder and have an own chapter.
If you want to modify Purple Dome and contribute to it I can point you to the *Extending* chapter. Thanks to a plugin interface this is quite simple.
If you want to modify Purple Dome and contribute to it I can point you to the *Extending* chapter. Thanks to a plugin interface this is simple.
Data aggregator
---------------
We currently can use logstash
We use logstash
Caldera
-------
Caldera is an attack framework. Especially useful for pen testing and blue team training.
You can use the attack framework Caldera for pen testing and blue team training.
Starting it: *python3 server.py --insecure*
@ -69,7 +69,7 @@ Web UI on *http://localhost:8888/*
@ -6,7 +6,7 @@ Configuration is contained in yaml files. The example shipped with the code is *
For your first experiments use *hello_world.yaml* which will run a simple attack on a simulated system.
To define the VMs there are also *Vagrantfiles* and associated scripts. The example shipped with the code is in the *systems* folder. Using Vagrant is optional.
To define the VMs there are also *Vagrantfiles* and associated scripts. The example shipped with the code can be found in the *systems* folder. Using Vagrant is optional.
Machines
========
@ -27,7 +27,7 @@ You can install vulnerabilities and weaknesses in the targets to allow your atta
Sensors
=======
Sensors are all kinds of technology monitoring system events and collecting data required to detect an attack. Either while it happens or as a forensic experiment.
All kinds of technology monitoring system events and collecting data required to detect an attack is referred as a "sensor" here. Data collection is done either while the attack happens or as a forensic experiment afterwards.
Each machine can have a list of sensors to run on it. In addition there is the global *sensor_conf* setting to configure the sensors.
@ -39,7 +39,7 @@ Attacks
caldera_attacks
---------------
Caldera attacks (called abilities) are identified by a unique ID. Some abilities are built to target several OS-es.
Caldera attacks (called abilities) are identified by a unique ID. Some abilities are built to target multiple OS-es.
All Caldera abilities are available. As some will need parameters and PurpleDome does not offer the option to configure those in the YAML, some caldera attacks might not work without implementing a plugin.
@ -55,7 +55,7 @@ In the YAML file you will find two sub-categories under plugin_based_attacks: li
attack_conf
-----------
All plugin based attacks can use configuration. This is in plugin-name sub categories in here.
All plugin based attacks can use configuration. Find more in the plugin-name sub categories in here.
Attack features of PurpleDome can be extended using a plugin system. Those attack plugins can start Caldera attacks, run Kali command line tools or use Metasploit.
Extend attack features of PurpleDome by the plugin system. Those attack plugins can start Caldera attacks, run Kali command line tools or 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.
..attention::
This projects goal is to improve defense. Adding any attack must be done with this goal in mind. To guarantee that:
Improving defense is the goal of this project. Kepp this goal in mind when you add an attack. To guarantee that:
* Only add attacks that are already used by malware and attackers
* Add attacks that are **already used** by malware and attackers
* Link to blog posts describing this attack
* Maybe already drop some ideas how to detect and block
* Or even add code to detect and block it
@ -28,11 +28,11 @@ The boilerplate contains some basics:
* name: a unique name, also used in the config yaml file to reference this plugin
* description: A human readable description for this plugin.
* ttp: The TTP number of this kali attack. See https://attack.mitre.org/ "???" if it is unknown "multiple" if it covers several TTPs
* ttp: The TTP number of this kali attack. See https://attack.mitre.org/ "???" if unknown, "multiple" if it covers several TTPs
* references. A list of urls to blog posts or similar describing the attack
* required_files: A list. If you ship files with your plugin, listing them here will cause them to be installed on plugin init.
* required_files: A list. If you ship files with your plugin, listing them here will install them on plugin init.
Better than using required_files is to use:
Better than using required_files use:
* required_files_attacker: required files to send to the attacker
* required_files_target: required files to send to the target
I recommend to start contributing code by using the plugin system. But beyond that there is much more you can do.
Code code
=========
Code
====
Several core module create the system. They are in the *app* folder
Core modules create the system. Find them in the *app* folder
* experimentcontrol: Control experiments. This is the central control for everything
* calderaapi_2: Direct REST Api to caldera 2.* (deprecated)
* calderaapi_4: Direct REST Api to caldera 4.* (Caldera 4 is alpha)
* calderacontrol: Remote control for Caldera with convenience methods
* metasploit: Metasploit control. Simplifies the basic attack step so they can be used from plugins
* metasploit: Metasploit control. Simplifies the basic attack step to make them usable from plugins
* machinecontrol: Create/start and stop VMs. Will call the machinery plugin
* pluginmanager: Plugin manager tasks. Has methods to verify plugin quality as well
* config: Reading and processing configuration files
@ -93,7 +93,7 @@ Class controlling the experiment
Config
------
Internal configuration handling. Currently there are two classes. One for the whole experiment configuration. The second one for machine specific configuration.
Internal configuration handling. There are two classes. One for the whole experiment configuration. The second one for machine specific configuration.
To experiment with different sensors installed on the targets there is the sensor plugin. It contains a plugin class that **MUST** be based on the *SensorPlugin* class.
The main goal of PurpleDome is to study sensor technology: what data can be collected and how to create an accurate picture of what happens during an attack. So this can be one of the most important plugin classes to extend.
The main goal of PurpleDome is to study sensor technology: what data can be collected and how to create an accurate picture of what happens during an attack. This can be one of the most important plugin classes to extend.
Usage
=====
To create a new plugin, start a sub-folder in plugins. The python file in there must contain a class that inherits from *SensorPlugin*.
If the plugin is activated for a specific machine specific methods will be called to interact with the target. Especially:
If the plugin is activated for a specific machine specific methods will be called to interact with the target:
* start: Start the sensor
* stop: Stop the sensor
@ -26,22 +26,22 @@ The boilerplate contains some basics:
* description. A human readable description for this plugin.
* required_files: A list. If you ship files with your plugin, listing them here will cause them to be installed on plugin init by creating a copy in the share.
Additionally you can set *self.debugit* to True. This will run the sensor on execution in gdb and make the call blocking. So you can debug your sensor.
In addition to that you can set *self.debugit* to True. This will run the sensor on execution in gdb and make the call blocking. this way you can debug your sensor.
Method: collect
---------------
This is the essential method you will have to implement. It will collect the data produced by the sensor and make it available to be stored in the zip-results
This is the essential method you will have to implement. It will collect the data produced by the sensor and make it available for storage in the zip-results
Method: start
-------------
Also an important method. Will be called before the attack to start the sensor. You will have to implement this. *But* if your collect method just collects log files from the system that are already generated you can also skip that.
Also an important method. Called before the attack to start the sensor. You will have to implement this. *But* if your collect method just collects log files from the system you can also skip that.
Method: stop
------------
Will stop the sensor just prior to calling collect. There could be scenarios where you do not need it.
Will stop the sensor just prior to calling collect. This is not required in all possible scenarios.
The experiment being run handles the machines. Those machines can be targets or attacker machines. Different types of machine controllers are covered by plugins of the type "MachineryPlugin".
a
A VM plugin handles several things:
* vm creation/destruction
* vm starting/stopping
VM controller plugins can use SSH as a mixin class. This is implemented in *ssh_features.py* and reduces code duplication. In certain cases (for example if SSH needs some extra features) you can extend or replace methods from there. SSH handles:
VM controller plugins can use SSH as a mixin class - implemented in *ssh_features.py* and reduces code duplication. In certain cases (for example if SSH needs some extra features) you can extend or replace methods from there. SSH handles:
* connecting to the VM and running commands there
* Copying files from and to the VM
@ -21,7 +21,7 @@ Usage
To create a new plugin, start a sub-folder in plugins. The python file in there must contain a class that inherits from *MachineryPlugin*.
There is an example plugin *vagrant_plugin.py* that you can use as template.
Use the example plugin *vagrant_plugin.py* as template.
Boilerplate
-----------
@ -30,10 +30,10 @@ The boilerplate contains some basics:
* name: a unique name, also used in the config yaml file to reference this plugin
* description. A human readable description for this plugin.
* required_files: A list. If you ship files with your plugin, listing them here will cause them to be installed on plugin init.
* required_files: A list. If you ship files with your plugin, listing them here will install them on plugin init.
There are two sets of commands to implement for machines
Two sets of commands to be implemented for machines
Basic handling:
@ -52,7 +52,7 @@ Communication:
* put
* get
The communication commands are already implemented in *ssh_features.py* and you can use them they way the vagrant_plugin.py is doing. At least as long as you want to use SSH to communicate (recommended !).
The communication commands are already implemented in *ssh_features.py* and you can use them they way the vagrant_plugin.py does. At least as long as you want to use SSH to communicate (recommended !).
For an attack to leave attack traces the target machie machine should be vulnerable. This means:
For an attack to leave attack traces the target machine machine should be vulnerable. This means:
* Services run
* Old and unpatched application are installed
@ -10,7 +10,7 @@ For an attack to leave attack traces the target machie machine should be vulnera
You get the idea.
To get your systems vulnerable there is a vulnerability plugin type that adds vulnerabilities to targets.
To get your systems vulnerable use a *vulnerability* plugin type that adds vulnerabilities to targets.
This plugin type allows you to punch some holes into the protection of a machine. Which vulnerability plugins are loaded for a specific target is defined in the configuration file. Feel free to weaken the defenses.
@ -19,7 +19,7 @@ Usage
To create a new plugin, start a sub-folder in plugins. The python file in there must contain a class that inherits from *VulnerabilityPlugin*.
There is an example plugin *linux_sshd_config_issues.py* that you can use as template.
An example plugin is the file *linux_sshd_config_issues.py* you can use as template.
Boilerplate
-----------
@ -28,9 +28,9 @@ The boilerplate contains some basics:
* name: a unique name, also used in the config yaml file to reference this plugin
* description: A human readable description for this plugin.
* ttp: The TTP number linked to this vulnerability. See https://attack.mitre.org/ as a hint which TTP this vulnerability could be related to. If you do not know the TTP, use "???"
* ttp: The TTP number linked to this vulnerability. See https://attack.mitre.org/ as a hint which TTP this vulnerability is related to. If you do not know the TTP, use "???"
* references: A list of urls to blog posts or similar describing the vulnerability
* required_files: If you ship files with your plugin: listing them here will cause them to be installed on plugin init.
* required_files: If you ship files with your plugin: listing them here will install on plugin init.
There are three command line tools that offer a simple interface to PurpleDome.
Three command line tools exists offering a simple interface to PurpleDome.
The central one is Experiment control where you start your experiments:
@ -16,7 +16,7 @@ The central one is Experiment control where you start your experiments:
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.
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 referenced there) and the attacks to run.
Thorsten Sick
2 years ago