CloudPath AI

AI-Powered Cloud Attack Path Analyzer

"Discover how cloud weaknesses can be chained into real attack paths."

CloudPath AI is a defensive, open-source cloud security platform. Instead of reporting cloud misconfigurations as an isolated flat list (the way most scanners do), it builds a graph of your cloud environment, finds the actual chains an attacker could walk from the internet to your sensitive data, ranks those paths by real risk, and uses AI only to explain findings a deterministic engine already discovered — never to invent them.

Project status: v1.0.0 released, with a substantial security-hardening and coverage round on top. See Roadmap and CHANGELOG.md for exactly what's built. This is honestly-documented, not a claim of completeness — read this README for what actually exists today.

---

The problem

Cloud scanners (Prowler, ScoutSuite, native AWS tools) report findings in isolation:

• "S3 bucket X is public"
• "IAM role Y has * permissions"
• "Security group Z allows 0.0.0.0/0"

Individually, none of these tells you what actually matters: can these weaknesses be chained together into a real path to something valuable? CloudPath AI answers that question directly — "given what's exposed, what's the shortest way to my production database?" — rather than making you manually correlate hundreds of flat findings yourself.

How it's different

The deterministic graph/security engine discovers attack paths. AI only explains and summarizes what the engine already found — it never invents a finding, never gets to add a step to a path, and the system produces useful output even with AI fully disabled. See docs/ARCHITECTURE.md for the full design rationale.

What's actually built

Area	Status	Where
AWS discovery (IAM, EC2, S3, VPC, Security Groups)	✅	providers/aws/
Lambda, RDS, Secrets Manager, KMS collection	✅	providers/aws/collectors.py
Asset normalization + graph assembly	✅	engine/models.py, engine/graph/
IAM effective-permission analysis	✅	engine/iam/
Network exposure analysis (SGs, S3 public access)	✅	engine/network/
Security-group-to-security-group correlation (incl. egress-aware confidence)	✅	engine/network/analyzer.py
KMS encryption edges (S3, RDS, Secrets Manager, EBS→EC2)	✅	providers/aws/provider.py
Attack path discovery (k-shortest-paths)	✅	engine/attack_paths/engine.py
Risk + confidence scoring	✅	engine/risk/
What-if remediation simulation	✅	engine/attack_paths/whatif.py
REST API (FastAPI)	✅	backend/main.py
PostgreSQL persistence	✅	backend/db/
Background scanning (Celery + Redis)	✅	backend/tasks/
Auth, RBAC, rate limiting, audit logging	✅	backend/auth.py, backend/rate_limit.py
JWT revocation (logout invalidates tokens server-side)	✅	backend/token_revocation.py
Tenant isolation (per-account access control)	✅	backend/tenant_scope.py
GET /api/v1/audit-logs endpoint	✅	backend/audit_log_query.py
React dashboard	✅	frontend/
Interactive attack graph (React Flow), with click-to-inspect on nodes AND edges	✅	frontend/src/pages/AttackGraph.tsx
AI abstraction layer (Anthropic/OpenAI/Ollama)	✅	ai/
Evidence-first AI wired into the API, proven prompt-injection defense	✅	backend/ai_service.py
MITRE ATT&CK mapping (deterministic)	✅	mitre/
Synthetic scenario test suite	✅	tests/test_synthetic_scenarios.py
Benchmarking harness	✅	benchmarks/
Real cloudpath CLI (scan, assets, paths, simulate, report, incl. scan wait for async polling)	✅	cli/
Docker hardening (.dockerignore, migration entrypoint)	⚠️ audited and fixed, not verified by execution — see docs/POST_V1_DOCKER_AUDIT_NOTES.md
Lambda VPC-attached SG correlation	✅	providers/aws/provider.py
Multi-cloud (Azure/GCP)	❌ not built, deliberately out of scope — see docs/POST_V1_SESSION_SUMMARY.md
Independent accuracy benchmarking (vs. Prowler/ScoutSuite)	❌ not built — current harness is a regression detector, not independent validation

150+ tests passing across the full project (113 at v1.0.0 + 33+ added in the post-release hardening round), run against real Postgres, real Redis, and real moto-mocked AWS wherever persistence/queuing/cloud APIs are involved — not just mocks.

Architecture

