apk-docforge

apk-docforge 是一个本地优先的 Python 工具包，用于记录和审计 Android APK 工件。它结合了确定性静态分析、在经授权的 ADB 设备上进行可选的可控运行时观察、具有来源感知的下载、FastAPI Web 界面以及 MCP stdio 服务器。

仅将其用于您拥有、经授权评估或根据其许可证允许检查的应用程序。该项目不会绕过身份验证、支付、DRM、证书固定、许可或防篡改控制。

亮点

• 支持 APK、APKS 和 XAPK 摄取，并带有隔离和 SHA-256 来源记录。

• 静态映射包结构、清单数据、权限、资源、屏幕、网络信号、SDK、功能和安全发现。

• 证据引用以及明确的 observed、inferred 和 unknown 状态。

• 针对 F-Droid 和 GitHub Releases 的搜索适配器，以及精确主机白名单官方 URL。

• 在明确选择的 ADB 设备上进行受控动态分析，具有非破坏性导航和被阻止的敏感流程。

• 本地 Web UI、JSON API 和兼容 MCP 的 stdio 工具。

• 确定性 Markdown 输出，附带可选的有界 DeepSeek 附录。

Related MCP server: APK Security Guard MCP Suite

快速开始

要求：Python 3.11 或更高版本以及 uv。

uv sync --locked --extra dev
uv run --locked apk-docforge serve
open http://127.0.0.1:8765/

直接运行静态分析：

uv run --locked apk-docforge analyze ./app.apk --out ./outputs/app --mode static

生成的目录包含 analysis_summary.json、report.md、codex_ingestion_prompt.md、qa_report.json 以及带版本的 JSON 证据。

安全默认值

HTTP 服务有意仅限本地：

• serve 默认绑定 127.0.0.1，并拒绝所有其他绑定地址。

• ASGI 层还会拒绝套接字地址不是回环地址的 HTTP 客户端。

• 受信任的主机恰好是 127.0.0.1 和 localhost。

• 浏览器跨源访问仅限于已配置的回环来源。

• 上传主体在 multipart 解析之前和期间都有大小限制。

• 下载会验证 Content-Length，强制执行流式字节限制，并根据来源策略重新验证每个重定向和最终 URL。

• 嵌套工件、归档解压和清单读取具有独立的限制。

• 设置以原子方式写入权限为 0600 的常规 .env 文件。

默认限制较为保守，可通过环境变量进行配置：

复制 .env.example 进行本地配置，并保持生成的文件私密：

cp .env.example .env
chmod 600 .env

有关威胁模型和漏洞报告流程，请参阅 SECURITY.md。

命令

apk-docforge analyze ./app.apk --out ./outputs/app --mode static
apk-docforge search "TeamNewPipe/NewPipe" --sources github --limit 1
apk-docforge download --candidate-id 3 --out ./downloads
apk-docforge import-device --package com.example.app --out ./downloads
apk-docforge sources
apk-docforge serve
apk-docforge mcp-server

动态分析是可选加入的，需要经授权的设备序列号：

apk-docforge analyze ./app.apk \
  --out ./outputs/app-dynamic \
  --mode dynamic \
  --device emulator-5554

search 将候选结果持久化到本地 SQLite 索引中，并打印 download 接受的数字 ID。

下载策略

• F-Droid 下载保持在经批准的 F-Droid 主机上。

• GitHub 发布资产保持在经批准的 GitHub 资产主机上。

• 官方 URL 需要 HTTPS 以及 APK_DOCFORGE_OFFICIAL_URL_ALLOWLIST 中的精确 DNS 主机；拒绝 IP 字面量。

• 在接受响应主体之前，会使用相同的策略评估重定向目标和最终响应 URL。

• 第三方 APK 镜像和 Google Play 抓取保持禁用。

Google Play Developer 适配器仅作为预留的集成点；即使配置了凭据路径，它目前也不会搜索或下载工件。

可选的 DeepSeek 文档

仅当您需要可选的文档附录时才设置密钥：

export APK_DOCFORGE_DOCUMENTATION_PROVIDER=deepseek
export DEEPSEEK_API_KEY=...

不会发送 APK 二进制文件和完整的反编译源代码。提供商只会收到有界的 JSON 摘要和证据引用。没有密钥时，确定性的本地报告仍然可用。

API 和 MCP

本地 API 在 /api 下包含健康检查、上传、搜索、下载、分析、报告、发现、功能、屏幕、来源和设置端点。交互式 OpenAPI 文档可在 http://127.0.0.1:8765/docs 获取。

MCP 冒烟测试：

printf '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}\n' \
  | uv run --locked apk-docforge mcp-server

可选容器

Docker 服务仅绑定到回环地址，除非选择了其配置文件，否则处于禁用状态。MobSF 固定到已发布的带版本镜像：

docker compose --profile mobsf up mobsf

PostgreSQL 和 Redis 是未来的集成服务；应用程序默认使用 SQLite。在启动未来配置文件之前，请设置非空密码：

export APK_DOCFORGE_POSTGRES_PASSWORD='replace-with-a-strong-secret'
docker compose --profile future up postgres redis

开发

uv sync --locked --extra dev
uv run --locked --extra dev ruff check .
uv run --locked --extra dev pytest

CI 在 Python 3.11 和 3.12 上运行相同的 lint、格式化和测试门禁。

当前限制

• 静态分析深度取决于可选的 Android 工具，例如 apkanalyzer、jadx 和 apktool。

• 动态模式仅安装一个选定的主 APK；未实现拆分包安装。

• 运行时导航永远不会进入凭据输入，也不会触发登录、支付、发布、分享、删除、订阅或退出登录流程。

• 有意不包含流量拦截和基于 Frida 的插桩。

• API 没有远程身份验证，因为不支持远程绑定。