DOCSEARCHbyAlgolia
Submit Docs

DuckDetector Documentation

repository·master·Indexed 20 days ago

https://github.com/eltavine/duck-detector-refactoring

An Android security auditing tool for on-device detection of root, bootloader tampering, and virtualization. It utilizes Kotlin and low-level C++/Assembly probes to identify Custom ROMs, dangerous applications, and kernel security issues. The tool includes specialized repositories like CustomRomRepository, DangerousAppsRepository, and KernelCheckRepository, and supports Android 10+ (minSdk 29) with optimizations for arm64-v8a.

Tokens
7K
Snippets
13
Records
30
Agent score
73%

What's inside DuckDetector

  1. Overview of DuckDetector

    master

    DuckDetector is an Android security detection application focused on local, device-side evidence collection. It is designed to identify Root-related tampering, runtime hooking, mount operations, KeyStore attestation trust, and virtualized execution environments.

    Key features include:

    • Modular Architecture: Independent modules for specific detection functions, each with its own Repository, Mapper, ViewModel, and UI.
    • Native Preload: Uses a transparent NativeActivity launcher to perform early-stage preloading to capture early mount and virtualization traces.
    • Native Probes: Employs C++ and Assembly for syscall-level, time-sensitive, and runtime visibility checks.
    • Cross-Process Validation: Uses multi-process and isolated processes to verify signals and reduce reliance on single indicators.
    • Privacy-First: Operates locally and offline by default. TEE revocation checks use built-in static snapshots unless the user manually enables "Online Refresh" in settings.

  2. Understand the DuckDetector project architecture

    master

    The project is organized into a core app module and specialized feature modules.

    Directory Structure

    • app/src/main/java/com/eltavine/duckdetector/core/: Common components and foundations.
    • app/src/main/java/com/eltavine/duckdetector/features/: Individual detection feature modules.
    • app/src/main/java/com/eltavine/duckdetector/ui/: Global UI and themes.
    • app/src/main/cpp/: Low-level C++ and Assembly probe source code (compiled into a single .so library).

    Feature Module Pattern

    Each detection feature module follows a strict package structure:

    • domain: Data models for reports and results.
    • data: Repositories, probes, native bridges, and system service helpers.
    • presentation: Data mappers and UI-state reducers.
    • ui: Detection card components and module-specific UI models.

  3. Project Architecture and Module Structure

    master

    The project follows a modular structure. Most detection feature modules follow this package pattern:

    • domain: Data models for reports and results.
    • data: Repositories, probes, native bridges, and system service assistants.
    • presentation: Data mappers and UI-state reducers.
    • ui: Detection card components and module-specific UI models.

    Core Components:

    • app/src/main/java/com/eltavine/duckdetector/core/: Core public components and foundation.
    • app/src/main/java/com/eltavine/duckdetector/features/: Individual detection feature modules.
    • app/src/main/java/com/eltavine/duckdetector/ui/: Global common UI and themes.
    • app/src/main/cpp/: Source code for all native probes (compiled into a shared .so library).

  4. Build DuckDetector from source

    master

    Requirements

    • Android Studio (Latest stable)
    • Android SDK 37.0 & Android Build Tools 37.0.0
    • JDK 17
    • Android NDK 30.0.14904198
    • CMake 4.1.2

    Build Commands

    Compile Debug Version (Windows):

    gradlew.bat :app:assembleDebug

    Compile Debug Version (Linux / macOS):

    ./gradlew :app:assembleDebug

    Daily Development Validation (Recommended): This command validates Kotlin compilation, runs unit tests, and packages the app.

    ./gradlew :app:compileDebugKotlin :app:testDebugUnitTest :app:assembleDebug
    # Windows
gradlew.bat :app:assembleDebug

# Linux / macOS
./gradlew :app:assembleDebug

# Validation
./gradlew :app:compileDebugKotlin :app:testDebugUnitTest :app:assembleDebug

  5. Build and Compile DuckDetector

    master

    Requirements

    • Android Studio: Latest stable version recommended
    • Android SDK: 37.0 & Android Build Tools 37.0.0
    • JDK: 17
    • Android NDK: 30.0.14904198
    • CMake: 4.1.2

    Build Commands

    Compile Debug version (Windows):

    gradlew.bat :app:assembleDebug

    Compile Debug version (Linux / macOS):

    ./gradlew :app:assembleDebug

    Recommended Development Validation Command: This command verifies Kotlin compilation, runs unit tests, and packages the app:

    ./gradlew :app:compileDebugKotlin :app:testDebugUnitTest :app:assembleDebug

    Automated Release Signing

    Release builds are automatically signed if the following four environment variables are present:

    • ANDROID_KEYSTORE_PATH
    • ANDROID_KEYSTORE_PASSWORD
    • ANDROID_KEY_ALIAS
    • ANDROID_KEY_PASSWORD

    When these are set, the build system enables the ciRelease signing configuration.

    # Windows
