docs: Add documentation on state machine and revert command

docs/user-guide/examples.md

@@ -2,6 +2,8 @@
 
 This page contains a full example of using Stratus Red Team.
 
+## Example 1: Basic usage
+
 ## Authenticating to AWS
 
 First, we'll authenticate to AWS using [aws-vault](https://github.com/99designs/aws-vault):
@@ -115,4 +117,91 @@ We can clean up any resources creates by Stratus Red Team using:
 
 ```
 stratus cleanup aws.persistence.backdoor-iam-role
+```
+
+## Example 2: Advanced usage
+
+In this example, we want to prepare our live environment with the pre-requisites ahead of time - say, a few hours before detonating our attack techniques.
+
+We start by warming up the techniques we're interested in:
+
+```bash
+stratus warmup aws.defense-evasion.stop-cloudtrail aws.defense-evasion.remove-vpc-flow-logs aws.persistence.backdoor-iam-user
+```
+
+We now have the pre-requisites ready:
+
+```
+CloudTrail trail arn:aws:cloudtrail:us-east-1:0123456789012:trail/my-cloudtrail-trail ready
+VPC Flow Logs fl-0ef2f69f9799cf52e in VPC vpc-072ec3075f9b5046a ready
+IAM user sample-legit-user ready
+```
+
+At this point, we can choose to detonate these attack techniques at any point we want. We can do it right away, or in a few hours / days:
+
+```bash
+stratus detonate aws.defense-evasion.stop-cloudtrail aws.defense-evasion.remove-vpc-flow-logs aws.persistence.backdoor-iam-user
+```
+
+```text
+Stopping CloudTrail trail my-cloudtrail-trail
+Removing VPC Flow Logs fl-0ef2f69f9799cf52e in VPC vpc-072ec3075f9b5046a
+Creating access key on legit IAM user to simulate backdoor
+```
+
+Now, say we want to replay (i.e., detonate again) an attack technique a few times, for testing and to iterate building our threat detection rules on the side:
+
+```
+stratus detonate aws.persistence.backdoor-iam-user
+stratus detonate aws.persistence.backdoor-iam-user
+```
+
+You will notice that the second call raises an error:
+
+```
+Error while detonating attack technique aws.persistence.backdoor-iam-user: 
+    operation error IAM: CreateAccessKey, 
+    https response error 
+    StatusCode: 
+    LimitExceeded: Cannot exceed quota for AccessKeysPerUser: 2
+```
+
+That's because detonating this attack technique has side-effects (here: creating an IAM user access key). Before replaying a technique, we should revert it:
+
+```
+stratus revert aws.persistence.backdoor-iam-user
+```
+
+``` 
+2022/01/19 15:43:35 Reverting detonation of technique aws.persistence.backdoor-iam-user
+2022/01/19 15:43:35 Removing access key from IAM user sample-legit-user
+2022/01/19 15:43:36 Removing access key AKIA254BBSGPJNHEDHNR
+2022/01/19 15:43:36 Removing access key AKIA254BBSGPBYLEHMVO
++-----------------------------------+-----------------------------------------+--------+
+| ID                                | NAME                                    | STATUS |
++-----------------------------------+-----------------------------------------+--------+
+| aws.persistence.backdoor-iam-user | Create an IAM Access Key on an IAM User | WARM   |
++-----------------------------------+-----------------------------------------+--------+
+```
+
+Our attack technique is now `WARM`, we can detonate it again:
+
+```bash
+stratus detonate aws.persistence.backdoor-iam-user
+```
+
+Generally, we can detonate then revert an attack technique indefinitely:
+
+```bash
+while true; do
+  stratus detonate aws.persistence.backdoor-iam-user
+  stratus revert aws.persistence.backdoor-iam-user
+  sleep 1
+done
+```
+
+Once we are done with our testing, we can clean up our techniques. Cleaning up a technique will revert its detonation logic (if applicable), then nuke all its pre-requisite resources and infrastructure:
+
+```bash
+stratus cleanup aws.defense-evasion.stop-cloudtrail aws.defense-evasion.remove-vpc-flow-logs aws.persistence.backdoor-iam-user
 ```

docs/user-guide/getting-started.md

@@ -7,7 +7,6 @@
 An *attack technique* is a granular TTP that has *pre-requisites* infrastructure or configuration.
 You can see the list of attack techniques supported by Stratus Red Team [here](../attack-techniques/list.md).
 
-
 ### Warm-up Phase
 
 *Warming up* an attack technique means making sure its pre-requisites are met, without detonating it. 
@@ -20,12 +19,27 @@ Behind the scenes, Stratus Red Team transparently uses Terraform to spin up and
 
 An attack technique can be *detonated* to execute it against a live environment, for instance against a test AWS account.
 
