agent-blast-radius 0.1.0__tar.gz

agent_blast_radius-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv pip install --system -e '.[dev]'
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: pytest -q
+
+  # The fixture must fail its own policy with a findings failure — exit code exactly 1.
+  # An unsupported-only failure (2) or a mixed one (3) is a regression, not a pass.
+  fixture-gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: uv pip install --system -e .
+      - name: scan the fixture and require exit code 1
+        run: |
+          set +e
+          agent-blast-radius scan fixtures/overprivileged-agent --json report.json
+          code=$?
+          set -e
+          echo "exit code: $code"
+          test "$code" -eq 1
+      - uses: actions/upload-artifact@v4
+        with:
+          name: fixture-report
+          path: report.json
+
+  # The wheel must install and run cold, with no repo checkout, from uvx.
+  cold-install:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - run: |
+          set +e
+          uvx --from ./dist/*.whl agent-blast-radius scan fixtures/overprivileged-agent -q
+          test $? -eq 1

agent_blast_radius-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,50 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - name: the wheel must run cold and fail the fixture with exit code 1
+        run: |
+          set +e
+          uvx --from ./dist/*.whl agent-blast-radius scan fixtures/overprivileged-agent -q
+          test $? -eq 1
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # PyPI trusted publishing; no API token stored anywhere
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

agent_blast_radius-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Terraform
+.terraform/
+# (lock file committed for the fixture so plan.json is reproducible)
+*.tfstate
+*.tfstate.*
+*.tfplan
+crash.log
+override.tf
+override.tf.json
+*_override.tf
+*_override.tf.json
+
+# Credentials — never commit, even dead ones (plan §11)
+.env
+*.pem
+*.tfvars
+!example.tfvars
+credentials
+.aws/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+*.swp

agent_blast_radius-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.1.0 — 2026-09-01
+
+First release. Everything the project plan called v0.1:
+
+- IAM resolver over a pinned, vendored snapshot of the Service Authorization Reference
+  (iam-dataset, not botocore — `iam:PassRole` is not an API operation). Identity and
+  attached managed policies, wildcard expansion, field-wise ARN matching, four modeled
+  condition operators with residue for the rest, Deny subtraction with subsumption.
+- `NotAction`/`NotResource` refused per statement and recorded, never approximated.
+- Trust policies first-class; the PassRole chain requires the trust fact to fire.
+- Taint propagation over per-tool gating and `returns_external_data`.
+- Escalation rule pack: 13 cited rules as bound hyperedges; every substitution
+  enumerated, provenance path per firing, depth per principal.
+- Parsers: Terraform plan JSON, MCP `tools/list`, Bedrock action groups; annotation
+  overlay with validation (every tool annotated; gating never assumed).
+- Report schema 1.0.0, terminal rendering from it, no score.
+- CI mode with `fail_if` gates and independent exit codes for findings vs incomplete.
+- Differential validation harness against `iam:SimulateCustomPolicy`: 44-policy corpus,
+  stratified boundary-weighted draws, confusion matrix.
+- Fixture: a Bedrock-style agent with six Lambda-backed tools, two gated, whose chain
+  cannot be reproduced by resolving any single role.

agent_blast_radius-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ali El-Asmar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_blast_radius-0.1.0/Makefile

@@ -0,0 +1,16 @@
+FIXTURE := fixtures/overprivileged-agent
+
+.PHONY: test lint fixture-plan
+
+test:
+	pytest -q
+
+lint:
+	ruff check . && ruff format --check .
+
+# Regenerate the checked-in Terraform plan JSON. Needs no credentials and deploys nothing.
+fixture-plan:
+	cd $(FIXTURE)/terraform && terraform init -input=false >/dev/null \
+	  && terraform plan -input=false -out=tfplan >/dev/null \
+	  && terraform show -json tfplan > ../plan.json && rm -f tfplan
+	@echo "wrote $(FIXTURE)/plan.json"

agent_blast_radius-0.1.0/PKG-INFO

@@ -0,0 +1,300 @@
+Metadata-Version: 2.5
+Name: agent-blast-radius
+Version: 0.1.0
+Summary: Static, pre-deployment analysis of what an agentic system can reach in an AWS account from untrusted model input.
+Project-URL: Homepage, https://github.com/aelasmar01/agent-blast-radius
+Project-URL: Source, https://github.com/aelasmar01/agent-blast-radius
+Author: Ali El-Asmar
+License: MIT License
+        
+        Copyright (c) 2026 Ali El-Asmar
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agents,aws,bedrock,iam,mcp,privilege-escalation,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: botocore>=1.34
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: validate
+Requires-Dist: boto3>=1.34; extra == 'validate'
+Description-Content-Type: text/markdown
+
+# agent-blast-radius
+
+**Static, pre-deployment analysis of what an agentic system can actually do to your AWS account.**
+
+> This agent's four tools look scoped. Three hops of IAM later, a prompt injection is an account takeover.
+
+That sentence is the whole project. Everything in this repo exists to make it provable against a
+real fixture, in CI, before deployment — not in production telemetry after the fact.
+
+---
+
+## What it looks like
+
+```
+$ agent-blast-radius scan ./fixtures/overprivileged-agent
+agent-blast-radius  deployment=overprivileged-agent  account=000000000000
+  report schema 1.0.0  dataset 8e8e0df0ce50  rules v1
+
+TOOLS
+  reachable    read_support_ticket      role=ticket-reader-role       tainted input: ticket_id
+  reachable    query_customer_record    role=customer-lookup-role     output of read_support_ticket re-enters the model context
+  reachable    call_internal_api        role=internal-api-role        output of read_support_ticket re-enters the model context
+  reachable    deploy_helper            role=agent-execution-role     output of read_support_ticket re-enters the model context
+  unreachable  run_maintenance_job      role=agent-execution-role     gated: approval_required
+  unreachable  rotate_credentials       role=incident-response-role   gated: approval_required
+
+PRINCIPALS REACHABLE FROM ATTACKER INPUT
+  depth 0  agent-execution-role         taint-reachable
+  depth 0  customer-lookup-role         taint-reachable
+  depth 0  internal-api-role            taint-reachable
+  depth 0  ticket-reader-role           taint-reachable
+  depth 1  incident-response-role       via 1 escalation hop
+
+ACCOUNT TAKEOVER
+  Attach AdministratorAccess to a reachable role  [iam-attachrolepolicy-self, rhino-2018]  depth 2
+    iam:AttachRolePolicy on *  <- incident-response-role/break-glass#BreakGlass
+
+ESCALATION CHAINS (1)
+  -> incident-response-role  via PassRole into a new Lambda function  [passrole-lambda-createfunction, rhino-2018]  depth 1
+       iam:PassRole on arn:aws:iam::000000000000:role/*  <- agent-execution-role/helper-deploy#PassRoleToLambda
+       lambda:CreateFunction on *  <- agent-execution-role/helper-deploy#ManageHelpers
+       lambda:InvokeFunction on *  <- agent-execution-role/helper-deploy#ManageHelpers
+       fact: role_trusts_service(role=incident-response-role, service=lambda.amazonaws.com)
+
+REACHABLE CAPABILITIES (199)
+  ... (see the full output in docs/post.md)
+
+UNSUPPORTED (0)
+  none — the analysis is complete for the constructs this tool models
+
+Reachability is not exploitability: this is what the tool graph permits if the model
+can be induced to make the calls, not a prediction that it will.
+
+FAIL: 9 finding(s) tripped fail_if:
+  - 'iam:*' matches 190 actions on * as incident-response-role (depth 1): iam:AcceptDelegationRequest, iam:AddClientIDToOpenIDConnectProvider, iam:AddRoleToInstanceProfile, ...  <- incident-response-role/break-glass#BreakGlass
+  - 'iam:*' matches iam:PassRole on arn:aws:iam::000000000000:role/* as agent-execution-role (depth 0): iam:PassRole  <- agent-execution-role/helper-deploy#PassRoleToLambda
+  - 'kms:Decrypt' matches kms:Decrypt on * as incident-response-role (depth 1): kms:Decrypt  <- incident-response-role/break-glass#BreakGlass
+  - escalation chain passrole-lambda-createfunction -> incident-response-role (depth 1)
+  - escalation chain iam-attachrolepolicy-self -> all_actions (depth 2)
+  - escalation chain iam-putrolepolicy-self -> all_actions (depth 2)
+  - chain passrole-lambda-createfunction -> incident-response-role at depth 1 <= max_chain_depth 2
+  - chain iam-attachrolepolicy-self -> all_actions at depth 2 <= max_chain_depth 2
+  - chain iam-putrolepolicy-self -> all_actions at depth 2 <= max_chain_depth 2
+$ echo $?
+1
+```
+
+## Threat model
+
+An attacker controls text that reaches the model: a support ticket, a scraped page, a document in a
+bucket the agent reads. They cannot call AWS directly. They can only induce the model to call the
+tools it already has.
+
+The question this tool answers: **given that starting position, what set of AWS actions becomes
+reachable?**
+
+It answers it by:
+
+1. Marking which tool inputs are attacker-influenced (explicit annotation — no inference).
+2. Propagating taint through the tools the model can reach, respecting per-tool gating.
+3. Resolving the IAM identity *and trust* policies behind those tools into an effective capability set.
+4. Applying an escalation rule pack to a fixpoint, so multi-action chains such as
+   `iam:PassRole` + `lambda:CreateFunction` surface as single findings with a provenance path.
+
+## Reachability is not exploitability
+
+This tool computes what the tool graph **permits** if the model can be induced to make the calls.
+It does not predict whether a given model will. It is a map of unlocked doors, not a prediction of
+which door someone walks through. Every finding should be read that way.
+
+## Prior art
+
+This re-implements policy resolution that Cloudsplaining and PMapper already do well. I built it to
+understand IAM evaluation from the inside, and extended it with taint propagation from untrusted
+model input, which those tools don't model.
+
+| Prior art | What it covers |
+|---|---|
+| [Cloudsplaining](https://github.com/salesforce/cloudsplaining) (Salesforce) | Least-privilege violations, wildcard detection, roles assumable by compute services |
+| [PMapper](https://github.com/nccgroup/PMapper) (NCC) | Principal-to-principal privilege escalation graphs |
+| [Parliament](https://github.com/duo-labs/parliament) (Duo) | Policy linting |
+| Rhino Security Labs | The canonical AWS privilege-escalation method list |
+| Obsidian, Grafyn, Entrust | Commercial "agent blast radius" — runtime, SaaS-identity focused |
+| AgentWard | Published cross-server MCP escalation chains against `awslabs/mcp` |
+| AWS Agent Toolkit | IAM condition keys distinguishing agent actions from human ones |
+
+The open gap is not detection quality. Everything commercial here is **runtime observability**.
+Nobody is doing **static, pre-deployment, CI-gating analysis over Terraform plus tool manifests**.
+That is the pitch: shift-left for agent permissions — catch the chain in the PR.
+
+---
+
+## Scope
+
+**In scope (v1)**
+
+- IAM identity policy parsing: wildcards, resource ARNs, basic conditions.
+- Trust policy parsing. `iam:PassRole` + `lambda:CreateFunction` cannot be resolved without it —
+  PassRole only succeeds if the target role's trust policy admits `lambda.amazonaws.com`.
+- Explicit `Deny`, evaluated after the allow set is assembled.
+- 10–12 Rhino escalation methods as declarative, cited rules.
+- Two input formats: MCP server manifest, Bedrock agent action group.
+- Taint as explicit config annotation.
+- Terminal report plus versioned JSON output.
+- CI mode with assertion-based failure.
+
+**Out of scope, deliberately — ordered by impact on *this* threat model**
+
+1. **Resource-based policies** beyond trust policies (S3 bucket, KMS key, Lambda resource policies).
+   Highest impact, because cross-account reach lives here.
+2. Permission boundaries.
+3. SCPs.
+4. Session policies.
+
+That ordering is not the conventional one. It follows from the threat model: this tool is about what
+untrusted input reaches, and the largest unmodeled reach is cross-account via resource policies.
+
+**Single-account assumption.** Stated in the IR and enforced in the analyzer. Cross-account reach
+lives in the gap above.
+
+**Gating is the load-bearing axis.** A survey of real deployments
+([docs/q2-shared-roles.md](docs/q2-shared-roles.md)) found that locally-run MCP servers and
+framework-on-Lambda agents put every tool behind one credential, while Bedrock action groups and
+Lambda-backed tools get per-tool roles — but *every* platform exposes per-tool gating (MCP client
+`autoApprove`, Bedrock `requireConfirmation`, AgentCore policy engine). So reachability is computed
+over gating first and the role graph second, and a single-role deployment with no gating annotations
+is told plainly that taint propagation adds nothing, rather than being handed a re-skinned
+Cloudsplaining report.
+
+**`NotAction` / `NotResource` are refused, not approximated.** They invert the set logic and are a
+silent under-report risk. The offending statement is skipped and recorded in the report's
+`unsupported` section with its policy and statement ID; the scan continues, and CI fails closed on
+a non-empty `unsupported` list by default. Failing visibly is defensible; under-reporting silently
+is not. The same section carries attached managed policies the vendored snapshot doesn't know and
+actions it doesn't recognise.
+
+**Conditions.** `StringEquals`, `StringLike`, `ArnLike`, and `Bool` are modeled and carried on the
+capability. Every other operator is recorded as residue and the capability is reported as
+*unconstrained but flagged* — the conservative direction. A `Deny` only removes a capability when
+it is unconditional and its resource pattern fully subsumes the capability's; a conditional or
+partial `Deny` is flagged, never trusted.
+
+**Action dataset.** Wildcards expand against a pinned snapshot of the AWS Service Authorization
+Reference (via [iam-dataset](https://github.com/iann0036/iam-dataset)), not botocore. botocore lists
+API operations, and IAM actions are not API operations: `iam:PassRole` and `s3:ListBucket` do not
+exist there, and expanding `iam:*` from it would silently drop the action the headline finding
+depends on. The snapshot commit is in `src/agent_blast_radius/data/VERSION` and printed in every
+report.
+
+**No 0–100 score.** It invites "how is that computed" and there is no good answer.
+
+---
+
+## Validation
+
+The resolver is differential-tested against `iam:SimulateCustomPolicy` over a fixed corpus of 44
+managed policies chosen for construct diversity plus the fixture's roles. Draws are stratified —
+half allow-expected, half deny-expected — and the deny half is weighted toward near-misses (right
+action / wrong resource, failing condition, actions just outside a wildcard boundary, explicit
+Deny, `NotAction` exclusions) because uniform draws are trivially denied and would inflate the
+numbers. The output is a confusion matrix, not an agreement rate; the cell that matters is
+*resolver says deny, AWS says allowed*. See [validate/results](validate/results/README.md) and
+[docs/divergences.md](docs/divergences.md).
+
+## Install and run
+
+```bash
+uvx agent-blast-radius scan ./fixtures/overprivileged-agent
+```
+
+No manual setup, no deployed AWS resources, no credentials. The action dataset and the managed
+policy documents are vendored and pinned; a scan never touches the network.
+
+`agent.yaml` describes the deployment either as inline IR or as **sources + annotations**:
+
+```yaml
+sources:
+  terraform_plan: plan.json                 # roles, trust policies, Lambda -> role links
+  mcp_tools: mcp-tools.json                 # tool names + argument schemas
+  bedrock_action_groups: [action-group.json]  # functions, requireConfirmation, shared Lambda
+annotations:                                # per tool: what no document can say
+  read_support_ticket:
+    gating: none
+    tainted_inputs: [ticket_id]             # validated against the tool's declared arguments
+    returns_external_data: true             # its output re-enters the model context
+  run_maintenance_job: {}                   # gating declared by Bedrock; still needs an entry
+```
+
+Every tool needs an annotation entry. Gating is never assumed to be `none`.
+
+### CI mode
+
+```yaml
+fail_if:
+  reachable_actions_matching: ["iam:*", "sts:AssumeRole", "kms:Decrypt"]
+  escalation_chains_found: true
+  max_chain_depth: 2               # fail on any chain reachable in <= 2 hops
+  unsupported_statements: true     # default: fail closed when the analysis skipped something
+```
+
+| exit | meaning |
+|---|---|
+| 0 | clean |
+| 1 | a findings gate tripped |
+| 2 | incomplete: `unsupported` is non-empty |
+| 3 | both |
+| 4 | input error |
+
+Findings and incompleteness are gated independently and never collapse into one code, so a run
+that skipped a `NotAction` statement cannot pass as clean, and a real finding cannot hide behind
+an incompleteness failure. The repo's own CI asserts the fixture exits with **exactly 1**.
+
+`--json report.json` writes the versioned report (schema `1.0.0`); the terminal output is rendered
+from that same model. There is no score.
+
+## Status
+
+v0.1 feature-complete; the first live validation run is pending. See [docs/roadmap.md](docs/roadmap.md)
+for the build order and [agent-blast-radius-analyzer-plan.md](agent-blast-radius-analyzer-plan.md)
+for the full project plan.
+
+| Component | State |
+|---|---|
+| IR (tools, roles, policies, taint, gating) | done |
+| IAM resolver (identity + managed + trust, Deny, wildcards, conditions) | done |
+| Differential validation vs `iam:SimulateCustomPolicy` | harness done; first live run pending |
+| MCP / Bedrock / Terraform parsers + annotation overlay | done |
+| Reachability fixpoint + rule pack (13 cited rules, bound hyperedges) | done |
+| Reporting (schema 1.0.0) + CI mode with independent exit codes | done |
+
+## License
+
+MIT. See [LICENSE](LICENSE).