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:

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:

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

The SELinux area also retains an app-zygote SID-table query/registration experiment. Repeated discrepancies are supporting warnings; synchronized policy hiding can leave no discrepancy. Controlled privileged-context writes run in a disposable child with malformed/stock controls; recognition and ordinary-app timing are supporting warnings, an app-zygote AVC lookup-count profile is informational only, and negative observations cannot exclude hidden policy. Access failures and incomplete experiments remain explicit coverage states. See the SELinux evidence record for source references and device-validation limits.

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.

Native Root also offers an optional fsnotify SRCU timing experiment, disabled by default. It requires an explicit choice, uses a temporary private dynamic permission on supported Android 12–14 systems, and reports repeatable contention as supporting evidence. Its thresholds await device calibration; it does not identify KernelSU, and its private-process deadline cannot recover a blocked kernel.

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

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
├─ uihelper/              # Pinned Git submodule: MIUIX / Material UI, included as a separate Gradle build
├─ 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.

Initialize the UI submodule after cloning (or clone with --recurse-submodules). It is an independent Gradle build; the detector SDK never depends on it:

git submodule update --init --recursive

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 CONTRIBUTING.md and 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.