apk-docforge

apk-docforge は、Android APK アーティファクトの文書化と監査のためのローカルファーストの Python ツールキットです。決定的な静的解析、承認された ADB デバイス上でのオプションの制御されたランタイム観測、来歴を認識したダウンロード、FastAPI Web インターフェース、MCP stdio サーバーを組み合わせています。

所有しているアプリケーション、評価を許可されているアプリケーション、またはそのライセンスに基づいて検査が許可されているアプリケーションにのみ使用してください。このプロジェクトは、認証、支払い、DRM、証明書ピンニング、ライセンス、または改ざん防止コントロールをバイパスしません。

ハイライト

• 検疫と SHA-256 来歴を備えた APK、APKS、XAPK の取り込み。

• パッケージ構造、マニフェストデータ、権限、リソース、画面、ネットワークシグナル、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 です。

• ブラウザのクロスオリジンアクセスは、設定されたループバックオリジンに制限されます。

• アップロード本文は、マルチパート解析の前と最中にサイズ制限されます。

• ダウンロードは 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、フォーマット、テストゲートを実行します。

現在の制限事項

• 静的深度は、apkanalyzer、jadx、apktool などのオプションの Android ツールに依存します。

• 動的モードは選択された 1 つのプライマリ APK をインストールします。分割パッケージのインストールは実装されていません。

• ランタイムナビゲーションは、資格情報を入力したり、ログイン、支払い、公開、共有、削除、サブスクリプション、ログアウトのフローをトリガーしたりすることはありません。

• トラフィック傍受と Frida ベースの計測は意図的に含まれていません。

• リモートバインドがサポートされていないため、API にはリモート認証がありません。