Enhanced basic getting started readme

README.md

@@ -10,45 +10,58 @@ The system is at the same time reproducible and quite flexible (target system wi
 
 ## Installation
 
-Setting up the python environment:
+On a current Ubuntu system, just execute the *init.sh* to install the required packages and set up the virtual env.
 
 ```
 ./init.sh
 ```
 
-The typical local use case is to create the machines using Vagrant and running them in VirtualBox:
-
-...
-sudo apt install vagrant virtualbox
-...
-
-You will have to switch into the python environment to run it
+Default vm will be vagrant and virtualbox
 
 Before using any PurpleDome commands switch into the python environment:
 
-...
+```
 source venv/bin/activate
-...
+```
 
-(this will contain the libraries in the required versions)
+## My first experiment
 
-## Testing
+Run
 
-Basic code and unit tests can be run by
+```
+python3 ./experiment_control.py -vvv  run --configfile hello_world.yaml
+```
+
+This will:
+
+* Use vagrant to generate attacker and target
+* run them
+* run several attacks from the attacker to the target
+* zip sensor logs and attack logs together
+
+Building the machines from vagrant will take some time ont he first run. Please be patient.
+
+After the experiment ran, open the zip file with the attack log and all the sensor logs:
 
 ```
-make test
+file-roller loot/2021_11_11___12_13_14/2021_11_11___12_13_14.zip
 ```
 
-That way you can also see if your env is set up properly
+or jump directly into the human readable attack log 
+
+```
+evince tools/human_readable_documentation/build/latex/purpledomesimulation.pdf
+```
+
+(which is included in the zip as well)
 
 ## Running the basic commands
 
 All command line tools have a help included. You can access it by the "--help" parameter
 
-...
+```
 python3 ./experiment_control.py -v  run
-...
+```
 
 * -v is verbosity. To spam stdout use -vvv
 * run is the default command
@@ -56,20 +69,42 @@ python3 ./experiment_control.py -v  run
 
 Most of the configuration is done in the yaml config file. For more details check out the full documentation
 
-## The real documentation
+## Testing
 
-This README is just a short overview. In depth documentation can be found in the *doc* folder.
+Basic code and unit tests can be run by
+
+```
+make test
+```
+
+That way you can also see if your env is set up properly.
 
-Documentation is using sphinx
+It will also check the plugins you write for compatibility. 
 
-https://www.sphinx-doc.org/en/master/index.html
+the tool
 
-Generate it switching to the directory doc and calling
+```
+./pydantic_test.py
+```
 
-*make all*
+is *not* included in the make test. But you can use it manually to verify your yaml config files. As they tend to become quite complex this is a time safer.
+
+## More documentation
+
+This README is just a short overview. In depth documentation can be found in the *doc* folder.
+
+Documentation is using sphinx. To compile it, go into this folder and call
+
+```
+make html
+```
+
+Use your browser to open build/html/index.html and start reading.
 
 ## Development
 
+The code is stored in [https://github.com/avast/PurpleDome](https://github.com/avast/PurpleDome). Feel free to fork it and create a pull request. 
+
 Development happens in *feature branches* branched of from *develop* branch. And all PRs go back there.
 The branch *release* is a temporary branch from *develop* and will be used for bug fixing before a PR to *main* creates a new release. Commits in main will be marked with tags and the *changelog.txt* file in human readable form describe the new features.
 

init.sh

@@ -2,8 +2,15 @@
 
 # Init the system
 
+# Python basics
 sudo apt-get -y install python3-venv
+
+# Virtualisation defaults
+sudo apt-get -y install vagrant virtualbox
+
+# For document generation
 sudo apt-get -y install latexmk texlive-fonts-recommended texlive-latex-recommended texlive-latex-extra
+
 python3 -m venv venv
 source venv/bin/activate
 pip3 install -r requirements.txt