MetaMaaz/iam-least-privilege

# AWS IAM 最小权限分析器 摄入 AWS IAM 配置，找出 **过度分配的权限和提权路径**，并生成 **最小权限修复计划** —— 即你完全可以直接应用且经过收紧的 IAM 策略 JSON，每项发现都可追溯到一个具名的原则（NIST SP 800-207 身份支柱 / AWS IAM 最佳实践）。基于规则且具备可解释性：**无 ML，无黑盒**。 [](https://github.com/MetaMaaz/iam-least-privilege/actions/workflows/ci.yml)    ## 核心产物：提权路径的前后对比 该分析器将身份、可代入角色和提权授权建模为有向图（网络攻击路径的 IAM 类比；概念上属于 [BloodHound](https://github.com/BloodHoundAD/BloodHound) 领域，后者被引为先行研究）。通向 **ADMIN**（管理员）的路径是一条具体的提权链。 ``` graph LR ADMIN(["ADMIN — full account control"]):::admin ci_deploy_user["ci-deploy-user"] dev_user["dev-user"] ec2_app_role["ec2-app-role"] lambda_exec_role["lambda-exec-role"] dev_user -->|"iam:PassRole + lambda:CreateFunction"| lambda_exec_role lambda_exec_role -->|"holds admin-equivalent permissions"| ADMIN ci_deploy_user -->|"iam:AttachUserPolicy"| ADMIN ec2_app_role -->|"iam:PutRolePolicy"| ADMIN classDef admin fill:#b00020,stroke:#600,color:#fff; classDef start fill:#ffd54f,stroke:#c79100,color:#000; class ci_deploy_user start; class dev_user start; class ec2_app_role start; ``` 一个名义上低权限的开发者 (`dev-user`) 拥有 `iam:PassRole` + `lambda:CreateFunction`。这允许他们将权限过大的 `lambda-exec-role`（拥有 `iam:*`）附加到他们创建并调用的函数上 —— 从而继承管理员权限。该工具找到此链条，然后 **针对修复后的策略重新运行相同的图计算**，并展示所有三个入口点都无法再到达管理员权限。请在 [`output/report.md`](output/report.md) 中查看完整的生成输出。 ## 快速开始 ``` pip install -r requirements.txt # 对内置的、刻意存在漏洞的 mock account 的完整分析 — 无需 AWS： python cli.py report --in data/mock_account.json --out output/ # 仅在 stdout 上输出 findings + escalation summary： python cli.py analyze --in data/mock_account.json # Real account (read-only): 快照 IAM，然后离线分析 export： aws iam get-account-authorization-details > export.json python cli.py ingest --export export.json --out inventory.json python cli.py report --in inventory.json --out output/ ``` 除了 `ingest --live` 之外，所有操作均在完全离线状态下运行。该工具是 **只读的** —— 它永远不会修改 IAM。 ## 它能检测什么 | 类别 | 标记内容 | 引用原则 | | --- | --- | --- | | `wildcard` | `s3:*`, `Action: "*"`, `Resource: "*"` | AWS —— 授予最小权限，避免使用通配符 | | `over-provisioned` | 超出实际使用需求的宽泛授权 | NIST 800-207 最小权限 | | `unused` | 已授权但 N 天内未使用的服务 | NIST 800-207 最小权限 | | `dangerous-combo` | 已知的提权权限组合 | 基于规则 (Rhino Security Labs 目录) | | `standing-admin` | 人类用户拥有的常驻管理员权限 | AWS —— 推荐使用角色 + 即时访问 | | `long-lived-key` | 超过阈值的访问密钥 | AWS —— 推荐使用临时角色凭证 | 每项发现都会汇总为一个 **针对每个身份的风险评分**（严重性权重 + 提权影响范围），为报告提供一个可排序的核心指标。 ## 架构 不可妥协的设计原则是 **摄入与推理之间的硬分离**。`ingestion.py` 是*唯一*了解 AWS 的模块；它生成一个普通的 `Inventory`。所有核心逻辑 —— 分类、分析、提权、推荐 —— 都只消费该数据结构，且从不调用 AWS，因此整个引擎可以针对 mock 策略 JSON 进行离线单元测试。 ``` iam-least-privilege/ ├── cli.py # ingest | analyze | report ├── analyzer/ │ ├── models.py # Identity, Policy, Permission, Finding, EscalationPath, RiskScore │ ├── ingestion.py # AWS export / boto3 → Inventory (ONLY AWS-facing module) │ ├── classifier.py # identity/permission → privilege tier + sensitivity (pure) │ ├── analyzer.py # findings + risk scoring (pure) │ ├── escalation.py # privilege-escalation path graph, before/after (pure) │ ├── recommender.py # → tightened least-privilege policy JSON (pure) │ └── reporter.py # → Markdown report + Mermaid diagram + policy export ├── data/ │ ├── sensitive_actions.yaml # high-risk actions → sensitivity (editable heuristics) │ ├── escalation_rules.yaml # known priv-esc permission combinations │ └── mock_account.json # hand-written vulnerable IAM setup for offline testing ├── ingest/ │ └── account_authorization_details.json # redacted real-export sample ├── tests/ # classifier / analyzer / escalation └── output/ # generated report + remediation policies (sample committed) ``` 启发式规则存在于 **YAML 而非代码中** (`data/*.yaml`)，因此每项发现都易于辩护和扩展，无需改动 Python。 **数据流：** `ingestion` → `Inventory` → `classifier` (分类器) 添加标注 → `analyzer` (分析器) 生成发现 → `escalation` (提权模块) 计算路径 → `recommender` (推荐模块) 输出收紧的策略 → `reporter` (报告模块) 将所有内容写出。 ## 无基础设施测试 IAM 是配置，而非基础设施 —— 无需 VM，无需 Docker。手工编写的 `data/mock_account.json` 是一个刻意设计的易受攻击账号（一个 `*:*` 用户、一个拥有 `PassRole` 的开发者、一个未使用的 power-user、长期有效的密钥），它覆盖了每一条代码路径。单元测试针对它运行整个推理引擎： ``` python -m pytest -q # 19 tests: classifier, analyzer, escalation ruff check analyzer cli.py # lint ``` GitHub Actions 在每次推送时跨 Python 3.10–3.12 运行这两项测试，外加流水线冒烟测试。 **安全提示：** 永远只对 **只读** 的 AWS profile 使用 `--live`。绝不要提交真实的账号 ID、ARN 或密钥 —— `.gitignore` 已排除 `inventory.json` / 导出文件；已提交的示例导出已脱敏为 `000000000000`。 ## 设计原则 1. **摄入与推理分离** —— 所有智能逻辑均可离线测试。 2. **基于规则且具备可解释性** —— 每项发现都引用具名的原则；注重可辩护性而非复杂性。 3. **映射到框架** —— 主要是 NIST SP 800-207（身份支柱），其次是 AWS IAM 最佳实践。 4. **永远只读** —— 提供建议；由人工执行应用。 ## 先行研究与参考 - Rhino Security Labs —— *AWS IAM Privilege Escalation: Methods and Mitigation* (本项目所建模的提权技术目录)。 - NIST SP 800-207 —— *Zero Trust Architecture* (身份支柱：最小权限，按请求访问)。 - AWS —— *Security best practices in IAM*. - BloodHound —— 针对 Active Directory 的基于图的攻击路径分析（提权图的概念渊源）。 *配套项目：网络分段顾问（相同的 发现 → 分类 → 推荐 → 攻击路径 骨架，应用在网络侧）。两者结合：从身份和网络双重角度遏制横向移动。*

标签：AWS IAM, DevSecOps, Python, 上游代理, 安全规则引擎, 无后门, 最小权限, 权限分析, 权限提升检测, 逆向工具