apk-docforge

apk-docforge는 Android APK 아티팩트를 문서화하고 감사하기 위한 로컬 우선(local-first) Python 툴킷입니다. 결정적 정적 분석, 승인된 ADB 기기에서의 선택적 통제된 런타임 관찰, 출처 추적 다운로드, FastAPI 웹 인터페이스, 그리고 MCP stdio 서버를 결합합니다.

소유한 애플리케이션, 평가 권한이 있는 애플리케이션, 또는 라이선스에 따라 검사가 허용된 애플리케이션에만 사용하십시오. 이 프로젝트는 인증, 결제, DRM, 인증서 고정, 라이선싱 또는 변조 방지 제어를 우회하지 않습니다.

주요 기능

• 격리 및 SHA-256 출처 추적을 포함한 APK, APKS, XAPK 수집.

• 패키지 구조, 매니페스트 데이터, 권한, 리소스, 화면, 네트워크 신호, SDK, 기능, 보안 발견 사항의 정적 매핑.

• 증거 참조와 명시적 observed, inferred, unknown 상태.

• F-Droid 및 GitHub Releases 검색 어댑터, 정확한 호스트 허용 목록 기반 공식 URL.

• 명시적으로 선택된 ADB 기기에서의 통제된 동적 분석, 비파괴적 탐색 및 민감한 흐름 차단.

• 로컬 웹 UI, JSON API, MCP 호환 stdio 도구.

• 선택적 제한된 DeepSeek 부록이 포함된 결정적 Markdown 출력.

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 아래에 health, upload, search, download, analysis, report, findings, features, screens, sources 및 settings 엔드포인트가 포함됩니다. 대화형 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에서 동일한 린트, 포맷, 테스트 게이트를 실행합니다.

현재 제한 사항

• 정적 분석 깊이는 apkanalyzer, jadx, apktool과 같은 선택적 Android 도구에 따라 달라집니다.

• 동적 모드는 선택된 하나의 기본 APK만 설치합니다. 분할 패키지 설치는 구현되지 않았습니다.

• 런타임 탐색은 자격 증명 입력, 로그인, 결제, 게시, 공유, 삭제, 구독 또는 로그아웃 흐름에 절대 진입하지 않습니다.

• 트래픽 가로채기 및 Frida 기반 계측은 의도적으로 포함되지 않습니다.

• 원격 바인딩이 지원되지 않으므로 API에는 원격 인증이 없습니다.