# APK SDK Analyzer

Static third-party SDK detection tool for Android APK files.

[![PyPI](https://img.shields.io/pypi/v/apk-analyzer)](https://pypi.org/project/apk-analyzer/)
[![Python](https://img.shields.io/pypi/pyversions/apk-analyzer)](https://pypi.org/project/apk-analyzer/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## Features

- **Zero-dependency on decompilers** — pure Python static analysis
- **5-layer detection engine**: DEX class names · AndroidManifest components · Native `.so` libs · META-INF version files · DEX BuildConfig static fields
- **Structured output**: JSON + interactive single-file HTML report
- **Extensible signature database**: YAML files in `sdk_signatures/` — update without recompiling
- **Cross-platform**: Windows / macOS / Linux

## Installation

**Using pip:**

```bash
pip install apk-analyzer
```

**Using uv (recommended):**

```bash
# As a project dependency
uv add apk-analyzer

# As a standalone CLI tool
uv tool install apk-analyzer
```

## Usage

```bash
# Basic analysis — generates <apk>_report.json and <apk>_report.html
apk-analyzer target.apk

# Analyze specific categories only
apk-analyzer target.apk --categories push,ads,analytics

# Custom output paths
apk-analyzer target.apk --output-json report.json --output-html report.html

# JSON output only
apk-analyzer target.apk --format json

# Verbose mode
apk-analyzer target.apk --verbose

# Use a custom signatures directory
apk-analyzer target.apk --signatures-dir ./my_signatures
```

### Output

Two files are generated next to the APK by default:

| File | Description |
|------|-------------|
| `<apk>_report.json` | Structured data — suitable for scripting and CI integration |
| `<apk>_report.html` | Interactive single-file report — open in any browser |

## Detection Methods

| Layer | Method | Coverage |
|-------|--------|----------|
| L1 | DEX class name prefix matching | ~90% of SDKs |
| L2 | AndroidManifest service/receiver/activity | Confirms presence |
| L3 | Native `.so` library names | Native SDKs |
| L4 | META-INF `.version` files | AndroidX / Google libs |
| L5 | DEX `BuildConfig.VERSION_NAME` static fields | Exact versions |

## Output JSON Structure

```json
{
  "meta": { "tool_version": "1.5.0", "analysis_time": "...", "analysis_duration_seconds": 0.33 },
  "apk_info": { "package_name": "com.example.app", "version_name": "1.2.3", "min_sdk": 21, ... },
  "detected_sdks": [
    {
      "id": "xiaomi_mipush",
      "name": "小米推送 MiPush",
      "version": "5.9.6",
      "confidence": "high",
      "detection_evidence": { "matched_packages": ["com.xiaomi.push"], ... },
      "risk": { "privacy_risk": "low" }
    }
  ],
  "summary": { "total_detected": 12, "by_category": { "push": 3, "ads": 2 } }
}
```

## SDK Signature Format

Add signatures by dropping a YAML file into `sdk_signatures/<category>/`. No code changes required.

```yaml
id: xiaomi_mipush
name: 小米推送 MiPush
category: push
vendor: Xiaomi
description: "小米厂商推送通道"

detection:
  package_prefixes:
    - "com.xiaomi.push"
  native_libs:
    - "libmipush.so"
  manifest_services:
    - "com.xiaomi.push.service.XMPushService"

version_extraction:
  buildconfig:
    class_pattern: "com.xiaomi.push.BuildConfig"
    field: "VERSION_NAME"

risk:
  privacy_risk: low   # low / medium / high
  notes: "..."
```

## Build from Source

```bash
git clone https://github.com/1PersonLtd/apk-analyzer.git
cd apk-analyzer
uv sync
uv run apk-analyzer target.apk
```

## Release Pipeline

```
PR merge (feature-* or fix-*)
   ↓ auto-tag.yml
Creates v1.y.z tag
   ↓ publish.yml
Publishes to PyPI → pip install apk-analyzer
```

## License

MIT
