APSA mobile app security audit

APSA

面向 Android 和 iOS 的证据优先安全审计。

English · 한국어

这份英文 README 是唯一的权威来源。韩文 README 以其为准。

APSA 1.6.2 修复了 Objective-C 绑定范围、不完整的 OSV 查询、精确的声明验证、运行时取消和 APK 集发现来源。 请参阅补丁范围和升级影响。

APSA 1.6 分析扩展。 此版本新增了有界原生跨文件流和输入约束路径保护、JS/TS/Dart 候选项、已记录的 Gradle 变体选择、OSV 批处理与传输排除项、经过身份验证的运行时证据、AAB 标量资源、分离式 CMS 一致性检查和成对验证。 请参阅范围、选项和剩余限制以及新标注的合成结果。 后续工作新增了明确的 .apks 设备选择、IPA 稀疏页／资源密封和提供的锚点链检查，以及使用新合成应用模型进行测试的类型化运行时记录器。 合成 bundletool 选择检查已通过；已安装分包合并、Apple 签名者身份和物理设备验证仍不在已验证范围内。 最新比较器样本仍不完整，无法据此确定准确性排名。 iOS OS URL 传递仍在验证中；仅有回调分发并不能证明应用已获取 URL 或后端已撤销。 五项验证门槛记录了新的编译器、签名变更和已安装 iOS 模拟器证据，以及单独的软件包、比较器、bundletool 和后端测量范围。 请参阅1.6 版本发布验证，了解当前候选项门槛和升级影响，包括已更改的 MCP 工具清单。

APSA 1.6 大输入后续改进。 规则版本：2026.10.15.apsa.160。 输入暂存和 AST 分析在推断的模块组内共享代码优先级并采用轮转调度。 锁文件清单跟随应用代码；含糊的 *Tests/ 和普通 Frameworks/ 目录保留生产代码优先级。 报告会记录模块遗漏项，比较结果会显示输入完整度，而 Action 摘要会显示暂存遗漏项。不完整指纹仍作为 SBOM 元数据，而非应用哈希。请参阅范围和验证。

APSA 1.6 审查修复。 有界设备规格元数据、逐文件不完整原因、文本／编译混合覆盖、明确的签名绑定范围、可移植的源代码比较和精确的软件包内容检查，详见强化范围和证据限制。 合成获取适配器是源代码测试辅助工具，不包含在已安装的 wheel 中。

APSA 可帮助开发者和安全团队审计自己的移动应用。它会检查源代码和 APK/AAB/IPA 构建产物，关联公开漏洞信息，并集中保留证据、覆盖范围和报告历史。可使用 CLI、终端 UI，或通过 MCP 和可复用技能使用同一审计引擎。

发音为 “ap-sah”；韩文名称为 앱사。名称将“app + audit”与 App Security Audit 联系起来。APSA 将早期的 Quaygate lint 引擎和 Mobile Audit 工作流整合在一个软件包中。

APSA 1.1 新增了有界模型报告页面、可移植的已批准基线、导出的策略决策，以及明确的源代码模块／配置选择。请参阅模型和团队工作流了解相关约定，并参阅发布路线了解后续分析里程碑。

混合使用不支持的源代码语言和被截断的模式结果均属于不完整结果。声明的 Gradle 版本在提供已解析构建证据之前仍只是候选项。OS-CVE 关联会报告有界的近期时间窗口，因此仅有信息源的新鲜度无法满足历史覆盖要求。 APSA 1.2 新增了 AAB 基础清单和模块 DEX 分析、嵌入式 IPA Mach-O 元数据、范围受限的 Objective-C .m 候选文件分析，以及默认情况下在能够启动时启用的解析器 OS 隔离。 每次 AAB 审计仍然都是部分审计，嵌入式 IPA 元数据也无法验证签名。请参阅分析范围和限制和独立留出测试。

从 1.1 升级。 使用默认设置 APSA_PARSER_SANDBOX=auto 时，输入为空的激活探测成功后，解析器会在 macOS Seatbelt 或 Linux bubblewrap 下运行。如果没有可用的后端，报告会记录 parser_isolation.state: unavailable，并且仅应用资源限制进行解析。如果后端存在但无法启动（例如在另一个沙箱内，或用户命名空间受到限制），报告也会记录尝试使用的后端和探测原因，并添加一条清单警告。required 会拒绝此类审计；off 会跳过后端。隔离启动后发生解析器故障时，审计会中止，不会重试未沙箱化的解析。仅在 Gradle 版本目录中声明的依赖项，在提供构建用法或解析后的版本之前，将不再匹配 CVE。新增规则（AST-CRYPTO-ECB、AST-CRYPTO-WEAK-HASH、AST-SQL-CONCAT、OBJC-CRYPTO-WEAK-HASH、OBJC-WEBVIEW-UNTRUSTED-REQUEST）可能会相较于现有的 1.1 基线新增发现结果。

APSA 1.3 会将 Gradle 版本目录别名关联到使用这些别名的已打包依赖配置，并将应用模块的 gradle.lockfile 坐标作为解析后的版本读取。它还会解码 AAB 功能模块清单，在不验证签名的情况下重新计算 Mach-O CodeDirectory 页面哈希和授权哈希，适配更多 Swift 和 Objective-C 语法，并可针对明确指定的 Android 安全公告范围，补充 SoC 厂商及厂商补丁级别上下文。请参阅依赖证据结果、独立源代码对和分析范围和限制。