+### Reverting and Cleaning up an Attack Technique
+
+*Reverting* an attack technique means "cancelling" its detonation, it had a side effect. *Cleaning up* an Attack Technique means nuking all its pre-requisites and making sure no resource is left in your environment.
+
+### State Machine
+
+The diagram below illustrates the different states in which an attack technique can be.
+
+<figure markdown>
+![](./state-machine.png)
+<figcaption>State Machine of a Stratus Attack Technique</figcaption>
+</figure>
+
 ### Example
 
 Let's take an example. The attack technique [Exfiltrate EBS Snapshot through Snapshot Sharing](../../attack-techniques/AWS/aws.exfiltration.ebs-snapshot-shared-with-external-account/) is comprised of two phases:
 
 - Warm-up: Create an EBS volume and a snapshot of it
 - Detonation: Share the EBS snapshot with an external AWS account
+- Revert: Unshare the EBS snapshot with the external AWS account
+- Clean-up: Remove the EBS volume and its snapshot
 
 ## Sample Usage
 

docs/user-guide/state-machine.drawio

@@ -0,0 +1 @@
+<mxfile host="app.diagrams.net" modified="2022-01-19T14:23:16.112Z" agent="5.0 (Macintosh)" etag="4jXSCMjP05Alxxhrl84s" version="16.2.4" type="device"><diagram id="yF30Bdg-q_bzkUsnMItz" name="Page-1">5Vlbb9owGP01PFLl5hAegdBOE123Mqnto0mcxJuJI2Nu/fVziHMj4VYIIK2VKvvYsR2f73w+cVv6YLp6YjAKnqmLSEtT3FVLt1ua1jUM8TcG1gkAtG4C+Ay7CaTmwBh/IgkqEp1jF81KHTmlhOOoDDo0DJHDSxhkjC7L3TxKyrNG0EcVYOxAUkXfsMuDBLWAkuPfEPaDdGZVkS1TmHaWwCyALl0WIH3Y0geMUp6UpqsBIvHepfuSPPe4ozVbGEMhP+aB70/RiLTH3B5aU7v/+OgHv4y2YcrF8XX6xsgVGyCrlPGA+jSEZJij/RwdURqJbqoA/yDO15I/OOdUQAGfEtmKVpi/i7Iiyx9x+QHImr0qNNnrtBJytn7PO8bVj2Jb/timlj7nzNkCuXLiGWf0b0ZdjCQvHL/lzo2U0IzOmYP27F4aBRwyH/F9HUFGuBAKolMkFiweZIhAjhfllUAZsn7WL2dVFCSxp5DcSQZeQDKXU71BNhXIPKqlfwQnQsUlAiHBfijKjtgkxASwQIxjoZOebJhi191EB0Mz/Aknm/FiOiKKQ755JdBvAVsgHg15GmFKWk8iR9UzhuIJ0KpO5HLwXFpF7vaEeXX/5fDKg2qacpNknpJp62iC5Ng/45ctdKGeNxORsc1gtoQzSLW+oNySNM6QsVqQsXqkiE+R8H2o1lTqo+ZKqu1WVGsjLuji6NaiVa8jWuuAaDWzUxZtu3vvqk1jr0Dq4GVkVwklRDicmJllgDkaR3AT0kvhsbYonkWJ7fHwKlZ238OEDCihbDOQ7kJkeU4mqUKL6Vho4sVcI4bFeyEWz4JDv6S4GkIrmttJkaYr5aQqq8vcSWV+KSi6qBS8uKiAfidZ85D5aTYDgmN9y00zIDCqYiEIhv+RcUni9RTjot17CjTVWuquI8FcdqdYl/L3h3rAvGxHRVwv5F3Djn/vRuJnm5zNoz3G4LrQQWqnGl+pLjrlk0FXtz5et/ob2t7+opCs4LKRqt2fA9sdV8rmp5EsZO4/5tvKg6J2u2UrdmYekkPrtYNewaeBCvVvvdfn5nya53maU+vTXHNiArNRn6ZuqStT5w2N2lcuppo5JZTjTgm1eEYUjoxbfOKaR19M3ST7b2dz1Tot+6dh12j2B9Vbs/txn9f5Agf7r81E3teVrU9wcJG0D66W5295i/aly/BSmjlkRe8kydz09htU79FeUaySW2v4Sl+QB2/RdAWUXZZ+EQ0b19KwWb1Ts4e/X370fg8bvFjzLAfVG7aJBQygNGrY9E79AdqIYRPV/L+UCWn5v3r14T8=</diagram></mxfile>

mkdocs.yml

@@ -23,6 +23,8 @@ markdown_extensions:
   - meta
   - abbr
   - def_list
+  - attr_list
+  - md_in_html
 
 extra_javascript:
   - https://cdnjs.cloudflare.com/ajax/libs/tablesort/5.2.1/tablesort.min.js