awslabs/aws-cloudsaga is a Python framework from AWS that replays security-event scenarios drawn from real AWS CIRT casework so blue and purple teams can validate detection and response in their own accounts.
| Tool | awslabs/aws-cloudsaga — Python CLI that simulates AWS security events modeled on AWS Customer Incident Response Team findings |
| Category | Cloud security validation / purple-team simulation |
| Primary Use | Running benign replications of known attack patterns (imds-reveal, mining-bitcoin, network-changes, iam-credentials, public-resources) against your own AWS account to test detection and response |
| Safe Use | Designed for authorized use by account owners and their security teams — running simulations in owned AWS accounts, labs, or during sanctioned purple-team exercises |
| Telemetry Note | Each scenario emits ordinary AWS API calls (ec2:RunInstances, iam:GenerateCredentialReport, s3:PutPublicAccessBlock) visible in CloudTrail, plus a local cloudsaga_timestamp.log; defenders should see alerts fire for this activity |
Every detection engineering program eventually hits the same wall: you have GuardDuty, CloudTrail, and a stack of alerting rules, but no cheap, repeatable way to prove they actually fire when attacker-shaped activity appears. aws-cloudsaga, published under the awslabs organization, is AWS's own answer for its cloud. The tool generates simple scenarios modeled on security events the AWS Customer Incident Response Team (CIRT) has actually observed in the wild, and replays them against your account so you can watch your defenses respond. It is a purple-team instrument by design — the repo's own topic tags include blue-team, purple-team, and red-teaming — and it sits at roughly 475 stars with an Apache-2.0 license, written entirely in Python.
The conceptual model matters here. CloudSaga is not a fuzzing framework or an exploit harness; it is a scenario player. Each scenario, called a "chapter" in the tool's vocabulary, reproduces one class of CIRT-observed event using ordinary AWS API calls executed through boto3. When you run a chapter, you are generating the exact telemetry that a real incident of that class would produce, which is precisely what makes it valuable for testing whether CloudTrail events, Config rules, and detective controls translate into actionable alerts on your side.
Installation follows the standard pattern: pip3 install cloudsaga. Prerequisites are modest — Python 3.7+, boto3 1.21.7 or later, and pip3. The README strongly recommends running inside AWS CloudShell rather than locally with static IAM credentials, which is a sensible operational choice: CloudShell inherits your console session's identity, avoids leaving long-lived keys on a workstation, and keeps the simulation inside the account you are intentionally testing. After installation, cloudsaga -h presents the interface, which is deliberately minimal: --chapters lists available scenarios, --about <scenario> prints details for one, and --scenario <name> executes it.
The five scenarios shipped in the README cover a solid cross-section of AWS attack taxonomy. The imds-reveal scenario is grounded in server-side request forgery against EC2 instances still using IMDSv1, the unauthenticated version of the Instance Metadata Service; the tool enumerates regions and flags instances like i-99999999999999999 running IMDSv1, where no authentication header is required. The mining-bitcoin scenario simulates the single most common form of account abuse — adversaries spinning up Amazon EC2 cryptomining instances on a victim's billing. network-changes replays hostile infrastructure modification, creating Amazon VPCs and mutating Security Groups. iam-credentials pulls the IAM credential report, mimicking credential reconnaissance, and public-resources creates and then audits publicly accessible S3 and RDS exposure.
Permission scoping is where the README is most useful to a careful operator. Each chapter has an explicit IAM requirement, which means you can build a dedicated least-privilege role per exercise: imds-reveal needs only ec2:DescribeInstances; mining-bitcoin adds ec2:RunInstances; network-changes requires ec2:CreateVpc, ec2:CreateSecurityGroup, and related describe calls; iam-credentials maps to iam:GenerateCredentialReport and iam:GetCredentialReport; and public-resources spans rds:CreateDBInstance, s3:CreateBucket, s3:PutPublicAccessBlock, and their counterparts. This granularity is itself a teaching artifact — the permission list is effectively a threat-modeling cheat sheet for what each attack class requires.
Several scenarios are deliberately non-destructive in an interesting way. The public-resources chapter creates a resource, checks whether your tooling notices it is public, and cleans up — a closed loop that exercises both detection and hygiene enforcement. The mining-bitcoin scenario actually launches EC2 instances, so cost-conscious operators should run it in a region with cheap instance types and tear down promptly; the README's cleanup section notes that artifacts and the log file live in the CloudShell root directory and should be downloaded to Amazon S3 or locally before the session expires.
Logging is well considered. Every run produces a cloudsaga_timestamp.log file in the working directory containing per-region, per-API-call detail. The sample output in the README shows the tool iterating through regions like me-south-1, sa-east-1, and us-east-1, logging each DescribeInstances call and catching AuthFailure errors cleanly rather than crashing. That log is your exercise record — the artifact you diff against what your SIEM actually ingested, which is the whole point of a purple-team run.
From a defensive perspective, CloudSaga's real value is asymmetry of effort. Writing a faithful simulation of cryptomining abuse or SSRF-driven IMDS credential theft from scratch requires understanding both the attacker tradecraft and the AWS API surface well enough to reproduce it benignly; here, AWS has done that work from first-party incident data. A blue team can schedule chapters as regression tests after every detection-rule change, verifying that the CloudTrail events for ec2:RunInstances bursts or s3:PutPublicAccessBlock removal still route to a human.
The telemetry note cuts both ways, and defenders should internalize it: everything CloudSaga does is visible in CloudTrail as ordinary API activity, which is exactly why it works as a test. If your run of iam-credentials does not generate an alert on iam:GetCredentialReport from an unusual principal, that is a finding. Conversely, the same benign calls are indistinguishable from hostile ones at the API level, so exercise windows should be communicated to the SOC to avoid wasted triage — a standard purple-team coordination practice for authorized assessments.
Caveats worth noting: the README's last sample log entries date to early 2022, and the tool targets scenarios from documented CIRT casework of that era, so teams should treat it as one input among others rather than a complete adversary emulation library à la Atomic Red Team. Feedback and bugs route through the GitHub Issues section, and security disclosures follow the standard CONTRIBUTING process at awslabs. For what it is — a lightweight, first-party, pip-installable way to prove your AWS detective controls react to the incident classes AWS responders see most — cloudsaga earns a place in the cloud security validation toolkit, especially for teams that want CIRT-grounded scenarios without building their own harness.
awslabs/aws-cloudsaga.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.