从 1.2 升级。

• 发布配置中引用的目录别名会成为 declared 候选项，并可再次获得 CVE 匹配；未引用的、仅用于测试的别名以及构建工具别名仍保持未解析状态。应用模块锁文件中的坐标是精确的，因此其匹配状态为 version-affected，默认策略会对高危和严重问题判定失败；其他模块的锁文件坐标仍保持为 declared 候选项。若某个 declared 候选项已被所有发布应用解析，则该候选项会被取代，不再参与 CVE 关联。输入不完整时会保留所有候选项；如果项目引用未能解析，则只有应用自身的声明可以被取代。
• 锁文件注意事项：APSA 不会检查是否启用了依赖锁定，也不会检查锁文件是否为最新版本；它会合并每个应用模块的发布运行时类路径（包括不同变体以及可穿戴设备、电视或汽车应用）。--source-module 只扫描该模块的目录，因此不会读取模块目录之外的根版本目录和库模块声明。
• 基线和豁免：通过锁文件解析的问题会有新的位置（gradle.lockfile）和状态，因此 only_new 会将其视为新问题，针对旧问题 ID 的豁免也不再匹配。升级后请重新批准基线。
• --online 会将依赖名称和版本发送至 OSV，其中包括发布配置中的目录别名、传递性锁文件坐标和私有组 ID，除非将其排除。默认的 auto 模式对最多 100 个符合条件的唯一软件包版本坐标使用旧版查询，对更大的清单使用批量查询。默认在线预算为 1000 个软件包、每批 100 个软件包和 2000 次 OSV 请求，其中包括分页和漏洞记录查询。 scan --online --osv-query-mode legacy 保留 100 个软件包的限制；--osv-query-mode batch 会显式启用批量查询，并使用默认预算。使用 scan 的 --osv-exclude-ecosystem、--osv-exclude-name 或 --osv-exclude-coordinate，可在本地排除数据传输。即使之前有缓存结果，被排除的依赖也绝不会发送或标记为已检查。未检查、未解析、不受支持或被排除的依赖会导致在线覆盖不完整；某个软件包有新结果并不意味着其余部分也已完成。
• IPA 报告新增 BINARY-IOS-CODE-INTEGRITY。哈希一致并不能证明真实性，因为经过修改并重新签名的二进制文件仍可能一致。哈希不匹配会添加警告，而非问题；App Store 加密和未签名的可执行文件仍标记为 not-run。
• intel sync 仅刷新近期的 Android 公告时间范围；较早的月份请使用 intel backfill。由 1.2 缓存的记录根据组件名称确定其供应商范围；芯片组和内核部分之外的条目仅使用平台补丁级别。AAB 功能模块的安装状态仍为未知。
• 经过适配的 Swift 和 Objective-C 文件仍为部分解析；与规范化预处理器条件重叠的 Objective-C 函数会因存在不确定性而跳过。未修改的 1.2 技能可通过 apsa skill install 升级。

APSA 1.4 更便于面向开发者和编码 Agent 使用。GitHub Action 会将 SARIF 上传至代码扫描功能，并附上稳定指纹、安全严重性、MASWE 标签和证据状态；每份报告都包含一份 OWASP MASWE v1.0 覆盖矩阵，列明 APSA 未评估的弱点；MCP 服务已打包，可用于 MCP Registry，也可作为 Claude Code 插件，并附有文档说明的 MCP 安全模型。

从 1.3 升级。

• SARIF 导出现在会为每条包含结果的规则列出描述符（帮助文本、 security-severity、精确度、MASVS/MASWE 标签），根据发现项身份添加 partialFingerprints， 并将未运行和部分覆盖情况报告为工具执行通知。候选发现项的级别为 warning 而非 error，其规则会标记为 candidate。--sarif-root 会使位置相对于仓库；URI 会进行百分号编码，APK/AAB/IPA 成员及目标范围外的文件会作为目标上的逻辑位置显示。 因此，代码扫描可能会显示一次重新键控的告警。
• 新增的源代码检查（导出组件、备份、targetSdk、隐私清单、ATS 例外、硬编码密钥、不安全随机数、信任所有 TLS、外部存储、Java 反序列化、更多 SQL 接收点、可变的 PendingIntent）会添加发现项和覆盖条目。包含 required_rules 或严重性门槛的策略可能会失败，而 1.3 中不会；在收紧门槛前，请先查看首份 1.4 报告。
• 规则元数据新增 MASWE v1.0 标识符；模型上下文和 capabilities 新增 maswe 部分，Markdown 报告新增 MASWE 覆盖表。由 reports ingest 生成的报告会添加 external_inputs 和 origin: external 的发现项；现有字段的含义不变。
• MCP 服务新增 verify_finding、 specs_validate、reports_ingest_sarif、reports_checklist 和 reports_history。 tool_manifest_sha256 现在涵盖经过规范化的 APSA 自有表面，因此其值会发生变化；请更新任何固定的哈希值。未修改的 1.3 技能可通过 apsa skill install 升级。

