安全保障论证（Security Assurance Case）¶

本文档是 httptap 的安全保障论证。它阐述项目**为何**相信其安全属性成立，而不仅仅是这些属性**是什么**。文档结构遵循 OpenSSF Best Practices 银级（silver-level）的 assurance_case 准则。

最近审阅： 2026-04-13，针对 httptap 0.5.0。

保障论证是一份持续演进的文档；它会在每个大版本发布时、以及威胁态势或功能集发生实质性变化时接受审阅。修订提案以针对本文件的 pull request 形式受理。

httptap 是什么¶

httptap 是一个命令行诊断工具。开发者提供单个 URL（并可选地附带请求头、请求体、代理、CA 包等），httptap 便执行一次 HTTP 请求（或一段简短的重定向链），并渲染每个阶段的计时与 TLS 信息。它**不会**：

• 接受来自不受信任对端的网络输入（它不是服务器）；
• 管理用户账户、会话或长期凭证；
• 执行远程代码或求值服务器提供的脚本；
• 在可选的 --json 导出之外持久化任何机密或用户数据。

安全需求¶

项目承诺以下可观测的安全属性。每一项都在下文各节中映射到相应的支撑论据。

信任边界¶

   ┌─────────────────────┐
   │ CLI user            │   trusted
   │ (argv, stdin, env)  │
   └──────────┬──────────┘
              │
              ▼
   ┌─────────────────────┐
   │ httptap process     │   trusted
   │ (Python 3.10+)      │
   └──────────┬──────────┘
              │  TLS/HTTP  ◄─── untrusted: network, proxy, remote host
              ▼
   ┌─────────────────────┐
   │ Remote HTTP server  │   untrusted
   └─────────────────────┘

• 用户 → httptap 是受信任的：假定用户有正当理由发起任何给定请求。输入校验仍会拒绝格式错误的 URL、方法、超时等，以防止操作者的失误。
• httptap → 网络 → 远程服务器 是不受信任的。所有跨越此边界的数据都被视为受攻击者控制：响应头、状态码、Location 值、TLS 证书、内容体。
• 构建流水线 → PyPI / GitHub Releases 是一个独立的信任边界，由 GitHub OIDC（无长期密钥）、Sigstore 签名以及按 SHA 固定的 actions 加以保护。

威胁模型¶

以下威胁按适用于诊断型 HTTP 客户端的 STRIDE 类别列出。超出客户端范围的威胁（例如服务器端 DoS）作为非目标被明确排除。

超出范围的威胁¶

• 在开发者机器上拥有本地代码执行能力的攻击者。 超出范围——该攻击者已然掌控了进程本身。
• 控制用户终端 / TTY 的攻击者。 超出范围。
• 针对 TLS 本身的密码分析攻击。 委托给 OpenSSL；缓解措施继承自系统 Python 构建。
• 后量子威胁。 由上游跟踪（OpenSSL / Python）；对 httptap 自身而言超出范围。

所应用的安全设计原则¶

映射到 Saltzer & Schroeder（1975）及现代补充原则。

所应对的常见实现弱点¶

源自 CWE Top 25 (2023) 和 OWASP ASVS 4.0。未列出的条目要么不适用于 HTTP 客户端，要么由上游处理。

供应链保障¶

支撑发布完整性属性（SR-5）：

• 发布：通过 GitHub OIDC Trusted Publishing 发布到 PyPI（并以 TestPyPI 作为预生产冒烟测试）——任何地方都没有长期的 PyPI 令牌。PEP 740 证明在 PyPI 上以“Verified publisher”呈现。
• 容器镜像：多架构（linux/amd64、linux/arm64）镜像使用 Buildx 构建并推送到 GHCR，使用 cosign 无密钥签名，并附带附加到镜像仓库的 SLSA 构建来源证明。
• Git 签名：发布提交和带注解的标签使用 gitsign（经 Fulcio 的 x.509 + Rekor 透明日志）以无密钥方式签名，采用发布工作流的 OIDC 身份。
• 签名：通过 actions/attest-build-provenance 和 cosign 进行 Sigstore 无密钥签名。签名密钥是短期的，由 Fulcio 按每次运行签发，并可通过 Rekor 透明日志验证。
• 来源证明：SLSA v1.0 证明伴随每个 wheel、sdist 和容器镜像摘要。
• Dockerfile 检查：hadolint 在每个 PR 上运行，失败阈值为警告级别。
• 固定（Pinning）：每个工作流中的每个 GitHub Action 都按 SHA 固定；由 Scorecard Pinned-Dependencies 和 zizmor pedantic 在每个 PR 上强制执行。
• 依赖跟踪：在发布期间生成 CycloneDX 和 SPDX 格式的 SBOM，并作为 GitHub Release 资产附上。
• 可利用性披露：一份 OpenVEX 文档（httptap-X.Y.Z.openvex.json）随 SBOM 一同发布，为每个依赖的 CVE 声明 httptap 是否实际受影响。真实来源以版本化形式保存在 .vex/httptap.openvex.json；消费 VEX 的扫描器（Grype、Trivy、Snyk）借助它抑制针对不可达的脆弱代码路径的误报告警。

用户可以独立验证已下载的制品：

gh attestation verify dist/httptap-X.Y.Z-py3-none-any.whl \
  --repo ozeranskii/httptap

已知残余风险¶

以下风险是被记载而非缓解的。它们代表的是显式的权衡取舍，而非疏漏。

• 单一维护者。 Bus factor 为 1（在 GOVERNANCE.md 中跟踪）。连续性计划缓解了运营层面的单点故障，但未缓解代码审查层面的单点故障：单个审查者可以在没有第二双眼睛的情况下合并变更。Pre-commit、CI 门禁和公开的审计轨迹部分弥补了这一点。
• 无运行时沙箱。 httptap 以用户的全部权限运行。这对于开发者诊断工具而言是恰当的，但意味着 httptap 自身的缺陷会以用户的权限运行。
• TLS 信任锚继承自操作系统。 如果操作系统信任库被攻陷（例如企业 MITM 代理安装了私有 CA），httptap 无法察觉。JSON 导出中的 network.tls_custom_ca 和 proxy_source 字段会记录是否使用了自定义 CA 包或代理。

变更历史¶

参考资料¶

• SECURITY.md —— 漏洞报告流程与受支持的版本。
• GOVERNANCE.md —— 项目角色、决策与连续性计划。
• ROADMAP.md —— 范围、非目标与弃用策略。
• 故障排查与常见问题 —— 运维指引。
• CWE Top 25 和 OWASP ASVS 4.0 —— 实现弱点的参考目录。