PerspectiveGraph

扫描器能发现问题，而我们能找到入侵路径。

PerspectiveGraph 将你已经在使用的工具——Trivy、Semgrep、Cloud Custodian、Falco，以及你的 AWS 和 Kubernetes 状态——整合到一张反映你真实环境的图谱中，并提出一个问题：有人能否从互联网出发，利用过于宽泛的权限，最终触及值得窃取的东西？

它会在拉取请求中、合并之前提出这个问题：只有本次变更开辟了路径，检查才会标红；修复也会以独立拉取请求的形式提交。开源（Apache 2.0），运行在你的基础设施上，不收集遥测数据。

十二秒的 make demo：当前可利用的内容 → 排序后的路径 → 某条路径的攻击链及其生成的修复 → 评分是否可信。使用的是扫描器示例输出和预置判定，并非真实环境。

• 查看运行效果 ——同一仪表盘，以只读方式发布。无需安装。
• 阅读文档 ——按主题编写的手册，每个主题一页，并支持搜索。
• 检查你自己的 AWS 账户 ——一条只读命令，无需部署。
• 将其加入拉取请求 ——十行 YAML。

这里的评分是模型根据提供的证据得出的结论，而不是测量出的发生频率：目前尚未根据现场数据进行任何校准，引擎会如实说明，而不会擅自上调评分。哪些内容经过测量，哪些没有。

30 秒检查自己的账户

无需部署，无需 Docker，也无需导入任何数据。一个静态二进制文件会询问 AWS 自带的策略评估器，查看哪些角色可以获得管理员权限——它会应用服务控制策略、权限边界和条件键，而单靠阅读策略无法发现这些因素：

# macOS (Apple silicon); swap darwin_arm64 for linux_amd64, linux_arm64 or darwin_amd64
curl -sSL https://github.com/luiacuaniello/perspectivegraph/releases/latest/download/perspectivegraph_darwin_arm64.tar.gz | tar xz
./perspectivegraph redteam -roles -region eu-west-1

它只读且免费：每次检查都是一次 iam:SimulatePrincipalPolicy 空运行，不会创建任何内容，也不产生费用；它仅需 iam:ListRoles 和前述权限，二者都属于 SecurityAudit。Windows 构建版本可在发布页面获取；每个二进制文件都使用 cosign 签名并附带 SLSA 来源证明，运行任何内容前，只需两条命令即可验证两者。

添加 -compare 后，它还会在同一账户上运行引擎，如果两者结果不一致，就以非零状态码退出。引擎的首个真实误报就是这样发现的，也正是这样保持修复状态的。如果它在你的账户上出现不一致，请报告问题：没有什么比这类报告更有价值。接下来，如何评估将分阶段引导你对自己的环境得出结论，每个阶段都会给出一个答案。

90 秒了解整个引擎

make demo

拉取已发布且经 cosign 签名的镜像，为其提供 Trivy / Semgrep / Custodian / Falco / Kubernetes / IAM / SSO 示例输出，并打印优先级最高的攻击路径及其生成的修复方案。仪表板地址为 **http://localhost:3000**，运行 make down 即可拆除。它需要 Docker、jq 和 curl，不会编译任何内容；从空镜像缓存开始大约需要 23 秒；make demo-build 则是使用你工作树构建的同一演示。

在 Kubernetes 上，该 Chart 是 Artifact Hub 上的官方软件包：

helm install perspectivegraph oci://ghcr.io/luiacuaniello/charts/perspectivegraph \
  --version 1.39.1 # x-release-please-version

在一台装有 Docker、具有 DNS 名称的机器（例如 VM）上，只需一条命令即可设置 TLS、生成凭据、启用经过身份验证的总线、设置每日备份并启动服务：在一台机器上用于生产环境。

make prod-init DOMAIN=perspectivegraph.example.com

该 Chart 和它运行的三个镜像（ghcr.io/luiacuaniello/perspectivegraph、-dashboard 和 -postgres）均使用 cosign 无密钥签名，并附带 SPDX SBOM 和 SLSA 来源证明：验证它们，不要盲目信任供应链。

仪表板打开后直接显示决策，而不是资产清单：当前正在被利用的内容、能够消除最多风险的最少改动，以及这些数值有多可信。路径按分诊优先级排序——路径能触及什么、运行时是否已确认、入口暴露程度如何——因此，得分较低的路径也可能排在得分较高的路径之前。

此路径为何为 P1、一个带范围的概率，以及每一跳能让攻击者做什么、其概率来源是什么。	引擎自身的评分是否经得起已记录结果的检验，以及结果数量是否足以得出结论。

