SO 使用的系统符号与 minSdk 边界怎样核对

链接成功与目标设备可用是两件事

Native 链接发生在构建环境，使用指定 sysroot、API 级别、对象文件和库；设备装载发生在目标 Android 系统，使用实际系统镜像、ABI、linker namespace 与安装集合。构建时能生成 SO，只说明当前链接步骤满足，并不证明 minSdk 设备存在同名系统符号，也不证明符号版本、调用约定和运行分支适合目标环境。

Android NDK stable APIs 明确给出稳定 Native API 与可用级别边界。若某 API 高于应用 minSdk，不能直接静态调用并期待低版本安全忽略；需要在调用前完成版本和符号可用性判断，并提供缺失时的业务回退。发布检查从最终 SO 的未定义符号出发，把每个系统引用连接到首次可用 API 与调用方式。

检查范围只覆盖系统符号与 minSdk 可用性，不重复完整重定位、DT_NEEDED、linker namespace 或 ABI 交付矩阵。相邻问题通过证据链接：本页发现动态解析时，可以继续参考同站 [dlopen 与 linker namespace 排查](/zh-cn/articles/dlopen-linker-namespace-hardening/)；当前结论仍限定在符号目录、守卫和实际调用结果。

先固定最终 SO、minSdk 与 ABI 身份

扫描对象必须从最终签名 APK 或设备实际 split 中提取，不能使用未 strip 中间库替代。记录 APK SHA-256、SO SHA-256、压缩路径、ABI、ELF Machine、Build ID、build variant、minSdk、targetSdk、NDK 和链接器版本。加固处理、strip、打包或渠道步骤都可能改变最终文件，旧输出不能自动继承。

Android ABIs 文档说明每个 ABI 具有独立调用约定、寄存器使用、对齐和设备支持范围。即使两个 ABI 导出相同 C 名称，它们的最终对象、依赖和优化结果仍不同。符号清单按 ABI 建立，Machine 与 APK 路径必须一致；声明支持某 ABI 不证明对应文件已经构建、打包或在设备运行。

minSdk 也必须来自发布变体，而不是仓库默认值或开发者记忆。不同 product flavor、动态模块和预编译库可能有不同最低要求，最终应用取值还会受合并配置影响。门禁记录实际候选使用的 minSdk，并让每个系统符号目录以该值判定。无法从发布证明确认时，状态为待审，不能选择一个较高值让扫描通过。

未定义符号需要先区分系统、运行库和项目依赖

GNU readelf 可以读取 ELF header、dynamic section、符号和重定位。使用宽输出查看动态符号表，将索引为 UND 的符号视为需要外部解析的候选，再按来源分类为 Android 稳定系统 API、C/C++ 运行库、NDK 库、项目其他 SO、第三方预编译库或未知来源。UND 不等于错误，但每个条目必须知道由谁在何时提供。

符号名称可能带版本后缀、弱绑定、C++ 名字修饰或工具显示差异。归一化时保留原始行，并在目录中同时记录 rawName、baseName、binding、visibility、version 和 sourceLibrary。粗暴删除 @ 后内容用于查表可能方便，但最终判定仍要确认版本需求；只 grep 一个字符串会漏掉绑定与版本差异。

项目内部符号和系统符号应分开。系统目录回答首次可用 API 与调用策略；项目依赖目录回答哪个最终 SO 提供、是否同 ABI 打包和装载顺序。未知符号不应自动归入 libc，也不因名称以下划线开头就忽略。门禁输出未知来源、目录缺项和 ABI 不匹配，交给依赖或 API 专项处理。

直接调用必须满足 minSdk，守卫要控制真实调用

直接引用系统函数时，最终 SO 的未定义符号会由动态链接过程解析。若函数首次可用 API 高于 minSdk，低版本可能在业务分支执行前就遇到装载或解析问题。静态门禁把 usage=direct 与 introducedApi 比较，introducedApi 大于 minSdk 时失败，不接受“这段代码在低版本不会点到”作为证据。

高版本能力可以采用运行时解析，但必须把库加载、符号查询、返回值检查、版本条件和失败回退放在同一可审阅路径。Android NDK stable APIs 提到使用 dlopen 与 dlsym 处理版本化 API 的方式。系统版本判断本身不足够，仍要检查符号指针；符号存在也不保证当前 namespace、设备实现和业务前置条件全部成立。