APSA 1.5 扩大了源代码扫描的检查范围。新增检查涵盖导致大多数 MASTG 演示漏报的 OWASP MASWE 弱点：损坏的密码算法和隐式 ECB、由常量构造的密钥材料和 IV、短密钥（512–1536 位）RSA、DSA 和 DH 密钥长度，以及 CryptoKit Insecure 摘要；未绑定到密钥的生物识别结果、设备凭据回退，以及在重新注册后仍保留的密钥；低于 1.2 的 TLS、绕过 App Transport Security 的 iOS 连接，以及网络安全配置中的用户 CA 或明文传输；未经验证的 App Links、Intent 重定向和隐式内部 Intent；路径遍历和未启用安全编码的键控归档；以及关闭的安全浏览、UIWebView 和 WKWebView 文件访问。在一组由 MASWE 弱点标注的 24 组公开漏洞/修复配对盲测集中，APSA 1.5.0 在 21 组计分且属于范围内的配对中，于标注行找到了 7 组（Wilson 95% 置信区间为 17–55%）。其中 7 组中的 2 组来自 1.5 新增规则，5 组来自 1.4 已有规则；修复侧误报率上限为 21 组中的 4 组，另有第 22 组范围内配对扫描失败。请参阅盲测配对结果 和分析范围与限制。

从 1.4 升级。

• 新规则会新增发现项和覆盖范围条目：AST-CRYPTO-WEAK-CIPHER、 IOS-CRYPTO-WEAK-CIPHER、AST-CRYPTO-HARDCODED-KEY、AST-CRYPTO-STATIC-IV、 SOURCE-WEAK-KEY-SIZE、SOURCE-BIOMETRIC-EVENT-BOUND、 SOURCE-BIOMETRIC-FALLBACK、SOURCE-BIOMETRIC-ENROLLMENT、 SOURCE-WEAK-TLS-VERSION、IOS-ATS-BYPASS-API、ANDROID-NSC-USER-CA、 ANDROID-DEEPLINK-AUTOVERIFY、AST-INTENT-REDIRECTION、 AST-IMPLICIT-INTENT、IOS-WEBVIEW-FILE-ACCESS、 WEBVIEW-SAFE-BROWSING-OFF、IOS-UIWEBVIEW、AST-PATH-TRAVERSAL 和 IOS-INSECURE-UNARCHIVE。默认情况下，候选项不会触发门禁。新的经配置确认的发现项（ANDROID-NSC-USER-CA，以及来自网络安全配置的 ANDROID-CLEARTEXT）会计入默认的 allowed_statuses，但默认关闭中危和低危阈值。会对候选项或中低危发现项设置门禁的策略，以及 only_new 基线，都将纳入这些发现项。
• MASWE 矩阵有所变化：MASWE-0003、0013、0020、0021 和 0022 不再标记为未评估（对于 APK 和 IPA，它们属于未运行，因为这些源代码检查不会读取这些文件）；ANDROID-NSC-CONFIG 则为 MASWE-0026 和 0027 增加了覆盖范围。
• 现有规则的检测范围扩大：AST-CRYPTO-ECB 也会报告裸 "AES" 转换（其标题现为“选择了 ECB 模式的 AES”；指纹保持不变）；AST-CRYPTO-WEAK-HASH 会报告 CryptoKit 的 Insecure.MD5 和 Insecure.SHA1；AST-SQL-CONCAT 会读取 SQLiteQueryBuilder.query、groupBy/having/orderBy/limit 参数以及嵌套的导出型 Provider；SOURCE-INSECURE-RANDOM 会在 Swift 和 Objective-C 上运行（在仅包含 iOS 的目录中，其覆盖状态会从不适用变为已检查）。
• AST 引擎现在会跟踪 Kotlin 的 let、also、use、apply、run 和 with Lambda，因此每条结构规则都能报告其中的代码。?.let Lambda 或包含 return@ 的 Lambda，会按可能不运行的分支进行合并；现在，在一定会运行的 Lambda 中重新赋值，也可能消除一项 1.4 发现。其他 Lambda 和 Swift 闭包仍不会被分析。
• ANDROID-CLEARTEXT 也会从引用的网络安全配置中检测（经配置确认，因此代码扫描会对其评级）。如果已解析该配置、minSdk 为 24 或更高，且配置声明了 cleartextTrafficPermitted，或者 targetSdk 为 28 或更高，则会删除清单中的 usesCleartextTraffic 候选项。由多个源集定义的配置所产生的发现项属于候选项。
• 新的覆盖状态可能导致审计不完整：如果被引用的配置无法解析、不在扫描源中，或是构建占位符，ANDROID-NSC-USER-CA 和 ANDROID-NSC-CONFIG 就会标记为部分覆盖；达到匹配数量上限而停止的检查也会报告部分覆盖。使用默认的 fail_on_partial 时，此类扫描会导致门禁失败，且无法导出为基线。已编译的 AAB 配置属于未运行。
• 文本规则不再将软件包中的二进制 XML 计为已检查，因此 APK 上的 WEBVIEW-SAFE-BROWSING-OFF 状态为未运行。规则资源可以包含 case_sensitive 和 once_per_file；清单新增了 deep_links[].browsable 和 network_security_parsed。未修改的 1.4 技能可通过 apsa skill install 升级；MCP 工具清单哈希保持不变。

从 1.5.0 升级。 1.5.1 会对大型源代码树执行部分审计，而不是拒绝审计，并修复了 Android 翻译导致的性能变慢问题。

