cloud-pathfinder

cloud-pathfinder 🛰️

基础设施即代码的攻击路径审计工具——支持 Terraform、CloudFormation、Kubernetes、CDK、Pulumi、Bicep/ARM。 它不是代码检查器。它会将你的 IaC 解析为资源图，解析跨资源（以及跨文件）关系，并搜索从公共互联网通往核心资产（数据存储、机密信息、管理员）的多跳攻击链。它会返回 BREACHABLE / EXPOSED / HARDENED 判定，以及攻击者实际会走的具体路径。

它找到的攻击链示例： open security group (SSH 0.0.0.0/0) → EC2 instance-profile role → iam:PassRole privilege escalation to admin → S3 exfiltration

提供MCP 服务（Claude、Cursor、任何 MCP Agent）和按次付费的 x402 API（持有钱包的自主 AI Agent）。

---

🔐 隐私与数据模型（请先阅读）

将你的 IaC 发送给第三方属于敏感操作——以下是具体的处理方式：

• 你的 IaC 绝不会被存储或记录日志。 每次审计都在托管服务的内存中运行，发送响应后即丢弃。不会建立你的模板数据库，不会保留数据，也不会分析文件内容。
• 发送的内容： 仅有你传入的 IaC 文本（files 映射或 source 数据块）。 不会读取你机器上的任何内容、你的云账户或凭据——cloud-pathfinder 不会接触任何正在运行的云环境（请参见下文“诚实说明限制”）。你无需提供云密钥，因为它只分析声明式模板。
• 免费层与深度层——两者都在服务端运行，原因及区别如下：
  • 轻量 npm 客户端不包含任何分析逻辑（没有图引擎，也没有 IAM 权限提升知识库）。它只是一个 HTTP 调用方。因此，即使是免费判定和计数，也由托管服务计算，然后丢弃你的 IaC。这种坦诚的权衡让核心优势不落到你的机器上——我们会直言不讳，而不是声称有虚假的“100% 本地”模式。
  • 深度分析必须由用户主动选择（deep: true，且需付费）。只有在这种情况下才会返回完整攻击链、文件:行证据和修复建议。无论选择哪一层，你发送的 IaC 都相同——深度层不会让额外内容离开你的机器。

托管服务： https://cloud-pathfinder.vercel.app——所有分析均在服务端运行。 这个 npm 包是一个轻量 MCP 客户端：它会将 IaC 文本发送到托管端点并呈现判定结果。你的机器上不会运行任何分析逻辑。

---

⚡ 工作原理（30 秒）

1. 你的 MCP Agent 调用 audit_iac_attack_paths { files: { "main.tf": "..." } }。
2. 轻量客户端通过 POST 将 IaC 文本发送到 https://cloud-pathfinder.vercel.app。
3. 托管引擎会构建类型化的资源图，从 INTERNET 节点开始，使用 BFS 搜索到每个数据存储／机密信息／管理员终点的路径，并解析每一跳中的 IAM 权限提升可达性——整个过程都在内存中进行。
4. IaC 会被丢弃；不会持久化任何内容。
5. 深度层会返回每条完整攻击链及逐跳的 file:line 证据；免费层则返回判定、评分和计数。

npm 压缩包只包含 HTTP 调用方，因此无论免费层还是深度层，都无法离线运行。没有服务端时，它会返回明确的网络错误。

---

🆚 为什么它不是代码检查工具（以及为什么本地代码检查工具无法取代它）

代码检查工具会逐个标记资源：“这个 SG 是开放的”“这个角色权限范围过广”。 cloud-pathfinder 会推理这些事实如何关联——这是逐文件本地工具从结构上无法做到的：

能力	本地代码检查工具	cloud-pathfinder
标记一个开放的 SG / 一个权限范围过广的角色	✅	✅
图谱 — 哪个 SG 关联到哪个实例、实例采用哪个角色、角色读取什么	❌	✅
可达性 BFS 从互联网到核心资产，包含完整的多跳链路和文件:行号	❌	✅
IAM 权限提升知识库（20 多种原语：PassRole、CreatePolicyVersion……）	❌	✅
多云 — 在一个图谱中处理 AWS / GCP / Azure	❌	✅
瓶颈点分析（修复某一跳后可切断最多路径）	❌	✅
Diff 模式 — PR 引入 / 消除 / 加剧了什么	❌	✅
Kubernetes LB/NodePort → 特权 Pod → cluster-admin SA → Secret	❌	✅
SARIF 2.1.0，用于 GitHub 代码扫描（在 Security 选项卡中内嵌显示链路）	❌	✅