工具链支持的弱 API 引用同样要求调用前检查。弱绑定只改变符号缺失时的链接或解析语义，不会自动阻止空地址调用，也不定义产品回退。目录为 weak_checked 或 runtime_lookup 条目记录 guardEvidenceId、fallbackId、最低测试 API 和最高测试 API；缺少守卫证据时即使静态符号标为 WEAK 也不放行。

ABI 与 namespace 是独立于 API level 的边界

同一系统函数的首次可用 API 满足 minSdk，不等于所有 ABI 产物一致。编译条件、预处理宏、汇编、第三方库和链接输入可能让某个 ABI 引用额外符号。扫描对每个最终 SO 独立执行，并比较同源模块在不同 ABI 的目录差异。差异需要解释，但不能用一个 ABI 的成功覆盖另一个 ABI。

linker namespace 进一步限制库与符号是否可达。NDK stable APIs 说明的稳定 API 是使用基础，但应用自定义 dlopen 路径、非公开库或厂商库仍可能受 namespace 与设备环境影响。系统符号目录不应把“设备上看见某个文件”当成稳定依赖。动态解析路径的 namespace 行为进入相邻专项，本页只要求记录实际库名、符号和回退。

ABI 产物完整性也要先确认。APK 或 split 中缺少目标 ABI、第三方 SO 只有部分架构、Machine 与目录不一致时，符号扫描结果没有资格进入兼容判定。完整 ABI 交付矩阵另行维护；当前文章只在已确认的最终产物上检查系统符号，并将缺包状态明确返回给产物门禁。

用 readelf 和 API 目录阻断越界系统符号

自动门禁接收 readelf、最终 SO 和审核过的 API 目录。目录包含 minSdk、Machine、ABI 以及每个允许外部符号的 source、introducedApi、usage、abis、guardEvidenceId 和 fallbackId。脚本读取宽格式动态符号表，提取 UND 条目并保留绑定属性，去除显示用途的版本后缀后查目录；未知符号、Machine 不符、ABI 不符和越界直接调用都失败。

下面 Python 示例只读 ELF 和 JSON，不修改文件、不加载 SO、不包含私有符号。它要求三个显式输入，运行 readelf header 与 dynamic symbols，解析 Machine 和 UND 行，按目录筛选 source=system 的条目，并检查 direct、runtime_lookup、weak_checked 三种策略。动态或弱路径若没有守卫与回退标识，同样阻断。通过时输出 Machine、ABI、minSdk 和已核对系统符号。

目录必须由项目从 NDK API 信息、供应链和源码审阅中产生，不能让模型或扫描器猜 introducedApi。readelf 输出格式变化要用固定版本和测试捕获，原始 stdout 与 JSON 摘要同时归档。项目内部依赖可以在另一目录核对，但不可简单忽略；示例只输出系统条目，是为了保持当前搜索意图集中。

• readelf、最终 SO 和 API 目录使用显式路径
• Machine、ABI 与发布变体目录一致
• introducedApi 来自审核过的权威目录
• direct 调用不得越过 minSdk
• 动态与弱引用同时记录守卫和回退
• 原始 readelf 输出与门禁 JSON 一起归档

from pathlib import Path
import json
import re
import subprocess
import sys

if len(sys.argv) != 4:
    raise SystemExit("usage: check_native_apis.py readelf lib.so api-catalog.json")

readelf_bin = Path(sys.argv[1])
so_file = Path(sys.argv[2])
catalog_file = Path(sys.argv[3])
for required in (readelf_bin, so_file, catalog_file):
    if not required.is_file():
        raise SystemExit(f"missing input file: {required}")

catalog = json.loads(catalog_file.read_text(encoding="utf-8"))
result = subprocess.run(
    [str(readelf_bin), "-W", "-h", "--dyn-syms", str(so_file)],
    text=True,
    capture_output=True,
    check=False,
)
if result.returncode != 0:
    raise SystemExit(f"readelf failed: {result.stderr.strip()}")

machine_match = re.search(r"^\s*Machine:\s*(.+?)\s*$", result.stdout, re.MULTILINE)
if not machine_match:
    raise SystemExit("ELF Machine field was not found")
machine = machine_match.group(1)

if catalog.get("machine") != machine:
    raise SystemExit("catalog Machine does not match the ELF")
