JamesOlaitan/accessgraph
GitHub: JamesOlaitan/accessgraph
AccessGraph 是一款基于图遍历的离线安全工具，用于量化 AWS IAM 环境中的提权路径与爆炸半径，并针对主流开源工具提供检测覆盖率的基准测试对比。
Stars: 0 | Forks: 0
# AccessGraph
基于图的 AWS IAM 提权路径检测与爆炸半径量化。
## 概述
AccessGraph 将 AWS IAM 环境建模为有向图，并使用
广度优先搜索 (BFS) 来枚举从任何
受损主体出发的提权路径。对于每个起始身份，它计算爆炸半径
指标：有多少敏感资源是可达的，通过什么路径，以及
在什么深度。策略违规通过嵌入的 OPA 规则进行评估，针对
四个 Rego 规则集，涵盖通配符操作、跨账户信任、提权
基元和敏感度分类。
与 AccessGraph 一起进行基准测试的三个开源工具涵盖了多种
方法。PMapper (NCC Group) 本身就是基于图的：它将 IAM 主体
建模为有向图并执行多跳路径遍历以查找提权
路由。Prowler 引入了攻击路径可视化，将
资源、发现和权限链接到知识图中，尽管其
单独的检查历来是按策略条件进行评估的。Checkov
对基础设施即代码模板执行静态分析，独立评估每个
策略文档，而不进行跨主体图遍历。
然而，这些工具都没有将基于图的提权路径发现
与定量的爆炸半径指标（可达资源计数、环境
可达百分比、到达管理员的最小跳数深度）相结合，或者在
公共数据集上提供系统的
基准比较，包括所有工具的精确率、召回率和 F1 分数。有关
工具选择的基本原理，请参阅 `docs/benchmark_methodology.md` 第 1.3 节。
AccessGraph 贡献了一个基准测试工具，用于评估
[IAMVulnerable](https://github.com/BishopFox/iam-vulnerable) 数据集中 31 个提权场景上
所有四个工具的检测覆盖率（Seth Art，
Bishop Fox, 2021）。该基准测试生成按链长度类别（简单、两跳、多跳）细分的
每个工具的精确率、召回率和 F1
分数，并附带 Wilson 分数 95% 置信区间。AccessGraph 还将图
遍历与爆炸半径量化和嵌入式 OPA 策略评估
集成到单个离线管道中。所有分析都是离线的 —— 在图
构建或遍历期间不会进行实时 AWS API 调用。
## 快速开始
### 前置条件
- Go 1.26.1 或更高版本 ([下载](https://go.dev/dl/))
- Linux 或 macOS；任何 Go 支持的平台
- 不需要 Docker，不需要 AWS 账户，基本使用不需要外部服务
- golangci-lint v2.11+（仅用于 `make lint`；构建或测试不需要）
OPA 通过 Go 库嵌入；不需要单独安装 OPA。
### 克隆、构建、验证
```
git clone https://github.com/JamesOlaitan/accessgraph.git
cd accessgraph
make build
make test
```
`make build` 将二进制文件编译到 `bin/accessgraph`。`make test` 运行
单元测试套件并启用竞态检测。这两个命令都只需要 Go。
### 运行演示
```
make demo
```
这将针对捆绑的示例
数据 (`sample/aws/demo_policy.json`) 运行一个独立的端到端演示。它执行三个步骤：
1. 摄取示例 IAM 快照并将其持久化到本地 SQLite 数据库。
2. 从示例受损主体运行爆炸半径分析
(`arn:aws:iam::123456789012:user/dev-user`) 并输出到终端。
3. 使用 `--output json` 重新运行相同的分析以显示结构化
JSON 报告格式。
不需要环境变量或外部数据。演示可以在
`make build` 后立即从干净的克隆中运行。
**成功指标。** 步骤 1 向 stdout 打印一行摘要：
`Snapshot ingested: id= label=demo principals=N policies=N resources=N edges=N`。
步骤 2 打印 "AccessGraph Analysis Report" 标题，后跟
爆炸半径表、发现的攻击路径和任何 OPA 发现。步骤 3
向 stdout 打印一个 JSON 对象。所有三个步骤均以代码 0 退出。
## 用法
### 从 AWS 账户导出 IAM
使用 `export-iam` 生成 `accessgraph ingest`
和 `accessgraph analyze` 使用的 IAM JSON 快照。这是实时 AWS
账户与 AccessGraph 离线分析管道之间的桥梁。
```
./bin/accessgraph export-iam --output iam-export.json
```
所需的 AWS 权限：`ReadOnlyAccess` 或 `SecurityAudit` 托管
策略就足够了（特别是 `iam:GetAccountAuthorizationDetails` 和
`sts:GetCallerIdentity`）。
| 标志 | 默认值 | 描述 |
|------|---------|-------------|
| `--profile` | (默认链) | 来自 `~/.aws/config` 的 AWS 配置文件名称 |
| `--output` | stdout | 输出文件路径 |
| `--region` | us-east-1 | STS 的 AWS 区域（IAM 是全局的，但 STS 需要一个区域） |
| `--endpoint-url` | (无) | 用于 LocalStack 开发的自定义 AWS 端点 URL |
示例：
```
# 默认 credential chain，输出到 stdout
./bin/accessgraph export-iam > iam-export.json
# 命名 profile，输出到文件
./bin/accessgraph export-iam --profile prod --output iam-export.json
# LocalStack 开发
./bin/accessgraph export-iam --endpoint-url http://localhost:4566 --output iam-export.json
```
输出是一个与现有解析器
使用的格式相同的 JSON 文件（小写顶级键：`users`、`roles`、`groups`、`policies`、
`account_id`；与 AWS API 匹配的 PascalCase 嵌套字段）。将其
直接输入到分析管道中：
```
./bin/accessgraph export-iam --output iam-export.json
./bin/accessgraph ingest --source iam-export.json --label prod-2026-04
./bin/accessgraph analyze --label prod-2026-04 --from arn:aws:iam::123456789012:user/dev-user
```
### 摄取 IAM 快照
```
./bin/accessgraph ingest --source --label
```
解析 AWS IAM 环境导出，对敏感资源进行分类，并将
快照持久化到本地 SQLite 数据库（默认为 `accessgraph.db`）。
```
./bin/accessgraph ingest --source sample/aws/demo_policy.json --label demo
```
### 分析爆炸半径
```
./bin/accessgraph analyze --label --from [--output terminal|json|dot]
```
构建权限图，综合提权边，从指定的
主体运行 BFS，计算爆炸半径指标，评估 OPA 策略规则，
并渲染报告。
| 标志 | 默认值 | 描述 |
|------|---------|-------------|
| `--label` | 必需 | 要分析的快照标签 |
| `--from` | 必需 | 受损起始主体的 ARN |
| `--max-hops` | 8 | 最大 BFS 遍历深度 |
| `--output` | terminal | 输出格式：`terminal`、`json` 或 `dot` |
| `--db` | accessgraph.db | SQLite 数据库路径 |
| `--policy-dir` | policy | 包含 OPA Rego 规则的目录 |
JSON 输出示例：
```
./bin/accessgraph analyze \
--label demo \
--from arn:aws:iam::123456789012:user/dev-user \
--output json
```
**输出格式：**
| 格式 | 标志 | 描述 |
|--------|------|-------------|
| 终端 | `--output terminal` (默认) | 彩色报告：爆炸半径表、攻击路径、带有严重性标签的 OPA 发现 |
| JSON | `--output json` | 符合 `docs/findings_schema.md` 的结构化 JSON 对象 |
| Graphviz DOT | `--output dot` | 可达子图的 DOT 图，用于 `dot -Tsvg` |
### 渲染存储的报告
```
./bin/accessgraph report --snapshot [--output terminal|json|dot]
```
从存储中加载先前计算的快照、其攻击路径和其发现，
并以请求的格式渲染报告。不执行重新分析；
此命令仅渲染由先前的 `analyze` 运行存储的数据。
| 标志 | 默认值 | 描述 |
|------|---------|-------------|
| `--snapshot` | 必需 | 要加载和渲染的快照 ID |
| `--output` | terminal | 输出格式：`terminal`、`json` 或 `dot` |
### 运行基准比较
```
./bin/accessgraph benchmark \
--scenarios \
--tools prowler,pmapper,checkov \
--account-id \
--output json
```
这需要 `integration` 构建标签和安装在
`$PATH` 上的外部工具。有关详细信息，请参阅 [基准复现](#benchmark-reproduction)。
| 标志 | 默认值 | 描述 |
|------|---------|-------------|
| `--scenarios` | 必需 | 包含场景子目录的目录，每个子目录都有一个 `manifest.json` 和 IAM 导出 JSON |
| `--tools` | `accessgraph` | 逗号分隔的列表：`accessgraph`、`prowler`、`pmapper`、`checkov` |
| `--output` | `terminal` | 输出格式：`terminal` 或 `json` |
| `--account-id` | (空) | 测试账户的 AWS 账户 ID；用于实时 AWS 固件捕获 |
## 基准复现
主要的定量声明是 AccessGraph
在所有 31 个 IAMVulnerable 场景上与三个开源工具的精确率/召回率比较。计划了
两条复现路径：
### 离线复现（不需要 AWS 账户）
**状态：推迟 -- 尚未实施。**
`make reproduce-fixtures` 将根据从 IAMVulnerable 场景导出派生的黄金
固件文件验证分析管道。此路径允许
审查者在不部署基础设施的情况下验证检测逻辑和指标计算。固件生成和校验和待定。
### 实时 AWS 复现
**状态：推迟 -- 尚未实施。**
`make reproduce` 将自动化完整的基准测试：将 IAMVulnerable 部署到
AWS 账户，导出 IAM 状态，运行所有四个工具，并生成比较
报告。这需要一个 AWS 账户和 [前置条件](#prerequisites) 中列出的外部工具。每次运行的估计成本低于 5 美元。
有关完整的方法规范，包括
检测匹配规则、置信区间计算、超时
处理和工具版本固定，请参阅 `docs/benchmark_methodology.md`。
### 针对 LocalStack 捕获基准固件
为了在不产生 AWS 费用的情况下进行开发和集成测试，
`scripts/capture_scenario.sh` 针对 LocalStack 部署单个场景，
捕获所有四个工具的固件（AccessGraph IAM 导出、PMapper 图存储、
Prowler json-ocsf 输出、Checkov Terraform 扫描），并拆除
部署。该脚本处理两种模式：IAMVulnerable 提权
场景 (privesc*) 和真阴性环境 (tn-clean-NNN)。
```
./scripts/capture_scenario.sh privesc1-CreateNewPolicyVersion
./scripts/capture_scenario.sh tn-clean-001
make capture-scenario SCENARIO=privesc1-CreateNewPolicyVersion
```
捕获的固件被写入 `fixtures/iamvulnerable//` 或
`fixtures/tn-environments//`。需要 Docker、Terraform、一个已构建的
二进制文件 (`make build`) 和基准 Docker 镜像 (`make docker-build`)。
LocalStack 固件适用于开发迭代，但不是
规范的；有关规范的实时 AWS 捕获工作流程，请参阅 `docs/benchmark_methodology.md` 第 7.1 节。
## 项目结构
```
accessgraph/
├── cmd/accessgraph/ CLI entry point and Cobra commands (ingest, analyze, report, benchmark)
├── internal/ Domain logic organized by responsibility
│ ├── model/ Domain types: Snapshot, Principal, Edge, Finding, AttackPath
│ ├── graph/ Graph construction, BFS traversal, escalation edge synthesis
│ ├── analyzer/ Blast-radius metric computation
│ ├── parser/ AWS IAM JSON ingestion
│ ├── store/ DataStore interface (SQLite and in-memory implementations)
│ ├── policy/ Embedded OPA evaluator with graceful degradation
│ ├── benchmark/ Tool adapter harness and IAMVulnerable scenario loader
│ ├── report/ Output renderers: terminal, JSON, Graphviz DOT
│ ├── service/ Facade orchestration (AnalysisFacade, BenchmarkFacade)
│ ├── config/ Environment-variable-based configuration
│ └── transport/ Offline HTTP enforcement
├── tests/ Unit and integration tests (mirrors internal/ structure)
├── policy/ OPA Rego rules (4 files)
├── sample/ Sample IAM data for demo and tests
├── docs/ Specification documents
├── terraform/ Terraform infrastructure (scanner role, 10 TN environments)
└── scripts/ Automation and audit scripts
```
代码库遵循三层架构，具有严格单向的
依赖关系。第 1 层 (model, store, config, transport) 没有向上导入。
第 2a 层 (graph, analyzer, parser, policy, benchmark, report) 可以导入
第 1 层和其他第 2a 层包；它不得导入第 3 层。第 2b 层
(service) 通过外观模式编排第 2a 层。第 3 层 (cmd) 连接依赖关系
并处理 I/O。有关完整规范，请参阅 `docs/ARCHITECTURE.md`。
## 测试
```
make test # Unit tests (-race, no external dependencies)
make test-integration # Full benchmark suite (requires external tools on PATH)
make lint # golangci-lint v2
make audit # Architectural fitness checks (layer deps, interfaces, JSON tags)
```
运行单个测试：
```
go test -race -run TestName ./tests/graph/...
```
运行带覆盖率的测试（镜像 CI）：
```
go test -race -count=1 -timeout 120s -coverprofile=coverage.txt \
-coverpkg=./internal/... ./tests/...
```
CI 要求 75% 的总覆盖率。`internal/graph` 和 `internal/analyzer` 必须
分别超过 80%。测试位于 `tests/` 中，镜像 `internal/`
包结构，而不是与源文件并列。集成测试需要
`integration` 构建标签。
## 文档
| 文档 | 描述 |
|----------|-------------|
| `docs/ARCHITECTURE.md` | 系统架构、层契约、接口规范和数据流 |
| `docs/benchmark_methodology.md` | 基准设计、检测匹配规则、统计方法和复现程序 |
| `docs/findings_schema.md` | JSON 输出架构、字段类型、不变量和浮点序列化契约 |
## 限制性
以下限制适用于基准评估。完整讨论请参阅
`docs/benchmark_methodology.md` 第 8 节。
- **样本量。** 基准测试涵盖 n=31 个提权场景。
在单个链长度类别内低于 0.2 的召回率差异
在没有额外数据的情况下不应被解释为有意义。
- **工具版本敏感性。** 外部工具输出格式和检测
逻辑随版本而变化。基准测试结果仅对
方法文档中指定的固定版本有效。
- **Checkov 方法不对称性。** Checkov 针对 Terraform
源进行评估；所有其他工具都针对实时部署的环境进行评估。
结果在“相同场景”轴上具有可比性，而不是在“相同输入”
轴上。
- **IAMVulnerable 覆盖范围。** 这 31 个场景是已知
提权路径的精选子集。AccessGraph 对 IAMVulnerable 中不存在的路径的
检测能力未被测量。
- **未测量外部工具 FPR。** 仅针对真阴性环境测量 AccessGraph 的 FPR。
外部工具的调度路径在 TN 场景上无条件返回
`LabelFN`，基准输出中不会为它们发出 FPR 条目。使用者可以检查
每个 `false_positive_rate` 条目上的 `fpr_measured` 字段：`fpr_measured: false` 表示
未测量该值；`fpr_measured: true` 表示它是根据实际 TN
评估计算的。
- **仅限静态分析。** IAM 条件键在遍历期间被解析但不被评估。
权限边界被检测为发现，但不限制 BFS。服务控制策略 (SCP) 未被建模。
## 引用
论文即将发表。本部分将在发表时更新引用详细信息。
## 许可证
Apache License 2.0。请参阅 [LICENSE](LICENSE)。
标签：AWS, CSV导出, DPI, EVTX分析, Groq API, IAM, IAMVulnerable, OPA, PMapper, Prowler, Rego, 云安全监控, 协议分析, 反取证, 图分析, 图谱, 安全评估, 攻击路径, 日志审计, 权限提升, 权限管理, 模型越狱, 横向移动, 编程规范, 静态分析, 靶场