• 🔗 图谱，而非代码检查。 构建类型化资源图谱，并解析跨文件和跨云的真实关系。
• 🧭 可达性搜索。 从 INTERNET 开始，对每个数据存储 / Secret / 管理员目标进行 BFS，返回完整的多跳链路，并附上每一跳的文件:行号证据。
• 👑 IAM 权限提升知识库。 了解 AWS 托管策略权限以及 20 多种权限提升原语（PassRole+RunInstances、CreatePolicyVersion、AttachRolePolicy、SSM SendCommand、UpdateFunctionCode、UpdateAssumeRolePolicy……）。
• ☸️ Kubernetes 攻击面。 LoadBalancer/NodePort 暴露 → 特权 / hostPath / hostNetwork Pod、cluster-admin ServiceAccounts，以及挂载的 Secret。

系统会自动检测每个文件的格式，并将文件合并分析——一次调用即可混合处理 .tf、 CloudFormation .yaml/.json 和 Kubernetes 清单。

---

🚀 快速入门 — 将其添加到 MCP 客户端

{
  "mcpServers": {
    "cloud-pathfinder": { "command": "npx", "args": ["-y", "cloud-pathfinder-mcp"] }
  }
}

免费层无需密钥。重启客户端后，即可看到 audit_iac_attack_paths + diff_attack_paths 工具。（远程服务： https://cloud-pathfinder.vercel.app/mcp。）

工具：audit_iac_attack_paths

{
  "files": {
    "main.tf": "resource \"aws_security_group\" \"web\" { ingress { ... cidr_blocks = [\"0.0.0.0/0\"] } } ...",
    "k8s.yaml": "apiVersion: v1\nkind: Service\n..."
  }
  // or: "source": "<a single IaC blob>", "filename": "main.tf"
}

示例 — 输入 → 输出

