Skip to content

Developer Guide

Jump to bottom
Emirhan Uçan edited this page Aug 4, 2026 · 13 revisions

Developer Guide

Deep-dive into the HydraDragonAV Mobile codebase for contributors. For the function-level API of every class and function, see Java-API-Reference and Rust-API-Reference.

Project Structure

HydraDragonAV-Mobile/
├── app/                                  # Android application module
│   └── src/main/
│       ├── java/com/hydradragon/antivirus/
│       │   ├── engine/                   # 46 classes — ScanEngine, NativeScanner, HIPS, network, whitelist, self-protection
│       │   ├── service/                  # GuardService, DnsVpnService, DynamicAnalysisService, ScreenCaptureService, receivers
│       │   ├── ui/                       # DashboardFragment, ScanFragment, NetworkFragment, SettingsFragment, ThreatLogFragment, BlockActivity, MalwareFoundActivity
│       │   ├── views/                    # HexagonStatusView, LiveNetworkChart
│       │   ├── adapter/                  # NetworkEventAdapter, ScannedFileAdapter, ThreatAdapter
│       │   ├── model/                    # ProcessInfo, ScannedFileInfo, ScanResult, ThreatResult
│       │   ├── security/                 # SecureWindowGuard, StrandHoggGuard
│       │   ├── HydraDragonApp.java       # Application — theme + native init
│       │   ├── MainActivity.java         # launcher activity, permission bootstrap
│       │   └── BootReceiver.java         # boot → GuardService
│       ├── jniLibs/{arm64-v8a,armeabi-v7a,x86,x86_64}/libhydradragonandroid.so
│       └── assets/scan/                  # .yrc rules, model.mpk, .xf filters, whitelist DBs
├── hydradragonandroid/                   # JNI bridge crate — scan pipeline (lib.rs 4196 lines)
│   └── src/{lib,asset_reader,benign_db,dex_scan,elf,emulate,ip_scan,url_scan}.rs
├── hydradragonclamav/                    # Pure-Rust ClamAV engine (21 files)
│   └── src/{scanner,database,pattern,logical,bytecode_vm,atom*,fuzzy,icon*,pe,version_info,cert,phishing,yara_scan,...}.rs
├── hydradragonml/                        # Burn (ndarray) binary APK classifier
│   └── src/{lib,main,model}.rs + features/mod.rs + bin/train.rs
├── hydradragonextractor/                 # archive extraction (zip/tar/gz/xz/7z/rar/bz2/lzma)
│   └── src/{lib,rar}.rs
├── hydradragonxorfilter/                 # Binary-Fuse16 .xf format (shared writer + reader)
│   └── src/lib.rs
├── dev-tools/
│   ├── hydradragon_yara_x_compile/       # offline .yar → .yrc compiler
│   ├── xorfilter_writer/                 # offline .xf blob builder
│   └── yarGen/                           # vendored Florian Roth yarGen (Python)
├── yara-x/                               # YARA-X source rules (.yar) + helper scripts + yr.exe
├── database/                             # filtered ClamAV signature databases
├── database_non_filtered/                # unfiltered ClamAV databases (source for clam_juice.py)
├── whitelist/                            # NSRL whitelist data
├── allxfilters/                          # URL/domain XOR filter sources
├── allips/                               # malicious IP list sources
├── dataset/                              # benign (F-Droid) + malware (MalwareBazaar) APKs
└── *.py                                  # data-pipeline scripts (clam_juice, gen_*, build_url_xfilter, ...)

The yara-x engine is a git dependency (github.com/HydraDragonAntivirus/yara-x), not a submodule. The local yara-x/ directory at the repo root holds the project's rule files, not the engine source. Clone the engine fork separately if you need to modify the modules — see YARA-X-Modules.

Native Engine (Rust)

The native engine (libhydradragonandroid.so) is built from five Rust crates and communicates with Java via JNI through com.hydradragon.antivirus.engine.NativeScanner. See Rust-API-Reference for the full function-level reference.

Key Crates

Crate Purpose Key source
hydradragonandroid JNI bridge + scan pipeline (extract → hydradragon metadata → YARA/ClamAV → ML → verdict) lib.rs
hydradragonclamav Pure-Rust ClamAV-compatible signature engine + YARA-X bridge scanner.rs, database.rs, pattern.rs, logical.rs, bytecode_vm.rs
hydradragonml Burn (ndarray) binary APK classifier (vocab.json-mapped subword tokenizer + 18 engine features) + scan CLI lib.rs, features/mod.rs, model.rs, main.rs, bin/train.rs
hydradragonextractor Recursive archive extraction (zip/gz/tar/xz/lzma/7z/rar) + zip-bomb detection lib.rs, rar.rs
hydradragonxorfilter Binary-Fuse16 .xf format shared by writer + on-device reader lib.rs