AWS API → Collectors → Asset Inventory → Relationship Builder
                                              ↓
                            IAM Engine ─→ Graph Engine ←─ Network Engine
                                              ↓
                                     Attack Path Engine
                                              ↓
                                    Risk / Confidence Engine
                                        ↓           ↓
                                  MITRE Mapper   AI Explanation Layer
                                              ↓
                          FastAPI Backend ←→ PostgreSQL + Redis
                                ↓
                    React Dashboard  /  cloudpath CLI

Full detail, including the graph data model, IAM evaluation logic, risk-scoring formula, and threat model: see docs/ARCHITECTURE.md.

Example attack path

Internet
  ↓ (EXPOSED_TO)
Public EC2 Instance
  ↓ (RUNS_AS)
WebServerRole
  ↓ (CAN_PASS_ROLE)
HighPrivilegeRole
  ↓ (CAN_READ)
Production S3 Bucket

Risk: HIGH (score 72/100) · Confidence: 0.95 · MITRE: T1190, T1133, T1098.003, T1530

(This exact score was verified by running the real RiskEngine against this exact scenario shape, not written by hand.)

Installation

Local (no Docker)

git clone https://github.com/Aymwvn/CloudPath-AI.git
cd CloudPath-AI
pip install -r requirements.txt

createdb cloudpath
alembic upgrade head

export JWT_SECRET_KEY=$(python -c "import secrets; print(secrets.token_hex(32))")
python scripts/create_admin.py --username admin   # prompts for a password

uvicorn backend.main:app --reload

Frontend:

cd frontend
npm install
npm run dev   # http://localhost:5173, proxies /api to :8000

CLI:

pip install -e .
cloudpath login --url http://localhost:8000 --username admin
cloudpath scan aws --region us-east-1
cloudpath paths list --min-severity HIGH

Docker

cp .env.example .env   # fill in POSTGRES_PASSWORD and JWT_SECRET_KEY
docker compose up --build
docker compose exec backend python scripts/create_admin.py --username admin

Note: the Docker setup has been carefully audited (non-root containers, .dockerignore, automatic migrations on startup — see docs/POST_V1_DOCKER_AUDIT_NOTES.md) but has not been verified by actually running it end-to-end. Confirm it works for you before relying on it.

AWS permissions required

Read-only, least-privilege. Never requires write/mutating permissions. Full policy JSON: see docs/ARCHITECTURE.md Section 10.

Authentication

Three roles: viewer (read-only) < analyst (can trigger scans/simulations) < admin (can manage users and grant cross-account access).

curl -X POST http://localhost:8000/api/v1/auth/login \
  -d "username=admin&password=yourpassword"

Use the returned access_token as Authorization: Bearer <token>. Log out to revoke a token server-side before its natural 30-minute expiry:

curl -X POST http://localhost:8000/api/v1/auth/logout -H "Authorization: Bearer <token>"

Tenant isolation: non-admin users only see scan data for AWS accounts they've been explicitly granted access to. Admins see everything. See docs/POST_V1_REVOCATION_AUDIT_TENANT_PATCH.md.

AI configuration

Set one of these environment variables to enable POST /api/v1/attack-paths/{id}/analyze:

• ANTHROPIC_API_KEY — uses Claude
• OPENAI_API_KEY — uses OpenAI
• OPENAI_BASE_URL (e.g. http://localhost:11434/v1) — uses a local Ollama model

Without any of these set, everything else in the platform still works — the deterministic engine never depends on AI being configured.

Testing

python -m pytest tests/ -v

150+ tests. Tests requiring Postgres/Redis skip cleanly (not fail) if those aren't reachable. See docs/PHASE16_NOTES.md for the 8 canonical synthetic attack scenarios this project validates against.

Benchmarking

python -m benchmarks.run_benchmark

Writes docs/benchmarks.md. Read docs/PHASE17_NOTES.md for an honest description of what this does and doesn't prove — it's a regression detector against hand-traced ground truth, not independent real-world accuracy validation.

Security model

See SECURITY.md for the full threat model, RBAC design, tenant isolation, and vulnerability reporting process.

Roadmap

All 20 originally-planned phases are complete (v1.0.0), plus a substantial post-release round covering deeper AWS coverage (Lambda/RDS/Secrets/KMS, SG-to-SG correlation, encryption edges), security hardening (JWT revocation, tenant isolation, audit logs), and UX (interactive graph with edge-click detail, a real CLI). See CHANGELOG.md and docs/POST_V1_SESSION_SUMMARY.md for the full history including every real bug caught and fixed along the way.

Known gaps, tracked honestly, not hidden: multi-cloud support, independent accuracy benchmarking, NACL-level network modeling, VPC peering reachability, Docker execution verification.

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE.