iam-armor/iamarmor
GitHub: iam-armor/iamarmor
针对 Terraform 中 AWS IAM 策略的离线静态分析工具，在过度授权的策略被合并到主干之前拦截通配符、AdministratorAccess 等常见高危配置错误。
Stars: 1 | Forks: 0
# iamarmor
**一个用于 Terraform 中 AWS IAM 策略的静态分析器——在过度授权的策略被合并前拦截它们。**
[](https://pypi.org/project/iamarmor/)
[](https://pypi.org/project/iamarmor/)
[](https://github.com/iam-armor/iamarmor/actions/workflows/ci.yml)
[](LICENSE)
## 为什么使用 iam-armor？
IAM 配置错误是 AWS 安全违规的头号原因——`Action` 和 `Resource` 上的通配符、被遗忘的 `AdministratorAccess` 附加项，以及过度授权的 `assume_role_policy`，这些都很容易被发布，却很难在代码审查中被发现。
`iamarmor` 是一个**针对 Terraform IAM 资源的静态分析器**。它完全在离线状态下运行——无需 AWS 凭证，也无需 `terraform plan`——并且可以作为 pre-commit 钩子或 CI 步骤无缝集成到您的工作流中。
```
$ iamarmor scan modules/iam/
modules/iam/main.tf
✘ IAM001 [HIGH] resource 'aws_iam_policy.app' has Action: "*" — grant least-privilege actions instead.
✘ IAM005 [HIGH] resource 'aws_iam_policy.deployer' grants iam:PassRole on Resource: "*" — scope to specific role ARNs.
✘ IAM010 [HIGH] resource 'aws_iam_role_policy_attachment.admin' attaches AdministratorAccess — grant only required permissions.
3 findings (3 high, 0 medium, 0 low) in 0.12 s
exit 1
```
## 演示
## 快速开始
```
# 安装（需要 Python 3.11+）
pip install iamarmor
# 扫描当前目录
iamarmor scan .
# 扫描特定文件
iamarmor scan modules/iam/main.tf
# 用于 CI 管道的机器可读输出
iamarmor scan . --format json
```
`iamarmor scan` 退出码说明：当没有发现问题时返回 **0**，当发现的问题达到 `fail_on` 阈值（默认：`medium`）时返回 **1**，在用法/配置错误时返回 **2**，在内部错误时返回 **3**——这让 CI 集成变得非常简单。
## 配置
在您的 Terraform 仓库根目录下放置一个 `.iamarmor.yml` 文件：
```
version: 1
severity_threshold: low # report findings at or above this level (default: info)
fail_on: high # exit 1 only for high/critical (default: medium)
rules:
ignore: [IAM004] # skip noisy rules for your environment
overrides:
IAM002:
severity: critical # escalate a rule's severity
paths:
exclude:
- "modules/legacy/**" # skip paths you're not ready to fix yet
```
iamarmor 会从目标路径向上逐级查找，自动发现 `.iamarmor.yml`。
使用 `--no-config` 参数可跳过加载。
请参阅 [docs/config.md](docs/config.md) 获取完整的配置参考。
## 默认规则包
iamarmor 内置了 **10 条默认 IAM 规则**，涵盖了最常见的配置错误：
| ID | 名称 | 严重程度 |
|---|---|---|
| IAM001 | 禁止 `Action: "*"` | High |
| IAM002 | 执行敏感操作时禁止 `Resource: "*"` | High |
| IAM003 | 禁止内联策略 | Medium |
| IAM004 | IAM 角色必须设置 `max_session_duration` | Low |
| IAM005 | 禁止在 `Resource: "*"` 时使用 `iam:PassRole` | High |
| IAM006 | 基于资源的策略中禁止通配符 `Principal` | High |
| IAM007 | `assume_role_policy` 必须指定具体的主体 | High |
| IAM008 | Allow 语句中禁止使用 `NotAction` | Medium |
| IAM009 | Allow 语句中禁止使用 `NotResource` | Medium |
| IAM010 | 禁止附加 `AdministratorAccess` 托管策略 | High |
请参阅 [STARTER_RULES.md](STARTER_RULES.md) 获取每条规则的完整文档，包括基本原理、示例和配置选项。
## Pre-commit 钩子
将其添加到您的 `.pre-commit-config.yaml` 中：
```
repos:
- repo: https://github.com/iam-armor/iamarmor
rev: v0.1.1
hooks:
- id: iamarmor
```
详情请参阅 [docs/pre-commit.md](docs/pre-commit.md)。
## GitHub Actions CI
将以下内容添加到您的工作流中，以便在每个 PR 中扫描 Terraform：
```
- name: Scan IAM policies
run: |
pip install iamarmor
iamarmor scan . --fail-on high
```
或者固定到某个特定版本：
```
- name: Scan IAM policies
run: |
pip install iamarmor==0.1.1
iamarmor scan modules/iam/ --format json > iam-findings.json
```
## Python API
对于大多数用户，CLI 是推荐的入口点。如果需要将 iamarmor 嵌入到其他工具中，Python API 也是公开可用的：
```
from iamarmor import extract_from_directory, RuleEngine, load_default_rules
resources = extract_from_directory("path/to/terraform/")
engine = RuleEngine(rules=load_default_rules())
findings = engine.run(resources)
for finding in findings:
print(f"[{finding.rule_id}] {finding.severity.value.upper()} — {finding.message}")
```
## 重新生成演示 GIF
演示 GIF 是使用 [VHS](https://github.com/charmbracelet/vhs) 录制的。
要重新生成它，请执行：
```
# 安装 VHS（需要 Go）
go install github.com/charmbracelet/vhs@latest
# 重新录制
vhs docs/demo.tape
```
生成的 `docs/demo.gif` 将被提交到代码仓库中。录像脚本会对自带的 `tests/fixtures/` 目录执行 `iamarmor scan` 进行测试。
## 路线图
`iamarmor`（本代码仓库）是开源的静态分析器引擎。位于 **[iamarmor.dev](https://iamarmor.dev)** 的托管 GitHub App（即将推出）将增加以下功能：
- 🔌 带有内联 PR 注释的 GitHub App
- 📦 高级规则包：SOC 2, PCI-DSS, HIPAA, AWS Well-Architected Security
- 📊 发现结果仪表板和趋势跟踪
- 🔧 一键自动修复建议
## 许可证
[MIT](LICENSE) © 2026 iam-armor
标签：AWS IAM, AWS安全, CLI应用, DevSecOps, ECS, IaC安全, iamarmor, IAM Armor, IAM策略分析, Python, Terraform, 上游代理, 云安全监控, 代码审查, 安全合规, 开源, 无后门, 最小权限原则, 权限修复, 权限越权检测, 漏洞预防, 策略检查, 网络代理, 逆向工具, 静态分析