patrickbeane/tfstride
GitHub: patrickbeane/tfstride
一款针对 Terraform 计划的确定性云威胁建模工具，聚焦 AWS 并以 STRIDE 框架输出预部署风险报告。
Stars: 0 | Forks: 0
# tfSTRIDE & Policy Gate
`tfstride` 将 Terraform plan JSON 转换为确定性的云威胁模型、信任边界、面向 STRIDE 的发现结果，以及部署前针对 AWS 基础设施的观察性防护控制。
## 概述
该项目将 Terraform plan JSON 转换为部署前 AWS 基础设施的确定性云威胁模型。它规范化受支持的资源，识别信任边界，评估面向 STRIDE 的规则，并生成有证据支撑的发现结果以及供人工审查和 CI 门控的观察性防护控制。
引擎有意保持小巧且可解释：核心路径中没有 LLM，没有完整图引擎，也没有运行时云访问。目标是让高风险基础设施模式在 `terraform apply` 前更容易被审查。
## 功能特性
- 无 LLM 的确定性 Terraform plan 分析，核心流水线中不含大语言模型
- 信任边界检测加上面向 STRIDE 的发现结果
- IAM 图解析，支持计划中的内联策略、角色关联与 EC2 实例配置文件
- 通过 ECS 服务与任务定义规范化对 ECS/Fargate 工作负载的初步建模
- 对敏感数据服务的资源策略分析，支持 invoke/publish/queue 表面
- 基于受支持的源约束对信任与资源策略进行条件感知收窄
- 观察到信息性控制以提供清晰的缓解信号
- 机器可读的 JSON 输出，包含稳定的发现指纹
- Markdown 与 SARIF 2.1.0 输出
- 使用 `--fail-on low|medium|high` 的 CI 策略门控
- 抑制与基线，用于聚焦新引入发现的策略门控
- 仓库级 TOML 配置，用于默认门控、规则选择与严重性覆盖
- 自动化友好的 `--quiet` 模式与非零退出行为
- 以 AWS 优先的规范化与提供者边界，支持未来扩展
## 快速开始
从源码直接运行：
```
PYTHONPATH=src python3 -m tfstride fixtures/sample_aws_plan.json
```
本地安装 CLI：
```
python3 -m pip install -e .
tfstride fixtures/sample_aws_plan.json --output threat-model.md
```
从基础设施仓库生成 Terraform plan JSON：
```
terraform plan -out tfplan
terraform show -json tfplan > tfplan.json
```
在 CI 中对计划进行门控并输出 SARIF 伴随 Markdown 报告：
```
tfstride tfplan.json --quiet --fail-on high --output threat-model.md --sarif-output threat-model.sarif
```
输出机器可读的 JSON 报告：
```
tfstride tfplan.json --quiet --json-output threat-model.json
```
JSON 报告契约面向下游消费者进行版本管理。当前报告负载使用：
- `kind: "tfstride-threat-model-report"`
- `version: "1.0"`
捕获当前未抑制的发现结果作为基线，随后仅对新发现结果进行门控：
```
tfstride tfplan.json --quiet --baseline-output baseline.json
tfstride tfplan.json --quiet --fail-on high --baseline baseline.json
```
使用已提交的仓库配置，使 CI 与本地运行共享相同默认值：
```
tfstride tfplan.json --quiet
tfstride tfplan.json --config ./tfstride.toml --json-output threat-model.json
```
## 仪表板
该仓库还包含一个轻量级的 FastAPI 仪表板，位于 `apps/dashboard/`。它复用了与 CLI 相同的引擎、发现结果与 JSON 契约，而非增加第二条分析路径。
在线演示：`https://tfstride.beane.me`
安装 Web 依赖：
```
python3 -m pip install -e '.[dashboard]'
```
从仓库根目录运行仪表板：
```
uvicorn apps.dashboard.main:app --reload --port 8001
```
常用路由：
- `/`：计划分析的上传表单
- `/scenarios`：内置固定装置画廊页面
- `/demo/{scenario_id}`：内置固定装置场景，如 safe、mixed 与 nightmare
- `/api/analyze`：返回 JSON 报告契约的多部分上传端点
- `/api/docs`：仪表板 API 的 OpenAPI 文档
- `/healthz`：用于进程与代理检查的简单健康端点
部署说明：
- 仓库跟踪的系统服务单元示例位于 `apps/dashboard/deploy/tfstride-dashboard.service`
- 已提交的 systemd 单元与 Caddy 配置为部署示例，非固定要求
- 已提交示例使用通用的 `tfstride` 服务账户、`/srv/tfstride` 安装路径与 `tfstride.example.com` 主机名
- 在将单元安装到 `/etc/systemd/system/` 前，请更新工作目录、服务用户、虚拟环境路径、绑定地址与端口
- 更新单元后运行 `sudo systemctl daemon-reload && sudo systemctl enable --now tfstride-dashboard`
- 简单的 Caddy 反向代理示例位于 `apps/dashboard/deploy/Caddyfile.example`
## 示例输出
示例发现结果摘录：
```
#### 数据库可从来源过于宽松的权限访问
- STRIDE category: Information Disclosure
- Trust boundary: `workload-to-data-store:aws_instance.app->aws_db_instance.app`
- Severity reasoning: internet_exposure +2, data_sensitivity +2, lateral_movement +1, blast_radius +1, final_score 6 => high
- Evidence:
- security group rules: aws_security_group.db ingress tcp 5432 from 0.0.0.0/0
- network path: database trusts security groups attached to internet-exposed workloads
```
在失败计划上的预期结果：
```
Policy gate failed: 3 finding(s) meet or exceed `high` (3 high).
```
## CI 用法
GitHub Actions 示例，包含 SARIF 上传与高严重性门控：
策略门控在发现结果达到或超过所请求阈值时返回退出码 `3`。
```
name: threat-model
on:
pull_request:
push:
branches: [main]
jobs:
scan:
runs-on: ubuntu-latest
permissions:
actions: read
contents: read
security-events: write
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.11"
- run: python -m pip install -e .
- run: terraform plan -out tfplan
- run: terraform show -json tfplan > tfplan.json
- run: tfstride tfplan.json --quiet --fail-on high --sarif-output tfstride.sarif
- uses: github/codeql-action/upload-sarif@v3
if: always()
with:
sarif_file: tfstride.sarif
```
预应用门控示例：
```
terraform plan -out tfplan
terraform show -json tfplan > tfplan.json
tfstride tfplan.json --quiet --fail-on medium --output threat-model.md --sarif-output threat-model.sarif
terraform apply tfplan
```
## 演示场景
仓库包含多个可立即运行的 Terraform plan 固定装置：
- `sample_aws_alb_ec2_rds_plan.json`：公共 ALB、私有 EC2 应用层与私有加密 RDS，用于演示常见 Web 架构上的组合传递数据路径发现
- `sample_aws_baseline_plan.json`：大部分分段的环境，包含故意的 IAM 卫生问题与不明显的数据私有路径，用于演示基线检测器表面
- `sample_aws_cross_account_trust_unconstrained_plan.json`：最小跨账户假设角色信任，无限制条件，用于练习 IAM 信任发现路径
- `sample_aws_cross_account_trust_constrained_plan.json`：类似跨账户信任，但通过 `ExternalId`、`SourceArn` 与 `SourceAccount` 收窄，使报告展示控制而非发现
- `sample_aws_lambda_deploy_role_plan.json`：私有 Lambda 部署路径，范围受限的 S3 访问与故意的跨账户信任，用于练习 IAM 与信任发现且无公共网络噪声
- `sample_aws_safe_plan.json`：默认私有环境，受保护存储、私有数据库访问且无活动发现
- `sample_aws_plan.json`：混合案例，包含公共暴露、宽松的数据库可达性、风险性 IAM 与跨账户信任
- `sample_aws_nightmare_plan.json`：故意破坏的环境，叠加公共访问、公开存储、宽松 IAM、危险工作负载角色与爆炸半径扩展
## 架构
输入：
- 由 `terraform show -json` 生成的 Terraform plan JSON
流水线：
1. 将 Terraform plan 解析为原始资源记录
2. 将受支持的 AWS 资源规范化为与提供者无关的内部模型
3. 检测信任边界，例如互联网到服务、公共到私有分段、工作负载到数据存储、控制平面到工作负载关系与跨账户信任
4. 评估确定性的面向 STRIDE 的规则并观察明确的降低风险的管控措施
5. 渲染 Markdown 并可选地输出 SARIF
该引擎有意保持简单且可解释：
- 信任边界模型化对审查重要的跨越，而非完整图引擎
- 规则作用于规范化基础设施事实，而非原始 Terraform JSON
- 严重性采用小型加法模型，涵盖互联网暴露、权限广度、数据敏感度、横向移动与爆炸半径
当前信任边界类型：
- `internet-to-service`
- `public-subnet-to-private-subnet`
- `workload-to-data-store`
- `cross-account-or-role-access`
- `admin-to-workload-plane`
当前规则包括：
- 互联网暴露的计算资源且入站权限过于宽泛
- 可从公共或可来源访问的数据库
- 未加密的 RDS 存储
- 公开的 S3 暴露
- 允许公开或跨账户访问的敏感资源策略
- 允许公开或跨账户访问的服务资源策略
- 宽松 IAM 特权
- 包含敏感权限的工作负载角色
- 公共工作负载与私有数据层之间缺少分段
- 可从互联网暴露路径传递访问的敏感数据层
- 到达具有私有数据库或密钥访问权限的工作负载的宽松或跨账户控制路径
- 信任关系扩展爆炸半径
- 无收窄条件的跨账户或宽松信任
输出包括：
- 发现结果的摘要计数与已发现的信任边界
- 按严重性分组并附带理由、缓解措施、证据与严重性推理的发现结果
- 当引擎观察到明确的降低风险信号（如 S3 公共访问阻断、收窄的信任或私有加密 RDS）时，观察到的管控措施
- 包含规范化资源、发现结果、观察结果、指纹与过滤摘要的 JSON 输出
- 用于人工审查的 Markdown
- 用于扫描器兼容集成的 SARIF 2.1.0
## JSON 契约
JSON 报告旨在作为面向未来仪表板与自动化的稳定机器接口。
顶级部分：
- `kind`
- `version`
- `tool`
- `title`
- `analyzed_file`
- `analyzed_path`
- ``
- `filtering`
- `inventory`
- `trust_boundaries`
- `findings`
- `suppressed_findings`
- `baselined_findings`
- `observations`
- `limitations`
契约说明：
- 同一主版本内可添加附加字段
- 破坏性结构变更应递增主版本号
- `inventory.resources` 与 `trust_boundaries` 按稳定排序序列化，便于下游消费者使用
## 抑制与基线
抑制是明确的、可审查的例外。CLI 接受包含一个或多个选择器的 JSON 文件，例如 `rule_id`、`resource`、`trust_boundary_id`、`severity`、`title` 或 `fingerprint`。
```
{
"version": "1.0",
"suppressions": [
{
"id": "accept-cross-account-trust",
"rule_id": "aws-role-trust-expansion",
"reason": "Tracked in SEC-123 until the deploy role is narrowed."
}
]
}
```
基线由工具生成，并通过稳定发现指纹进行键控，以便 CI 仅聚焦于新引入的发现结果：
```
tfstride tfplan.json --quiet --baseline-output baseline.json
tfstride tfplan.json --quiet --baseline baseline.json --fail-on high
```
## 仓库配置
CLI 会从当前工作目录或计划文件目录自动发现 `tfstride.toml`。也可以通过 `--config` 显式传递。
CLI 标志优先于配置值。
示例：
```
version = "1.0"
title = "Platform Threat Model"
fail_on = "high"
baseline = ".tfstride/baseline.json"
suppressions = ".tfstride/suppressions.json"
[rules]
disable = ["aws-role-trust-expansion"]
[rules.severity_overrides]
aws-iam-wildcard-permissions = "low"
```
支持的配置键：
- `title`
- `fail_on`
- `baseline`
- `suppressions`
- `rules.enable`
- `rules.disable`
- `rules.severity_overrides`
## 支持的 AWS 资源
MVP 有意支持聚焦的资源集合：
- `aws_instance`
- `aws_ecs_service`
- `aws_ecs_task_definition`
- `aws_ecs_cluster`
- `aws_security_group`
- `aws_security_group_rule`
- `aws_nat_gateway`
- `aws_lb`
- `aws_db_instance`
- `aws_s3_bucket`
- `aws_s3_bucket_policy`
- `aws_s3_bucket_public_access_block`
- `aws_iam_role`
- `aws_iam_policy`
- `aws_iam_role_policy`
- `aws_iam_role_policy_attachment`
- `aws_iam_instance_profile`
- `aws_lambda_function`
- `aws_lambda_permission`
- `aws_kms_key`
- `aws_sns_topic`
- `aws_sqs_queue`
- `aws_secretsmanager_secret`
- `aws_secretsmanager_secret_policy`
- `aws_subnet`
- `aws_vpc`
- `aws_internet_gateway`
- `aws_route_table`
- `aws_route_table_association`
未支持的资源将被跳过并在报告中指出。
## 仓库布局（简略）
```
.
├── fixtures/
│ ├── sample_aws_alb_ec2_rds_plan.json
│ ├── sample_aws_baseline_plan.json
│ ├── sample_aws_cross_account_trust_constrained_plan.json
│ ├── sample_aws_cross_account_trust_unconstrained_plan.json
│ ├── sample_aws_ecs_fargate_plan.json
│ ├── sample_aws_lambda_deploy_role_plan.json
│ ├── sample_aws_nightmare_plan.json
│ ├── sample_aws_plan.json
│ └── sample_aws_safe_plan.json
├── examples/
│ ├── alb_ec2_rds_report.md
│ ├── baseline_report.md
│ ├── lambda_deploy_role_report.md
│ ├── nightmare_report.md
│ ├── sample_report.md
│ └── safe_report.md
├── apps/
│ └── dashboard/
│ ├── api_models.py
│ ├── deploy/
│ │ ├── Caddyfile.example
│ │ └── tfstride-dashboard.service
│ ├── static/dashboard.css
│ ├── templates/
│ │ ├── base.html
│ │ ├── index.html
│ │ ├── report.html
│ │ └── scenarios.html
│ └── main.py
├── src/
│ └── tfstride/
│ ├── __init__.py
│ ├── analysis/
│ │ ├── policy_conditions.py
│ │ ├── rule_registry.py
│ │ ├── stride_rules.py
│ │ └── trust_boundaries.py
│ ├── input/
│ │ └── terraform_plan.py
│ ├── providers/
│ │ ├── base.py
│ │ └── aws/normalizer.py
│ ├── reporting/
│ │ ├── json_report.py
│ │ ├── markdown.py
│ │ └── sarif.py
│ ├── app.py
│ ├── cli.py
│ ├── config.py
│ ├── filtering.py
│ └── models.py
└── tests/
```
## 限制
- 仅 AWS v1
- 有意不完整的 Terraform 资源覆盖
- 子网分类优先使用明确的路由表关联，但不建模主路由表继承或所有路由边缘情况
- IAM 分析聚焦于内联策略、独立策略、角色策略关联与信任策略，而非完整关联图
- 支持的条件收窄有意聚焦于 `SourceArn`、`SourceAccount`、`ExternalId` 等键，而非每个服务特定的授权条件
- 无运行时校验、云 API 调用或漂移检测
- 无架构图或图形可视化
## 示例资源
- 安全示例：
[`fixtures/sample_aws_safe_plan.json`](fixtures/sample_aws_safe_plan.json),
[`examples/safe_report.md`](examples/safe_report.md)
- 基线：
[`fixtures/sample_aws_baseline_plan.json`](fixtures/sample_aws_baseline_plan.json),
[`examples/baseline_report.md`](examples/baseline_report.md)
- 真实的 ALB / EC2 / RDS：
[`fixtures/sample_aws_alb_ec2_rds_plan.json`](fixtures/sample_aws_alb_ec2_rds_plan.json),
[`examples/alb_ec2_rds_report.md`](examples/alb_ec2_rds_report.md)
- ECS / Fargate：
[`fixtures/sample_aws_ecs_fargate_plan.json`](fixtures/sample_aws_ecs_fargate_plan.json)
- 跨账户信任，无限制：
[`fixtures/sample_aws_cross_account_trust_unconstrained_plan.json`](fixtures/sample_aws_cross_account_trust_unconstrained_plan.json)
- 跨账户信任，收窄：
[`fixtures/sample_aws_cross_account_trust_constrained_plan.json`](fixtures/sample_aws_cross_account_trust_constrained_plan.json)
- Lambda 部署角色：
[`fixtures/sample_aws_lambda_deploy_role_plan.json`](fixtures/sample_aws_lambda_deploy_role_plan.json),
[`examples/lambda_deploy_role_report.md`](examples/lambda_deploy_role_report.md)
- 混合：
[`fixtures/sample_aws_plan.json`](fixtures/sample_aws_plan.json),
[`examples/sample_report.md`](examples/sample_report.md)
- 噩梦：
[`fixtures/sample_aws_nightmare_plan.json`](fixtures/sample_aws_nightmare_plan.json),
[`examples/nightmare_report.md`](examples/nightmare_report.md)
## 测试
运行单元测试：
```
PYTHONPATH=src python3 -m unittest discover -s tests
```
## 项目存在的原因
Terraform plan 可读，但当网络态势、IAM 信任与数据层暴露相互交织时，仍容易误判。该项目存在的意义在于通过确定性分析、具体证据与 CI 友好输出，使这些路径显式化。
其有意限定在小型 AWS 优先的覆盖范围，以保持输出易于理解且稳定，而非假装成为完整云策略引擎。
## 许可证
MIT
标签：API安全, AWS, DPI, ECS, ECS, Fargate, IAM, JSON输出, Markdown报告, SARIF, STRIDE, Terraform, Terraform, TOML配置, 云计算, 信任边界, 可解释性, 威胁建模, 安全左移, 安全治理, 开源安全工具, 确定性分析, 策略门禁, 自动化合规, 规则引擎, 资源策略, 逆向工具, 逆向工程平台, 预部署扫描