怎样阻止调试证书签名的 APK 进入发布

文件名和任务成功都不能证明使用了发布证书

名为 app-release.apk 的文件可能来自 release build type，也可能由脚本复制、改名或从旧目录取出。Gradle 任务成功只说明构建流程按当前配置产生产物，不说明最终文件使用了哪张证书。调试 keystore、临时测试证书、上传证书和正式应用签名证书都能产生结构有效的 APK，因此门禁必须从最终字节中提取签名身份，而不是依赖命名约定。

Sign your Android app 区分应用签名密钥、上传密钥、证书和 Play App Signing 责任。团队要先明确某个渠道的门禁期望：直接分发 APK 应匹配该渠道允许的应用签名证书；提交 Play 的上传产物可能匹配上传证书，而用户设备获得的分发 APK 由 Play App Signing 使用应用签名密钥。两类文件不能用同一条“生产证书”口号模糊处理。

门禁失败必须停止发布而不是退回人工目测。人工审批适合确认新增证书是否经过授权，却不应允许操作者跳过摘要比较或把未知证书标记为“看起来正常”。工程判断是允许列表进入版本管理，由独立责任人审阅变更，并且每次验证回执同时保存 APK 摘要、包名、渠道、证书摘要和策略版本。

构建变体组合是调试证书误入的主要入口

Android build variants 说明 build type、product flavor、source set、applicationId 和签名配置会组合成多个变体。项目可能有 release、staging、benchmark、internal 以及地区或客户 flavor，其中某些变体继承 debug signingConfig，某些变体覆盖 applicationIdSuffix，另一些由脚本在 CI 中注入配置。只检查一个 release 块无法代表所有实际可上传产物。

变体清单应由构建系统实际枚举，而不是由文档手写。每个可发布变体记录 applicationId、versionCode、build type、flavor 组合、调试标志、签名配置标识、输出路径和候选摘要。流水线只允许明确列出的变体进入发布阶段，名称相似但不在列表中的任务不能自动上传。若新 flavor 首次出现，先建立证书和渠道策略再放行。

调试状态与证书身份需要分别检查。android:debuggable 为 false 并不保证证书正确，使用正式证书也不代表调试能力和测试端点已经关闭。本文只处理调试证书门禁，但实际发布仍应独立验证 debuggable、测试组件、网络端点和日志配置。工程判断是避免把多个安全属性压缩成“release=true”一个布尔值。

门禁只接受最终候选的可计算身份

候选身份至少包含文件 SHA-256、applicationId、versionCode、签名者证书摘要和渠道。流水线在构建结束后把 APK 移入只读候选目录，计算摘要，然后依次执行包元数据、签名、证书策略和来源验证。后续步骤只能引用该摘要路径，不能通过通配符重新搜索“最新 APK”，避免并行任务或旧文件被误选。

Android apksigner 文档要求签名后不再修改 APK，因为修改会使签名失效。zipalign 等需要影响文件布局的步骤必须在签名前完成；任何资源注入、渠道标记或重新压缩都会产生新字节，需要重新签名和重新验收。即使修改工具随后重签名并让结构验证通过，证书也可能已经改变，因此旧回执不能沿用。

AOSP app signing 说明 Android 使用应用签名建立更新身份，不同签名方案覆盖的文件区域和平台版本存在差异。门禁应根据应用支持范围和发布策略检查所需方案，但不能机械要求所有方案都存在。策略来源应是当前 minSdk、渠道和升级路径，验证结果按方案分别记录，不能只看一个总的 Verified。

apksigner 输出要解析方案与全部签名者

Android apksigner 可以输出签名验证结果、签名方案覆盖和签名者证书信息。流水线应使用固定工具版本和明确参数运行 verify，并捕获退出状态、标准输出和标准错误。退出状态非零立即失败；输出缺少预期字段也失败，因为工具版本变化、命令参数错误或本地化输出都可能让解析器误以为没有风险。

