Content
<!-- Rename this file to README.md in your public GitHub repo.
Replace Pratikchandrathakur and the landing-page URL before pushing. -->
<h1 align="center">🛡️ IAM Sentinel</h1>
<p align="center">
<b>Air-gapped, deterministic cloud IAM privilege-escalation scanner — AWS · Azure · GCP.</b><br>
Runs 100% on your own metal. Plugs into Cursor / Claude Code via MCP. Zero data egress.
</p>
<p align="center">
<img alt="license" src="https://img.shields.io/badge/license-BSL%201.1-blue">
<img alt="docker" src="https://img.shields.io/badge/docker-compose-2496ED?logo=docker&logoColor=white">
<img alt="clouds" src="https://img.shields.io/badge/clouds-AWS%20%7C%20Azure%20%7C%20GCP-orange">
<img alt="offline" src="https://img.shields.io/badge/network-air--gapped-10b981">
<img alt="tests" src="https://img.shields.io/badge/tests-68%20passing-brightgreen">
<img alt="ci" src="https://img.shields.io/badge/CI-PR%20gate%20%2B%20SARIF-6d7dff">
</p>
<p align="center">
<a href="https://iam-sentinel-site.vercel.app">Website</a> ·
<a href="#quickstart">Quickstart</a> ·
<a href="INSTALL.md">Install (Mac/Win/Linux/WSL)</a> ·
<a href="#pricing">Pricing</a>
</p>
---
## Why
Cloud IAM scanners (Wiz, Snyk, GitHub Advanced Security) send your policies to *their* cloud.
Regulated teams **can't** do that. IAM Sentinel finds privilege-escalation paths, wildcards,
`PassRole`/`roleAssignment` abuse, public bindings, and data-exfil grants with a **deterministic
rule engine** — reproducible and auditable, not an LLM guess — entirely on your infrastructure.
- 🔒 **Air-gapped** — no telemetry, no outbound calls (except an *optional* local model).
- 🎯 **Deterministic** — version-stamped findings from a rule engine, not hallucinations.
- 🔌 **In your IDE** — native stdio MCP server for Cursor / Claude Code.
- 🧾 **Auditable** — every scan persisted with actor, timestamp, SHA-256, and rule-pack version.
- 🖥️ **Runs anywhere** — CPU-only core; a GPU is only for the optional written remediation.
## Quickstart
```bash
git clone https://github.com/Pratikchandrathakur/IAM-Sentinel && cd iam-sentinel
cp .env.example .env # set API keys (Community tier needs no license)
docker compose up -d --build
open http://127.0.0.1:8080 # dashboard · API at /api/... · health at /api/health
```
Audit a policy (provider auto-detected):
```bash
curl -s http://127.0.0.1:8080/api/audit/iam -H "X-API-Key: $KEY" \
-H "Content-Type: application/json" \
-d '{"policy_json":"{\"Statement\":[{\"Effect\":\"Allow\",\"Action\":\"*\",\"Resource\":\"*\"}]}"}' | jq
```
No GPU / macOS? Set `LLM_NARRATIVE_ENABLED=false` — you still get every deterministic finding.
Full per-OS steps in **[INSTALL.md](INSTALL.md)**.
## Use it inside your IDE (MCP)
```json
{ "mcpServers": { "iam-sentinel": {
"command": "python3", "args": ["/abs/path/to/iam-sentinel/mcp_stdio.py"],
"env": { "AUTH_ENABLED": "false", "LLM_NARRATIVE_ENABLED": "false" }
}}}
```
Then ask your assistant: *"Audit this IAM policy with iam-sentinel."*
## CI/CD guardrails — block privilege escalation on every PR
Scan the IAM inside a Terraform plan (or raw policy files) and **fail the build** when a new
escalation path appears. Findings show inline on the PR via SARIF. No server needed.
```yaml
# .github/workflows/iam-guardrails.yml (see examples/github-actions/)
- run: terraform show -json tf.plan > plan.json
- uses: Pratikchandrathakur/IAM-Sentinel@v1
with: { tfplan: plan.json, fail-on: HIGH }
```
Or run the gate locally / in any CI (pure stdlib, offline):
```bash
python3 guardrails.py --tfplan plan.json --fail-on HIGH # exit 1 = blocking findings
python3 guardrails.py policies/*.json --format sarif > iam.sarif
```
It **extracts IAM from Terraform plans** (AWS `aws_iam_policy`/roles, Azure `azurerm_role_definition`,
GCP custom roles/bindings) — no HCL parsing, using the resolved plan JSON.
> **No model required.** Every scan returns a full **deterministic remediation report** (fixes +
> least-privilege skeleton) with zero external services. The optional local LLM is pure polish.
> **Custom rules** are a config drop-in — see `custom_rules.example.json` (no code change).
## What it detects
- **AWS** — 19 escalation techniques (Rhino/PMapper): `AttachUserPolicy`, `PutRolePolicy`,
`CreateAccessKey`, `PassRole`+compute, `UpdateAssumeRolePolicy`, …; wildcards, `NotAction` traps,
wildcard principals, unconditioned `AssumeRole`, data-exfil grants.
- **Azure** — `roleAssignments/write`, `elevateAccess`, `Microsoft.Authorization/*`, wildcard actions, scope breadth.
- **GCP** — primitive roles, `allUsers` bindings, `setIamPolicy` / `serviceAccountTokenCreator` / `actAs`.
## Pricing
Open-core. Run it free; upgrade for seats, history, and enterprise controls (offline-licensed).
| Tier | Price | Seats | Scans/mo | Adds |
|---|---|---|---|---|
| Community | **Free** | 1 | 100 | AWS/Azure/GCP · MCP · audit trail |
| Team | $199/mo | 10 | 5,000 | Remediation diff |
| Enterprise | $4,999/yr | ∞ | ∞ | SSO/RBAC · TLS · SLA |
See the [website](https://iam-sentinel-site.vercel.app) or email **krisprogrammer1@gmail.com** for a pilot.
## Tests
```bash
python3 tests/test_iam_engine.py # + test_multicloud / test_store / test_mcp / test_auth / ...
```
## License
**Business Source License 1.1** (see [`LICENSE`](LICENSE)). Source is open; **Community use
is free** (single user / evaluation). Team, CI/CD, and organization-wide **production use
requires a commercial subscription** — contact **krisprogrammer1@gmail.com**. Converts to
Apache-2.0 on 2030-07-25. You may not resell it or offer it as a competing hosted service.
<p align="center"><i>⭐ If this is useful, star the repo — it helps a lot.</i></p>