• 超出文本暂存预算（64 MiB、12,000 个文件）的源代码树不再因输入预算错误而失败（退出码 1）。文件按类型暂存：应用代码和配置、其他随附文本、本地化或限定的 Android res/values-* 文件，然后是测试。inventory.input_snapshot.omitted 会统计未纳入的内容，审计结果为不完整（退出码 3）。使用默认值 fail_on_partial 时，门禁仍会失败，部分报告也不能成为基线。100,000 个条目和 64 层的预算也会停止读取，而不是直接拒绝。
• 如果应用代码、配置或其他随附文本被遗漏（app_scope_complete: false），不适用覆盖率也会变为部分覆盖率，且 DEPENDENCY-CVE 会增加一条部分记录（除非 --sbom 提供依赖项），因此即使 fail_on_partial = false，必需规则也无法通过。
• 此类审计生成的 SARIF 会包含警告通知和 run.properties.inputSnapshot。在 1.5.0 中会失败的工作流，现在设置 fail-on-incomplete: "false" 后，会显示警告并上传部分结果；代码扫描不会显示遗漏文件的结果。若要获得完整结果，请缩小 path 的扫描范围（每个任务扫描一个模块，并使用各自的 category）。MCP 报告上下文会新增 input.input_snapshot。
• 在 1.5.0 中，含有大量转义撇号（\'）的 strings.xml 文件（法语和意大利语翻译中很常见）会导致 WEBVIEW-SAFE-BROWSING-OFF 运行缓慢，进而触发解析器超时（一个 694 KiB 文件约需 150 s）。现在 XML 文件只会清理 `` 注释，因此 XML 文本中的 // 不再会隐藏匹配项。对于未终止的字符串和注释，注释清理现在也能保持线性复杂度；如果 /* 后没有闭合的 */，就会将其作为文本读取。
• 未修改的 1.5.0 技能可通过 apsa skill install 升级；MCP 工具清单哈希保持不变。

检查内容

区域	可用检查
源代码	Java/Kotlin/Swift AST 分析；范围受限的 Objective-C .m 候选文件；WebView 和深层链接模式；Manifest、Info.plist、存储和依赖检查，包括 Gradle catalog 用法和应用锁定文件；导出的组件、备份和 targetSdk；针对隐私清单检查 Apple 要求说明原因的 API；已知凭据格式（掩码处理）；用于安全值的弱随机数；可变的隐式 PendingIntents；信任所有证书的 TrustManagers 和主机名验证器、未经评估的 iOS 服务器信任以及弱化的 ATS 例外域；外部存储写入；Java 反序列化；（1.5）有缺陷的密码、常量密钥和 IV、较短的 RSA 密钥、生物识别绑定和回退、TLS 版本、ATS 之外的 iOS API、网络安全配置、App Links、Intent 重定向和隐式 Intents、路径遍历、带密钥的解档、Safe Browsing、UIWebView 和 WKWebView 文件访问
Android 构建	DEX 调用和常量流；AAB 基础模块和功能模块的清单及模块 DEX（始终为部分检查）；资源和网络配置；导出的组件/提供程序；签名块和 v1 证书证据；ELF 加固
iOS 构建	Mach-O 标头，包括嵌入式框架/扩展元数据；CodeDirectory 页面和权利哈希完整性（不验证签名真实性）；有限的权利/配置检查（嵌入式 XML 权利、ATS 例外、配置描述文件指标）；PIE、canary 和字符串证据
公开情报	Apple/Android 公告（含范围受限的 Android 公告回溯）、CVE、CISA KEV、OWASP 指南和 OSV 依赖关联
报告和 CI	SQLite 历史记录、比较和重新评估、JSON/Markdown/SARIF 导出、覆盖率要求和过期豁免
运行时	为自有 Android 测试应用和 iOS 模拟器应用准备的场景；不支持实体 iOS 设备
模型集成	stdio MCP 工具/资源和打包技能，无需指定模型提供商或 LLM API 密钥

发现项会区分 candidate、configuration-confirmed、version-affected 和 runtime-confirmed 证据。coverage 和警告会显示实际运行的检查。签名块不能证明签名真实有效，受影响的依赖版本也不能证明其可被利用。扫描未发现问题，并不代表整个应用是安全的。

OWASP 映射描述了相关检查；APSA 不会认证 MASVS 合规性，也不会实现每项 MASTG 测试。公开公告无法揭示尚未披露的零日漏洞。仅凭应用文件无法确定设备的 OS 补丁状态。有关已测试的范围和限制，请参阅 OWASP 覆盖范围和支持矩阵；两者目前均为韩语。

安装和运行

在 macOS 或 Linux 上安装 uv。APSA 面向 CPython 3.11 和 3.12；并非所有主机 / Python 组合都经过测试（参见支持矩阵）。示例选择 Python 3.12，必要时 uv 可以下载该版本。初次安装可能需要联网；之后扫描可使用本地输入和缓存的情报。

从 PyPI 安装已发布的软件包：

uv tool install --python 3.12 apsa==1.6.2
apsa --version
apsa doctor --json
apsa demo --out ./apsa-demo

该软件包提供 apsa 以及兼容别名 quaygate 和 mobile-audit。如果找不到该命令，请运行 uv tool update-shell 并打开新的终端。GitHub Releases 提供 wheel、源代码分发包、校验和，以及包含锁定的依赖项、归属信息和构建清单的已验证捆绑包。