gradlew.bat :app:assembleDebug

# Linux / macOS
./gradlew :app:assembleDebug

# Recommended validation
./gradlew :app:compileDebugKotlin :app:testDebugUnitTest :app:assembleDebug

  6. Understand the CustomRomReport structure

    master

    A CustomRomReport is the result of a scan. It provides a high-level summary of the device's state regarding Custom ROM detection. Key components include:

    • detectedRoms: A list of ROM names identified during the scan.
    • packageVisibility: Indicates if the scan had full or restricted visibility into installed packages (CustomRomPackageVisibility).
    • methods: A list of CustomRomMethodResult objects, each representing a specific detection technique (e.g., propertyScan, buildFieldScan, packageScan, serviceScan, nativeFiles).
    • stage: The current state of the report (e.g., CustomRomStage.READY).

    Each CustomRomMethodResult contains a label, a human-readable summary, an outcome (CustomRomMethodOutcome), and a detail string providing specific evidence for that method.

  7. LSPosedPackageVisibility levels

    master

    The LSPosedPackageVisibility enum (used in LSPosedPackageProbeResult) indicates how reliably the probe could inspect the device's installed packages. This is determined by the Android OS version and the number of apps returned by the PackageManager:

    • FULL: The probe has complete visibility (typically on Android versions < R, or when many apps are returned).
    • RESTRICTED: The probe has limited visibility (typically when the package list is small, indicating Android's package visibility restrictions are active).
    • UNKNOWN: The probe could not determine visibility (e.g., if no apps were returned).

  8. Understand the DangerousAppsReport structure

    master

    The DangerousAppsReport is the primary data contract returned by a scan. It contains the following key information:

    • stage: The current state of the report (e.g., DangerousAppsStage.READY).
    • packageVisibility: The level of visibility the PackageManager has on the device (DangerousPackageVisibility.FULL, RESTRICTED, etc.).
    • packageManagerVisibleCount: The number of packages visible to the system.
    • suspiciousLowPmInventory: Boolean indicating if the package count is unexpectedly low (suggesting HMA-style filtering).
    • suspiciousSharedStorageDenied: Boolean indicating if baseline shared storage paths returned access errors.
    • targets: The list of all applications defined in the DangerousAppsCatalog that were scanned.
    • findings: A list of DangerousAppFinding objects, where each finding contains a target and the methods used to detect it.
    • hiddenFromPackageManager: A list of findings that were detected via probes even though they were not visible via the standard PackageManager.
    • issues: A list of strings describing environmental issues found during the scan (e.g., restricted visibility or storage denials).

  9. Understand the KernelCheckReport structure

    master

    A KernelCheckReport is the primary data contract returned by a scan. It provides a detailed breakdown of the kernel's security posture. Key fields include:

    • stage: The current state of the report (e.g., KernelCheckStage.READY).
    • dangerFindings: A list of KernelCheckFinding objects representing high-severity issues (e.g., suspicious cmdline, non-standard kernel versions).
    • infoFindings: A list of KernelCheckFinding objects representing informational or lower-severity issues (e.g., exposed kernel pointers).
    • suspiciousCmdline: A boolean indicating if critical boot flags were detected.
    • kptrExposed: A boolean indicating if kernel pointers are accessible.
    • cvePatchState: The assessed state of specific CVE patches (e.g., UNPATCHED, PARTIALLY_PATCHED, PATCHED).
    • methods: A list of KernelCheckMethodResult objects, providing a summary of each individual check performed (e.g., emojiScan, cmdlineCheck, cvePatchCheck).

  11. Supported Security Detection Coverage

    master

    DuckDetector provides heuristic detection across several security domains, including:

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

    Additionally, the project includes auxiliary modules for dashboard (data aggregation), settings (user control), and deviceinfo (device context).

  12. Check DuckDetector compatibility and limitations

    master

    Compatibility

    • Android Version: Supports Android 10+ (minSdk 29). Built with targetSdk 37 / compileSdk 37.0.
    • Architecture (ABI): Low-level probes are implemented via NDK; some paths are optimized specifically for arm64-v8a.
    • Environment: Runs without root permissions; compatible with stock and customized systems.

    Limitations

    • Heuristic Nature: All detections are heuristic-based. No single signal should be considered absolute proof.
    • Hardware/Vendor Restrictions: OEM policies or sandbox rules may cause some probes to report downgraded, unavailable, or low-coverage statuses.
    • Architecture Dependency: Certain low-level checks require the arm64-v8a ABI.