DuckDetector

On-device Android environment integrity diagnostics backed by Kotlin and native probes.

Download Nightly · Documentation · SDK Integration

English   简体中文

Overview

DuckDetector collects and correlates security-relevant evidence on an Android device. It looks for boot-state changes, root and SU artifacts, runtime injection or hooking, mount namespace anomalies, modified system properties, suspicious applications, KeyStore and attestation inconsistencies, and signs of virtualization.

The app combines a Jetpack Compose interface, feature-oriented Gradle modules, and a native C++/assembly library. The same detectors are also published as a UI-free SDK AAR that other applications can embed. Results are diagnostic signals, not an authoritative statement that a device is secure or compromised.

Quick start

1. Download the APK from the Nightly release. Nightly builds are published from main and are also posted to the Telegram channel; there is no stable release yet.
2. Install it on a device running Android 10 or later. Root access is not required.
3. Scan. The first launch asks you to accept the user agreement and to settle a few startup choices: notifications, Live Update, the online revocation refresh used by the TEE check, and package visibility. Scanning then starts by itself, and each card fills in when its detector finishes.
4. Read the results as described below. To report a result or ask for help, open an issue and attach the file saved by Export Report at the top of the dashboard; a screenshot of the summary alone is not enough.

Reading the results

Each card shows one of these statuses:

Status	Meaning
Danger, Warning	The detector observed evidence; the card lists what it saw.
All Clear	The probes ran and found none of the evidence they look for. This does not prove that the device is unmodified.
Info (Support)	A probe was unsupported or unavailable on this device, so the absence of findings says nothing.
Info (Error)	The check failed; the card says why.

To see what a detector looks for and why that counts as evidence, open its evidence record from Detector coverage.

Detector coverage

Current feature areas, each linked to its evidence record, which explains what the detector looks for, why that counts as evidence, and what it cannot see:

Bootloader · Custom ROM · Dangerous Apps · Kernel Check · LSPosed · Memory · Mount · Native Root · Play Integrity Fix · SELinux · SU · System Properties · TEE · Virtualization · Zygisk

Play Integrity Fix refers to local indicators associated with integrity-spoofing modifications; DuckDetector does not return an official Google Play Integrity API verdict. The TEE area evaluates Android KeyStore and attestation evidence, including certificate chains, security levels, revocation data, and selected KeyMint, StrongBox, and Soter behavior where supported.

Supporting modules provide the dashboard, device information, settings, update checks, notifications, license information, and common UI infrastructure.

How it works

• Feature modules: each detector owns its collection, judgement rules, report projection, and UI in its own Gradle modules, while collection code that several detectors share lives in capability modules.
• Early native capture: a transparent NativeActivity runs before MainActivity and records early mount and virtualization evidence.
• Native probes: the shared native library performs checks that require direct system calls, /proc inspection, timing measurements, linker/runtime visibility, or architecture-specific assembly.
• Process separation: selected Zygisk, Mount, Native Root, virtualization, SELinux, LSPosed, and TEE checks run in dedicated or isolated services so evidence can be compared across process boundaries.
• Evidence correlation: the dashboard reports individual findings and coverage states instead of treating one heuristic as conclusive.

Compatibility

Area	Details
Android	Android 10 or later (minSdk 29); compiled and targeted against Android API 37.
ABIs	Native syscall paths are provided for arm64-v8a, armeabi-v7a, x86, and x86_64. Some timing and virtualization trap probes are available only on arm64-v8a.
Privileges	Root access is not required. Android permissions and platform visibility rules still limit what the app can observe.
Device variance	OEM changes, kernel configuration, Android version, and sandbox policy may cause a probe to be unsupported, unavailable, or lower-confidence.
Network use	Core device scans run locally. TEE revocation checks always include the bundled snapshot; downloading Google's current revocation feed requires user consent. The app also checks GitHub for Nightly updates after a cold start and when requested from Settings. With GitHub acceleration on, which Chinese-language users are asked about and Settings can switch, those checks and the Nightly download go through the third-party gh-proxy.com service instead.

Architecture