如需开发或使用仓库锁定的依赖项进行安装，请使用一个检出副本：

git clone https://github.com/ictechgy/apsa.git
cd apsa
uv sync --locked --python 3.12
uv run --locked apsa doctor --json
uv run --locked apsa demo --out ./apsa-demo

doctor 会检查解析器、可选设备工具和离线就绪情况。demo 会写入一个故意包含漏洞的示例并对其进行扫描；请选择一个新的输出目录。

如需将检出副本中的命令注册到 PATH：

uv tool install --editable . --force --python 3.12 --constraints requirements-release.txt
apsa --version

这会注册 apsa 及兼容别名 quaygate 和 mobile-audit。--force 会替换具有这些命令名称的现有工具。可编辑安装依赖于此检出副本；请勿移动或删除它。如果找不到该命令，请运行 uv tool update-shell 并打开新的终端。以下示例假设 apsa 位于 PATH 中。如果没有全局安装，请在检出副本中为这些命令添加前缀 uv run --locked。

apsa scan /path/to/owned/mobile-project
apsa scan /path/to/owned/app.apk
apsa scan /path/to/owned/app.ipa --sbom /path/to/build.cdx.json
apsa tui

使用来自实际构建的 CycloneDX JSON SBOM，以改进依赖项关联。tui 或不带参数运行 apsa，会打开终端界面。运行 apsa COMMAND --help 查看选项。

公共情报与网络使用

默认情况下，scan 会读取本地文件和缓存的情报，不会上传源代码或构建产物。收集公共信息源和查询 OSV 会使用网络：

命令	网络行为
apsa scan TARGET	使用本地输入和缓存的情报
apsa intel sync	获取公共漏洞信息源
apsa intel watch	轮询公共信息源并重新评估已保存的清单；不会重新读取应用文件，也不会隐式查询 OSV
apsa intel backfill --source android --since YYYY-MM	获取明确指定且范围有限的 Android 月度安全公告
apsa scan TARGET --online	将符合条件的依赖项名称和版本发送给 OSV；默认的 auto 模式会对至多 100 个符合条件的唯一坐标使用 legacy 模式，对超过 100 个使用 batch 模式，默认预算为 1000 个软件包。Scan 支持显式模式和下文的本地排除标志
apsa intel watch --online	每次轮询时，使用 auto 模式和默认预算，将每份已保存清单中的依赖项名称和版本发送出去；不支持模式或排除标志，也不会继承 scan 的排除项

apsa intel sync
apsa intel status
apsa intel watch --interval 900
apsa scan /path/to/owned/app --online
apsa scan /path/to/owned/app --online --osv-query-mode legacy
apsa scan /path/to/owned/app --online --osv-exclude-coordinate 'Maven:com.private:*'

Scan 支持可重复使用的 --osv-exclude-ecosystem、--osv-exclude-name 和 --osv-exclude-coordinate 标志。匹配模式区分大小写，并使用 shell 通配符；坐标 采用 ecosystem:name 格式。MCP dependency_check 接受 query_mode 以及对应的 exclude_ecosystems、exclude_names、exclude_coordinates 列表。排除项会在本地 应用后再传输，且不会被计为已从旧缓存中检查。每次 MCP 调用只使用该次调用提供的列表； 报告中记录的 scan 排除项不会被继承。每次调用 dependency_check 时都要传入所需的排除项。 SwiftURL 名称和坐标排除项会同时匹配存储的仓库名称 和规范化后的 OSV 传输名称（例如 github.com/owner/repo）。 启用此类策略时，不支持的仓库标识不会被传输。 需要排除策略时，请使用 scan 或 MCP：intel watch --online 既不接受这些控制项， 也不会沿用 scan 的排除项。不会向 OSV 发送源代码或构建产物。请求预算统计的是 OSV 操作， 包括分页和记录查找，而不是单独的 HTTP 重定向跳转次数。

Watch 默认每 900 秒轮询一次，最短间隔为 60 秒；它不是推送流。除非使用 --cycles 设置有限的轮询次数，否则它会一直运行，直到被中断。如果发现项、覆盖范围或情报状态发生变化，重新评估会保存新的快照。使用 intel status 检查信息源的新鲜度、失败情况和待处理的 CVE 处理任务。获取 CVE 文档和完成其处理是两个不同的状态。默认待处理项策略不允许积压；使用 intel_max_pending 设置明确的上限。

apsa reports reassess latest
apsa reports compare audit_BEFORE audit_AFTER
apsa reports export latest --format sarif --out audit.sarif
apsa reports verify

重新评估会将当前情报应用于已保存的清单；如文件有变更或需要运行新的静态检查，请再次运行 scan。如果已连接 AI 客户端，该客户端可能会将报告元数据发送给其模型提供方。APSA 的 MCP 上下文不包含源代码摘录、完整源文件或截图字节；客户端侧的数据处理方式仍取决于客户端。

CI 和后台作业

apsa policy init --out apsa.toml
apsa scan /path/to/owned/app --policy apsa.toml --out audit.json
apsa scan /path/to/owned/app --fail-on high --include-candidates
apsa scan /path/to/owned/app --background --json
apsa jobs status JOB_ID --json