min_sdk = catalog.get("minSdk")
abi = catalog.get("abi")
if not isinstance(min_sdk, int) or not isinstance(abi, str):
    raise SystemExit("catalog minSdk and abi are required")

undefined = set()
for line in result.stdout.splitlines():
    if not re.search(r"\bUND\b", line):
        continue
    fields = line.split()
    if fields:
        undefined.add(fields[-1].split("@", 1)[0])

symbols = catalog.get("symbols", {})
failures = []
checked = []
for name in sorted(undefined):
    item = symbols.get(name)
    if not isinstance(item, dict):
        failures.append(f"{name}: symbol is absent from the approved catalog")
        continue
    if item.get("source") != "system":
        continue
    if abi not in item.get("abis", []):
        failures.append(f"{name}: symbol is not approved for abi={abi}")
        continue
    introduced = item.get("introducedApi")
    usage = item.get("usage")
    if not isinstance(introduced, int):
        failures.append(f"{name}: introducedApi is missing")
    elif usage == "direct" and introduced > min_sdk:
        failures.append(f"{name}: direct call exceeds minSdk={min_sdk}")
    elif usage in {"runtime_lookup", "weak_checked"}:
        if not item.get("guardEvidenceId") or not item.get("fallbackId"):
            failures.append(f"{name}: guarded use lacks guard or fallback evidence")
    elif usage != "direct":
        failures.append(f"{name}: unsupported usage policy")
    checked.append(name)

if failures:
    for failure in failures:
        print(failure, file=sys.stderr)
    raise SystemExit(2)

print(json.dumps({
    "machine": machine,
    "abi": abi,
    "minSdk": min_sdk,
    "checkedSystemSymbols": checked,
}, indent=2))

CTS 合规与应用兼容证据不能互换

Android CTS overview 说明 CTS 用于验证设备实现与 Android 兼容性定义的一致性。设备通过 CTS 有助于建立平台基础，但不能证明某个第三方应用、特定 NDK 版本、预编译库、加固变换、JNI 签名和自定义动态加载路径兼容。发布报告可以记录设备认证状态，但不能用 CTS 标签替代应用级证据。

Android instrumented tests 运行在设备或模拟器上，适合从真实 Java 或 Kotlin 入口触发 Native 加载和调用。API 边界测试至少覆盖 minSdk、每个高版本可选符号引入前后的 API、对应 ABI 和缺失回退。对于 runtime_lookup 或 weak_checked，分别验证符号存在与不存在时的路径；只在高版本成功调用不能证明低版本回退。

测试结果绑定 APK 与 SO 摘要、设备、API、ABI、系统构建、WebView 等无关组件无需混入。记录加载返回、linker 日志、JNI 注册、业务输入输出、错误和进程存活。单一设备通过不能代表完整矩阵；模拟器和云真机有各自证据等级，未执行项保持未测试。

按最早符号差异修复并限定放行结论

静态门禁出现未知符号时，先确定它来自系统、C++ 运行库、项目依赖还是第三方库，再回到对象文件、链接 map 和变更记录。introducedApi 越界时，不通过提高 minSdk、删除扫描记录或把 usage 改成 runtime_lookup 文字标签掩盖；需要真实代码守卫、回退和边界测试。每次只改变一个可解释变量。

设备装载失败时比较静态与现场：候选摘要是否一致、目标 ABI 是否安装、Machine 是否正确、系统 API 是否达到边界、namespace 是否可达、提供者库是否存在、弱指针是否判空。若通过排除整个核心 SO 的加固使问题消失，继续缩小到符号、方法或链接参数，评估保护损失，不能把全库排除直接当作最终修复。

放行结论应限定为指定摘要候选的列出系统符号满足当前 minSdk 与调用策略，并在列出的 API、ABI 和业务入口完成装载与回退测试。不能写成所有系统符号可用、全部设备兼容或加固不会影响 Native。准备评估时，可整理最终 APK 与 SO、readelf 输出、API 目录、minSdk、守卫与回退清单和设备回执，再通过御盾中央平台提交申请。

• 未知符号先确定真实提供者和对象来源
• API 越界通过代码守卫和回退修复
• 每次只改变一个编译、链接或保护变量
• 运行失败核对摘要、ABI、API 与 namespace
• 大范围保护排除继续缩小到具体边界
• 新候选重新生成静态目录和设备回执