A Docker runner for docker-based vulnerable environments.
Project description
Docker Vuln Runner
A Docker runner for docker-based vulnerable environments.
Table of Contents
Overview
vuln-runner
is a tool that allows you to quickly run the docker vulnerable stacks.
The vulnerable stack actually supported are:
At SecSI we found it useful to reproduce vulnerable environments for training purposes. To reproduce vulnerable environment easily, take a look at DSP.
Install
You can easily install it by running:
pip install vuln-runner
This will install three basic command:
- vuln-runner: the basic module to run vuln-runner in local-mode;
- vuln-controller: the controller module that manages a set of vuln-nodes ;
- vuln-node : a vulnerable node that can receive commands from a vuln-controller.
Local Usage
It is possible to use vuln-env in local-mode. The docker environment is installed locally and it all the vulnerable stacks runs locally.
vuln-runner --help
This will display help for the tool. Here are all the switches it supports.
Usage: vuln-runner [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
Commands:
down Down a list of vulnerable projects
down-env Down an environment
generate-vulnenv Generate <no_env> vulnerable environments composed of...
init
list List the vulnerable names
run Run a list of vulnerable projects
run-env Run an environment taken from a JSON configuration file
update Update the vulnerable git repositories
- Initialized the vulnerable environment:
vuln-runner init
- List the vulnerable stacks:
vuln-runner list
- Run a list of vulnerable stacks:
vuln-runner run vulhub.CVE-2014-3120,vulhub.CVE-2018-1270
- Down the list of vulnerable stacks:
vuln-runner down vulhub.CVE-2014-3120,vulhub.CVE-2018-1270
Advanced usage: vulnerable environment
With the previous commands you can already manage your vulnerable stacks and manually run and stop them.
Anyway, you can also create vulnerable environments.
A vulnerable environment is a set of vulnerable docker-compose stacks that has not ports' conflicts.
You can generate a vulnerable environment descriptor in JSON format with the generate-vulnenv
command:
vuln-runner generate-vulnenv NO_VULNS [--no-env=<default=1>]
NO_VULNS
defines the number of vulnerable stacks for each environment.--no-env
defines the number of environments. It is useful if you want to run vuln-runner in different hosts, where each host runs a single environment.
For example, to create a JSON vulnerable descriptor with two vulnerable stack and two environments:
vuln-runner generate-vulnenv 2 --no-env=2
You can output into the JSON descriptor into a file an reuse with two commands:
- run-env: run the set of stacks belonging to a vulnerable environment.
vuln-runner run-env output.json 1
- down-env: down the vulnerable environment.
vuln-runner down-env output.json 1
Distributed Usage
It is possible to use vuln-runner
in distributed-mode:
- vuln-nodes initialize a token and run a tcp server that listens for commands
- A vuln-controller initializes the same token and can manage the vulnerable environments
The example architecture is shown in the following Figure:
node configuration
- Initializes the node:
vuln-runner init
vuln-node init
You have to define a token that will be used to validate the requests that comes from a controller.
- Start the vulnerable node:
vuln-node start
From this moment the vuln-node
listens for connections on port 4545 .
When a vuln-node is listening for a connection the controlle is able to find it through the discovery step.
controller configuration
- Initialize the controller
vuln-runner init
vuln-controller init
- Discover the remote nodes
vuln-controller discovery <subnet_vulnerable_nodes> -u
Through this command the controller finds all the hosts presents in the network.
When the -u
option is used, the hosts.json
configuration file present in the ~/.vulnenv folder is updated with the list of the vuln-nodes.
- Generate the vulnerable environments
After the configuration thehosts.json
it is possible to generate a vulnerable environment configuration composed of<no_env>
vulnerable scenarios. For example, the following command:
vuln-controller generate-vulnenv 2
generates two vulnerable environment for each vuln-node
discovered previosly.
- Manage the enviornments
To run a single vulnerable environment:
vuln-controller run-env <ip>
It is also possible to run all the vulnerable environments:
vuln-controller run-envs
To shutdown the environments:
vuln-controller down-envs
Design considerations for the distributed architecture
The token is used to authenticate the requests that comes from the controller. It is not used as secure mechanism. All the protocol is unencrypted, as we suppose that the environment is "unsecure-by-default". It is used to setup vulnerable machines. An attacker could potentially intercepts the requests and put them down.
You could setup firewall rules to allow the connections to the 4545 only from the controller IP host.
This is useful as the students should not be able to see that port.
Development
The poetry packaging and management tool was used to build the project.
To initialize the project:
poetry install
To run the several commands, you can use poetry as follows:
poetry run vuln-runner <command>
Credits
Developed by gx1 @SecSI
License
Docker Vuln Runner is released under the GPL LICENSE
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for vuln_runner-0.1.6-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 02fc91d36e5a7806b0958764e76f7e232f442fc18266c0a5abc71e14ad6d6476 |
|
MD5 | 851bc3cd644651b932b77d19e8831f95 |
|
BLAKE2b-256 | 347e924d49a5a9649555e850e2cd611eec2fd7cc496d5a7e79e530b7e3b02262 |