Metadata-Version: 2.4
Name: atlas-redteam
Version: 2.0.0a1.dev58
Summary: AWS Cloud Attack Path Mapping — BloodHound-style graph analysis (recon + planning + simulation, no execution)
Author: Omar
License-Expression: MIT
Project-URL: Homepage, https://github.com/Haggag-22/Atlas
Project-URL: Repository, https://github.com/Haggag-22/Atlas
Project-URL: Issues, https://github.com/Haggag-22/Atlas/issues
Keywords: aws,security,adversary-emulation,red-team,cloud-security
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Information Technology
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: boto3>=1.35.0
Requires-Dist: aioboto3>=13.0.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: pydantic-settings>=2.2.0
Requires-Dist: networkx>=3.2
Requires-Dist: structlog>=24.1.0
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.7.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: streamlit>=1.40.0
Requires-Dist: pyvis>=0.3.2
Provides-Extra: ai
Requires-Dist: openai>=1.30.0; extra == "ai"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: ruff>=0.3.0; extra == "dev"
Requires-Dist: types-pyyaml>=6.0.0; extra == "dev"
Requires-Dist: types-aiofiles>=24.1.0; extra == "dev"

# Atlas

**AWS Cloud Adversary Emulation Platform**

---

> **⚠️ This tool is still under development.** APIs and behavior may change. Use with caution in production environments.

---

## Attack Knowledge: pathfinding.cloud & Hacking the Cloud

