AccessGraph

Offline-first AWS IAM attack-path analysis for local policy bundles.

AccessGraph turns IAM-style account snapshots into evaluated permission graphs, privilege-escalation paths, risk scores, and remediation proposals that can be verified against access assertions. It is built to be deterministic and local by default: the core engine makes no AWS calls, LLM support is mock-first, and unsupported IAM semantics are documented instead of hidden.

Why It Exists

IAM findings get noisy when they stop at "principal can call action." AccessGraph connects policy evaluation, graph traversal, and remediation verification so you can answer:

• Who can reach a sensitive resource?
• Which routes depend on direct access versus privilege escalation?
• What breaks if an SCP-style remediation is applied?
• Can an explanation be generated without sending raw ARNs or account IDs to a model?

What Works Today

• Offline ingestion for synthetic AWS account, principal, policy, role, group, and resource bundles.
• IAM policy evaluation with identity policies, resource policies, boundaries, SCP-style ceilings, explicit deny handling, and condition support documented in COVERAGE.md.
• Permission graph generation and attack-path search across direct access and modeled privilege-escalation techniques.
• Risk scoring for discovered paths, including sensitive target and privilege-escalation signals.
• Remediation verification for direct edges with assertion checks to catch expected access regressions.
• Typer/Rich CLI, localhost FastAPI API, and a TypeScript + D3 frontend.
• Mock-first LLM explanation layer with ARN and 12-digit account ID redaction before provider invocation.

Current Limits

AccessGraph is a working local analysis prototype, not a complete IAM simulator. The current known gaps include live AWS import, full cross-account path stitching, service-specific resource applicability, large-graph frontend filtering, and hosted LLM providers. See COVERAGE.md and STATUS.md for the explicit source of truth.

Quickstart

Requirements:

• Python 3.12+
• uv
• Node.js ^20.19.0 or >=22.12.0 for the frontend

Install dependencies and run the synthetic demo:

uv sync --dev
cd frontend && npm ci && cd ..
make demo

The demo bundle in demo/accessgraph-demo-bundle.json contains two synthetic AWS accounts with planted paths: a privilege-escalation path from Attacker to a sensitive S3 object and a direct analyst-to-report path with a verified SCP remediation.

CLI

Commands operate on a local AccessGraph bundle JSON file:

uv run accessgraph ingest demo/accessgraph-demo-bundle.json
uv run accessgraph analyze demo/accessgraph-demo-bundle.json
uv run accessgraph paths demo/accessgraph-demo-bundle.json \
  --source arn:aws:iam::123456789012:user/Attacker \
  --target arn:aws:s3:::security-sensitive/admin-secret.txt
uv run accessgraph explain demo/accessgraph-demo-bundle.json \
  --source arn:aws:iam::123456789012:user/Attacker \
  --target arn:aws:s3:::security-sensitive/admin-secret.txt \
  --llm
uv run accessgraph verify demo/accessgraph-demo-bundle.json demo/accessgraph-demo-assertions.json
uv run accessgraph remediate demo/accessgraph-demo-bundle.json \
  --source arn:aws:iam::210987654321:user/Analyst \
  --target arn:aws:s3:::prod-sensitive-reports/q2.csv \
  --assertions demo/accessgraph-demo-assertions.json

Assertion files are JSON lists:

[
  {
    "principal_arn": "arn:aws:iam::123456789012:user/Alice",
    "action": "s3:GetObject",
    "resource": "arn:aws:s3:::bucket/key",
    "should_be_allowed": true
  }
]

API

Run the local API server:

uv run accessgraph serve

The server binds to 127.0.0.1 by default. The FastAPI app is also importable as accessgraph.api:app.

Implemented endpoints:

• GET /health
• POST /analyze
• POST /paths
• POST /explain
• POST /verify
• POST /remediate

Frontend

Run the D3 frontend locally:

cd frontend
npm ci
npm run dev

The frontend loads frontend/public/demo-analysis.json and renders the permission graph, selected path inspector, assertion results, and remediation viewer.

Repository Map

• src/accessgraph/ - ingestion models, evaluator, graph/path logic, scoring, remediation, API, CLI, and mock LLM layer.
• tests/ - unit and API coverage for the implemented behavior.
• frontend/ - Vite, TypeScript, and D3 UI.
• demo/ - synthetic bundle and assertion data used by make demo.
• docs/architecture.md - module diagram and data flow.
• COVERAGE.md - modeled IAM semantics and known gaps.
• THREAT_MODEL.md - security boundaries and assumptions.
• TECHNIQUES.md - modeled privilege-escalation catalog.

Development

Run the full local quality gate:

uv run pytest
uv run mypy --strict src tests
uv run ruff check
uv run ruff format --check
cd frontend && npm run typecheck && npm run build

Or run the aggregate target:

make gate

Before public pushes, run a quick secret scan over tracked content and keep demo data synthetic. The included demo ARNs, account IDs, names, and bucket paths are fixtures.