apk-docforge

apk-docforge — это локальный Python-инструментарий для документирования и аудита артефактов Android APK. Он сочетает детерминированный статический анализ, необязательное контролируемое наблюдение за выполнением на авторизованном ADB-устройстве, загрузку с учётом происхождения, веб-интерфейс FastAPI и MCP-сервер stdio.

Используйте его только с приложениями, которыми вы владеете, которые уполномочены оценивать или можете проверять в соответствии с их лицензией. Проект не обходит аутентификацию, платежи, DRM, сертификатный пиннинг, лицензирование или защиту от взлома.

Возможности

• Приём APK, APKS и XAPK с карантином и SHA-256-происхождением.

• Статическое сопоставление структуры пакета, данных манифеста, разрешений, ресурсов, экранов, сетевых сигналов, SDK, функций и результатов проверки безопасности.

• Ссылки на доказательства, а также явные статусы observed, inferred и unknown.

• Поисковые адаптеры для F-Droid и GitHub Releases, а также официальные URL-адреса из белого списка с точным совпадением хоста.

• Контролируемый динамический анализ на явно выбранном ADB-устройстве с неразрушающей навигацией и блокировкой чувствительных потоков.

• Локальный веб-интерфейс, 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-клиентов, чей сокетный адрес не является loopback.

• Доверенные хосты — ровно 127.0.0.1 и localhost.

• Кросс-ориджин доступ браузера ограничен настроенными loopback-ориджинами.

• Тела загрузок ограничены до и во время multipart-разбора.

• Загрузки проверяют Content-Length, применяют потоковый лимит байт и повторно проверяют каждый редирект и конечный URL на соответствие политике источника.

• Вложенные артефакты, распаковка архивов и чтение манифестов имеют независимые лимиты.

• Настройки записываются атомарно в обычный файл .env с режимом 0600.

Лимиты по умолчанию консервативны и настраиваются через переменные окружения:

Скопируйте .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 и выводит числовой ID, принимаемый командой download.

Политика загрузки

• Загрузки F-Droid остаются на одобренном хосте F-Droid.

• Ресурсы релизов GitHub остаются на одобренных хостах ресурсов GitHub.

• Официальные URL-адреса требуют HTTPS и точного DNS-хоста в APK_DOCFORGE_OFFICIAL_URL_ALLOWLIST; IP-литералы отклоняются.

• Адресаты редиректов и конечный URL ответа оцениваются по той же политике до принятия их тел ответа.

• Сторонние зеркала APK и скрейпинг Google Play остаются отключёнными.

Адаптер Google Play Developer — это только зарезервированная точка интеграции; в настоящее время он не ищет и не загружает артефакты, даже если настроен путь к учётным данным.

Необязательная документация DeepSeek

Задайте ключ, только если хотите необязательное дополнение к документации:

export APK_DOCFORGE_DOCUMENTATION_PROVIDER=deepseek
export DEEPSEEK_API_KEY=...

APK-бинарники и полный декомпилированный исходный код не отправляются. Провайдер получает ограниченные JSON-сводки и ссылки на доказательства. Без ключа детерминированный локальный отчёт остаётся доступным.

API и MCP

Локальный API включает конечные точки health, upload, search, download, analysis, report, findings, features, screens, sources и settings в разделе /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 привязываются только к loopback и отключены, если не выбран их профиль. 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.

Текущие ограничения

• Глубина статического анализа зависит от необязательных инструментов Android, таких как apkanalyzer, jadx и apktool.

• Динамический режим устанавливает один выбранный основной APK; установка раздельных пакетов не реализована.

• Навигация во время выполнения никогда не вводит учётные данные и не запускает потоки входа, оплаты, публикации, публикации, обмена, удаления, подписки или выхода.

• Перехват трафика и инструментирование на основе Frida намеренно отсутствуют.

• API не имеет удалённой аутентификации, поскольку удалённая привязка не поддерживается.