Metadata-Version: 2.4
Name: sibyl-aws
Version: 0.3.3
Summary: AWS Policy Simulation CLI — predict SCP, IAM, and RCP impact before deployment
License: MIT
Project-URL: Homepage, https://github.com/radekpadrta/sibyl-aws
Project-URL: Bug Tracker, https://github.com/radekpadrta/sibyl-aws/issues
Project-URL: Documentation, https://github.com/radekpadrta/sibyl-aws#readme
Project-URL: Source Code, https://github.com/radekpadrta/sibyl-aws
Keywords: aws,scp,iam,rcp,policy,simulation,organizations,security,sibyl
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: boto3>=1.28
Requires-Dist: click>=8.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: questionary>=2.0
Requires-Dist: rich>=13.0
Provides-Extra: tui
Requires-Dist: textual>=0.50; extra == "tui"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: moto>=4.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"

# 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.

[![PyPI](https://img.shields.io/pypi/v/sibyl-aws)](https://pypi.org/project/sibyl-aws/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://pypi.org/project/sibyl-aws/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

---

## Install

```bash
pipx install sibyl-aws
```

Or with pip:

```bash
pip install sibyl-aws
```

---

## Quick Start

```bash
# 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)

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
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](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

```bash
# 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](SECURITY.md) for details.
