DigitalTwinSocCyberrange

DigitalTwinSocCyberrange is a research project by the University of Regensburg and the Ionian University. This prototype aims to provide training for SOC analysts in a highly realistic scenario making use of the simulation component of the digital twin of an industrial filling plant. In the scenario, an attacker has gained access to the industrial system and performs various attacks (Man-In-The-Middle-Attack, Log-File-Manipulation-Attack and Denial-Of-Service-Attack) to disrupt the filling plant. The components of the industrial system thereby produce log data which are forwarded to a SIEM system. Completing the tasks of the cyber range, a trainee gains knowledge about the selected attacks on the industrial system and how to detect these attacks in a SIEM system by creating correlation rules. The following video gives an introduction to the project and the learning concept of the cyber range.

User interface of the cyber range:

The concept was evaluated in an extensive user study. The results of the user study are presented in the userStudy repository.

Architecture of the prototype

• The Virtual Environment consists of the simulation component of a Digital Twin which is tailored to the needs of the cyber range scenario. It is implemented with MiniCPS, an academic framework for simulating cyber-physical systems which builds upon Mininet. The simulated attacks are performed with Ettercap and hping. The firewall functionalities are implemented with Scapy.
• The SIEM system is realized with Dsiem, which builds upon Filebeat, Elasticsearch, Logstash and Kibana.

The Digital Twin Simulation and the SIEM system of the prototype are based on a microservice architecture realized with Docker Containers.

• The Learning Management System (LMS) is implemented with the JavaScript Framework Vue.js. The respective source code is stored in the frontendCyberrange repository of the project.
• A REST-API implemented with Flask connects the LMS, the Digital Twin and the SIEM-System
• The user data is stored in a Firestore collection, described in detail here

Installation (for Ubuntu 20.04)

1. Install Docker and Docker-Compose as described in the respective docs
2. Clone the required repositories:

git clone git@github.com:DigitalTwinSocCyberrange/DigitalTwinCyberrange.git && \
git clone git@github.com:DigitalTwinSocCyberrange/frontendCyberrange.git

3. Install dependencies for deployment of the frontend:

cd frontendCyberrange && \
bash setup_frontend.sh

4. Install dependencies for deployment of the Flask-Api:

cd DigitalTwinCyberrange && \
bash setup_python.sh

5. Setup and start the cyber range: This will start the microservice-infrastructure (Elasticsearch, Filebeat, Logstash, Kibana, Dsiem and Digital Twin), the cyber range frontend (running on port 7080) and the API that connects both

cd deployments/docker && \
bash init_cyberrange.sh

6. Enter the ip address or hostname where the cyber range should be deployed. Usually, this is either the default ip address of the maschine or localhost. 199.999.9.99 is used as an example ip address here.

Enter the Hostname or IP Address where the cyber range will be deployed: 199.999.9.99

7. Access the cyber range on port 7080: http://199.999.9.99:7080. To get an idea of the prototype, you can use the demo user (without user data management) ID=127

8. If you want to conduct a cyber range training with multiple participants and use the scoreboard, please proceed with User Data Management

Frontend only installation (Windows, MacOS)

To install only the frontend (e.g. for development) on Windows or MacOS, download the latest version of https://nodejs.org/en/[nodejs].

1. Replace the demo code in firebase.js with the credentials of your own firebase database.

2. In the frontendCyberrange directory, run

npm install

followed by

npm run serve

The frontend then runs on port 7080 of localhost

Shutdown

To shut down the infrastructure you can either the use the API-functionality http://199.999.9.99:9090/stop_cr or run the shutdown script:

cd deployments/docker && \
bash docker_stop.sh

Startup

To restart the infrastructure you can either the use the API-functionality http://199.999.9.99:9090/start_cr or run the startup script:

cd deployments/docker && \
bash start_docker_api.sh

User Data Management

User data management enables the gamification aspect of the cyber range with a score board displaying the scores of the other players in order to motivate the trainees to engage well in the training.

Furthermore, storing the progress of each user in a central database enables the trainer to monitor the conduction of the training and facilitates to evaluate the training after conduction. Every trainee initially needs to be assigned the following attributes.

• userID: randomly chosen ID to log into the cyber range, primary key of the Firestore Collection
• username: each userID is assigned a username. This is displayed on the scoreboard
• round: refers to the round (or the group) of conduction of the cyber range training. The trainee will only see the scores of the players that are playing in the same round as he or she does

While taking part in the cyber range training the following data is recorded:

• points: current score of the trainee (out of a maximum score of 101)
• level: number of tasks the trainee has completed
• startTime: timestamp when the trainee first logged in
• taskTimes: time the trainee took to solve a task

Create Firestore Collection

1. Within a Firebase project create a Firestore collection named "cyberrangeDashboard" as described here.
2. To link the cyber range to your collection copy the firebaseConfig object from the firebase console (Settings -> General) as described here and add it to the configruation file firebase.js.

Create user data

1. Create a list containing the user data with a tuple of userID, username and round

userID	username	round
7683	SudoSven	1
1235	SecuritySandra	1
2364	RootRuth	1
2346	Crewmate	2
5671	AnonymousAnna	2
2397	MrsRobot	2

This example user data set provides user data for two rounds of training with three trainees each.

2. Add all valid userIDs to the usernames.js file in the frontend project. For the previous example this would be adding userIDs 7683, 1235, 2364, 2346, 5671 and 2397.
3. Either add the user data manually to the Firestore collection or use the provided python scripts as described in the next section to import user data from a csv file to the Firestore collection.

Import and export of user data with .csv files

1. Create a Service Account on Firebase. This can be done on the Firebase Dashboard via Settings -> Service Account -> "Generate Private Key" as described here
2. Replace the file serviceAccount.json with your created key (also naming it serviceAccount.json)
3. Replace the sample user data in userdata.csv with your user data sets
4. Install firebase package

sudo pip install firebase-admin

5. Run import script:

cd frontendCyberrange/userDataScripts && \
python3 importFromCsv.py

To export user data (points, level, times) after the training, run:

cd frontendCyberrange/userDataScripts && \
python3 exportToCsv.py

Research and Citation

Please consider citing our DBSec'21 publication when using the DigitalTwinSocCyberrange for your research.

Conference presentation