Merge pull request #24 from avast/documentation_improvements

Documentation improvements

README.md

@@ -11,7 +11,12 @@ The system is at the same time reproducible and quite flexible (target system wi
 
 ## Installation
 
-On a current Ubuntu system, just execute the *init.sh* to install the required packages and set up the virtual env.
+On a current Ubuntu 21.10 system, just execute the *init.sh* to install the required packages and set up the virtual env. 
+
+You need python 3.9 (which is part of this Ubuntu)
+
+And it will not run properly in a VM as it spawns its own VMs ... unless VT-x is available.
+We confirmed it is working in VirtualBox. Please reserve enough disk space. The simple hello_world will already download a kali and an ubuntu image. They must be stored on your VM. 
 
 ```
 ./init.sh
@@ -27,7 +32,7 @@ source venv/bin/activate
 
 ## My first experiment
 
-Run
+Run and be very patient. The first time it runs it will build target and attacker VMs which is time consuming and will need some bandwidth. 
 
 ```
 python3 ./experiment_control.py -vvv  run --configfile hello_world.yaml
@@ -56,6 +61,41 @@ evince tools/human_readable_documentation/build/latex/purpledomesimulation.pdf
 
 (which is included in the zip as well)
 
+## Fixing issues
+
+### Machine creation
+
+One of the big steps is creation of attacker and target machines. If this fails, you can do the step manually and check why it fails.
+
+```
+cd systems
+vagrant up attacker
+vagrant up target3
+vagrant ssh attacker
+# do someting
+exit
+vagrant ssh target
+# do something
+exit
+vagrant destroy target3
+vagrant destroy attacker
+```
+
+### Caldera issues
+
+The caldera server is running on the attacker. It will be contacted by the implants installed on the client and remote controlled by PurpleDome using a REST Api. This can be tested using curl:
+
+```
+curl -H 'KEY: ADMIN123' http://attacker:8888/api/rest -H 'Content-Type: application/json' -d '{"index":"adversaries"}'
+```
+
+If there are errors, connect to the attacker using ssh and monitor the server while contacting it. Maybe kill it first.
+
+```
+cd caldera
+python3 server.py --insecure
+```
+
 ## Running the basic commands
 
 All command line tools have a help included. You can access it by the "--help" parameter

app/machinecontrol.py

@@ -404,7 +404,7 @@ class Machine():
         else:
             cleanupcmd = ""
 
-        cmd = f"cd {self.caldera_basedir}; {cleanupcmd}  git clone https://github.com/mitre/caldera.git --recursive --branch {version}; cd caldera; pip3 install -r requirements.txt"
+        cmd = f"cd {self.caldera_basedir}; {cleanupcmd} git clone https://github.com/mitre/caldera.git --recursive --branch {version}; cd caldera; git checkout {version}; pip3 install -r requirements.txt"
         self.attack_logger.vprint(f"{CommandlineColors.OKGREEN}Caldera server installed {CommandlineColors.ENDC}", 1)
         res = self.vm_manager.__call_remote_run__(cmd)
         return "Result installing caldera server " + str(res)

systems/Vagrantfile

@@ -136,7 +136,7 @@ Vagrant.configure("2") do |config|
 
 	  # Every Vagrant development environment requires a box. You can search for
 	  # boxes at https://vagrantcloud.com/search.
-	  target3.vm.box = "ubuntu/groovy64"
+	  target3.vm.box = "ubuntu/impish64"
 	  # target.vm.base_mac = "080027BB1475"
 	  target3.vm.hostname = "target3"
 	  target3.vm.define "target3"

systems/target3/bootstrap.sh

@@ -33,28 +33,30 @@ wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | apt-key add -
 echo "deb https://artifacts.elastic.co/packages/7.x/apt stable main" | tee /etc/apt/sources.list.d/elastic-7.x.list
 apt update
 
+
+################# This must move into a plugin !!! ###############
 # Install Logstash
-apt -y install default-jre
+# apt -y install default-jre
-apt -y install logstash
+# apt -y install logstash
 
 # Install filebeat
-apt -y install filebeat
+# apt -y install filebeat
 # Configure logstash as output
-cp /vagrant/target1/config/filebeat.yml /etc/filebeat/filebeat.yml
+# cp /vagrant/target1/config/filebeat.yml /etc/filebeat/filebeat.yml
-cp /vagrant/target1/config/caldera_agent.service /etc/systemd/system/
+# cp /vagrant/target1/config/caldera_agent.service /etc/systemd/system/
 
 # Config logstash
-cp /vagrant/target1/logstash_conf/*.conf /etc/logstash/conf.d
+# cp /vagrant/target1/logstash_conf/*.conf /etc/logstash/conf.d
-rm /vagrant/target1/logstash/filebeat.json
+# rm /vagrant/target1/logstash/filebeat.json
-touch /vagrant/target1/logstash/filebeat.json
+# touch /vagrant/target1/logstash/filebeat.json
-chmod o+w /vagrant/target1/logstash/filebeat.json
+# chmod o+w /vagrant/target1/logstash/filebeat.json
 
 # Start Logstash and filebeat
-filebeat modules enable system,iptables
+# filebeat modules enable system,iptables
-filebeat setup --pipelines --modules iptables,system,
+# filebeat setup --pipelines --modules iptables,system,
-systemctl start logstash.service
+# systemctl start logstash.service
-systemctl enable filebeat
+# systemctl enable filebeat
-systemctl enable logstash.service
+# systemctl enable logstash.service
 
 # Run logstash manually for debugging:
 # https://www.elastic.co/guide/en/logstash/current/running-logstash-command-line.html