截图来自运行 make demo，并使用了预置的判定结果：make seed-validation 会在部分路径上记录合成结果，类似 BAS 运行会测试部分环境，这就是校准面板有内容可显示的原因——也是它仍会显示结果仍不足的原因：它记录的少量结果远少于得出判定所需的 30 个。截图中的数量对应截图拍摄时的版本；示例数据之后有所增加，因此你的结果可能相差一两条路径。全新安装和公开演示都会显示数据不足，直到有真实结果为止。公开演示运行在一台免费的 VM 上，因此请将其视为尽力提供的服务。

为什么？

扫描器会报告容器携带严重的 CVE，但它无法报告这个容器位于面向互联网的负载均衡器之后，以可读取生产数据库的角色运行，因此是 1 万条发现中本周最值得修复的一条。这需要将其他工具的输出放在同一张图中，这正是本项目要实现的。开发者可以获得一项检查：只有当他们的更改打开了真实路径时，检查才会变红；安全团队则能获得一份简短的攻击路径排名列表，而不是一长串发现。

阻止打开攻击路径的拉取请求

无需部署。 运行器以只读方式读取你的环境，导入此拉取请求的扫描结果，并通过同一个引擎在进程内给出结果：

- uses: luiacuaniello/perspectivegraph@v1
  with:
    mode: local
    aws-region: eu-west-1     # read-only; give the job an OIDC role with SecurityAudit
    report: trivy.json

当此更改打开了通往敏感资产的路径，或使其更有可能时，检查会变红；而不是在更改添加了严重 CVE 时变红：无法通过任何路径到达的主机上的严重 CVE 不会导致构建失败，而现在可以到达生产数据库的容器上的中危 CVE 则会。更改之前就已存在的路径不计入，即使它们经过了此次更改涉及的对象：扫描结果会应用到环境副本上，再与原环境比较，不会写入任何内容。此外还有第三种结果，因为扫描从未到达的流水线不能和扫描结果干净的流水线得到同样的绿色通过标记：

判定	退出码	含义
clean	0	引擎已分析此更改：它没有打开或加重任何严重攻击路径
blocked	1	它打开或加重了严重攻击路径——检查会列出这些路径
unknown	2	无人分析过它。 扫描、导入或 SHA 有误

Terraform 计划也会在部署前经过同一道关卡：使用 source: terraform 和 terraform show -json 的输出，可单独评估，也可与实时环境进行比较。会打开路径的安全组规则、策略绑定或存储桶策略，会导致包含这些更改的拉取请求检查失败——请参阅 Terraform 计划。

在 GitHub Actions 之外，只需运行一条命令；它也可以作为 Trivy 插件安装：

perspectivegraph gate -local -aws-region eu-west-1 -report trivy.json -slug owner/name -sha "$COMMIT_SHA"

trivy plugin install github.com/luiacuaniello/perspectivegraph
trivy image -f json myapp:pr-42 | trivy perspectivegraph gate -local -aws-region eu-west-1 -report -

警告

来自分叉仓库的拉取请求无法获取机密，因此关卡会对其采取失败关闭策略，返回 unknown。不要用 pull_request_target 绕过此限制：它会使用你的机密——在本地模式下则是云凭据——运行贡献者的代码。

**在公开仓库中，**被阻止的检查会在公开的作业日志中打印路径（真实资产名称、CVE、敏感资产）。请使用 soft-fail，并将详细信息发布到私密位置。

手册涵盖其余内容：将操作指向已部署的引擎、对渲染后的清单进行关卡检查、使用预先收集的环境、逐步推出关卡，以及 action.yml 中的所有输入项。

让 Agent 查询它

大模型无法可靠地枚举数千条边或运行 Dijkstra；如果让它回答“我账户中的攻击路径”，它就会编造看似合理的路径。因此，引擎使用 MCP 通信：Agent 提出查询，并根据它不可能凭空编造的答案进行推理。

perspectivegraph mcp --api http://localhost:8080   # or https://demo.a3thinker.it, no credential needed

共有 8 个工具，每个工具都为只读，并且在协议中声明了这一点。最值得集成的是 simulate_fix：它会切断给定的边并重新运行模拟，报告实际发生的变化。此服务已列入官方 MCP 注册表，也可在 Glama 上找到；工具和客户端配置请参阅手册。

项目状态与成熟度