Building the .so

cd hydradragonandroid
build-android.cmd

Or with a specific ABI:

build-android.cmd -Abi arm64-v8a

This compiles libhydradragonandroid.so for all four Android ABIs (arm64-v8a, armeabi-v7a, x86_64, x86) using cargo-ndk and copies the outputs into app/src/main/jniLibs/. Prerequisites: Rust toolchain with the four Android targets, Android NDK (ANDROID_NDK_HOME), cargo-ndk (cargo install cargo-ndk).

The 25 JNI functions

NativeScanner exposes 25 native methods, all named Java_com_hydradragon_antivirus_engine_NativeScanner_<methodName> (note: com_hydradragon_antivirus, not com_hydradragon_av). They cover init/readiness, settings pushes (emulation/max-scan-size/zip-bomb/scan-relevant-only), whitelist queries, URL/IP/text/HIPS/packet scans, APK scan, batch scan lifecycle, rule hot-learning, and diagnostics. See Rust-API-Reference#jni-exposed-functions-25-total for the full table with Java signatures.

Adding a New YARA Rule

  1. Add the rule to yara-x/*.yar (use import "hydradragon" for module-gated rules).
  2. Compile: cargo run --release --manifest-path dev-tools/hydradragon_yara_x_compile/Cargo.toml -- yara-x/ app/src/main/assets/scan/ (or --check to validate only).
  3. Rebuild the APK (./gradlew assembleDebug) — the .yrc is picked up from assets/scan/.

Updating the YARA-X Dependency

After making changes to the yara-x fork (e.g. adding a module export), commit + push the fork, then update the pin in all three dependent crates so the offline compiler and the on-device engine stay on the same rev (the serialized .yrc is backend-specific):

cd hydradragonandroid; cargo update -p yara-x   # builds the .so
cd ../hydradragonclamav; cargo update -p yara-x
cd ../dev-tools/hydradragon_yara_x_compile; cargo update -p yara-x

All three must match. Then recompile the .yrc files (compiler) and rebuild the .so (the module metadata contract in hydradragonandroid/src/lib.rs must match the fork's schema).

Android App (Java/Kotlin)

The Android app is a standard Gradle project. The minimum SDK is 26 (Android 8.0 Oreo); per-app network attribution requires API 29 (Android 10) but the rest of the suite runs on Oreo+. See Java-API-Reference for the full class-level reference.

Key Services

Service Type Purpose
GuardService Foreground Service (START_STICKY) 24/7 monitoring, owns both ScanEngine instances, periodic scans, Downloads/full-storage observers, root-exploit transition detection
DynamicAnalysisService Accessibility Service On-screen text scanning, clickjacking/UI-spam/notification-spam detection, removal-resistance
ScreenCaptureService Foreground Service (mediaProjection) Periodic screen OCR → NetworkObservations + NativeScanner.scanText
DnsVpnService VpnService DNS filtering (Web Shield) + optional full-capture packet scanning

Receivers

BootReceiver (boot → GuardService), InstallReceiver (on-install scan), UninstallReceiver (cleanup), SmsReceiver (SMS scam/phishing), UserActionReceiver (alert actions), AdminReceiver (device-admin self-protection).

Code Standards

Rust

  • cargo clippy -- -D warnings must pass; use rustfmt.
  • JNI functions follow Java_com_hydradragon_antivirus_engine_NativeScanner_<name>.
  • All unsafe blocks have safety comments.

Java

  • Follow Android AOSP style.
  • Services handle lifecycle properly (particularly VpnService and AccessibilityService).
  • Settings UI uses guardedToggleListener rate-limiter + FLAG_WINDOW_IS_OBSCURED tapjacking checks.

Testing

Unit Tests

./gradlew test

Native Tests

cd hydradragonandroid && cargo test
cd ../hydradragonclamav && cargo test

Manual Testing

  1. Build debug APK and install on a physical device or emulator (Android 10+ for full feature coverage).
  2. Verify all permission flows (All-Files-Access mandatory; accessibility/VPN/MediaProjection/SMS/overlay optional).
  3. Test scan with known EICAR/malware test files.
  4. Test accessibility, VPN, and screen-capture service toggles.

See Also

Clone this wiki locally