Metadata-Version: 2.4
Name: droidseal
Version: 1.1.0
Summary: Android release security with an evidence trail: audit, optional hardening, align, sign, verify (Windows x64 / Linux x64).
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/newnju/droidseal#readme
Project-URL: Source, https://github.com/newnju/droidseal
Project-URL: Issues, https://github.com/newnju/droidseal/issues
Project-URL: Changelog, https://github.com/newnju/droidseal/blob/main/CHANGELOG.md
Project-URL: Security, https://github.com/newnju/droidseal/security/policy
Project-URL: Releases, https://github.com/newnju/droidseal/releases
Keywords: android,apk,apk-security,apk-signing,apksigner,zipalign,release-engineering,android-security,apk-hardening,static-analysis,taint-analysis,sast,sbom,supply-chain,devsecops
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Dynamic: license-file

# DroidSeal · Android Release Seal

[中文](README.zh-CN.md) | [English](README.md)

[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-181717.svg?logo=github&logoColor=white)](https://github.com/newnju/droidseal/blob/main/LICENSE)
[![npm](https://img.shields.io/npm/v/droidseal.svg?logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/droidseal)
[![PyPI](https://img.shields.io/pypi/v/droidseal.svg?logo=pypi&logoColor=white&color=3775a9)](https://pypi.org/project/droidseal)

**Ship an Android release you can defend.**

DroidSeal is a local-first release pipeline: audit the app, optionally harden the APK, sign it with the official Android tools, and verify the result. Every release run leaves an evidence trail — SHA-256, JSON/Markdown reports, a CycloneDX SBOM, and a release decision.

> **Version scope.** This document describes DroidSeal **1.1.0** (tag `v1.1.0`). See the [1.1.0 release notes](https://github.com/newnju/droidseal/blob/v1.1.0/docs/releases/v1.1.0.md) for the frozen feature and evidence set.

[Release notes](https://github.com/newnju/droidseal/blob/v1.1.0/docs/releases/v1.1.0.md) · [Security policy](https://github.com/newnju/droidseal/blob/v1.1.0/SECURITY.md) · [Threat model](https://github.com/newnju/droidseal/blob/v1.1.0/docs/threat-model.md) · [Benchmarks](https://github.com/newnju/droidseal/blob/v1.1.0/benchmark/README.md)

**Quick start:** `npm install --global droidseal` → `droidseal` → choose audit, release, or opt-in hardening.

**Evidence at a glance:** 387 tests · 391 detector entries (390 unique codes) · 434 benign apps, dataflow FP = 0 · API 26 x86_64 emulator acceptance (hardening path).

## Architecture

<p align="center">
  <a href="https://raw.githubusercontent.com/newnju/droidseal/v1.1.0/docs/assets/droidseal-architecture.svg">
    <img src="https://raw.githubusercontent.com/newnju/droidseal/v1.1.0/docs/assets/droidseal-architecture.png" alt="DroidSeal 1.1.0 release architecture" width="100%">
  </a>
</p>

**Figure 1.** DroidSeal 1.1.0 release architecture. Solid teal boxes are self-developed components; amber boxes are official Android tools; the dashed purple path is opt-in APK hardening. Every release run writes an evidence bundle (signed APK, SHA-256, reports, SBOM and release decision). The device layer covers the stated emulator matrix only.

## Why DroidSeal

A successful Gradle build proves the app compiles. It does not prove the release is signed correctly, free of release-blocking findings, or unchanged since the audit.

DroidSeal closes that gap:

- **Find release blockers before users do** — permissions, signing schemes, hardcoded secrets, DEX/TLS heuristics, native `.so` hardening, third-party dependencies.
- **Harden without uploading your APK** — opt-in DEX encryption and keyed integrity/environment checks; tampering derives wrong keys instead of printing a bypassable warning.
- **Sign and verify the Android way** — `zipalign → apksigner → verify`, with per-step artifacts and rollback on failure.
- **Prove what shipped** — SHA-256, reports, SBOM, release gate and remediation evidence in one output directory.

Built for small Android teams, security reviewers and CI pipelines that need an auditable release without adopting a black-box cloud service.

## What it does

- **Audit**: static audit of projects and APKs — permissions, targetSdk, signing schemes, hardcoded secrets, DEX/TLS heuristics, native `.so` hardening, third-party dependencies and a CycloneDX SBOM;
- **Release**: runs `zipalign → apksigner sign → verify` in the official order, with automatic rollback on failure and an independent artifact per step;
- **Artifacts**: APK + SHA-256 + JSON/Markdown reports + a release gate + SBOM.

<img width="960" alt="DroidSeal UI screenshot" src="droidseal-screenshot.png" />

## Install

| Channel | How |
|---|---|
| npm | `npm install --global droidseal` |
| PyPI | `pip install droidseal` |
| GitHub Releases | Download the Windows zip / Linux tar.gz directly |

> The npm package ships a verified single-file bundle (`dist/droidseal.mjs`): the `droidseal` launcher checks the bundle's SHA-256 against the pinned build metadata on every run, then loads it — requires Node.js ≥ 18. After install, run `droidseal --version` to confirm.

> **Windows note**: if SmartScreen blocks the exe on double-click, right-click → Properties → Unblock. The TUI must run in a terminal: run `droidseal` in PowerShell, or double-click the bundled `droidseal-gui.cmd` launcher.

## Usage

```powershell
droidseal              # interactive TUI wizard (one-click / step-by-step)
droidseal doctor       # non-interactive environment diagnosis
droidseal --version
```

### APK hardening mode (opt-in)

`droidseal <input.apk> --output <dir> --cert-sha256 <sha256> --keystore <jks> --ks-alias <alias> --ks-pass <keystore-password> --key-pass <key-password>`

> **Credential handling:** the command above uses placeholders only. Prefer the interactive TUI prompt for passwords; if non-interactive flags are required, keep production passwords out of shell history and logs, and remove temporary credential files immediately.

Runtime-hardens a release APK: DEX payload encryption (AES-256-GCM, per-entry HKDF-derived keys), a randomized bootstrap shell (dual-DEX: a plaintext stub loads an encrypted loader from assets), shell entry-class / container-magic / meta-key randomization per build, and method code-item extraction. Every build emits an honest findings report — anything not implemented is reported as a finding, never claimed as protection.

**Keyed hardening layers** (tampering derives wrong keys instead of emitting a bypassable warning):

- **Integrity anchor in key derivation**: the final binary `AndroidManifest.xml` SHA-256 is folded into every per-entry HKDF info. Re-packaging always edits the manifest → wrong keys → GCM silently fails (P0-A).
- **Environment gate in key derivation**: runtime anti-analysis votes (Java detection + a native fork-based parent-TracerPid check / port probe / maps scan + the debuggable flag) are folded into the same HKDF info. Attach Frida and the derived keys are simply wrong — no signal to locate (P0-B).
- **Key sharding**: the master key is recombined per-entry and wiped immediately; no complete key ever sits in memory, and decrypted DEX buffers are zeroed right after class loading (P0-C).
- **Redundant heterogeneous detection**: three independent sources (Java / native C / system flags) with different read paths — bypassing one does not flip the vote (P1). Note: the native port probe tests localhost 27042/27043 (Frida defaults); another process legitimately listening on those ports on the same device (e.g. while instrumenting a *different* app) can produce a false positive.

| Flag | Effect |
|---|---|
| `--cert-sha256 <hex>` | signing-cert fingerprint; keys derive from it — **re-signing with a different key breaks decryption by design** |
| `--no-random-names` | keep fixed shell identifiers (debugging only) |
| `--no-triple-entry` | skip extra shell entry hooks |

**Expectation management**: hardening raises reverse-engineering cost; it does not make reversing impossible. On rooted devices with Frida, in-memory DEX dumps cannot be fully prevented by any offline packer — the layers above narrow the window and degrade tampered environments, but a sufficiently skilled attacker with sustained physical access still wins eventually. `minSdk < 26` falls back to a file-backed `DexClassLoader` (still works, slightly weaker isolation). Real-device install is the only authoritative acceptance test.

## Platform & status

- **Platform**: Windows x64 / Linux x64;
- **Status**: 1.1.0 (tag `v1.1.0`) — the CLI, output layout and report formats are stable; APK hardening is opt-in and has limited device validation, so accept it on your own device matrix;
- **Software**: an ANSI/Unicode-capable monospace terminal is required for the TUI; Bun 1.3.14 to run from source; JDK/Gradle/Android Build Tools are auto-discovered or downloaded per flow (Node only for Capacitor web builds);
- **Hardware (practical advice, not a hard floor)**: ~500 MB disk (100 MB executable + toolchain + artifacts), ≥2 GB RAM (more for large APKs — parsing is memory-sensitive with a fail-safe cap), x64 dual-core CPU.

## Positioning

Android security tooling often splits into two tracks: **audit** (MobSF, AndroBugs, APKiD — analyze, never rewrite) and **hardening** (commercial: DexGuard / DexProtector / 360 Jiagu; open source: Jiagu, nmmp, dpt-shell, XopProtector — rewrite the APK). DroidSeal integrates audit, optional hardening, signing, and verification in one offline pipeline; it does not claim to match dedicated audit or VMP products feature-for-feature.

| Track | Closest peers | What DroidSeal adds |
|---|---|---|
| Audit | MobSF (broad static/dynamic analysis), AndroBugs, APKiD | Audit findings drive **fixes in the same toolchain**: audit → remediation report → R8 → hardening → re-sign → re-verify, with a CycloneDX SBOM and release-evidence chain (releaseDecision / remediation). MobSF covers dynamic analysis and reporting; DroidSeal focuses on the release pipeline. |
| Hardening (open source) | dpt-shell (method-level), nmmp (VMP), XopProtector | **Keyed defenses**: integrity anchors and anti-analysis votes fold into per-entry key derivation (P0-A/B/C, P1) — patching detection code restores the *correct* key, but attaching Frida without patching derives *wrong* keys. The design goal is that disabling a check is not a simple "suppress the warning" operation; failing inputs derive wrong keys. This is a design property, not a claim that every commercial shell behaves the same way. Also: key sharding, honest findings. |
| Hardening (commercial) | DexGuard, DexProtector, 360 加固保 | Fully **offline** (code never leaves your machine), auditable behavior. Trade-off: no VMP/white-box crypto, less battle-tested, no SLA. |

**Where DroidSeal does NOT compete (honest boundaries)**:

- Need VMP-grade protection that survives a memory dump of the master key? Use nmmp or DexGuard — DroidSeal does not ship a VMP layer in this release and explicitly does not invest in white-box AES or full-instruction-set VM protection; on rooted devices with sustained physical access, a sufficiently skilled attacker eventually wins.
- Doing malware triage or dynamic behavior analysis? Use MobSF + APKiD — DroidSeal only audits and hardens, it never sandboxes.
- Need contractual support/SLA for a high-stakes product? The project is early (real-device acceptance, independent security review, and community size are all still ahead of it) — commercial vendors are the safer bet there.

**One-line summary**: an offline audit → optional harden → sign → verify pipeline with an auditable evidence chain; hardening strength is not claimed to match commercial VMP products; maturity is the main gap.

## Measured capabilities (benchmarked, not claimed)

Numbers below come from reproducible harnesses in [`benchmark/`](benchmark/README.md); each is stated with its measurement criteria — the same discipline the tool applies to its own findings.

**Audit (static analysis)**

| Capability | Measured | Criteria |
|---|---|---|
| Malicious-flow detection (TaintBench, 39 apps / 249 GT flows) | endpoint TP 171 / 249 (68.7%), flow TP 136 | endpoint = target API present in the GT class; flow = both ends hit |
| False positives (434 benign apps, AndroZoo VT=0 proxy) | dataflow engine FP = **0** (95% CI upper 0.69%) | only the dataflow layer counts; auxiliary config hints reported separately |
| Detector base (source/config/hardening patterns) | 391 detector entries (390 unique codes), precision 76.9% / recall 90.9% on the 38-case built-in bench | pattern-level, MSTG-mapped |
| JNI dynamic-register recovery | registry-string co-occurrence + DEX cross-validation | new finding class `JNI_DYNAMIC_REGISTER`; native attack surface invisible to static symbol scans |
| Native linear dataflow | JNI exported-function source→sink co-occurrence | **linear heuristic, not pointer analysis**; `confidence: low` by design |

**Hardening (release APK, opt-in)**

| Layer | Status |
|---|---|
| DEX payload encryption (AES-256-GCM, HKDF, keyed anchors P0-A/B/C) | shipped; validated on an API 26 x86_64 emulator with build-level regression tests (SEC-010/011/012) |
| Method extraction (code-item hollowing) + lazy restoration | shipped; fail-open fallback to full restore |
| String encryption with call-site rewrite (MUTF-8 safe ciphertext + checksum recompute) | shipped; apktool fail-closed on write-back |
| Keyed defenses (integrity anchor / environment gate / key sharding) | shipped, with honest caveats in the hardening section below |

**Honest boundaries of the numbers**: TaintBench line numbers and jadx line numbers are different sources (230 endpoints, only 6 exact) — connected-level matching therefore offers a strict tier (line ±2, historically 0) and a lenient tier (class-stem alignment, 66/249); the lenient tier must never be quoted alone. Obfuscated GT method names (`i`, 31 occurrences) are recovered only when the wrapping method body contains exactly one known source/sink API; ambiguous cases are dropped, not guessed.



Maturity here means *claimed capabilities are tested capabilities* — three layers, from cheapest to most expensive:

| Layer | Tool | When it runs | What it proves |
|---|---|---|---|
| Unit + regression | `bun test` | every change (CI core job) | crypto layout, URL patching, container format invariants |
| Security regression | `bun test tests/security-regression.test.ts` | mandatory per security fix | each accepted security fix ships a `SEC-XX` test reproducing its *trigger condition* (red on pre-fix code, green after; policy in [SECURITY.md](SECURITY.md#adversarial-regression-policy), full fix history in the [Security Ledger](docs/security-ledger.md)) — covers C1 (no PTRACE_TRACEME in generated native source), C3 (pre-XOR seal ordering), C4 (byte-length-preserving debuggable flip), C5 (whitelist smoke permanence), R2/R3 |
| Artifact baseline | `bun scripts/verify-harden-artifact.ts <apk>` | after every harden build | encrypted loader present & stored (H1/H2), container stored with valid magic (H3/H4), no key material in plaintext DEX (H5), shell manifest present (H6); `--expect-plain` asserts a *non*-hardened APK |
| Device acceptance | `bash scripts/device-test.sh <apk> <package>` | on real devices/emulators | install → 5s-alive decrypt-and-launch loop, no integrity/BadTag markers; full matrix and manual cases (re-sign must fail, Frida) in `docs/device-testing.md`; threat surface & residual risks in the [threat model](docs/threat-model.md), build-level proof-of-attack in `scripts/attack-sample-resign.ts` (re-sign must fail, by construction) |

CI (`.github/workflows/ci.yml`) runs `tsc --noEmit` + full tests + an npm-pack whitelist smoke on every push/PR, plus a separate NDK job that compiles the generated native shell sources (including `guard_vote.c`) with a real NDK — the native path is no longer paper-only. Releases: `bun scripts/release.ts <version> [--sync]` runs local verification and creates a local git tag only; uploading (git push / npm publish) is always a deliberate human step.

**Honest boundary**: build-time green ≠ runtime correct. The device layer above is the only trustworthy acceptance, and it needs real hardware.

**Emulator acceptance record (2026-09)**: the first full emulator run (API 26 x86_64) *crashed on launch* despite the then-current 264/264 test suite and the H1–H6 artifact baseline all being green — and fixing the first defect exposed the second, then the third. Three build-level defects that no static check could catch were found and fixed ([SEC-010](docs/security-ledger.md#sec-010--patched-payload-dex-fails-art-checksum-verification-critical) checksum/signature ordering, [SEC-011](docs/security-ledger.md#sec-011--method-extraction-stub-leaves-non-zero-padding-at-section-boundary-critical) non-zero section padding from extraction stubs, [SEC-012](docs/security-ledger.md#sec-012--identifier-randomization-breaks-dex-string_ids-ordering-critical) out-of-order string_ids from identifier randomization). Re-test after all three fixes: install PASS, first launch PASS, second launch PASS, zero logcat failure markers, clean uninstall (D1/D2/D3/D5). This is the concrete proof behind the honest boundary above: the device layer is the only one that catches this defect class.

## Security boundary

A defensive tool: by default it does not unpack, pack, or inject hooks / anti-debug code; it runs fully locally and never uploads APKs, paths or signing information.

**Exception — APK hardening mode (explicit opt-in)**: when you pass an APK with the hardening flags above, DroidSeal *does* pack (DEX encryption + bootstrap shell injection into **your own release APK**) and embeds anti-analysis detection. This mode only ever modifies the APK you explicitly supply as input; the default audit/release flows keep the no-packing boundary.

## Architecture, innovation & self-developed parts

### Innovation highlights

1. **Fully self-developed APK format handling**: parsing and rewriting of the ZIP central directory, ARSC resource table, AXML, DEX and ELF are all self-implemented at the byte level — no heavy parser dependencies (supply-chain convergence, clear failure semantics);
2. **Deterministic post-processing**: unchanged ZIP entries reuse the original compressed bytes, reducing unexpected churn in repacking / recompression / signing digests;
3. **Failure rollback**: each step keeps an independent APK artifact; "skip and roll back" preserves the last valid artifact before the step;
4. **Self-developed anti-debug stub** (C + Kotlin + CMake, optional source integration);
5. **Auditable results**: signature verification + SHA-256 + JSON/Markdown reports + CycloneDX SBOM + confidence-aware release gate;
6. **Pure local-first**: never uploads APKs, paths or signing information; by default no unpacking, packing or injection;
7. **Single binary, three channels**: Bun-compiled single-file executable with zero runtime npm dependencies; same-source release on npm / PyPI / GitHub Releases;
8. **Bilingual TUI + three entry points** (step-by-step / one-click / diagnosis).

### Self-developed vs third-party calls

- **Self-developed** (business core): `src/core` (ZIP/DEX/ELF/ARSC/AXML parsing and audit, pipeline orchestration, signing strategy, release gate, taint dataflow, JNI dynamic-register recovery), `src/ui` (TUI + i18n), the anti-debug stub, `scripts` (build/release/gate/bench scripts), and the dual launchers;
- **Third-party** (rendering/build layer): OpenTUI (terminal rendering), Solid.js (reactive UI), Terser (build minification, optional web JS only), TypeScript/Bun (toolchain), and external Android tools (keytool/Gradle/zipalign/apksigner/aapt — orchestrated through self-developed discovery and verification).

All format parsing / rewriting / auditing / reporting is self-developed (offline, low supply-chain footprint); rendering uses OpenTUI/Solid (third-party); external tools are called only in officially mandated steps, always orchestrated through self-developed discovery, SHA-256 verification and graceful degradation.

## Documentation

- [1.1.0 release notes](https://github.com/newnju/droidseal/blob/v1.1.0/docs/releases/v1.1.0.md)
- [Security policy](https://github.com/newnju/droidseal/blob/v1.1.0/SECURITY.md) and [threat model](https://github.com/newnju/droidseal/blob/v1.1.0/docs/threat-model.md)
- [Security ledger](https://github.com/newnju/droidseal/blob/v1.1.0/docs/security-ledger.md) — security fixes and their regression tests
- [Device testing](https://github.com/newnju/droidseal/blob/v1.1.0/docs/device-testing.md) — emulator/device acceptance records
- [Benchmark harness](https://github.com/newnju/droidseal/blob/v1.1.0/benchmark/README.md) — reproducible measurement commands
- [Release process](https://github.com/newnju/droidseal/blob/v1.1.0/RELEASE.md) — maintainer checklist

## License & brand

- Open-source license: [Apache License 2.0](https://github.com/newnju/droidseal/blob/main/LICENSE)
- Name and logo usage: [TRADEMARKS.md](https://github.com/newnju/droidseal/blob/main/TRADEMARKS.md) (attribute the source in reviews, tutorials and sharing)
