enosimulator 0.3.4

Simulating an attack defense CTF competition using the game engine and services provided by Enowars

About

This software can be used to simulate an attack/defense cybersecurity competition using the game engine and services provided by Enowars. For further information on how to use it, please refer to the documentation.

Getting Started

Prerequisites

• Download and install the latest versions of Python and Pip.
• Download and install the latest version of Terraform.
• Download and install the latest version of Packer.
• Create an account with your preferred cloud provider (currently supporting Microsoft Azure and Hetzner Cloud).
• If you are using Windows, make sure to install Git Bash and add C:\Program Files\Git\bin to your PATH environment variable to be able to run shell scripts.

Setup

Pip

1. Install the package via pip:

   pip install --user enosimulator
   

2. Start the simulation with the following command:

   enosimulator -c /path/to/config.json -s /path/to/secrets.json -v
   

Manual

1. Clone the repository to your local machine as follows:

   git clone https://github.com/ashiven/enosimulator.git
   

2. Install the necessary dependencies:

   pip install --user -r requirements.txt
   

3. Start the program (paths to the configuration files can also be defined in the environment variables ENOSIMULATOR_CONFIG and ENOSIMULATOR_SECRETS):

   python enosimulator -c /path/to/config.json -s /path/to/secrets.json
   

4. Navigate to the frontend directory and start the frontend:

   cd ./frontend && npm install && npm run build && npm run start
   

5. A graphical user interface is available at http://localhost:3000 to monitor the simulation. (It may take up to 20 minutes for the simulation to start.)

Docker

1. Clone the repository to your local machine as follows:

   git clone https://github.com/ashiven/enosimulator.git
   

2. Create an SSH key pair in the config directory:

   ssh-keygen -f ./enosimulator/config/simkey
   

3. Specify simulation details in enosimulator/config/config.json and enosimulator/config/secrets.json with the following SSH key paths.

   {
      "vm-secrets": {
         "ssh-public-key-path": "/app/enosimulator/config/simkey.pub",
         "ssh-private-key-path": "/app/enosimulator/config/simkey"
      }
   }
   

   {
      "setup": {
         "ssh-config-path": "/app/enosimulator/config/simconfig"
      }
   }
   

4. Start the docker containers:

   docker compose up -d
   

5. A graphical user interface is available at http://localhost:3000 to monitor the simulation. (It may take up to 20 minutes for the simulation to start.)

Configuration

There are two configuration files that need to be supplied before launching the simulation (examples can be found here).

secrets.json

{
   "vm-secrets": {
      "github-personal-access-token": "<string> <required> <a github personal access token that will be used on machines to pull repositories>",
      "ssh-public-key-path": "<string> <required> <path to the public key that will be stored on machines>",
      "ssh-private-key-path": "<string> <required> <path to the matching private key that will be used to connect to machines>"
   },
   "cloud-secrets": {
      "azure-service-principal": {
         "subscription-id": "<string> <required> <the azure subscription id>",
         "client-id": "<string> <required> <the azure service principal client id>",
         "client-secret": "<string> <required> <the azure service principal client secret>",
         "tenant-id": "<string> <required> <the azure service principal tenant id>"
      },
      "hetzner-api-token": "<string> <required> <the hetzner api token>"
   }
}

config.json

{
   "setup": {
      "ssh-config-path": "<string> <required> <the path, including filename, where the ssh config for the simulation should be saved locally>",
      "location": "<string> <required> <'local' or the name of the cloud provider to be used for the simulation setup>",
      "vm-sizes": {
         "vulnbox": "<string> <required> <the size of the vms that should be used for the vulnboxes>",
         "checker": "<string> <required> <the size of the vms that should be used for the checkers>",
         "engine": "<string> <required> <the size of the vms that should be used for the engine>"
      },
      "vm-image-references": {
         "vulnbox": "<string> <optional> <a vm image that should be used for vulnboxes>",
         "checker": "<string> <optional> <a vm image that should be used for checkers>",
         "engine": "<string> <optional> <a vm image that should be used for the engine>"
      }
   },
   "settings": {
      "duration-in-minutes": "<int> <required> <the duration of the simulation in minutes>",
      "teams": "<int> <required> <the number of teams that should participate in the simulation>",
      "services": "<List(string)> <required> <the repository names of the services that should be used for the simulation>",
      "checker-ports": "<List(int)> <required> <the port numbers of the service checkers. the order should be the same as in services>",
      "simulation-type": "<string> <required> <the type of simulation to run. choose between 'realistic', 'basic-stress-test', 'stress-test' and 'intensive-stress-test'>",
      "scoreboard-file": "<string> <optional> <the path to a scoreboard file in json format from a past competition that will be used to derive a team experience distribution for the simulation>"
   },
   "ctf-json": {
      "title": "<string> <required> <the title of the ctf>",
      "flag-validity-in-rounds": "<int> <required> <the number of rounds a flag is valid>",
      "checked-rounds-per-round": "<int> <required> <the number of rounds checked per round>",
      "round-length-in-seconds": "<int> <required> <the length of a round in seconds>"
   }
}

Packer Images

The deployment process can be sped up considerably by using virtual machine images that were created with Packer. The following steps describe how to create such images.

1. Navigate to the packer directory for your chosen cloud provider. For example, for Hetzner Cloud:

   cd ./packer/hetzner
   

2. Install the Hetzner plugin for Packer:

   packer plugins install github.com/hashicorp/hcloud
   

3. Modify the available provisioning scripts and build templates to your liking. For example, you can add the specific services to be played during the simulation.

4. Make sure to also add your GitHub Personal Access Token to the provisioning script so it can be used to pull repositories from GitHub. For this, modify the following line in the provisioning script:

   pat="<insert-your-token-here>"
   

5. Build the image:

   packer build -var 'hcloud_token=<insert-your-token-here>' your-packer-template.json
   

Monitoring

Browser UI

There is a browser UI available at http://localhost:3000 that can be used to monitor the simulation.

CLI

To receive detailed information about the current state of the simulation in the CLI, start the program with the -v flag. The following command should be used:

python enosimulator -c /path/to/config.json -s /path/to/secrets.json -v

Scoreboard

The current state of the scoreboard can be monitored via the public IP address of the engine VM. It is available at http://<engine-ip>:5001/scoreboard.

Direct connections via SSH

During the process of building the simulation infrastructure, an SSH configuration file will be generated in the location specified inside config.json. To connect to a specific VM via SSH, use the following command:

ssh -F /path/to/simconfig <vm-name>

---

GitHub @ashiven  ·  Twitter ashiven_