Droid LLM Hunter

Droid LLM Hunter is an automated security analysis tool designed to detect vulnerabilities in Android applications with high precision. By combining traditional static analysis (SAST) with the contextual understanding of Large Language Models (LLMs), it bridges the gap between keyword-based scanning and human-like code review.

It supports Hybrid Decompilation (Smali/Java), Context-Aware Analysis (Call Graphs), and Intelligent Risk Filtering, ensuring that security engineers can focus on verified, high-severity findings rather than false positives.

Features Auto-Exploit Generation, transforming from a passive scanner into an active capable of verifying vulnerabilities with generated Proof-of-Concept (PoC) scripts.

📊 Dashboard Report

Dashboard Report Droid-LLM-Hunter web interface designed to visualize and manage security analysis reports generated by the Droid-LLM-Hunter tool. Link: dashboard-report-dlh

📱 VulnerApp for Testing

VulnerAppDLH is a vulnerable Android application specifically created to test Droid-LLM-Hunter. It serves as a comprehensive testbed for validating the scanner's detection capabilities across various vulnerability categories. Link: VulnerAppDLH

📦 Package Attributes

🎬 Demo - Droid LLM Hunter

Tutorial Install Droid LLM Hunter

WebView via DeepLink - Exported Components

Features

🧠 Intelligent Analysis Engine: Droid LLM Hunter goes beyond regex. It breaks down code into chunks, summarizes functionality, and understands context before flagging vulnerabilities, significantly reducing false positives compared to traditional tools.
⭐ Staged Prompt Architecture: Uses a specialized pipeline of prompts (Summarization -> Filtering -> Deep Scan) to ensure consistent reasoning and reduce hallucination. Read the Docs
🔍 Hybrid Filter Modes: Choose your strategy!
- llm_only: Maximum accuracy using pure AI analysis.
- static_only: Blazing fast keyword scanning.
- hybrid: The best of both worlds Static keywords filter the noise, AI verifies the danger.
🏗️ Hybrid Architecture (v1.1.5): A revolutionary "Search -> Regex Filter -> LLM" pipeline that drastically reduces token usage and increases speed. Read the Docs
🛠️ Flexible Configuration: a simple yet powerful configuration file (config/settings.yaml) allows for easy management of LLM providers, models, rules, and Decompiler Settings (Apktool/JADX).
🕸️ Context-Aware Scanning: Utilizes a Call Graph to understand file dependencies. Use CrossReference Context to let the AI know who calls a function and with what arguments. Read the Docs
⚔️ Attack Surface Mapper: Combines Manifest Structure (Exported components) with Code Logic (AI Summaries) to identify high-risk entry points (e.g., specific activities processing unvalidated URLs). Read the Docs
📚 RAG with OWASP MASVS: Every finding is automatically enriched with the relevant OWASP Mobile Application Security Verification Standard (MASVS) ID (e.g., MASVS-STORAGE-1), making your reports audit-ready instantly.
🤖 Multi-Provider Support: Run locally with Ollama (free & private) or scale up with Gemini, Groq, OpenAI, Anthropic, and OpenRouter.
📊 Structured Security Reports: Get detailed JSON output containing severity, confidence scores, evidence snippets, and even an "Attack Surface Map" of the application.
💥 Auto-Exploit Generation: Automatically generates actionable Proof-of-Concept (PoC) scripts (Bash, HTML, Python, Js) for confirmed vulnerabilities, proving the impact instantly. Read the Docs
🛡️ Smart Scope Protection: The "Immune System" of the scanner. Automatically filters out library code (e.g., androidx, google, r0.java) using a combination of Package Whitelisting (via Manifest) and Library Blocklisting. Read the Docs
👑 Cross-Component Chaining: The "Crown Jewel". Capability that enables the AI to "connect the dots" between different files. It uses a Two-Pass Analysis (Discovery -> Global Context -> Execution) to generate chained exploits (e.g., using a token found in File A to exploit File B). Read the Docs
📦 XAPK Support: Direct support for .xapk files. The engine automatically handles extraction and selects the main APK for seamless analysis.

Scan Workflow

Droid LLM Hunter uses a multi-stage process to analyze an APK:

Decompilation: The APK is decompiled using Apktool (for Smali/Manifest) and optionally JADX (for Java Source), depending on the decompiler_mode.
Smart Filtering: Based on the filter_mode, the engine identifies potentially risky files using Static Analysis (static_only), AI Summarization (llm_only), or both (hybrid).
Smart Scope Protection: Irrelevant files (libraries) are discarded based on package name and blocklists.
Risk Identification: High-level analysis determines which files require deep inspection.
Deep Dive Analysis: Risky files are scanned for vulnerabilities.
Global Context Building: All findings are summarized to create a "Global Context".
Chained Exploit Generation: The engine generates exploits that leverage the Global Context to connect vulnerabilities across files.
Enrichment & Reporting: Vulnerabilities are mapped to OWASP MASVS standards, and a detailed JSON report is generated.

+-------------------------------------------------------+
|  PHASE 1: PREPARATION                                 |
|  [ Start ] -> [ Load Config ] -> [ Decompiler Engine ]|
|                      |             (Apktool / JADX)   |
|                      v                                |
|             [ Parse AndroidManifest.xml ]             |
|          (Extract Package Name & Components)          |
+----------------------+--------------------------------+
                       |
                       v
+----------------------+--------------------------------+
|  PHASE 2: SMART SCOPE PROTECTION (The Immune System)  |  <-- [v1.1.3]
|                                                       |
|  [ All Smali/Java Files ]                             |
|          |                                            |
|          v                                            |
|  [ SCOPE FILTER ]                                     |
|     1. Whitelist: Must match App Package Name         |
|     2. Blocklist: Drop known libs (androidx, r0...)   |
|          |                                            |
|          v                                            |
|  [ Relevant Files Only ] (Noise Reduced by ~70%)      |
+----------------------+--------------------------------+
                       |
                       v
+----------------------+--------------------------------+
+----------------------+--------------------------------+
|  PHASE 3: DISCOVERY & RISK ID (Hybrid Pass)           |
|                                                       |
|    [ Loop: Analyze Relevant Files ]                   |
|                 |                                     |
|                 v                                     |
|    [ REGEX FILTER (Zero Cost) ]                       |  <-- [NEW v1.1.5]
|    (Match 'detection_pattern'?)                       |
|       NO |             | YES                          |
|          v             v                              |
|       [ Skip ]      [ LLM VERIFICATION ]              |
|                     (Context & Logic Check)           |
|                                |                      |
|                                v                      |
|                     [ Validate Finding ]              |
|                                |                      |
|                                v                      |
|                     [ Store in Knowledge Base ]       |
|                   (Do NOT Generate Exploits Yet)      |
+----------------------+--------------------------------+
                       |
                       v
+----------------------+--------------------------------+
|  PHASE 4: INTELLIGENT CHAINING (Pass 2)               |  <-- [v1.1.3]
|                                                       |
|      [ Build Global Context ]                         |
|   (Summarize all findings from Phase 3)               |
|                 |                                     |
|                 v                                     |
|    [ Loop: Generate Exploits ]                        |
|                 |                                     |
|                 v                                     |
|      [ Inject Context + Manifest + Secrets ]          |
|   "Use the token from File A to hack File B"          |
|                 |                                     |
|                 v                                     |
|      [ Generate Chained Exploit Scripts ]             |
|       (Python / Bash / HTML / Frida)                  |
+----------------------+--------------------------------+
                       |
                       v
+----------------------+--------------------------------+
|  PHASE 5: REPORTING                                   |
|                                                       |
|      [ JSON Report ] + [ Exploit Artifacts ]          |
+-------------------------------------------------------+

For more detailed information JSON Report Structure, see the JSON Report

🎬 Demo - Droid LLM Hunter

Hardcoded Secrets

SQL Injection - Generate-Exploit

Available Scanners

Droid LLM Hunter supports the following LLM providers:

Ollama: For running local LLMs. (Recommended)
Gemini: Google's family of generative AI models.
Groq: A high-performance inference engine for LLMs.
OpenAI: OpenAI's family of generative AI models.
Anthropic: Claude's family of generative AI models.
OpenRouter: Access to hundreds of models (Llama 3, Claude 3.5, etc.) via a single API.

Available Rules

Rules Vulnerability Droid LLM Hunter:

Enable or Disable these rules in config/settings.yaml:

true: Enable the rule.
false: Disable the rule.