默认情况下，严重性门槛会排除 candidate 发现项。使用 --include-candidates 或策略的 allowed_statuses 可选择将其纳入。必需规则仅接受覆盖状态为 checked 或 not-applicable；部分执行和缺少必需检查均不算通过。豁免项必须包含发现项 ID、原因和到期日期。后台作业的状态为 completed 表示作业已结束；在将审计视为完成前，请检查其 audit_incomplete 标志和报告。

无法读取的源目录和文件会产生警告并导致覆盖不完整；如果源树中没有可读取的受支持文件，则会明确失败。源树超过文本暂存预算（64 MiB、12,000 个文件）时，会执行部分审计，而不是拒绝审计。文件按以下顺序分类暂存：应用代码和配置（先配置，再应用代码，然后是头文件和第三方代码，例如 .build/ 或 vendor/）、其他随应用分发的文本（基础资源、JSON、YAML）、本地化或限定的 Android res/values-* 文件，然后是测试。inventory.input_snapshot.omitted 会按类型统计未纳入的文件数和字节数（code_and_config、other_text、localized_values、tests），包括超过 8 MiB 单文件限制的文件，以及无法读取或暂存的文件。无法读取的目录，以及超出整棵目录树预算的目录（按名称顺序读取，最多 100,000 个条目或 64 层）则会作为警告报告。如果应用代码、配置或其他随应用分发的文本未纳入，app_scope_complete 将为 false，not-applicable 覆盖也会变为部分覆盖。要完成完整审计，请扫描更小范围的文件夹，例如应用模块。存储捕获失败时状态仍为 not-run，无法证明金丝雀已删除。

退出代码	统一 CLI 中的含义
0	命令已完成或策略已通过
1	执行错误
2	参数无效
3	审计或策略不完整、报告验证失败，或情报同步失败或不完整
4	发现项超出配置的 CI 阈值
130	已中断

--json 会输出一个包含 ok、data 或 error，以及 exit_code 的封装对象；watch 每个周期会输出一个 JSON 封装对象（NDJSON）。代码为 0 和 4 时，ok 为 true；代码 4 表示评估成功，但超出了 CI 阈值。CI 必须检查 exit_code 和策略结果。代码为 3 和 4 时仍可能生成报告。

GitHub 代码扫描

permissions:
  contents: read
  security-events: write
  actions: read            # private repositories: lets the upload read the workflow run
steps:
  - uses: actions/checkout@v7
    with:
      persist-credentials: false
  - uses: ictechgy/apsa@<commit-sha> # v1.6.2; pin the full commit SHA
    with:
      path: android            # source folder, or a built APK/AAB/IPA in the workspace
      fail-on-incomplete: "true"

该操作会从 PyPI 安装与发布版本匹配的 apsa，并使用发布版本中由哈希锁定的依赖项；随后运行 scan，并指定 --format sarif --sarif-root，写入作业摘要，将 SARIF 文件上传到代码扫描，然后应用扫描结果。即使审计同时不完整，策略失败或触发 fail-on 阈值也会导致作业失败（退出代码 3 可能掩盖阈值失败，因此该操作会读取报告，而不只依赖退出代码）。使用策略时，每项未满足的策略条件（必需规则、必需情报、已过期的豁免项、基线检查）都会导致作业失败；只有部分审计由 fail-on-incomplete 处理，除非将其设为 "false"，否则退出代码为 3 时会导致作业失败。团队门槛请使用 policy（搭配 baseline-file 和 baseline-sha256）；若要设置排除候选项的严重性阈值，请使用 fail-on。

默认情况下，该操作处于离线状态：不会进行 CVE 或依赖项公告关联分析，依赖项发现需要 intel-sync（先获取公开公告；部分同步会产生警告）和 online（将依赖项名称和版本发送到 OSV，参见网络使用）。私有仓库需要 GitHub Code Security 才能上传 SARIF；设置 upload-sarif: "false" 即可仅保留文件。来自 fork 的拉取请求和每个由 Dependabot 触发的运行都会获得只读令牌，因此该操作会跳过上传，但仍会写入文件和摘要。 每个警报的指纹都是 APSA 发现项的身份标识：规则加上证据位置（文件、行、函数或归档成员）。因此，编辑被标记的行或移动文件，都可能关闭一个警报并触发另一个警报。候选发现项会以 warning 级别上传，并标记为 candidate；若某条规则的结果全是候选项，则不会设置 security-severity，因此不会触发代码扫描对 High 或 Critical 警报的默认检查。规则若有已确认的结果，其 security-severity 将根据这些结果确定，候选警报也会沿用该评级。代码扫描按 category 跟踪警报（默认为 apsa）；如果你之前曾用其他类别上传 APSA SARIF，请保留该值，因为新类别会创建新的警报，并使旧类别的警报保持打开状态，直到你删除其分析记录。如果你的计划支持，GitHub 可能会针对第三方警报提供 Copilot Autofix 建议；这尚未在 APSA 警报上经过测试，且 APSA 的证据状态会保留在每个警报的属性中。

不使用该 Action 时：

apsa scan android --format sarif --out apsa.sarif --sarif-root android
apsa reports export latest --format maswe --out maswe.json
apsa reports export latest --format cyclonedx --out apsa.cdx.json

