From bad5615efe4e4c596a968f022e3ce5457b8e2d13 Mon Sep 17 00:00:00 2001 From: "Lili (Tlapka)" Date: Tue, 30 Jan 2024 15:06:35 +0100 Subject: [PATCH] add assistant guide --- Assistant-guide.-.md | 197 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 197 insertions(+) create mode 100644 Assistant-guide.-.md diff --git a/Assistant-guide.-.md b/Assistant-guide.-.md new file mode 100644 index 0000000..0ca8549 --- /dev/null +++ b/Assistant-guide.-.md @@ -0,0 +1,197 @@ +# How to use the assistant +This guide will describe all the functions of the assistant. +Please read it before playing. + +The game is controlled completely by running the assistant script. +The script is located in the `assistant` subfolder, and you launch it +by running `python assistant.py` (or `./assistant.py`) in terminal in the folder. + +On Windows, you can use the command line or PowerShell, but make sure you're +running it as an administrator! The game will error out otherwise. + +The assistant tells you the basic commands when you launch it, +and you can type `help` anytime to get a list of all commands. +## Double-checking that everything is in order +Before launching the game, you can run `git pull` to make sure that you are on the latest project version. + +Then you are free to start the assistant script. Before launching the game, you can double-check that your installation +is in order by typing `check`: +``` +Welcome to the adaptive game assistant. +Basic commands are: +(S)tart, (N)ext, (H)elp, (C)heck, (E)xit +Waiting for your input: +check +checking Python version: +OK, Python version higher than 3.7. +checking Vagrant version: +OK, Vagrant version higher than 2.2. +checking Virtualbox version: +OK, VirtualBox version higher than 5 detected. +Waiting for your input: +``` +If the assistant tells you that everything is OK, you can move on to playing +the game. + +If you tried to play the game previously and something went wrong, you can also +make sure there are no leftover files by typing `abort`: +``` +Waiting for your input: +abort +Aborting game, deleting all VMs. +==> attacker: Forcing shutdown of VM... +==> attacker: Destroying VM and associated drives... +==> web: Forcing shutdown of VM... +==> web: Destroying VM and associated drives... +==> br: Forcing shutdown of VM... +==> br: Destroying VM and associated drives... +==> internet-router: Forcing shutdown of VM... +==> internal-router: Forcing shutdown of VM... +==> internal-router: Destroying VM and associated drives... +Game aborted, progress reset, VMs deleted. +Waiting for your input: +``` +## Starting the game +You start the game by typing `start` in the assistant. +What will follow is a short quiz where you answer yes/no questions. +### The quiz +Your answers to the quiz will help the assistant decide what levels you will +play. +``` +Waiting for your input: +start +Before the game starts, please fill in a little quiz. +It will help better decide what levels you will play. +Please answer 'yes' if you have ever used a tool or skill before, +or 'no' if you haven't. +Are you familiar with metamask? +no +Are you familiar with SQL injection? +yes +Are you familiar with webshell? +``` +If you suddenly realize that you can't play the game just yet, you can +interrupt the quiz by typing `exit` as well. The game will not start. + +## Setup +After you fill out the quiz, the assistant will set up the virtual environment +for the game. This can take a while (20-30 minutes), so you should be patient. + +During this initial set-up, the assistant may also ask for your input when it's setting up an internet connection for the virtual machines. It will ask you for an internet provider - it's usually the first one on the list. + +This is what the end of succesful setup looks like. (both `ok` and `changed` are good.): +``` +PLAY RECAP ********************************************************************* +attacker : ok=5 changed=4 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + +If you do not see any error messages above, +then the game was started succesfully! +You can start playing now. +``` + +Once you see this in the terminal window, you can move on to +completing the first level objective. + +### Troubleshooting problems +If the assistant gets stuck on a command, outputs an error or `failed` in the +command line, something went wrong during setup. + +There is a brief list of known errors and possible causes in the [[troubleshooting]] doc, along +with solutions. + +## Moving on to next level +Once you finish a level and find the corresponding flag, it is time to +continue the game in the assistant. + +For that there is the `next` command. You will also need to enter the flag +you found in order to continue. +``` +Waiting for your input: +next +To continue, please enter the flag you found: +(case sensitive) +[flag] +Flag is correct! +Going to set up level 2 +Setting up next level: level2b +Bringing machine 'web' up with 'virtualbox' provider... +``` +Once more, you should keep an eye for possible errors in the output. +If everything seems fine, you can go read the level instructions and play! + +## Finishing the game +Once you go through all the levels, there is no need to press `next`, but you +should still submit your last flag! +You do that by typing `finish` into the assistant. +``` +Waiting for your input: +finish +To continue, please enter the flag you found: +(case sensitive) +[flag] +Flag is correct! +Game finished, total time saved! +``` + +You save the log by typing `log`. +``` +Waiting for your input: +log +Writing file... +Waiting for your input: +``` +The log will be saved as `assistant/logs/game_log.yml`. +If you previously saved another log (on accident, or for troubleshooting +reasons), the assistant will ask you if it can rewrite the current log. +## Getting hints +Sometimes, it might happen you will get stuck while trying to complete a level. +For that reason, there is a hint system present in the assistant. + +You can ask for a hint by writing `hint` into the assistant, and then picking +a number of the hint you want. (By typing `hint`, you will also get a recap +of all the hints you received previously.) + +``` +Waiting for your input: +hint +Choose which hint to take (Write a number): +0: (cancel, take no hint) +1: Where to start +2: Database +3: Input +4: Solution +2 +2: [hint text will be right here!] +Waiting for your input: +``` +If taking all the other hints doesn't help, the final hint is always the +exact solution for how to find the flag in the level. + +## Quitting the assistant +To properly quit the assistant, write `exit`. It will automatically stop +the running game, and delete all the data. +``` +Waiting for your input: +exit +Aborting game, deleting all VMs. +==> attacker: Forcing shutdown of VM... +==> attacker: Destroying VM and associated drives... +==> web: Forcing shutdown of VM... +==> web: Destroying VM and associated drives... +==> br: Forcing shutdown of VM... +==> br: Destroying VM and associated drives... +==> internet-router: Forcing shutdown of VM... +==> internet-router: Destroying VM and associated drives... +==> internal-router: Forcing shutdown of VM... +==> internal-router: Destroying VM and associated drives... +Game aborted, progress reset, VMs deleted. +Exiting... +``` +## Restoring a game log +If you forgot to save the log after you ended the game, and you already exit +the assistant, don't panic. +The game saves a log of the last game on every quit action. +In the `assistant/logs` folder, you should see several files named something +like `aborted_game1617806264.6124976`. The last modified of these should be the +log of the game you just played. If you forgot to save your log, you can use +this one in its place. \ No newline at end of file