Skip to content

Commit

Permalink
docs: Add documentation on state machine and revert command
Browse files Browse the repository at this point in the history
  • Loading branch information
christophetd committed Jan 19, 2022
1 parent 7e84bff commit 0340d76
Show file tree
Hide file tree
Showing 5 changed files with 107 additions and 1 deletion.
89 changes: 89 additions & 0 deletions docs/user-guide/examples.md
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down Expand Up @@ -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
```
16 changes: 15 additions & 1 deletion docs/user-guide/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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

Expand Down
1 change: 1 addition & 0 deletions docs/user-guide/state-machine.drawio
Original file line number Diff line number Diff line change
@@ -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>
Binary file added docs/user-guide/state-machine.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 2 additions & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 0340d76

Please sign in to comment.