{"id":15115367,"url":"https://github.com/DataDog/grimoire","last_synced_at":"2025-09-27T20:32:21.850Z","repository":{"id":252426450,"uuid":"592819571","full_name":"DataDog/grimoire","owner":"DataDog","description":"Generate datasets of cloud audit logs for common attacks","archived":false,"fork":false,"pushed_at":"2024-08-09T16:37:00.000Z","size":1169,"stargazers_count":192,"open_issues_count":5,"forks_count":14,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-01-11T12:07:52.320Z","etag":null,"topics":["cloud-security","detection-engineering","purpleteaming"],"latest_commit_sha":null,"homepage":"https://securitylabs.datadoghq.com/articles/announcing-grimoire/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DataDog.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-24T15:54:44.000Z","updated_at":"2025-01-08T05:32:27.000Z","dependencies_parsed_at":"2024-08-09T18:24:23.945Z","dependency_job_id":"2c94412b-9aaf-47ae-8271-82e44ea3d613","html_url":"https://github.com/DataDog/grimoire","commit_stats":null,"previous_names":["datadog/grimoire"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fgrimoire","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fgrimoire/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fgrimoire/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fgrimoire/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DataDog","download_url":"https://codeload.github.com/DataDog/grimoire/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234460505,"owners_count":18836837,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloud-security","detection-engineering","purpleteaming"],"created_at":"2024-09-26T01:43:47.804Z","updated_at":"2025-09-27T20:32:21.438Z","avatar_url":"https://github.com/DataDog.png","language":"Go","readme":"# Grimoire\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./logo.png\" alt=\"logo\" width=\"300\" /\u003e\n\u003c/p\u003e\n\nGrimoire is a \"REPL for detection engineering\" that allows you to generate datasets of cloud audit logs for common attack techniques. It currently supports AWS.\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/DataDog/grimoire/raw/main/stratus-red-team.png\"\u003e\n    \u003cimg src=\"./stratus-red-team.png\" alt=\"Terminal screenshot\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/DataDog/grimoire/raw/main/shell.png\"\u003e\n    \u003cimg src=\"./shell.png\" alt=\"Terminal screenshot\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n## How it works\n\nFirst, 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.\n\nSupported detonators:\n- [Stratus Red Team](https://github.com/DataDog/stratus-red-team)\n- AWS CLI interactive shell\n\nSupported logs backend:\n- AWS CloudTrail (through the `LookupEvents` API)\n\n## Installation\n\n### Direct install\n\nRequires Go 1.22+\n\n```bash\ngo install -v github.com/datadog/grimoire/cmd/grimoire@latest\n```\n\n### Homebrew\n\n```bash\nbrew tap datadog/grimoire https://github.com/DataDog/grimoire\nbrew install datadog/grimoire/grimoire\n```\n\n### Pre-built binaries\n\nDownload one of the pre-built binaries from the [releases page](https://github.com/DataDog/grimoire/releases).\n## Getting started\n\nMake sure you're [authenticated against AWS](https://docs.aws.amazon.com/signin/latest/userguide/command-line-sign-in.html) and have `AWS_REGION` set before running Grimoire:\n\n```\nexport AWS_REGION=us-east-1\n```\n\n## Usage\n\nGrimoire has two main commands: \n- [`grimoire stratus-red-team`](#detonate-an-attack-technique-with-stratus-red-team)\n- [`grimoire shell`](#detonate-an-attack-manually-in-an-interactive-shell)\n\n### Detonate an attack technique with [Stratus Red Team](https://github.com/DataDog/stratus-red-team):\n\n```bash\n$ grimoire stratus-red-team -o /tmp/logs --attack-technique aws.credential-access.ssm-retrieve-securestring-parameters\nINFO[0000] Warming up Stratus Red Team attack technique aws.credential-access.ssm-retrieve-securestring-parameters\nINFO[0000] Detonating Stratus Red Team attack technique aws.credential-access.ssm-retrieve-securestring-parameters\nINFO[0003] Stratus Red Team attack technique successfully detonated\nINFO[0003] Searching for CloudTrail events...\nINFO[0009] Found new CloudTrail event generated on 2024-07-30T20:58:43Z UTC: DescribeParameters\nINFO[0009] Found new CloudTrail event generated on 2024-07-30T20:58:42Z UTC: DescribeParameters\n```\n\nIn 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.\n\nKeep 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](https://stratus-red-team.cloud/attack-techniques/AWS/aws.credential-access.ec2-steal-instance-credentials/).\n\n### Detonate an attack manually in an interactive shell\n\nYou 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.\n\n```bash\n$ grimoire shell -o /tmp/logs\nINFO[0000] Grimoire will now run your shell and automatically inject a unique identifier to your HTTP user agent when using the AWS CLI\nINFO[0000] You can use the AWS CLI as usual. Press Ctrl+D or type 'exit' to return to Grimoire.\nINFO[0000] When you exit the shell, Grimoire will look for the CloudTrail events that your commands have generated.\nINFO[0000] Press ENTER to continue\n\n# We're now in a \"Grimoire-instrumented\" shell\n$ aws sts get-caller-identity\n$ aws ec2 describe-instances\n$ exit\nINFO[0040] Welcome back to Grimoire!\nINFO[0040] Searching for CloudTrail events...\nINFO[0090] Found event: DescribeInstances\nINFO[0090] Found event: GetCallerIdentity\n```\n\nIn 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:\n\n```\n$ grimoire shell -o /tmp/logs\n$ awscurl -H \"User-Agent: $GRIMOIRE_DETONATION_ID\" --service ec2 \\\n    'https://ec2.amazonaws.com?Action=DescribeRegions\u0026Version=2013-10-15'\n```\n\n... will allow Grimoire to identify CloudTrail events generated by `awscurl` as well.\n\n### Detonate an attack manually by specifying commands\n\nYou can use `grimoire shell` in non-interactive mode, passing it a command or a script to run instead:\n\n```\n$ grimoire shell --command 'aws sts get-caller-identity'\nINFO[0000] Running detonation command: aws sts get-caller-identity\n{\n    \"UserId\": \"AIDAEXAMPLE\",\n    \"Account\": \"012345678901\",\n    \"Arn\": \"arn:aws:iam::012345678901:user/christophe\"\n}\nINFO[0002] Searching for CloudTrail events...\nINFO[0140] Found event: GetCallerIdentity\n```\n\nUsing a script:\n\n```\n$ cat /tmp/script.sh\naws sts get-caller-identity\naws iam create-user --user-name foobar\naws iam create-access-key --user-name foobar\n\n$ grimoire shell --script /tmp/script.sh\nINFO[0000] Running detonation script: /tmp/script.sh\n+/tmp/script.sh:1\u003e aws sts get-caller-identity\n+/tmp/script.sh:2\u003e aws iam create-user --user-name foobar\n+/tmp/script.sh:3\u003e aws iam create-access-key --user-name foobar\nINFO[0005] Searching for CloudTrail events...\n```\n\n### Advanced usage\n\nYou can use `--timeout`, `--max-events`, `--include-events`, `--exclude-events` and `--only-write-events` to control how long Grimoire should poll CloudTrail, how many events to retrieve, and which events to include or exclude.\n\n```bash\n# Wait for a single sts:GetCallerIdentity event and exit\ngrimoire shell --command 'aws sts get-caller-identity' --include-events 'sts:GetCallerIdentity' --max-events 1\n\n# Only keep iam:* events and exit after 5 minutes or 2 events (whichever comes first)\ngrimoire stratus-red-team --attack-technique aws.persistence.iam-create-admin-user --include-events 'iam:*' --max-events 2 --timeout 3m\n\n# Only keep IAM write events\ngrimoire shell --script /tmp/attack.sh --include-events 'iam:*' --only-write-events\n\n# Exclude sts:AssumeRole events\ngrimoire shell --script /tmp/attack.sh --exclude-events 'sts:GetCallerIdentity'\n\n# Wait for at least one IAM or EC2 write event and exit. Fail if the logs aren't available within 10 minutes.\ngrimoire shell --script /tmp/attack.sh --only-write-events --include-events 'iam:*,ec2:*' --max-events 1 --timeout 10m\n```\n## Development\n\nRunning locally:\n\n```bash\nalias grimoire='go run cmd/grimoire/*.go'\ngrimoire --help\n```\n\nUse `--debug` for verbose logging.\n\nBuilding binaries:\n\n```bash\nmake\n```\n\nRunning the tests:\n\n```bash\nmake test\n```\n\n## Disclaimer\n\nWhen detonating attacks with Stratus Red Team, it's best to avoid interrupting execution with Ctrl+C while the technique is being detonated. While we take a great deal of care to clean up after ourselves, it may happen that some resources are left behind, specifically because the [terraform-exec](https://github.com/hashicorp/terraform-exec) wrapper used by Stratus Red Team panics on Ctrl+c and doesn't offer an option to exit cleanly.\n\n## FAQ\n\n### Why are CloudTrail events slow to arrive?\n\nDelivery of CloudTrail events can take up to 15 minutes. If you don't see events immediately, wait a few minutes and try again. In the majority of cases, though, it's expected that CloudTrail events are made available within 5 minutes.\n\nFor more information, see the [AWS documentation](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/get-and-view-cloudtrail-log-files.html) and [How fast is CloudTrail today?](https://tracebit.com/blog/how-fast-is-cloudtrail-today-investigating-cloudtrail-delays-using-athena).\n\n### Why isn't Grimoire part of Stratus Red Team?\n\nWe chose to separate Grimoire from Stratus Red Team because we feel that Grimoire should support other ways of detonating attack techniques. \n\nThat said, Stratus Red Team has a dedicated section `Detonation logs` for every AWS attack technique. These logs have been generated using Grimoire and can be used to validate the detection rules you've written.\n\n### What about CloudTrail Data Events?\n\nData events are not supported for now. If you're interested, please upvote [this issue](https://github.com/DataDog/grimoire/issues/1).\n","funding_links":[],"categories":["Go","others"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDataDog%2Fgrimoire","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FDataDog%2Fgrimoire","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDataDog%2Fgrimoire/lists"}