- sql_injection
- webview_xss
- hardcoded_secrets
- webview_deeplink
- insecure_file_permissions
- intent_spoofing
- insecure_random_number_generation
- jetpack_compose_security
- biometric_bypass
- graphql_injection
- exported_components
- deeplink_hijack
- insecure_storage
- path_traversal
- insecure_webview
- universal_logic_flaw
- pending_intent_hijacking
- fragment_injection
- zip_slip
- deeplink_logic_bypass
- unsafe_reflection
- webview_file_access
- insecure_deserialization
- strandhogg
- hardcoded_secrets_xml

Filter Mode Scanners

Configure the analysis strategy using filter_mode in settings.yaml to balance speed, cost, and accuracy.

1. `llm_only` (Default)

Decision Maker: 100% AI (LLM).

How it works:

All Smali files are chunked and summarized by the LLM (summarize_chunks).
The summaries are analyzed by the LLM to identify risks (identify_risky_chunks).
Only files marked as "Risky" are deep-scanned.

Pros: Most Intelligent (understands context), Minimal False Negatives.
Cons: Most Expensive (high token usage), Slowest.

2. `static_only`

Decision Maker: Classic Keyword Matching (CodeFilter).

How it works:

The scanner searches for dangerous keywords (e.g., WebView, SQLite, Cipher).
If found, the file is immediately marked for deep scan.
LLM is NOT used for filtering.

Pros: Super Fast, Zero Token Cost for filtering.
Cons: "Dumb" (no context), High False Positives, High False Negatives (obfuscation).

3. `hybrid` (Recommended)

Decision Maker: Static Analyzer + LLM Verification.

How it works:

Phase 1 (Static): Find files with dangerous keywords.
Phase 2 (LLM Verification): Only those specific files are summarized and checked by the LLM to confirm if they are truly risky.

Pros: Extreme Token Savings (ignores safe files), Good Accuracy.
Cons: Risk of Obfuscation (same as static_only).

Usage Recommendations:

Use llm_only if have abundant tokens and need 100% accuracy.
Use hybrid for daily usage (balanced).
Use static_only if are low on tokens or need a very fast scan.

Decompiler Modes

Droid LLM Hunter supports dual decompilation to balance reliability and analysis quality. Configure this via decompiler_mode in settings.yaml.

1. `apktool` (Default / Classic)

Format: Smali (Assembly).
Pros: 100% Reliability, critical for Manifest analysis.
Cons: Harder for LLM to understand logic, higher token usage.

2. `jadx` (Modern)

Format: Java Source Code.
Pros: Native code format, LLM understands it perfectly, logic is clear.
Cons: May fail on some obfuscated apps.

3. `hybrid` (Smart Fallback - Recommended)

Format: Java (Primary) + Smali (Fallback).
Logic: The engine tries to use JADX output. If JADX fails or produces empty/corrupt code for a file, it automatically switches to the Smali version from Apktool.
Result: Best of both worlds Analysis quality of Java with the reliability of Smali.

Installation

Clone the repository:

git clone https://github.com/roomkangali/droid-llm-hunter.git
cd droid-llm-hunter

Create and activate a virtual environment:

Linux/macOS:

python3 -m venv venv
source venv/bin/activate

Windows:

python -m venv venv
venv\\Scripts\\activate

Install dependencies:
```
pip install -r requirements.txt
```
Install Apktool & JADX:
- Apktool (Required): Must be installed. Instructions
- JADX (Optional but Recommended): Required if you want to use jadx or hybrid decompiler modes. GitHub

Configuration

The configuration for Droid LLM Hunter is located in the config/settings.yaml file. This file allows for configuration of the LLM provider, model, API keys, rules, and external tools paths.

Note on JADX: If jadx is not in your system PATH, you can specify the absolute path in settings.yaml:

jadx:
  path: "/opt/jadx/bin/jadx"

Docker Installation

Running Droid LLM Hunter via Docker ensures all dependencies (Java, Python, Apktool) are correctly configured.

1. Build Image

docker build -t dlh .

2. Run Scan

Mount the volume to access input files and save output results.

# Syntax: docker run -v [HOST_DIR]:/app/output dlh scan [APK_FILE]

# Example (Assuming APK is in the 'output' folder of current directory):
docker run --rm -v $(pwd)/output:/app/output dlh scan [APK_FILE]

3. Run with Flags

docker run --rm -v $(pwd)/output:/app/output dlh -v scan [APK_FILE]

4. Custom Configuration (Live Editing)

