Agent Blast-Radius

Quickstart

npm install -g @shieldly/cli

Run it with no arguments in a project that has an agent config (.mcp.json, Claude Code settings, Claude Desktop, Cursor, Windsurf, VS Code) — it auto-discovers the config and any AWS profile or role it references:

shieldly agent-scan

Or point it at an input explicitly:

shieldly agent-scan --policy-file agent-policy.json
shieldly agent-scan --role-arn arn:aws:iam::123456789012:role/my-agent
shieldly agent-scan --cfn-file cdk.out/MyStack.template.json
shieldly agent-scan --sarif > results.sarif

Inputs

Auto-discovery paths

With no input flag, agent-scan walks these paths (project-level relative to the current directory, plus global/cross-project locations) looking for AWS_PROFILE, role ARNs, or hardcoded access keys:

How to read a blast-radius report

Every scan produces one overall grade — the worst finding wins:

Findings are grouped into six categories:

Each finding lists the matched actions, the affected resources, and a one-line fix — start with CRITICAL/HIGH findings in ESCALATION and DESTRUCTIVE first; those are the ones that turn a compromised or misbehaving agent into an account-wide incident.

Rule reference

Rules are matched by glob intersection (e.g. a grant of s3:* matches a rule for s3:DeleteObject) — no AWS action list is expanded or shipped.* marks rules whose severity is bumped when the statement's Resource is also "*". Suppress any rule with --ignore <rule-id>.

Budget file reference (CI enforcement)

--budget shieldly.policy.yml declares the maximum permission budget an agent's credentials may have; agent-scan exits non-zero when a scan violates it — wire it into a PR check the same way you would a test suite.

# shieldly.policy.yml
maxSeverity: HIGH
denyCategories:
  - ESCALATION
ignoreRules:
  - BR-GUARD-NO-BOUNDARY
maxFindings: 10

YAML or JSON both work. See shieldly.policy.example.yml for a full example.

Use in CI

The Shieldly GitHub Action runs agent-scan directly — no API key needed, fully offline:

- name: Agent Blast-Radius
  uses: shieldly-io/action@v1
  with:
    agent-scan: true
    agent-scan-path: .
    budget-file: shieldly.policy.yml

See the GitHub Action docs for every input.

History, diffs & alerts (Builder plan+)

--upload sends the scan's findings (rule IDs, categories, severities, grade — never the policy document itself) to your Shieldly account: it builds a per-agent history, diffs each scan against the last one for that identity, and alerts Slack when a new CRITICAL finding appears. View it at /app/agents. Connected AWS accounts (Team plan+) also get a daily scheduled re-scan of their registered agent roles, so permission drift is caught even between manual scans.

FAQ

Links

• CLI reference
• GitHub Action
• Free web analyzer
• Source & issues