引擎及其公共 API 已完成，并有文档和测试。评分尚未校准。 还没有人把它用于真实环境，测试它发现的路径，并将判定结果反馈回来：这个闭环所需的机制已经构建并测试完成，但闭环尚未跑通。因此，应将评分理解为模型的判断及其自述的置信程度，而非经过测量的发生频率。可以用它来查找并切断路径；不要把它给出的百分比拿到董事会上。如果你在自己的环境中运行了它，欢迎告诉我们效果如何。 定位说明阐明了我们主张什么、不主张什么。

截至 v1.39.1，目前的测量结果。 make bench-cloudgoat 会在 CI 中使用四个 CloudGoat 风格的场景为引擎评分：

场景	预期	结果
ec2_ssrf	存在一条路径	已找到，未凭空编造
iam_privesc_by_attachment	存在一条路径（起点为泄露的凭证）	已找到，未凭空编造
ec2_private_subnet_no_path	不存在路径（SG 开放，但子网为私有）	未生成路径
iam_privesc_denied_by_guardrail	不存在路径（显式 Deny 优先）	未生成路径

这四种已知模式（其中两种为负向对照）上的精确率和召回率均为 1.00，因此它是一个回归门禁，而非衡量你的环境中准确率的指标。在真实 AWS 上，make reachability-lab-aws 可免费以同样方式检查暴露情况；make redteam-aws 则会根据 AWS 自己的策略评估器为引擎的提权主张评分。该评分已经发现过一个误报：引擎忽略了权限边界；问题现已修复，并且只要引擎与 AWS 存在分歧，make boundary-lab-aws 就会失败。make entrypoints-lab-aws 也会以同样方式将存储桶策略和函数 URL 交由 AWS 检查；首次运行发现了四个错误，这些错误也已修复。make public-access-lab-aws 可免费检查在整个账户上设置的 Block Public Access；make terraform-lab-aws 则会应用合并门禁评估过的 Terraform 计划，并询问互联网每个计划是否打开了入侵通道。这些实验室都会将发现结果写入构建产物，而仪表板的 Accuracy 页面会在 Checked against AWS 下展示结果：每个问题、AWS 的答案、引擎的答案，以及接受检查的版本。

• 云平台。 AWS 已上线，并通过真实账户验证；一次读取多个账户的功能已在测试夹具上验证，尚未在真实账户上验证。Azure 仅支持测试夹具，且没有 GCP 或 OpenStack 连接器：路线图说明了各自的规划。
• 接口。 GraphQL 架构已冻结并受到漂移防护，因此破坏性变更会伴随主版本发布，不会出现在补丁版本中：API 稳定性。
• 部署。 后端采用 distroless 镜像，以非 root 用户运行于只读根文件系统；镜像通过摘要固定；在 Helm 下，所有工作负载都满足 restricted Pod 安全标准，并在 CI 中进行断言。Compose 默认配置有意保持开放；除非 API 和 ingest 已通过身份验证，否则 PG_ENV=production 会拒绝启动。实际部署还需要更多措施（TLS、备份、代理后面的 TRUSTED_PROXY_CIDRS、可故障转移的数据库）：在单台机器上，make prod-init 会完成前三项；每次变更时，CI 都会从其中一个备份恢复；运维手册列出了其余事项。
• 支持。 仅支持最新版本，并设有安全修复时限（严重：7 天，高危：30 天）：SUPPORT.md。
• 遥测。 无。开箱即用时不会建立任何出站连接；GitHub、AI 助手和 KEV/EPSS 数据源都默认关闭，直到你进行配置。
• 范围。 面向开发者工作流中的可达攻击路径问题。它不是扫描器、CNAPP 或合规产品，也不能替代它们。
• 编写方式。 由一位与 Claude（Anthropic）协作的人类编写：设计决策和发布内容由维护者负责，大部分实现及其测试是在这次协作中完成的。请检查，而不要盲目信任：make test、make bench-cloudgoat、govulncheck ./... 和 CONTRIBUTING。

文档

• 通俗概念介绍 - 路径、评分、区间、优先级、结果、校准：仪表板使用的术语
• 连接你自己的基础设施 - 从笔记本电脑、单台机器、EKS 或任意集群连接你的 AWS 账户和 Kubernetes 集群
• 手册 - 架构、评分、所有集成、部署，以及适用于你自身环境的运维手册
• 评估 - 分阶段在你自己的环境中试用，每个阶段都会得出结论
• 定位 - 声明了什么、没有声明什么，以及如何核查
• 运维 · 威胁模型 · 规模 · API 稳定性
• 支持 · 升级 · 路线图 · 安全
• 贡献 · 治理 · 维护者 · 采用者

许可证

Apache License 2.0。每个文件都按 REUSE 定义的形式声明了许可证，并在 CI 中进行检查：REUSE.toml。