To edit settings.yaml without rebuilding the image, mount the local configuration file:

docker run --rm \
  -v $(pwd)/output:/app/output \
  -v $(pwd)/config/settings.yaml:/app/config/settings.yaml \
  dlh scan [APK_FILE]

Changes made to config/settings.yaml on the host machine will immediately apply to the scan.

Usage

python dlh.py scan [APK file]

Examples

Scan an APK with verbose logging:
```
python dlh.py -v scan [APK file]
```

Skip the decompilation step:

python dlh.py --no-decompile scan [APK file]

Run only specific rules:

python dlh.py --rules "sql_injection,webview_xss" scan [APK file]

List all available rules:
```
python dlh.py --list-rules
```
Show Options and Commands:
```
python dlh.py --help
```
Show Manage Configuration:
```
python dlh.py config --help
```
Show Manage Scan:
```
python dlh.py scan --help
```

Flags

+--------------------+------+----------------------------------------------------+
| Flag               | Short| Description                                        |
+--------------------+------+----------------------------------------------------+
| --verbose          | -v   | Enable verbose logging.                            |
| --output           | -o   | Output file for the scan results.                  |
| --no-decompile     | —    | Skip the decompilation step.                       |
| --rules            | -r   | Comma-separated list of rules to run.              |
| --list-rules       | —    | List all available rules and exit.                 |
| --profile          | -p   | Use a specific configuration profile.              |
+--------------------+------+----------------------------------------------------+

Commands

+------------------------------------+---------------------------------------------------------------+
| Command                            | Description                                                   |
+------------------------------------+---------------------------------------------------------------+
| scan                               | Scan an APK file for vulnerabilities.                         |
| scan [APK] --generate-exploit      | Generate PoC scripts for confirmed vulnerabilities.           |
| config                             | Manage the configuration of Droid-LLM-Hunter.                 |
| config wizard                      | Run the interactive configuration wizard.                     |
| config provider <provider>         | Set the LLM provider.                                         |
| config model <model>               | Set the LLM model.                                            |
| config rules --enable <rules>      | Enable rules.                                                 |
| config rules --disable <rules>     | Disable rules.                                                |
| config validate                    | Validate the configuration file.                              |
| config show                        | Show the current configuration.                               |
| config profile                     | Manage configuration profiles.                                |
| config profile create <name>       | Create a new profile.                                         |
| config profile list                | List all available profiles.                                  |
| config profile switch <name>       | Switch to a different profile.                                |
| config profile delete <name>       | Delete a profile.                                             |
| config attack-surface --enable     | Enable attack surface map generation.                         |
| config attack-surface --disable    | Disable attack surface map generation.                        |
| config context-injection --enable  | Enable Cross-Reference Context Injection.                     |
| config context-injection --disable | Disable Cross-Reference Context Injection.                    |
| config filter-mode                 | Set or show the code analysis filter mode.                    |
| config decompiler-mode             | Set or show decompiler mode (apktool, jadx, hybrid).          |
| list-rules                         | List all available rules.                                     |
+------------------------------------+---------------------------------------------------------------+

CI/CD Integration

Droid LLM Hunter is designed for seamless integration into CI/CD pipelines (GitHub Actions, GitLab CI, etc.).

GitHub Actions (Recommended)

We provide a Gold Standard workflow example that includes:

Auto-building your Android APK.
Running Droid LLM Hunter with specific rules.
Uploading the security report as an artifact.

👉 View the Professional Workflow Example

Key Features in CI/CD:

Dynamic Rules: Enable/Disable rules directly from YAML (e.g., rules: "sql_injection:true, webview_xss:false").
Custom Config: Load your own settings.yaml via config-path.
Hybrid Fallback: Automatically switches to Static Analysis if JADX fails in the container.

Development Roadmap

This document outlines the future development plans for the Droid-LLM-Hunter.

AI-Powered Dynamic Analysis (v2.0): Integration with Frida & ADB to verify static findings by running the app and simulating attacks (e.g., Reflection/IPC tracing, Intent Fuzzing). This directly addresses the limitations of static analysis regarding
CI/CD Integration : GitHub/GitLab templates for automated security scanning in DevOps pipeline. Dynamic Dispatch and JNI.
Taint Analysis Engine: Implementation of a lightweight Trace Engine (or FlowDroid integration) to map Source-to-Sink data paths, verifying if inputs are properly sanitized before reaching sensitive functions.
De-obfuscation Support: Support for mapping files (Proguard) and AI-based variable renaming to handle Obfuscated Applications and improve Call Graph accuracy.
Auto-Patching: Generating secure code fixes or .diff patches to automatically resolve identified vulnerabilities.
More Rules: Constantly adding new vulnerability detection rules to cover the latest Android security threats.