reports ingest REPORT --sarif FILE --tool NAME（MCP reports_ingest_sarif）会将其他工具的 SARIF 2.1.0 结果（例如 Android Lint、CodeQL 或 Semgrep）导入为新报告。导入的结果仍为候选项，带有 origin: external，不会增加 APSA 覆盖率，并会与同一位置的相关弱点的 APSA 发现项建立交叉链接。其文本会经过清理，并按不可信内容处理。

--format checklist --checklist masvs-v2（或将自定义检查项映射到 MASWE 标识符和 APSA 规则的 TOML 文件）会按检查项列出相关检查的状态和发现项；状态绝不会声称某项检查已通过。reports history TARGET 会列出每个发现项首次和最近一次被观察到的时间，以及后续报告不再观察到该发现项的时间，作为检查和修复记录。参见将 APSA 用于韩国检查标准（韩语）。

--format cyclonedx 会生成 CycloneDX 1.6 SBOM，其中包含 APSA 发现的依赖项、包 URL 及各版本背后的证据，并将 APSA 的依赖项匹配结果作为 VEX 条目嵌入其中。每个条目都包含证据状态、CISA KEV 标记，以及 APSA 首次在该目标中观察到此项的时间，有助于管理欧盟《网络弹性法案》等法规规定的漏洞处理时限。每项分析状态均为 in_triage：APSA 绝不会将漏洞标记为 not_affected；请自行记录该决定并附上理由。此 SBOM 并非完整的构建清单，也不会使应用符合任何法规。

有关策略、备份、限制和故障排除，请参阅 CI 示例和运维指南（韩语）。

MCP 和技能

apsa integrations --root /absolute/path/to/owned-apps
apsa mcp --root /absolute/path/to/owned-apps
apsa skill install
apsa context --report latest --section findings --limit 20 --json

使用 integrations 生成包含已安装可执行文件路径的配置；如果未找到 apsa 可执行文件，则使用 python -m apsa 作为备用方案。以下配置仅供示例；请替换两个绝对路径：

{
  "mcpServers": {
    "apsa": {
      "command": "/absolute/path/to/apsa",
      "args": ["mcp", "--root", "/absolute/path/to/owned-apps"]
    }
  }
}

为 Agent 安装

客户端	安装
Claude Code	运行 /plugin marketplace add ictechgy/apsa，然后运行 /plugin install apsa@apsa。该插件会运行 uvx --python 3.12 apsa@VERSION mcp --root <current project> 并添加技能。
任意 MCP 客户端	使用 apsa integrations 生成的配置，或使用 MCP Registry 条目 io.github.ictechgy/apsa（PyPI 包、uvx，必需参数为 --root）。
Codex 和其他技能运行时	运行 apsa skill install，并添加 integrations 配置。
在 1.4 开发期间，已验证 Claude Code 2.1.295（从检出目录加载插件，并通过
--plugin-dir 指定，根目录为 ${CLAUDE_PROJECT_DIR}）和 Codex CLI 0.162.0 均针对全新生成的合成项目上的该历史本地构建调用了 capabilities 和 audit_scan。这些并非 1.6 客户端检查。软件包发布后才会检查 Marketplace 和 MCP Registry 安装。其他客户端尚未验证。

MCP 使用 stdio，并且必须显式指定 --root；有多个根目录时需重复指定。未提供根目录时，integrations 默认使用当前目录。根目录会限制受审计的目标，以及对其报告和任务的访问。--allow-any-root 会明确移除此限制。APSA 不会自动更改模型客户端配置；客户端身份验证由客户端负责。

用途	MCP 工具
审计	capabilities、audit_scan、audit_start、audit_reassess、verify_finding、specs_validate
任务	jobs_list、jobs_status、jobs_cancel
报告	reports_list、reports_get、reports_compare、reports_export_baseline、reports_ingest_sarif、reports_checklist、reports_history
威胁情报	intelligence_sync、intelligence_search、intelligence_get、dependency_check
策略	policy_evaluate
运行时规划	runtime_plan、runtime_devices

verify_finding（CLI apsa verify）会将其他工具或 AI 审查者提出的发现与 APSA 的证据进行交叉核查，且绝不会予以反驳。项目污点规范会指定项目特定的源和汇，例如深层链接解析器或应用内浏览器封装器，供 APSA 确定性地追踪；请参阅项目规范。

精确的规则声明会匹配相应规则；MASWE 声明可以使用相关检查。目前，通过显式检查映射，精确的 CWE 印证支持 CWE-22、CWE-89、CWE-295 和 CWE-502。其他 CWE 声明会返回 not-assessed；仅有宽泛的 MASWE 重叠不足以印证这些声明。若同时提供规则和弱点，两者都必须匹配。已检查和未执行的覆盖范围并存时，状态为 partial。

capabilities 会报告 tool_manifest_sha256，这是 APSA 自有工具接口（名称、描述、注释提示和参数形状）的哈希；工具集在单个进程内不会变化。请将根据 tools/list 计算出的哈希与已发布的值进行比较，而不要盲信服务自身的报告。只读工具会标注为只读且幂等，网络工具则标注为开放世界。应用内容和安全公告文本均视为不可信数据，模型上下文中不包含源代码摘录；请参阅 MCP 安全模型。

资源包括 apsa://rules 和 apsa://reports/{report_id}。之前的 quaygate:// 和 mobile-audit:// 资源方案仍保持兼容。

