README.md 3.66 KB
Newer Older
1
# Cyber Sandbox Creator
Jan Vykopal's avatar
Jan Vykopal committed
2

3
Cyber Sandbox Creator is a tool that can generate portable input files for building lightweight virtual environments using Vagrant and Ansible from a simple YAML definition of topology. The combination of these three tools makes it possible to build virtual machines connected with virtual networks even on a desktop computer.
Attila Farkas's avatar
Attila Farkas committed
4

Attila Farkas's avatar
Attila Farkas committed
5
![usage](doc/sandbox_creator_general.svg "Usage")
Attila Farkas's avatar
Attila Farkas committed
6

7
8
9
---

**Note: This is just a quick guide how to install and generate files with Cyber Sandbox Creator. For full description of how to prepare the host device to run the generated environments and how to build the virtual machines, check our [wiki page](https://gitlab.ics.muni.cz/muni-kypo-csc/cyber-sandbox-creator/-/wikis/Installation-and-Usage).**
Attila Farkas's avatar
Attila Farkas committed
10

11
12
13
**The latest stable release is available in [Releases](https://gitlab.ics.muni.cz/muni-kypo-csc/cyber-sandbox-creator/-/releases).**

## Installation
Attila Farkas's avatar
Attila Farkas committed
14

Jan Vykopal's avatar
Jan Vykopal committed
15
### Linux (Ubuntu/Debian)
Attila Farkas's avatar
Attila Farkas committed
16
17
18
19
20
21
22
23

1. Install git using the command `$ sudo apt-get install git`.
2. Clone the project with `$ git clone https://gitlab.ics.muni.cz/cs4eu/sandbox-creator.git` to an arbitrary directory.
3. Navigate to the project directory (`$ cd sandbox-creator`).
4. Install pip using `$ sudo apt-get install python3-pip`.
5. Install setuptools with `$ pip3 install setuptools`.
6. Install dependencies with the command `$ pip3 install -r requirements.txt`.

Attila Farkas's avatar
Attila Farkas committed
24
### Windows 10
Attila Farkas's avatar
Attila Farkas committed
25
26
27
28

1. Install [Python 3](https://www.python.org/downloads/windows/). At the beginning of the installation mark the "Add Python to PATH" option.
2. Install [git](https://git-scm.com/downloads).
3. Clone the project with `git clone https://gitlab.ics.muni.cz/cs4eu/sandbox-creator.git` to an arbitrary folder.
Attila Farkas's avatar
Attila Farkas committed
29
4. Navigate to the project folder (`cd sandbox-creator`).
30
5. Install Python dependencies using the command `python -m pip install -r requirements.txt`.
Attila Farkas's avatar
Attila Farkas committed
31

Attila Farkas's avatar
Attila Farkas committed
32
## Usage
Attila Farkas's avatar
Attila Farkas committed
33

Jan Vykopal's avatar
Jan Vykopal committed
34
### Linux (Ubuntu/Debian)
Attila Farkas's avatar
Attila Farkas committed
35

36
1. After the installation, simply run the command `$ python3 create.py topology.yml` to generate intermediate definition files.
Attila Farkas's avatar
Attila Farkas committed
37
38
2. Navigate to the newly created directory `sandbox` and run `$ vagrant up` to build the virtual environment.
3. The built environment can be deleted using the command `$ vagrant destroy -f`.
Attila Farkas's avatar
Attila Farkas committed
39

Attila Farkas's avatar
Attila Farkas committed
40
### Windows 10
Attila Farkas's avatar
Attila Farkas committed
41

42
1. Generate files using the command `python create.py --ansible_local topology.yml`.
43
2. Navigate to the newly created directory `sandbox` and run `vagrant up` to build the virtual environment.
Attila Farkas's avatar
Attila Farkas committed
44
3. The built environment can be deleted using the command `vagrant destroy -f`.
Attila Farkas's avatar
Attila Farkas committed
45

46
47
48
49
## License

This project is licensed under the [MIT License](LICENSE).

Attila Farkas's avatar
Attila Farkas committed
50
## Credits
Attila Farkas's avatar
Attila Farkas committed
51

52
**[Cybersecurity Laboratory](https://kypo.fi.muni.cz)**\
Attila Farkas's avatar
Attila Farkas committed
53
**Faculty of Informatics**\
Attila Farkas's avatar
Attila Farkas committed
54
**Masaryk University**
Attila Farkas's avatar
Attila Farkas committed
55

56
57
**Project lead**: Jan Vykopal

Attila Farkas's avatar
Attila Farkas committed
58
**Lead developer**: Attila Farkas
Attila Farkas's avatar
Attila Farkas committed
59

Jan Vykopal's avatar
Jan Vykopal committed
60
61
**Developer**: Jana Ziková

62
**Contributors**:
Attila Farkas's avatar
Attila Farkas committed
63

64
65
66
- Valdemar Švábenský - user testing
- Daniel Tovarňák (KYPO Cyber Range Platform) - technical advisor
- Kamil Andoniadis (KYPO Cyber Range Platform)
Jan Vykopal's avatar
Jan Vykopal committed
67

68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
**Student contributors:**  all students who use the tool for their thesis projects or training

### Acknowledgements

<table>
  <tr>
    <td>![EU](doc/EU.jpg "EU emblem")</td>
    <td>
This software and accompanying documentation is part of a [project](https://cybersec4europe.eu) that has received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement No. 830929.
</td>
  </tr>
  <tr>
      <td>![TACR](doc/TACR.png "TACR logo")</td>
      <td>This software was developed with the support of the Technology Agency of the Czech Republic (TA ČR) from the National Centres of Competence programme (project identification TN01000077 – [National Centre of Competence in Cybersecurity](https://nc3.cz/)). 
      </td>
  </tr>
 </table>
Jan Vykopal's avatar
Jan Vykopal committed
85

Jan Vykopal's avatar
Jan Vykopal committed
86

Jan Vykopal's avatar
Jan Vykopal committed
87

Jan Vykopal's avatar
Jan Vykopal committed
88