多签名者场景不能只取第一条摘要。策略应声明允许的签名者集合、是否允许多个签名者以及证书谱系边界，解析器收集所有证书 SHA-256，规范化为固定大小写与分隔符后做集合比较。出现调试证书、未知证书、重复异常条目或额外签名者都拒绝。证书主题、序列号和有效期可以记录作诊断，真正允许判断以受控摘要或公钥身份为准。

签名方案检查要结合支持范围。v1、v2、v3 和其他方案服务不同平台与能力，所需集合应由发布策略明确。AOSP app signing 与 Android apksigner 提供方案事实，但不能替项目决定 minSdk、证书轮换和渠道要求。没有策略时应标为未接入，不能因为某个方案显示 true 就宣称升级兼容已经验证。

• 固定 apksigner 版本和 verify 参数
• 退出状态非零立即停止发布
• 解析所有签名者而不是只取第一条
• 证书摘要规范化后做集合比较
• 签名方案要求来自版本化发布策略
• 解析字段缺失视为失败而不是忽略

允许证书策略按包名和渠道精确选择

单一全局证书允许列表容易把测试应用、正式应用和不同渠道混在一起。策略文件应以 applicationId 和渠道为主键，记录允许证书摘要、允许签名者数量、所需签名方案、允许 build type 及策略责任人。Play 上传包与直接分发包使用不同策略节点，避免上传证书被错误接受为用户侧分发证书。

策略变更需要双向验证。新增证书时核对授权记录和适用版本，删除证书前确认仍在发布或升级链中的旧版本不会被意外阻断。本文不展开私钥托管或轮换实现，但门禁至少要记录策略版本和变更依据。紧急操作不能直接把当前未知摘要加入列表，应先确认候选来源和发布责任，再通过审阅提交更新。

Debug 证书的识别不宜依赖固定一张默认摘要，因为不同机器和 CI 可能生成不同调试 keystore。正确防线是只允许明确登记的正式或上传证书，任何未登记摘要都失败；已知调试摘要可以作为更清晰的错误提示，但不是完整拒绝规则。这样即使出现自定义调试证书，也不会因未命中黑名单而放行。

用只读解析器把证书策略变成失败关闭门禁

人工查看 apksigner 文本容易漏掉额外签名者、false 方案或格式变化。可以在签名验证之后，把原始输出和发布策略交给只读解析器。解析器确认报告包含 Verifies 标记，收集所有证书 SHA-256、解析每个签名方案的 true 或 false，并根据 applicationId、channel 和 buildType 选择唯一策略。无法选择策略、证书集合不等或必需方案未通过时返回非零。

下面 Python 示例不运行签名工具、不处理 keystore，也不包含真实证书。输入 output.txt 是前一步 apksigner verify --verbose --print-certs 的输出，policy.json 使用公开占位摘要展示结构。真实工程应把 apksigner 退出状态单独传给门禁，锁定输出语言和工具版本，并在隔离环境保存原始回执。示例通过只说明解析到的证书与方案满足策略，不证明私钥管理和渠道实际上传正确。

解析器应当对格式变化敏感。正则没有命中证书、方案或总体验证标志时直接失败，并提示更新工具适配，而不是返回空集合后继续。策略输入也需要 schema 校验，重复节点、空允许列表和无责任渠道都不允许。工程判断是宁可短暂阻塞发布，也不能在验证链失明时默认信任候选。

• 输入来自固定版本 apksigner 的最终候选输出
• 真实流水线单独检查工具退出状态
• 证书集合精确相等而非子集匹配
• 必需方案逐项为 true
• 策略选择必须唯一
• 格式变化导致失败并要求更新适配

from pathlib import Path
import json
import re
import sys

if len(sys.argv) != 5:
    raise SystemExit("usage: gate.py output.txt policy.json appId channel")

output_path = Path(sys.argv[1])
policy_path = Path(sys.argv[2])
app_id = sys.argv[3]
channel = sys.argv[4]
if not output_path.is_file() or not policy_path.is_file():
    raise SystemExit("apksigner output and policy are required")

output = output_path.read_text(encoding="utf-8")
policy = json.loads(policy_path.read_text(encoding="utf-8"))
if "Verifies" not in output:
    raise SystemExit("apksigner did not report a verified APK")

