lili
/
adaptive-game-assistant
Archived
1
0
Fork 0
Code Wiki

assistant readme rewrite finish, first draft

This commit is contained in:
Lili (Tlapka) 2021-05-26 12:20:27 +02:00
parent 229327b179
commit b6ad1db967
1 changed files with 84 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

130
README.md
View File

@ -1,77 +1,115 @@
# Adaptive game assistant # Adaptive game assistant
The adaptive game assistant is a Python program allowing easy deployment and playing of adaptive cybersecurity games. The adaptive game assistant is a Python program allowing easy deployment and playing of adaptive cybersecurity games.
The assistant was made as a part of my [bachelor's thesis]() for the university's KYPO lab, The assistant was made as a part of my [bachelor's thesis]() for the university's KYPO lab.
so it mainly extends the design of games at the KYPO Cyber Range. The original version The version of the assistant included in the thesis appendix required
included in the thesis appendix required that the player get some help from an instructor while playing. that the player get some help from an instructor while playing.
This improved version allows for the player to play through the game completely on their own. This improved version allows for the player to play through the game completely on their own.
The games the assistant can help with must be made with Vagrant and Ansible (as other games for The games the assistant can help with must be made with Vagrant and Ansible (as other games for
the KYPO Cyber Range), and have all tasks in the Ansible playbooks tagged with tags. the KYPO Cyber Range). The Ansible playbooks need to have all tasks tagged, and
There's also a need for some config files in the `resources` subfolder. there need to be game-specific config files in the `resources` subfolder.
## Assistant usage ## Usage
The adaptive game assistant is ran by running `./assistant.py` or `python assistant.py` in the project folder. The adaptive game assistant is ran by running `./assistant.py` or `python assistant.py` in the project folder.
It automatically runs Vagrant commands to prepare levels of the game, It automatically runs Vagrant commands to prepare levels of the game,
checks flags when player completes level and provides hints when needed. checks flags when player completes level and provides hints when needed.
Basic commands: Basic assistant commands:
- (S)tart - starts the game from level 1. - (S)tart - starts the game from level 1.
- (N)ext - continues the game to the next level. - (N)ext - continues the game to the next level.
- (E)xit - properly ends the game and exits the assistant. - (E)xit - properly ends the game and exits the assistant.
- (C)eck - Checks versions of all required apps. - (C)eck - checks versions of all required apps.
- (H)elp - displays a full list of commands. - (H)elp - displays a full list of commands.
- hin(T) - displays hints, offers new hints.
- (L)og - saves data from the game into a file.
The project's wiki also has a detailed user guide with examples: [How to use the assistant]()
## Requirements ## Requirements
The assistant requires Python 3.7 to run. The assistant requires Python 3.7 or higher to run.
It also requires the PyYAML package of version 5.1 or higher. It also requires the PyYAML package of version 5.1 or higher.
(You can install it with `pip install -r python-requirements.txt`) (You can install it with `pip install -r python-requirements.txt`)
The game the assistant will require Vagrant and VirtualBox to be installed. The game the assistant sets up will require Vagrant and VirtualBox to be installed.
Virtualbox 6.0 or higher and Vagrant 2.2.5 or higher are recommended. Virtualbox 6.0 or higher and Vagrant 2.2.5 or higher are recommended.
(The requirements of individual games may differ.) (The exact requirements of individual games may differ.)
## Python module structure ## Python module structure
The assistant consists of a `Game` class, that represents the game itself, and a `game_loop()` function, which keeps an instance of a `Game` and translates inputs from the command line into method calls on the `Game` object. The main file, `assistant.py`, wraps around several classes the `adaptive_game_module` folder,
and transforms the user's commands into method calls on the objects.
The adaptive game module contains:
- `adaptive_game.py`. The `Game` object from this file represents the game itself.
- `flag_checker.py`. The `FlagChecker` class checks if flags are correct.
- `hint_giver.py`. The `HintGiver` class keeps tracks of taken hints and gives new ones.
- `level_selector.py`. The `LevelSelector` class helps decide which level to go to next.
The assistant is written with modularity in mind, so it should support other adaptive games, as long as they provide a correct `levels.yml` file, and has complete tagging in the Ansible playbooks. ### Game config files
### Game and config files The assistant is written with modularity in mind, so it should support other adaptive games,
as long as config files for those are written. `assistant.py` looks for config files in the
`resources/` folder.
### levels.yml The needed files are:
`levels.yml` is the configuration file that tells the assistant what possible levels are in the game, what tags to run to set up that level, and what machines need to be provisioned for that level. - `levels.yml`
- `hints.yml`
- `level_keys.yml`
- `level_requirements.yml`
- `tools.yml`
Every line in the file represents a level, and each line must have the following format: All of the files should be in YAML. There are sample config files present in the `resources/` folder already.
(These are the files I created for the game I used in my thesis.)
#### levels.yml
`levels.yml` tells the Game object what possible levels are in the game, what Ansible tags
are needed for that level, and what machines need changes done.
Each line of the file should be in the the following format:
`level_name: {branch_name: [machines_to_provision]}` `level_name: {branch_name: [machines_to_provision]}`
### I want to try the assistant out, but I have no game on hand
## ??? Manual usage without the assistant `branch_name` is not just the name of the branch, but also the Ansible tag used to provision the level.
#### level_keys.yml
`level_keys.yml` is a dictionary of the level flags for the flag checker.
## ??? Common problems The keys should be in the following format:
- prolly delete `level_name: flag`
#### level_requirements.yml
`level_requirements.yml` is the list of requirements for the level selector.
The requirements should be in the following format:
## Manual usage without assistant `level_name: [[branch_name, requirements]]`
How to play the game without using the adaptive game assistant.
1. Run `ANSIBLE_ARGS='--tags "setup"' vagrant up`. where `requirements` is either `null` or `[time, tool]`
During the instantiation of `br` machine, you will be prompted for network
interface which connects you to internet (usually the first or second in the list). e.g. `level2: [[level2a, null], [level2b, [10, "SQL injection"]]]`
2. When the player finishes a level, it's time to prepare the next one. `null` requirement means that this is the "default" version of the level.
Some levels have multiple versions (level2a, level2b), some levels have only one version (level3). `[time, tool]` means that the player must know `tool` and have time less than `time`.
The file `levels.yml` lists all possible levels,
along with the vagrant boxes that need an update for the level to be ran. The `tools` are expected to also be listed in `tools.yml`.
To prepare the next level, run `ANSIBLE_ARGS='--tags "<level>"' vagrant up <boxes> --provision`, #### tools.yml
where `<level>` is a key from levels.yml, and `<boxes>` is the corresponding value from the same file. `tools.yml` is a list of tools that the assistant will ask the player about before they play the game.
(Examples: `ANSIBLE_ARGS='--tags "level2a"' vagrant up web attacker --provision`,
`ANSIBLE_ARGS='--tags "level3"' vagrant up web --provision`) If the player is familiar with a tool, they may be sent to a harder version of a level by the level selector.
3. After the game is finished, run `vagrant destroy` to remove the game components and virtual machines.
The game can be reran after this step. This file may also contain tools that do not appear in the game.
#### hints.yml
`hints.yml` contains all the hints the player can receive, and should have the following format:
`level_name: level+branch name: hint title: hint text`
As hints are usually long, the sample file uses indentation to make the file better readable.
## I want to try out the assistant, but I don't have an adaptive game.
The simplest way to try the assistant out with no access to another adaptive game is:
1. Download the [thesis archive]() of my Adaptive Cybersecurity Games thesis.
2. In the archive, replace the `assistant/` folder with the folder of this repository.
(The assistant included with the thesis is an earlier version.)
3. Make sure that the sample files in the `resources/` subfolder are present.
The assistant should run the game included with my thesis using the sample resources files.
The level instructions for that game are included in the `wiki/` subfolder of the thesis archive you downloaded.
## Troubleshooting ## Troubleshooting
### Set-up hangs on provisioning machine `br` All known common problems are in the [Troubleshooting doc]() on the repository wiki.
```
==> br: Running provisioner: ansible_local...
```
On Windows, the setup of the game rarely hangs on provisioning of the `br` machine.
When playing via the assistant, you will have to exist by pressing `Ctrl+C`. Then, you should kill the stuck process in the task manager (usually called similarly to `Ruby interpreter` or `Vagrant`)
Then you can resume the game by launching the assistant again, running `abort`, and then `start` again. (You can also attempt to make the assistant pick up where it ended before it got stuck, by not running `abort`, and running `start` only.)