Duck-Detector-Refactoring/
├─ app/                   # UI composition root: activities, dashboard cards, notifications
├─ sdk/runtime/           # Headless composition root: detector catalog, scan API, process hooks, native library registry
├─ sdk/aar/               # The distributable SDK: every headless module fused into one AAR
├─ core/                  # Contracts and shared infrastructure: evidence, native payloads, platform access, reports, scan lifecycle, detector, UI
├─ capability/            # Evidence collection shared by several detectors
├─ feature/               # One detector or supporting feature per directory, split into layers
├─ samples/sdk-consumer/  # A separate application built from the published AAR alone
├─ build-logic/           # Convention plugins, module boundary and dependency validation, generated assets
├─ docs/                  # Architecture overview, guides, and follow-ups
├─ .github/policies/      # Module, native, detector touch point, reflection, and text protocol policies
├─ .github/scripts/       # Repository guards and their self-tests
├─ gradle/                # Version catalog and Gradle wrapper files
├─ scripts/               # Detector scaffold and repository maintenance scripts
├─ build.gradle.kts
└─ settings.gradle.kts

Each detector is a set of Gradle modules under feature/<name>/:

• domain: result models, report models, status definitions, and judgement rules (pure JVM)
• data: probes, parsers, repositories, JNI bridges, and Android service access
• presentation: the card model, its mapping from the domain report, and the report projection (pure JVM)
• detector: the one headless <Name>Detector object that binds the other layers for the SDK and the app
• ui: the Compose card, the prompts for the detector's consents, and its integration with the dashboard

Dependencies point from :app to the SDK, from both to features, from features to capabilities, and from capabilities to core; features never depend on each other. Every module declares exactly the dependencies it uses. The build and CI enforce these rules. See the architecture overview.

A new detector touches only its own directory and its one line in DetectorCatalog, plus one registry line and one policy entry when it has a native unit; the app generates its dashboard cards from the ui modules. One command creates all of it, in a state that builds and reports "Not evaluated" until its probe is written:

python3 scripts/new_detector.py <name> --description "what it looks for and why that is evidence"

Continue with Adding a detector. To run the detectors inside another application, see Using the SDK.

Native sources are organized into units. Each unit lives in src/main/cpp/<unit>/ of the module that owns it, is compiled as its own object library and is linked into libduckdetector.so; Kotlin code reaches native results through the JNI bridges of that same module.

Build

Requirements

• Android Studio with Android SDK Platform 37 and Build Tools 37.0.0
• JDK 17
• Android NDK 30.0.16138531
• CMake 4.1.2

Dependency and tool versions are defined in gradle.properties and gradle/libs.versions.toml.

Commands

# macOS / Linux
./gradlew :app:assembleDebug

# Windows
gradlew.bat :app:assembleDebug

For the standard local validation path:

./gradlew unitTest :app:assembleDebug :app:lintDebug buildHealth
for s in .github/scripts/check-*.py; do python3 "$s"; done

The same build also produces the headless SDK as one AAR, without any UI, published to sdk/aar/build/repository (see Using the SDK):

./gradlew :sdk:aar:publish

The Nightly release includes the SDK AAR alongside the APK.

Before contributing, read CODING_STANDARDS.md.

Release signing

The build uses the ciRelease signing configuration only when all four variables are set:

• ANDROID_KEYSTORE_PATH
• ANDROID_KEYSTORE_PASSWORD
• ANDROID_KEY_ALIAS
• ANDROID_KEY_PASSWORD

Without the complete set, the local release build is signed with the debug key. Do not treat such an artifact as an official release.

Privacy and limitations

• Detection is performed on the device. The project does not claim that every modified environment can be detected.
• Network-capable features are limited to the consented TEE revocation refresh, GitHub update metadata and changelog checks (through gh-proxy.com while GitHub acceleration is on), and links explicitly opened by the user.
• Results are heuristic and can contain false positives, false negatives, unsupported checks, or incomplete evidence.
• Hardware-backed KeyStore, StrongBox, Binder behavior, /proc, SELinux, mount namespaces, and other low-level interfaces vary by device and OS build.

Project status

Disclaimer

This software is provided "as is", without warranty of any kind. It is intended for education, diagnostics, and security research. The developers are not liable for damage, data loss, or system instability resulting from its use. Interpret heuristic findings in the context of the device, OS build, and available probe coverage.

License

DuckDetector is licensed under the Apache License 2.0.