@shieldly/cli 1.0.5 → 1.2.0

package/README.md

@@ -63,11 +63,70 @@ large CloudFormation templates cost more. [Compare plans →](https://www.shield
 
 | Command | Description |
 | --- | --- |
+| `shieldly agent-scan [options]` | Blast radius of an AI agent's AWS credentials (offline) |
 | `shieldly analyze-iam <policy-file>` | Analyze an IAM policy for security issues |
 | `shieldly analyze-cf <template-file>` | Analyze a CloudFormation template |
 | `shieldly api-keys list\|create\|revoke` | Manage API keys |
 | `shieldly completion bash\|zsh\|install` | Shell completion |
 
+## Agent blast-radius scan
+
+See what your AI agents' AWS credentials could **destroy, exfiltrate, or
+escalate to**. Runs fully offline — your config never leaves your machine, no
+API key required.
+
+```bash
+# Scan an IAM policy file
+shieldly agent-scan --policy-file agent-policy.json
+
+# Fetch and scan a live role (uses your local AWS credentials, read-only)
+shieldly agent-scan --role-arn arn:aws:iam::123456789012:role/my-agent
+
+# Resolve an AWS profile's identity and scan it (users: includes group policies)
+shieldly agent-scan --profile agent-profile
+
+# Zero flags: auto-discover agent configs in the current directory
+# (.mcp.json, mcp.json, .claude/settings.json, .cursor/.vscode mcp.json,
+#  Claude Desktop config) and scan any AWS profiles / role ARNs / hardcoded
+#  keys they reference
+shieldly agent-scan
+```
+
+Findings are graded overall (CRITICAL / HIGH / MODERATE / LOW) and grouped into
+six categories: privilege escalation, destructive actions, wildcard grants, data
+access, cost risk, and missing guardrails. Hardcoded `AKIA…` keys in agent
+configs are flagged CRITICAL.
+
+**Output & remediation:**
+
+```bash
+shieldly agent-scan --policy-file p.json --json           # machine-readable
+shieldly agent-scan --policy-file p.json --sarif > out.sarif  # GitHub Security tab
+shieldly agent-scan --policy-file p.json --fix > tightened.json  # least-privilege draft
+shieldly agent-scan --policy-file p.json --ignore BR-DATA-S3     # suppress a rule
+```
+
+**CI enforcement** — declare a permission budget and fail the build when an
+agent's blast radius exceeds it:
+
+```bash
+shieldly agent-scan --policy-file agent-policy.json --budget shieldly.policy.yml
+```
+
+```yaml
+# shieldly.policy.yml
+version: 1
+max-severity: MEDIUM       # CRITICAL | HIGH | MEDIUM | LOW | none
+deny-categories:
+  - ESCALATION             # always fail on privilege-escalation findings
+ignore-rules: []           # accepted false positives, by rule ID
+# max-findings: 50
+```
+
+Exit code is `1` on any CRITICAL/HIGH finding (or any budget violation), `0`
+otherwise — drop it straight into CI. See
+[`shieldly.policy.example.yml`](./shieldly.policy.example.yml).
+
 ## Global options
 
 | Option | Description |
@@ -106,7 +165,8 @@ hashes of the input.
 No account required — these run in your browser or document the risks:
 
 - [IAM Privilege Escalation Cheat Sheet](https://www.shieldly.io/iam/cheatsheet?utm_source=github&utm_medium=readme) — every common escalation path on one page, with fixes
-- [Free browser tools](https://www.shieldly.io/tools?utm_source=github&utm_medium=readme) — IAM policy linter, trust policy explainer, S3 bucket policy checker, CloudFormation IAM checker
+- [Free browser tools](https://www.shieldly.io/tools?utm_source=github&utm_medium=readme) — IAM policy linter, trust policy explainer, S3 bucket policy checker, CloudFormation IAM checker, ARN parser, policy diff, CloudTrail least-privilege generator
+- [Awesome AWS IAM Security](https://github.com/shieldly-io/awesome-aws-iam-security) — curated list of IAM security tools and references
 - [IAM privilege escalation reference](https://www.shieldly.io/iam?utm_source=github&utm_medium=readme) — each method with a vulnerable policy, the exploit, and the fix
 
 ## License