报告上下文默认限制为 20 条记录和 64 KiB。解析一次 latest，然后使用返回的不可变报告 ID 和 page.next_cursor 翻页，并保持分区和筛选条件不变。partial_response 描述当前页；audit_incomplete 描述执行情况。超出大小限制的记录会被明确省略，但仍可通过本地导出获取。可移植基线必须具有明确的批准来源记录，并在经过审查的 CI 配置中固定 SHA-256。请参阅工作流示例。

默认服务会公开运行时规划功能。只有在服务启动时指定 --allow-runtime，才会注册 runtime_execute 和 runtime_start。两者默认都会预览场景；设置 execute=true 才会运行场景。runtime_start 会启动可取消的后台设备任务。运行时测试需要经过授权且已准备好的测试应用；默认审计不会启动设备或安装应用。运行场景前，请参阅运维指南（韩语）。 skill install 会将打包好的 APSA 技能复制到 ~/.codex/skills/apsa。若要直接安装到其他模型运行时的技能目录：

apsa skill install --name apsa --dest /path/to/runtime/skills/apsa

使用 --name quaygate 或 --name mobile-audit，可更新以旧默认名称安装的技能；除非指定 --force，否则会保留自定义修改。integrations 会报告技能状态。对于不支持 MCP 的客户端，context 会提供报告上下文，但不包含源代码摘录、完整源文件和截图字节。

兼容性与存储的数据

quaygate 和 mobile-audit 调用的是同一个统一 CLI。Python 入口 python -m apsa、python -m quaygate 和 python -m mobile_audit 仍然可用。现有报告和 QG-* 规则 ID 保持不变。

数据默认存储在 ~/.local/share/mobile-audit。路径优先级为 --home → APSA_HOME → QUAYGATE_HOME → MOBILE_AUDIT_HOME → 默认路径。重命名不会复制数据库或迁移历史记录。现有 MCP 配置必须包含已授权的 --root。

旧版 apk、ipa 和 device 子命令仍会输出快速检查结果，并使用退出码 0/1/2；它们不会保存统一审计历史记录，也不会关联漏洞情报。要运行完整工作流，请使用 scan。对于缺少严重性信息的旧版缓存 OSV 记录，需要重新运行 scan --online 或 intel watch --online；仅重新评估无法恢复缺失的评分。

开发、验证与许可

uv sync --locked --extra dev --python 3.12
make test benchmark
make export-release
make release RELEASE_OUT=dist/apsa-local-release

选择一个新的或空的发布目录。发布验证需要 uv 0.12.1，并会两次构建 wheel/sdist、比较其哈希值，还会在检出目录之外进行干净安装，并执行离线源码/APK 扫描、MCP 和技能安装检查。它会生成哈希值、SBOM、依赖项声明和发布清单，但不会发布内容。初始依赖项准备可以联网进行。同一主机上的重复检查不表示不同平台上的构建结果逐字节相同。

带标签的发布会在受支持的 CI 矩阵通过后，使用 GitHub Actions 将已验证的发行包发布到 PyPI。有关工作流和下载内容，请参阅发布流程。

已记录的产品验证见 RELEASE_READINESS.md。精选基准测试是回归语料库，并非生产环境检测率的衡量标准。集成边界和威胁模型目前为韩文。历史评审仍对应其原始快照。

可复现的 APSA/MobSF 对比及其 记录结果使用新生成的 合成源码项目和 APK。它们衡量的是 APSA 1.2.0 发布前记录的开发候选版本， 而非已发布的软件包；这些结果并非生产环境准确率估算值。使用 APSA 1.3.0 发布版运行时和新生成的输入重新运行后，重现了候选版本的数据（参见 RELEASE_READINESS.md）。

单独的公开源码与 CVE 评估记录了 六个固定版本的应用源码快照、选定的依赖项/CVE 单元和 OS 公告样例 的初始结果。评估保留了提取缺口、 扫描器故障和覆盖不完整的情况；它不衡量整个应用的安全性或一般生产环境准确率。

后续的加固后重跑完成了全部 六项源码扫描，并弥补了四个已测得的集成缺口。它沿用了观察到的标签， 并报告了仍未覆盖的部分；这是一项开发检查。

覆盖扩展记录了有限的 Swift/Kotlin 兼容性、已识别的函数数量，以及有 Apple 证据支持的 iOS/iPadOS 分支决策。改编后的源码仍不完整；所选样例无法证明一般性的 CVE 准确率。

补充分析与独立留出集 涵盖 AAB/IPA 元数据、Objective-C、解析器隔离和两个由独立人员标注的公开源码项目。 它分别记录了选定 CVE 边界的一致性、尚未解决的目录使用情况和仍存在的解析器缺口。

依赖项证据评估比较了 APSA 的 Gradle 目录用法和锁文件坐标与 Gradle 自身解析结果在三个冻结的公开应用留出集上的差异， 并将首次盲测结果与查看真实情况后的重跑结果分开记录。独立源码对 根据扫描前冻结的真实情况，对公开项目中存在漏洞和已修复的提交进行评分。 盲测 MASWE 标注对衡量了在由弱点标注的新留出集上的 1.5， 而 OWASP MASTG 演示则是开发基准测试。所有这些都是范围有限的样本，并非一般准确率估算值。

源码已在 GitHub 上公开。LICENSE保留了原始 Quaygate MIT 声明。本次发布未为组合产品声明额外许可。