【免费下载链接】plannotatorAnnotate and review coding agent plans and code diffs visually, share with your team, send feedback to agents with one click.项目地址https://gitcode.com/gh_mirrors/pl/plannotator点击查看免费下载本篇围绕 Plannotator 官方文档《Verifying Your Install》展开,系统讲解该项目的发布二进制如何做到可验证:每一次安装的 SHA256 侧车校验、基于 SLSA 的构建溯源(provenance)声明、gh attestation verify手动审计命令,以及安装器内置的可选溯源验证开关。读完本文,你将掌握如何对任意一台机器上的 plannotator 二进制做一次性密码学审计,以及如何通过 CLI 参数、环境变量或配置文件让每次升级都自动完成溯源校验,并能理解安装器脚本 scripts/install.sh 背后的实现细节与失败分类逻辑。两层验证体系:强制 SHA256 与可选构建溯源Plannotator 的每个发布二进制都伴随两层验证材料:SHA256 侧车文件:发布时随每个平台二进制附带一个binary.sha256文件,安装器在每次安装时自动执行比对,这是强制的、不可关闭的底线检查;SLSA 构建溯源声明:通过 Sigstore 签名、并记录在公开透明日志(Transparency Log)中的构建溯源证明。它提供从二进制回溯到确切 commit 确切 workflow run的密码学链路。溯源验证是可选的——只有当你需要这条强保证时才启用。从 README.md 的说明可以看出,v0.17.2 起发布流程还附加了 CycloneDX JSON SBOM,用 Grype 漏洞数据库评估通过后才允许签名和发布,并额外生成 GitHub/Sigstore 的 SBOM 声明,覆盖所有发布二进制和 npm 包。这个两层设计的动机在 scripts/install.sh 头部注释中写得很直白:如果只做 SHA256,攻击者只要控制了发布仓库就能替换二进制 校验文件而两者仍然一致;而溯源声明能把二进制锚定到构建时签名的 git ref 和 workflow,两者配合才构成完整信任链。手动验证:对任意已安装二进制做一次审计适合一次性审计场景。前提是安装了 GitHub CLI 并完成gh auth login。下面命令中vX.Y.Z替换为你实际安装的 tag。macOS / Linux:gh attestation verify ~/.local/bin/plannotator \ --repo backnotprop/plannotator \ --source-ref refs/tags/vX.Y.Z \ --signer-workflow backnotprop/plannotator/.github/workflows/release.ymlWindows (PowerShell 安装器):gh attestation verify $env:LOCALAPPDATA\plannotator\plannotator.exe --repo backnotprop/plannotator --source-ref refs/tags/vX.Y.Z --signer-workflow backnotprop/plannotator/.github/workflows/release.ymlWindows (CMD 安装器):gh attestation verify %USERPROFILE%\.local\bin\plannotator.exe ^ --repo backnotprop/plannotator ^ --source-ref refs/tags/vX.Y.Z ^ --signer-workflow backnotprop/plannotator/.github/workflows/release.yml为什么必须同时钉住 source-ref 和 signer-workflow这里有一个容易被忽略的细节:只传--repo只能证明这个制品是由我们仓库里的某个 workflow 构建的,而不能排除错误挂接(attestation 与资产错配)或来自无关 workflow 的声明。--source-ref钉住声明所基于的 git ref,--signer-workflow钉住签名它的 workflow 文件,二者同时给出才构成确切 commit 确切 workflow run的保证。scripts/install.sh 中的自动验证同样遵循这一约束,注释明确写道:这两个参数防止接受错误挂接的资产或来自无关 workflow 的声明。没有 gh 登录态?用公开 API 免认证验证attestations 端点对公开仓库是全世界可读的,因此可以不登录完成验证。步骤:计算本地二进制的 SHA256 摘要;用普通curl拉取https://api.github.com/repos/backnotprop/plannotator/attestations/sha256:digest;将响应中每个attestations[].bundle值写入文件(每行一个 JSON 文档,即 JSONL 格式);以--bundle file连同同样的--repo/--source-ref/--signer-workflow参数执行gh attestation verify。这正是安装器自动验证走的免凭据路径。两点限制需要注意:未认证的 API 限额为每 IP 每小时 60 次请求;并且无论哪条路径,gh每次运行时都要从网络拉取 Sigstore 信任根(TUF),因此验证永远需要网络可达。对于完全隔离(air-gapped)或无认证环境,GitHub 官方文档提供离线验证 attestation 的方案。仓库中保留了该 API 响应的真实结构示例 scripts/fixtures/attestations-response.json,可以看到响应形如{attestations: [{bundle: {...Sigstore bundle...}, ...}]},bundle 是标准 Sigstore v0.3 JSON,内含 RFC3161 时间戳和签名证书。安装时自动验证:三种启用方式与优先级溯源验证默认关闭——这与 rustup、brew、bun、deno、helm 等主流curl | bash安装器的默认行为一致。要让安装器在每次升级时额外执行gh attestation verify,有三种机制,优先级为:CLI 参数 环境变量 配置文件 默认值(关):方式一:单次安装参数curl -fsSL https://plannotator.ai/install.sh | bash -s -- --verify-attestationPowerShell 用-VerifyAttestation,Windows CMD 用install.cmd --verify-attestation。方式二:环境变量(写入 shell RC 持久生效):export PLANNOTATOR_VERIFY_ATTESTATION11/true/yes(不区分大小写)均为启用,0/false/no为显式关闭。方式三:配置文件(与 shell 无关的持久化):mkdir -p ~/.plannotator echo { verifyAttestation: true } ~/.plannotator/config.json源码中的三层解析逻辑scripts/install.sh 中的实现值得细看:# Precedence: CLI flag env var ~/.plannotator/config.json default (off). verify_attestation0 # 第 3 层:配置文件(最低优先级),grep 扁平布尔字段 if grep -q verifyAttestation[[:space:]]*:[[:space:]]*true $_config_dir/config.json; then verify_attestation1 fi # 第 2 层:环境变量 case ${PLANNOTATOR_VERIFY_ATTESTATION:-} in 1|true|yes|TRUE|YES|True|Yes) verify_attestation1 ;; 0|false|no|FALSE|NO|False|No) verify_attestation0 ;; esac # 第 1 层:CLI 参数(覆盖一切),-1 表示未设置 if [ $VERIFY_ATTESTATION_FLAG -ne -1 ]; then verify_attestation$VERIFY_ATTESTATION_FLAG fi几个从源码可以确认的实现细节:CLI 参数用哨兵值-1区分未设置和显式设置,未设置时才向下落层;--verify-attestation与--skip-attestation互斥,同时给出会直接报错退出;配置文件定位支持 XDG:优先$HOME/.plannotator(兼容旧默认),否则显式设置的绝对路径XDG_DATA_HOME/plannotator,安装脚本用正则直接 grep 扁平的顶层布尔字段(注释说明 PlannotatorConfig 中该字段不嵌套,故无假阳性问题);配置类型层:verifyAttestation?: boolean字段定义在 packages/shared/config.ts,安装脚本与运行时共享同一份配置类型契约,scripts/install.test.ts 中有专门测试断言config.ts确实导出该字段。免凭据 bundle 路径与回退策略启用后,安装器要求存在ghCLI,但不要求gh auth login。scripts/install.sh 的执行顺序:先走免凭据路径:向公开 attestations API 发起一次未认证curl请求(源码注释说明刻意不重试,因为未认证限额为 60 次/小时/IP,单次失败直接落入回退),响应中的attestations[].bundle需要用 PATH 上的 JSON 工具提取——依次尝试 node、python3、jq,三者都没有则该路径不可用;本地存在 JSONL 格式的 bundle 文件后,执行gh attestation verify binary --bundle file --repo ... --source-ref refs/tags/tag --signer-workflow ...;回退:bundle 路径不可用或未成功(老版本 gh 不识别--bundle、提取失败等),重试一次 gh 自己的认证拉取路径——验证本身永远不会被跳过;成功即安装,输出✓ verified build provenance (SLSA, credential-free via the public attestations API)或✓ verified build provenance (SLSA)。安全语义是硬失败:验证失败绝不静默跳过,临时文件会被清理并以退出码 1 终止安装。若某次安装确实想跳过,显式传--skip-attestation(bash/cmd)或-SkipAttestation(PowerShell)。失败原因的三级分类安装器不会笼统地报验证失败,而是按 gh 的输出做优先级分类(该逻辑与 install.cmd 对齐):输出特征分类含义含Sigstore verifiers连接性问题TUF 信任根每次运行都从网络拉取(不内嵌、不缓存),失败不代表二进制有问题,提示这不是坏二进制的证据含gh auth login环境问题免凭据路径未完成且 gh 未登录,提示登录或重试其他真正的溯源失败明确区分提示SHA256 匹配,但未找到有效的签名溯源,拒绝安装这种区分很重要:连接性失败和真实溯源失败对用户意味着完全不同的处置方式。测试 scripts/install.test.ts 覆盖了这三层优先级、参数互斥、免凭据路径与回退分支。溯源声明从哪来:release workflow 的 attest 任务验证端的命令只有构建端确实生成了声明才有意义。查看 .github/workflows/release.yml 可以看到attest任务的设计:权限隔离:id-token: write和attestations: write权限只授予独立的attest任务,构建任务本身没有任何 OIDC 铸币能力,且该任务只在 tag push 时运行——PR 构建和非 tag push 永远拿不到仓库身份 OIDC 令牌,从结构上关闭了恶意构建步骤铸币的攻击窗口;依赖顺序:attest依赖 build、smoke-binaries、release-security 等任务,先重新校验subject-checksums.sha256确认签名对象与构建产物一致;签名对象:原生二进制(plannotator 与 paste-service,覆盖 darwin/linux 的 x64/arm64 与 win32 的 x64/arm64),使用actions/attest-build-provenance(SLSA3 构建溯源);SBOM 声明:用actions/attest的 sbom-path 模式把发布级 CycloneDX 谓词绑定到所有发布对象(含 npm 包 tarball),而非 SBOM 文件本身;发布顺序:release任务声明needs: attest,确保签名溯源和 SBOM 声明先于 GitHub Release 发布存在,避免用户已能下载二进制但gh attestation verify查不到声明的竞态窗口。支持版本:为什么是 v0.17.2版本钉定与溯源验证从v0.17.2起完整支持——这是首个同时提供原生 ARM64 Windows 二进制和 SLSA 声明的发布。对此前 tag 的行为:macOS、Linux 与 x64 Windows 的默认安装(仅 SHA256)钉定旧 tag 仍可能可行;ARM64 Windows 主机会得到 404(该架构二进制当时不存在);启用溯源验证时,安装器在下载之前就做预检并干净地报错,而不是白白下载后再遇到晦涩的gh: no attestations found。这个预检的实现在 scripts/install.sh:MIN_ATTESTED_VERSIONv0.17.2当verify_attestation1且解析出的 tag 低于该常量时(install.sh#L657-L667),安装器输出可操作的错误信息:要么--version v0.17.2(或更高),要么--skip-attestation,要么取消环境变量/配置项。值得指出的是,这个比较用的是sort -V版本排序而非字典序,以正确处理v0.9.0与v0.10.0这类位宽差异。跨平台一致性由测试强制:scripts/install.test.ts 有一条测试专门断言三个安装器(bash/PowerShell/CMD)硬编码同一个MIN_ATTESTED_VERSION值,防止出现sh 说 v0.17.2、cmd 说 v0.17.3的漂移;另有测试断言 CMD 脚本的版本解析处理了v前缀剥离等边界。小结能力默认启用方式依赖SHA256 校验强制,不可关自动无SLSA 构建溯源(自动)关--verify-attestation/PLANNOTATOR_VERIFY_ATTESTATION1/~/.plannotator/config.jsonghCLI(免登录),node/python3/jq 之一(免凭据路径),网络手动审计按需gh attestation verify--source-ref--signer-workflowghCLI gh auth login(或用公开 API 免认证)Plannotator 这套机制的核心思想可以概括为:把 SHA256 当作不可妥协的地板,把构建溯源当作可选的天花板,并且无论哪一步失败都硬失败、把连接性问题与真实性问题明确分开。对任何采用curl | bash分发自签二进制的开源项目而言,这套三层配置优先级 免凭据 bundle 路径 失败分类的写法都具有很高的参考价值,可直接对照 scripts/install.sh、scripts/install.test.ts 与 .github/workflows/release.yml 深入研究。赞分享【免费下载链接】plannotatorAnnotate and review coding agent plans and code diffs visually, share with your team, send feedback to agents with one click.项目地址https://gitcode.com/gh_mirrors/pl/plannotator点击查看免费下载相关推荐Nativefier安装包校验SHA256与完整性验证Nativefier安装包校验SHA256与完整性验证 你是否曾担心下载的Nativefier安装包被篡改或损坏本文将详细介绍如何通过SHA256哈希值验证CLI桌面应用开发工具Wabbajack如何用自动化技术彻底改变游戏模组安装体验Wabbajack如何用自动化技术彻底改变游戏模组安装体验 你是否曾经为了安装心仪的游戏模组而花费数小时手动下载、配置和排序是否因为模组冲突而不得不反复调桌面应用游戏开发后端tfenv安全验证机制PGP签名、SHA256校验和keybase验证的完整流程tfenv安全验证机制PGP签名、SHA256校验和keybase验证的完整流程 想要安全地使用Terraform版本管理器tfenv吗本文将详细介绍tfe开发工具CLI上一篇PyWebIO错误处理与调试解决常见问题的10个方法下一篇微信Webhook推送助手5分钟快速上手企业微信消息自动化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考