diff --git a/docs/user-guide/examples.md b/docs/user-guide/examples.md index 73c8f4d0..fbaf5dc7 100644 --- a/docs/user-guide/examples.md +++ b/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 ``` \ No newline at end of file diff --git a/docs/user-guide/getting-started.md b/docs/user-guide/getting-started.md index 2a2fc1e0..862b11ea 100644 --- a/docs/user-guide/getting-started.md +++ b/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. + +
+![](./state-machine.png) +
State Machine of a Stratus Attack Technique
+
+ ### 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 diff --git a/docs/user-guide/state-machine.drawio b/docs/user-guide/state-machine.drawio new file mode 100644 index 00000000..cb78fb1e --- /dev/null +++ b/docs/user-guide/state-machine.drawio @@ -0,0 +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= \ No newline at end of file diff --git a/docs/user-guide/state-machine.png b/docs/user-guide/state-machine.png new file mode 100644 index 00000000..807db13f Binary files /dev/null and b/docs/user-guide/state-machine.png differ diff --git a/mkdocs.yml b/mkdocs.yml index 62309f41..030e742f 100644 --- a/mkdocs.yml +++ b/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