apk-docforge

apk-docforge is a local-first Python toolkit for documenting and auditing Android APK artifacts. It combines deterministic static analysis, optional controlled runtime observation on an authorized ADB device, provenance-aware downloads, a FastAPI web interface, and an MCP stdio server.

Use it only with applications you own, are authorized to assess, or may inspect under their license. The project does not bypass authentication, payments, DRM, certificate pinning, licensing, or anti-tamper controls.

Highlights

• APK, APKS, and XAPK intake with quarantine and SHA-256 provenance.
• Static mapping of package structure, manifest data, permissions, resources, screens, network signals, SDKs, features, and security findings.
• Evidence references plus explicit observed, inferred, and unknown status.
• Search adapters for F-Droid and GitHub Releases, plus exact-host allowlisted official URLs.
• Controlled dynamic analysis on an explicitly selected ADB device, with non-destructive navigation and blocked sensitive flows.
• Local web UI, JSON API, and MCP-compatible stdio tools.
• Deterministic Markdown output with an optional bounded DeepSeek addendum.

Quick start

Requirements: Python 3.11 or newer and uv.

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

Run a static analysis directly:

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

The generated directory includes analysis_summary.json, report.md, codex_ingestion_prompt.md, qa_report.json, and versioned JSON evidence.

Security defaults

The HTTP service is intentionally local-only:

• serve defaults to 127.0.0.1 and rejects every other bind address.
• The ASGI layer also rejects HTTP clients whose socket address is not loopback.
• Trusted hosts are exactly 127.0.0.1 and localhost.
• Browser cross-origin access is limited to configured loopback origins.
• Upload bodies are bounded before and during multipart parsing.
• Downloads validate Content-Length, enforce a streaming byte limit, and revalidate every redirect and final URL against the source policy.
• Nested artifacts, archive expansion, and manifest reads have independent limits.
• Settings are written atomically to a regular .env file with mode 0600.

Default limits are conservative and configurable through environment variables:

Setting	Default
APK_DOCFORGE_MAX_UPLOAD_BYTES	256 MiB
APK_DOCFORGE_MAX_DOWNLOAD_BYTES	512 MiB
APK_DOCFORGE_MAX_NESTED_ARTIFACT_BYTES	256 MiB
APK_DOCFORGE_MAX_ARCHIVE_MEMBERS	10,000
APK_DOCFORGE_MAX_ARCHIVE_UNCOMPRESSED_BYTES	1 GiB
APK_DOCFORGE_MAX_DOWNLOAD_REDIRECTS	5

Copy .env.example for local configuration and keep the resulting file private:

cp .env.example .env
chmod 600 .env

See SECURITY.md for the threat model and vulnerability reporting process.

Commands

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

Dynamic analysis is opt-in and requires an authorized device serial:

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

search persists candidates in the local SQLite index and prints the numeric ID accepted by download.

Download policy

• F-Droid downloads stay on the approved F-Droid host.
• GitHub release assets stay on approved GitHub asset hosts.
• Official URLs require HTTPS and an exact DNS host in APK_DOCFORGE_OFFICIAL_URL_ALLOWLIST; IP literals are rejected.
• Redirect destinations and the final response URL are evaluated with the same policy before their response bodies are accepted.
• Third-party APK mirrors and Google Play scraping remain disabled.

The Google Play Developer adapter is a reserved integration point only; it does not currently search or download artifacts, even when a credentials path is configured.

Optional DeepSeek documentation

Set a key only if you want the optional documentation addendum:

export APK_DOCFORGE_DOCUMENTATION_PROVIDER=deepseek
export DEEPSEEK_API_KEY=...

APK binaries and full decompiled source are not sent. The provider receives bounded JSON summaries and evidence references. Without a key, the deterministic local report remains available.

API and MCP

The local API includes health, upload, search, download, analysis, report, findings, features, screens, sources, and settings endpoints under /api. Interactive OpenAPI documentation is available at http://127.0.0.1:8765/docs.

MCP smoke test:

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

Optional containers

Docker services bind to loopback only and are disabled unless their profile is selected. MobSF is pinned to a published versioned image:

docker compose --profile mobsf up mobsf

PostgreSQL and Redis are future integration services; the application uses SQLite by default. Set a non-empty password before starting the future profile:

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

Development

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

CI runs the same lint, formatting, and test gates on Python 3.11 and 3.12.

Current limitations

• Static depth depends on optional Android tools such as apkanalyzer, jadx, and apktool.
• Dynamic mode installs one selected primary APK; split-package installation is not implemented.
• Runtime navigation never enters credentials or triggers login, payment, publishing, sharing, deletion, subscription, or logout flows.
• Traffic interception and Frida-based instrumentation are intentionally absent.
• The API has no remote authentication because remote binding is unsupported.