cert_pattern = re.compile(r"certificate SHA-256 digest:\s*([0-9A-Fa-f:]+)")
scheme_pattern = re.compile(r"Verified using (v\d+) scheme.*:\s*(true|false)", re.I)
certificates = {match.replace(":", "").lower() for match in cert_pattern.findall(output)}
schemes = {name.lower(): value.lower() == "true" for name, value in scheme_pattern.findall(output)}

if not certificates:
    raise SystemExit("no signer certificate digest was parsed")
if not schemes:
    raise SystemExit("no signature scheme result was parsed")

matches = [item for item in policy.get("releases", [])
           if item.get("applicationId") == app_id and item.get("channel") == channel]
if len(matches) != 1:
    raise SystemExit("expected exactly one release certificate policy")

selected = matches[0]
allowed = {value.replace(":", "").lower() for value in selected.get("allowedDigests", [])}
required = {value.lower() for value in selected.get("requiredSchemes", [])}
build_type = selected.get("buildType")

failures = []
if not allowed or certificates != allowed:
    failures.append("signer certificate set does not match the allowlist")
if build_type == "debug":
    failures.append("debug build type is forbidden for release")
for scheme in required:
    if schemes.get(scheme) is not True:
        failures.append(f"required signature scheme did not verify: {scheme}")

if failures:
    print("release signing gate failed:")
    for failure in failures:
        print(f"- {failure}")
    raise SystemExit(2)

print(f"accepted {len(certificates)} signer certificate(s)")

构建来源和 provenance 防止正确证书签错文件

证书允许列表只能回答签名者身份符合策略，不能回答被签名的文件来自哪个构建。若发布人员误取旧 APK、测试 APK 或未经批准的中间产物，再使用正式证书签名，证书门禁仍可能通过。SLSA Provenance v1.1 将产物主体与构建者、构建类型、外部参数和依赖材料关联，可以补充候选来源链。

provenance subject 摘要必须等于签名后最终 APK，builder 与 buildType 匹配批准流水线，externalParameters 中的变体和渠道与证书策略一致。若 provenance 只覆盖未签名中间产物，应明确记录变换关系和签名步骤证明，不能直接把中间摘要报告附给最终 APK。来源证明与证书门禁分别通过，才能降低“正确证书签错文件”的风险。

provenance 仍不能证明运行时安全或签名私钥保管正确。它能帮助回答由谁、按什么流程、使用哪些材料构建当前字节。工程判断是把来源验证放在证书比较之前或之后均可，但两者都引用同一 APK 摘要；任一失败都不能通过人工改名或重新归档修复，必须回到明确构建与签名步骤。

发布证据和事故处置要能反查同一候选

NIST SP 800-218 SSDF 将来源、构建、验证、变更和供应链风险纳入安全开发实践。调试证书门禁的证据包至少保存 APK 摘要、包名、版本、变体、渠道、apksigner 版本与回执、全部证书摘要、所需签名方案、策略版本、provenance 引用和最终决定。回执只读归档，不能用同名文件覆盖。

如果调试证书包已经提交，先停止发布并确认平台是否完成处理。计算误发 APK 摘要，记录证书、版本和渠道，撤回可撤回的发布，生成使用正确流程的新候选并重新执行全部门禁。不要把错误包重签名后保留同一文件名和旧回执，也不要宣称“覆盖上传”会自动让所有缓存和已安装实例消失。具体用户处置依据渠道回执和真实分发状态决定。

最终报告只能写成指定摘要候选的证书集合、签名方案、变体与来源满足当前策略，不能推导私钥永不泄露、业务代码安全或所有设备兼容。准备评估时，可通过御盾中央平台提交最终 APK、证书策略、apksigner 回执、变体清单和 provenance，先固定候选身份与发布边界。

• 证据包保存全部签名者而非单一摘要
• 策略、工具和构建变体都有版本
• 误发处置依据真实平台回执
• 正确重签名产物作为新候选重新验收
• 归档记录不可被同名文件覆盖
• 结论不越界到私钥管理或运行安全