audit_iac_attack_paths { "files": { "main.tf": "<SG open to 0.0.0.0/0 on 22 +
                          EC2 with instance-profile role that can s3:* + iam:PassRole>" } }

→ FREE:  verdict: BREACHABLE · risk 86/100 · 1 attack path · 1 crown jewel · 3 misconfigs

→ DEEP (deep:true):  verdict: BREACHABLE
   PATH #1 (internet → admin):
     [1] INTERNET → aws_security_group.web   (main.tf:4  — ingress 22 from 0.0.0.0/0)
     [2] → aws_instance.app                  (main.tf:19 — attaches sg web)
     [3] → aws_iam_role.app_role             (main.tf:31 — instance profile)
     [4] → iam:PassRole + ec2:RunInstances   (privesc → launch instance as admin role)
     [5] → s3:* on aws_s3_bucket.data        (main.tf:52 — exfiltration sink)
   CHOKE POINT: tighten main.tf:4 ingress → cuts this entire path.
   FIX: restrict ingress CIDR; split the role; add a permissions boundary.

免费层会返回判定结果、风险评分和计数（攻击路径、核心资产和错误配置的数量）。深度层会返回每条完整链路，包括跳点、文件:行号证据、权限提升可达性和修复建议。

工具：diff_attack_paths — CI/CD 闸门

提供更改前和后的 IaC（PR 的 base 和 head 树），它会准确报告更改对攻击面的影响：哪些互联网→核心资产链路是引入的、哪些是消除的、哪些是加剧的，并给出 INTRODUCES_BREACH / REDUCES_RISK / NEUTRAL / MIXED 判定结果。

{
  "before": { "files": { "main.tf": "...security group admits 10.0.0.0/16..." } },
  "after":  { "files": { "main.tf": "...security group admits 0.0.0.0/0..." } }
  // deep: true → full introduced/eliminated chains + before→after exploitability + which choke points now matter
}

逐文件代码检查工具或单状态扫描无法回答这个问题：它需要对两种状态都进行完整图谱分析和权限提升可达性分析，并对跨状态路径进行语义匹配。 HTTP：POST /diff（免费，仅返回计数）/ POST /pro/diff（深度分析）。

免费 HTTP API

POST /audit
Content-Type: application/json

{ "files": { "main.tf": "resource \"aws_security_group\" ..." } }

每个 IP 每小时限 30 次请求。如需无限制、商业或深度分析，请调用 /pro/audit。

输入格式： Terraform / OpenTofu、CloudFormation、Kubernetes、Helm、Kustomize、 Pulumi（TS/JS/Python）、Bicep/ARM，以及 AWS CDK — 包括合成后的 cdk.out/*.template.json 和未经合成的 CDK 程序（TypeScript + Python）， 因此 CI 闸门可在 cdk synth 之前基于 PR diff 运行。

---

SARIF 2.1.0 → GitHub 代码扫描

在 /audit、/pro/audit、/diff 或 /pro/diff 后添加 ?format=sarif（或 { "format": "sarif" }），即可获取可上传到 GitHub 代码扫描的 SARIF 2.1.0—— 每条攻击链都会内联显示在 PR 的 Security 选项卡中。

• 每条攻击链都是一个带有 codeFlow 的 SARIF result（逐步遍历路径： 互联网 → SG → 实例角色 → 权限提升 → S3），锚定到 IaC 的 file:line， 并附带 security-severity/CVSS，以正确显示徽章颜色。
• diff SARIF 只会对新增/加剧的路径（error 级别）判定检查失败； 已消除/缓解的路径会标记为 note。
• 免费层级会返回经过删减但符合架构规范的 SARIF（仅包含计数，不含 攻击链、代码流或路径的 file:line）；完整代码流属于高级功能。

# .github/workflows/cloud-pathfinder.yml (sketch)
- run: curl -s -X POST "$CPF/pro/diff?format=sarif" -H "Authorization: Bearer $KEY" \
       --data @payload.json -o cloud-pathfinder.sarif
- uses: github/codeql-action/upload-sarif@v3
  with: { sarif_file: cloud-pathfinder.sarif }

---

💳 解锁 /pro — 两种支付方式（双重支付）

深度分析 /pro/audit 会返回完整攻击链、每一跳的证据、权限提升分析 和修复建议。两种支付方式可并存：

方式	适用对象	操作方式
💳 银行卡（Stripe）	个人 / 团队	在 /pro/checkout 购买预付密钥，然后发送 Authorization: Bearer <key>（或设置 CLOUD_PATHFINDER_KEY）。
🪙 x402（USDC）	拥有钱包的 AI Agent	每次调用自动支付 $0.30。通过 Base 结算。无需注册，无需密钥。

POST /pro/audit          # 402 (shows BOTH lanes) → pay → result

---

可检测的问题（部分示例）

类别	详情
公网 → 角色 → 数据	敏感端口（SSH/RDP/DB）开放的 SG → 可读取 S3/Dynamo/RDS/Secrets 的实例角色 → 数据外泄
IAM 权限提升	iam:PassRole+ec2:RunInstances、iam:CreatePolicyVersion、iam:AttachRolePolicy、ssm:SendCommand、在 * 上使用通配符 *，以及约 15 种其他情况
公网数据存储	publicly_accessible = true 的 RDS、向所有人开放的存储桶
Kubernetes	LoadBalancer/NodePort → 特权 Pod → cluster-admin ServiceAccount → Secret
CloudFormation	解析 !Ref/!GetAtt 内置函数；分析 ManagedPolicyArns/内联策略

---

如何确保结果可靠

高级版引擎和知识库不会随 npm 包一起发布—— 已发布的客户端只是一个轻量级渲染器，会调用托管的分析服务。免费 层级确实实用（结论 + 计数）；深度攻击链、证据和权限提升 分析则在服务端提供，并通过付费解锁。

基于声明式 IaC 的启发式静态分析，并非实时云环境评估。它 根据模板声明的内容进行分析（不评估运行时的 SCP/权限边界/条件）。 请将检测结果视为优先排查线索，而非保证。

MIT · github.com/Baneado98/cloud-pathfinder