Atlas incorporates **all techniques from [pathfinding.cloud](https://github.com/DataDog/pathfinding.cloud)** (parginfd.cloud — Datadog's verified AWS IAM privilege escalation paths). The 65+ attack paths—covering IAM, EC2, Lambda, ECS, Glue, CodeBuild, SageMaker, SSM, CloudFormation, Bedrock, AppRunner, and more—are synced automatically on first run and merged into the attack graph.

Atlas also includes techniques from **[Hacking the Cloud](https://hackingthe.cloud)** — exploitation paths (IMDS credential theft, Lambda SSRF, misconfigured resource policies, OIDC trust misconfig, Cognito self-signup, CloudFront/S3 takeover, PassRole abuse), post-exploitation persistence (GetFederationToken survival, CodeBuild runner persistence, rogue OIDC provider, IAM Roles Anywhere, S3 ACL persistence), and defense evasion (GuardDuty, CloudTrail). Operational tradecraft from Hacking the Cloud is in `post_exploitation_operational.yaml`.

This gives Atlas comprehensive, battle-tested coverage of real-world AWS privilege escalation techniques.

---

## Contributing Red Team Techniques

**We welcome contributions of new red team techniques.** If you have attack paths, privilege escalation methods, or AWS abuse techniques you'd like to add to Atlas, please open an issue or submit a pull request. The planner and attack graph are designed to be extended—see `src/atlas/planner/attack_graph.py` and `src/atlas/knowledge/data/api_detection_profiles.yaml` for how techniques are modeled.

---

## What is Atlas?

Atlas is a next-generation AWS cloud adversary emulation platform. It helps red teams and security researchers:

- **Discover** attack paths from a given identity (recon + attack graph)
- **Plan** multi-step privilege escalation chains
- **Simulate** execution without making AWS API calls (BloodHound-style — mapping only, no execution)
- **Explain** attack paths with AI-powered or template-based explanations

---

## Features

| Feature | Description |
|---------|-------------|
| **pathfinding.cloud integration** | All 65+ verified IAM privilege escalation paths from pathfinding.cloud (Datadog) — auto-synced on first run |
| **Hacking the Cloud techniques** | Exploitation, post-exploitation persistence, and defense evasion from hackingthe.cloud |
| **BloodHound-style queries** | `who-can-reach-admin`, `blast-radius`, `external-trusts`, `wildcards`, `privileged-principals`, `detection-map` |
| **Detection encyclopedia** | CloudTrail + GuardDuty profiles for each API action; `atlas inspect` shows detection scores |
| **AI-powered explanations** | LLM-grounded explanations using verified pathfinding.cloud paths |
| **k8scout-style GUI** | D3.js force-directed graph, Attack Chain Analyzer, findings, export |
| **Access key decoder** | `atlas inspect-key` decodes AWS account ID from access key ID (offline) |
| **Case management** | Save, list, and delete cases with `atlas cases` and `atlas delete-case` |
| **Tiered permission recon** | Identity, policy, trust, guardrail, resource, and bruteforce tiers |
| **Noise budget** | Stealth-aware planning with configurable detection cost limits |

---

## Requirements

- Python 3.12+
- AWS credentials configured (e.g. `~/.aws/credentials`)

---

## Installation

**Install from PyPI (recommended):**

```bash
pip install atlas-redteam
```

**Or with pipx (isolated environment, no venv needed):**

```bash
pipx install atlas-redteam
```

**Update to latest version:**

```bash
pip install --upgrade atlas-redteam
# or
pipx upgrade atlas-redteam
```

> **Note for maintainers:** To publish new versions so users get updates, see [docs/RELEASE.md](docs/RELEASE.md).

**For development (editable install):**

```bash
git clone https://github.com/Haggag-22/Atlas.git
cd Atlas
pip install -e ".[dev]"
```

---

## Quick Start

```bash
# Configure AWS profile
atlas config --profile my-profile --region us-east-1

# Run recon + planning (creates a case)
atlas plan --case mycase

# List attack paths and simulate
atlas simulate --case mycase --attack-path AP-01

# Explain an attack path
atlas explain --case mycase --attack-path AP-01

# Open the GUI (k8scout-style, port 8050)
atlas gui --case mycase
```

> **Note:** If you see the old Streamlit UI (port 8501), you may have run `streamlit run` directly. Use `atlas gui` instead for the new D3.js-based interface.

---

## Commands

| Command | Description |
|--------|-------------|
| `atlas config` | Set or show AWS profile and region |
| `atlas plan` | Run reconnaissance + planning. Uses pathfinding.cloud (65+ verified IAM privesc paths) automatically—syncs on first run if needed. |
| `atlas simulate` | Simulate an attack path (no AWS calls) |
| `atlas cases` | List saved cases |
| `atlas delete-case` | Delete a saved case |
| `atlas explain` | Explain an attack path (AI or template) |
| `atlas gui` | Open the k8scout-style web UI (D3.js graph, Attack Chain Analyzer) |
| `atlas export-report` | Export case to JSON for offline GUI viewing |
| `atlas query` | BloodHound-style queries: who-can-reach-admin, blast-radius, external-trusts, wildcards, privileged-principals, detection-map |
| `atlas inspect` | Inspect detection profiles for API actions (CloudTrail + GuardDuty) |
| `atlas inspect-key` | Decode AWS account ID from access key ID (offline) |

---

## Output Structure

```
output/<case>/
├── case.json           # Case metadata
├── plan/               # Recon + planning
│   ├── env_model.json
│   ├── attack_edges.json
│   ├── graph.json
│   ├── attack_paths.json
│   └── ...
├── sim/                # Simulation results (if run)
└── explanations.json   # Cached AI/template explanations
```

---

## Attack Techniques

Atlas models techniques from **pathfinding.cloud**, **[Hacking the Cloud](https://hackingthe.cloud)**, and its own attack pattern registry, including:

- **IAM**: Role assumption, access key creation, policy attachment, inline policy injection, PassRole abuse, trust policy modification, permissions boundary manipulation
- **EC2**: PassRole via instance profile, userdata read/modify, EC2 Instance Connect, IMDS credential theft (Hacking the Cloud)
- **Lambda**: PassRole, code/config injection, credential theft, SSRF-based cred theft (Hacking the Cloud)
- **ECS, Glue, CodeBuild, SageMaker**: PassRole and service-specific escalation
- **SSM**: Session Manager, tag-based enablement
- **CloudFormation, Bedrock, AppRunner**: PassRole and resource abuse
- **S3**: Bucket policy, object read/write, ACL persistence (Hacking the Cloud)
- **Cognito, OIDC, CloudFront**: Self-signup, trust misconfig, domain takeover (Hacking the Cloud)
- **Post-exploitation**: GetFederationToken survival, rogue OIDC provider, IAM Roles Anywhere (Hacking the Cloud)
- **Defense evasion**: GuardDuty, CloudTrail evasion (Hacking the Cloud)

Detection costs and noise levels are derived from CloudTrail and GuardDuty profiles in `src/atlas/knowledge/`.

---

## Discovered Resources

The recon engine collects the following resource types (configurable via `recon.resource_types`):

| Resource | Service | Key Security Data |
|----------|---------|-------------------|
| S3 Buckets | S3 | Bucket policies, Public Access Block |
| EC2 Instances | EC2 | Instance profiles, IMDS config, security groups |
| Lambda Functions | Lambda | Execution roles, resource policies, environment variables |
| RDS Instances | RDS | Public accessibility, encryption, IAM auth, snapshots |
| KMS Keys | KMS | Key policies, grants, rotation status |
| Secrets Manager Secrets | Secrets Manager | Resource policies, rotation, KMS encryption |
| SSM Parameters | SSM | Parameter types (SecureString), KMS key IDs |
| CloudFormation Stacks | CloudFormation | Stack roles, capabilities, outputs |

---

## License

MIT
