grimoire: Generate datasets of cloud audit logs for common attacks

Grimoire

Grimoire is a “REPL for detection engineering” that allows you to generate datasets of cloud audit logs for common attack techniques. It currently supports AWS.

How it works

First, Grimoire detonates an attack. It injects a unique user agent containing a UUID. Then, it polls CloudTrail to retrieve the audit logs caused by the detonation, and streams the resulting logs to an output file or to your terminal.

Supported detonators:

• Stratus Red Team
• AWS CLI interactive shell

Supported logs backend:

• AWS CloudTrail (through the LookupEvents API)

Use

Grimoire has two main commands:

• grimoire stratus-red-team
• grimoire shell

Detonate an attack technique with Stratus Red Team:

$ grimoire stratus-red-team -o /tmp/logs --attack-technique aws.credential-access.ssm-retrieve-securestring-parameters
INFO[0000] Warming up Stratus Red Team attack technique aws.credential-access.ssm-retrieve-securestring-parameters
INFO[0000] Detonating Stratus Red Team attack technique aws.credential-access.ssm-retrieve-securestring-parameters
INFO[0003] Stratus Red Team attack technique successfully detonated
INFO[0003] Searching for CloudTrail events...
INFO[0009] Found new CloudTrail event generated on 2024-07-30T20:58:43Z UTC: DescribeParameters
INFO[0009] Found new CloudTrail event generated on 2024-07-30T20:58:42Z UTC: DescribeParameters

In another terminal, you can tail /tmp/logs to see the logs as they’re discovered in CloudTrail. Alternatively, you can use -o - to print the logs in your terminal as they are found. You can safely use Ctrl+C to exit.

Keep in mind that some Stratus Red Team attack techniques may take some time to complete. These are marked with a Slow badge on their documentation page, such as Steal EC2 Instance Credentials.

Detonate an attack manually in an interactive shell

You can also detonate an attack manually in an interactive shell. In that case, Grimoire will spin up a new $SHELL for you, and inject the AWS_EXECUTION_ENV environment variable to ensure that the AWS CLI commands you run generate logs that Grimoire captures.

$ grimoire shell -o /tmp/logs
INFO[0000] Grimoire will now run your shell and automatically inject a unique identifier to your HTTP user agent when using the AWS CLI
INFO[0000] You can use the AWS CLI as usual. Press Ctrl+D or type 'exit' to return to Grimoire.
INFO[0000] When you exit the shell, Grimoire will look for the CloudTrail events that your commands have generated.
INFO[0000] Press ENTER to continue

# We're now in a "Grimoire-instrumented" shell
$ aws sts get-caller-identity
$ aws ec2 describe-instances
$ exit
INFO[0040] Welcome back to Grimoire!
INFO[0040] Searching for CloudTrail events...
INFO[0090] Found event: DescribeInstances
INFO[0090] Found event: GetCallerIdentity

In the shell that Grimoire spawns, you can use the $GRIMOIRE_DETONATION_ID environment variable if you eed to propagate the user agent to other tools. For instance:

$ grimoire shell -o /tmp/logs
$ awscurl -H "User-Agent: $GRIMOIRE_DETONATION_ID" --service ec2 \
    'https://ec2.amazonaws.com?Action=DescribeRegions&Version=2013-10-15'

… will allow Grimoire to identify CloudTrail events generated by awscurl as well.

$ grimoire shell --command 'aws sts get-caller-identity'
INFO[0000] Running detonation command: aws sts get-caller-identity
{
    "UserId": "AIDAEXAMPLE",
    "Account": "012345678901",
    "Arn": "arn:aws:iam::012345678901:user/christophe"
}
INFO[0002] Searching for CloudTrail events...
INFO[0140] Found event: GetCallerIdentity

$ cat /tmp/script.sh
aws sts get-caller-identity
aws iam create-user --user-name foobar
aws iam create-access-key --user-name foobar

$ grimoire shell --script /tmp/script.sh
INFO[0000] Running detonation script: /tmp/script.sh
+/tmp/script.sh:1> aws sts get-caller-identity
+/tmp/script.sh:2> aws iam create-user --user-name foobar
+/tmp/script.sh:3> aws iam create-access-key --user-name foobar
INFO[0005] Searching for CloudTrail events...

# Wait for a single sts:GetCallerIdentity event and exit
grimoire shell --command 'aws sts get-caller-identity' --include-events 'sts:GetCallerIdentity' --max-events 1

# Only keep iam:* events and exit after 5 minutes or 2 events (whichever comes first)
grimoire stratus-red-team --attack-technique aws.persistence.iam-create-admin-user --include-events 'iam:*' --max-events 2 --timeout 3m

# Only keep IAM write events
grimoire shell --script /tmp/attack.sh --include-events 'iam:*' --only-write-events

# Exclude sts:AssumeRole events
grimoire shell --script /tmp/attack.sh --exclude-events 'sts:GetCallerIdentity'

# Wait for at least one IAM or EC2 write event and exit. Fail if the logs aren't available within 10 minutes.
grimoire shell --script /tmp/attack.sh --only-write-events --include-events 'iam:*,ec2:*' --max-events 1 --timeout 10m

Install