sibyl-aws 0.3.3

AWS Policy Simulation CLI — predict SCP, IAM, and RCP impact before deployment

sibyl — AWS Policy Simulation CLI

The Sibyls were oracles consulted before every major decision. sibyl does the same for your AWS policies.

Simulate SCP, IAM, and RCP policy changes against real CloudTrail data to predict what would break before deployment.

This tool is strictly read-only. It never creates, modifies, or deletes any AWS resources.

---

Install

pipx install sibyl-aws

Or with pip:

pip install sibyl-aws

---

Quick Start

# 1. Log in to AWS
aws sso login --profile your-profile

# 2. Discover your org structure (one-time)
sibyl init --profile your-profile

# 3. Simulate a policy
sibyl --ou dev_myapp --scp my-policy.json

---

Usage

Short form (recommended)

# Simulate an SCP
sibyl --ou dev_myapp --scp policy.json

# Simulate an RCP
sibyl --ou dev_myapp --rcp policy.json

# Dry-run: list all API calls without making them
sibyl --ou dev_myapp --scp policy.json --dry-run

# Save report as markdown
sibyl --ou dev_myapp --scp policy.json --output report.md

# Use a specific AWS profile
sibyl --ou dev_myapp --scp policy.json --profile my-profile

Full form

# Simulate an SCP against an OU by name
sibyl simulate --policy path/to/policy.json --type scp --target dev_myapp

# Simulate against all OUs where a policy is currently deployed
sibyl simulate --policy policy.json --type scp --target current

# Simulate an IAM policy for a specific role
sibyl simulate --policy policy.json --type iam --role-arn arn:aws:iam::123456789012:role/MyRole

# Simulate an RCP
sibyl simulate --policy policy.json --type rcp --target prod_myapp

# Extend lookback period (default: 7 days, max: 90)
sibyl simulate --policy policy.json --type scp --target dev_myapp --days 30

Other commands

# List available OUs and groups
sibyl list-targets

# Show SCPs attached to a target
sibyl show-policies --target dev_myapp

# Print the minimal IAM policy required by this tool
sibyl --show-permissions

---

Target Resolution

The --target / --ou option accepts:

Format	Example	Description
OU key	dev_myapp	Friendly name from organizational-units.yaml
OU group	all_dev	Expands to all member OUs
OU ID	ou-xxxx-yyyyyyyy	Raw AWS Organizations OU ID
current	—	OUs where the policy is currently deployed

---

How It Works

1. Load the proposed policy file (JSON or YAML)
2. Resolve target OUs to their member AWS accounts
3. Discover real API usage from CloudTrail (LookupEvents, read-only)
4. Scan existing resources in each target account (policy-driven, read-only) — so that resources idle during the lookback window are still counted toward blast radius
5. Fetch existing SCPs/RCPs attached to the targets (for delta comparison)
6. Simulate the proposed deny statements against discovered actions locally
7. Report which actions would be newly blocked, grouped by severity and principal

Resource discovery

Alongside CloudTrail, Sibyl enumerates the standing inventory for every AWS service the proposed policy denies. A bucket idle for 30 days won't appear in CloudTrail, but a Deny s3:DeleteBucket still threatens it. Resource counts appear in the HTML report under Resources in scope and are tied to each block's blast-radius estimate.

Covered services (36 resource types across 36 IAM prefixes):

Core compute & storage — ec2 (instances, volumes, VPCs), lambda, s3, iam, cloudformation, ecr, ecs, eks, elasticloadbalancing, apigateway, cloudfront, route53

Databases & caching — dynamodb, rds (instances + clusters, incl. Aurora/DocumentDB/Neptune), elasticache, memorydb, timestream

Analytics & data — athena, glue, redshift, es (OpenSearch), kinesis, kafka (MSK), elasticmapreduce (EMR)

ML / AI — sagemaker (endpoints + notebook instances), bedrock (custom models)

Messaging & integration — sqs, sns, secretsmanager, ssm, logs

Security & governance — acm, wafv2, guardduty, macie2, config, cloudtrail

Use --no-resource-scan to skip this phase.

Severity classification: HIGH = create/delete/modify, MEDIUM = put/start/invoke, LOW = read/list/describe. LOW does not mean low business impact — blocking read-only APIs can break consoles and AWS services.

---

Required AWS Permissions

All read-only. Get the exact policy JSON:

sibyl --show-permissions

cloudtrail:LookupEvents
organizations:ListRoots
organizations:ListChildren
organizations:DescribeOrganizationalUnit
organizations:ListAccountsForParent
organizations:ListPoliciesForTarget
organizations:DescribePolicy
organizations:DescribeOrganization
sts:GetCallerIdentity

---

Security & Transparency

See SECURITY.md for a full breakdown of:

• Every API call made per operation
• What is cached and where (~/.cache/sibyl/)
• What is NOT stored (credentials, IPs, session context)
• How to audit and remove all local data

---

Tests

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v --cov=sibyl

---

CloudTrail regions

Events are queried in all supported regions. When simulating a policy that denies specific services, only events for those services are fetched (faster). Use --no-event-filter to fetch all events.

Caching

CloudTrail results are cached in ~/.cache/sibyl/ (daily rotation). Use --no-cache to force a fresh query. See SECURITY.md for details.