FAQ

Is the AI analysis 100% accurate ?

No. While Droid LLM Hunter drastically reduces noise using Context Awareness and Smart Filtering, LLMs (Artificial Intelligence) are probabilistic and can still make mistakes or "hallucinate". Treat the results as leads that require manual verification. The tool is designed to augment human intelligence, not replace it. Always verify findings manually!

Is the AI generator exploit 100% accurate ?

No. The exploit scripts are generated by an LLM and can contain hallucinations (e.g., non-existent Intent Actions) or logic errors.

False Positives: Sometimes the script might misinterpret a system log as a "Success".
Verification: The scripts now include "Auto-Verification" logic (checking Logcat), but this is still heuristic.
Usage: Use the generated script as a Prototype or Template to save time, but always verify the findings manually.

How does the tool's accuracy compare to traditional SAST tools ?

Droid LLM Hunter complements, rather than replaces, traditional SAST. Traditional tools excel at finding well-defined pattern vulnerabilities with near-zero false positives but struggle with logical flaws, business logic, or novel attack patterns. This tool uses AI to reason about code context and intent, catching complex issues that pattern-matching misses. The ideal workflow is to use traditional SAST for breadth and Droid LLM Hunter for depth and complex logic analysis.

What are the main sources of false positives/negatives, and how DLH mitigate them ?

False Positives often arise from the AI misunderstanding benign code patterns. DLH mitigate this through our multi-stage pipeline (summarize → filter → deep scan) and especially the Cross-Reference Context, which provides the AI with crucial caller/callee information to make better judgments.
False Negatives can occur if code patterns are highly obfuscated, or if the relevant vulnerability rules are not yet defined in the knowledge base. DLH mitigate this by making the rule system fully extensible and encouraging community contributions based on new research.

Why Performance scan APK slow ?

Note on Performance: The speed of the analysis also heavily depends on:

The LLM Provider/Model: Local models (Ollama) depend on hardware (GPU/CPU). Cloud models (Groq/Gemini/OpenAI/Anthropic) are generally faster but depend on network latency.
Active Rules: Enabling more rules increases the number of queries sent to the LLM.
Context Injection: Using Cross-Reference Context (Call Graph) adds more data to process, slightly increasing analysis time for better accuracy.

How can I add a new vulnerability rule ?

To add a new vulnerability rule :

Create a new YAML file in the config/prompts/vuln_rules directory (containing name, description, and prompt).
Add the new rule to the RulesSettings class in core/config_loader.py.
Add the new rule to the config/settings.yaml file.
(Optional) Add a corresponding entry in config/knowledge_base/masvs_mapping.json to map the rule to an OWASP MASVS category.

Contributing

Contributions are welcome! Please create an issue or pull request to report bugs or add new features.

droid-llm-hunter

Description

README

Droid LLM Hunter

📊 Dashboard Report

📱 VulnerApp for Testing

📦 Package Attributes

🎬 Demo - Droid LLM Hunter

📋 Table of Contents

Features

Scan Workflow

🎬 Demo - Droid LLM Hunter

Available Scanners

Available Rules

Filter Mode Scanners

1. llm_only (Default)

2. static_only

3. hybrid (Recommended)

Usage Recommendations:

Decompiler Modes

1. apktool (Default / Classic)

2. jadx (Modern)

3. hybrid (Smart Fallback - Recommended)

Installation

Configuration

Docker Installation

1. Build Image

2. Run Scan

3. Run with Flags

4. Custom Configuration (Live Editing)

Usage

Examples

Flags

Commands

CI/CD Integration

GitHub Actions (Recommended)

Key Features in CI/CD:

Development Roadmap

FAQ

Contributing

Release History

Dependencies & License Audit

Similar Packages

1. `llm_only` (Default)

2. `static_only`

3. `hybrid` (Recommended)

1. `apktool` (Default / Classic)

2. `jadx` (Modern)

3. `hybrid` (Smart Fallback - Recommended)