droidHunter

A local-first workspace for inspecting Android applications for exposed Firebase services and embedded credentials.

Quick start · Usage · Scan sources · API · Security

Important

Use droidHunter only on applications and services you own or have explicit permission to test. The API can read server-side paths, run local tools, and perform network checks. It has no user authentication and binds to loopback by default. Do not expose it directly to an untrusted network.

Overview

droidHunter combines a FastAPI backend with a small local web interface. It can:

• extract Firebase project IDs, API keys, app IDs, database URLs, and storage buckets from APKs;
• inspect Realtime Database, Firestore, Storage, and Remote Config access;
• scan local APKs, APK folders, connected Android devices, or known Firebase projects;
• optionally obtain public apps through the Aurora-based downloader;
• run authenticated checks with a supplied test account;
• run opt-in reversible write checks;
• detect embedded secrets with redacted TruffleHog findings; and
• track progress, summaries, logs, generated files, and retained APKs.

Browser → Express UI → FastAPI → Job runner → Scanner and optional tools
                                      ↓
                                Local data/

Quick start

Requirements

Component	Requirement
Core application	Python 3.10+, Node.js 18+, Bash
Store downloads	JDK 21+, Gradle, optional Aurora downloader build
Connected devices	ADB and an authorized Android device
Secret detection	TruffleHog available on PATH
Deep extraction	JADX and optional OpenFirebase tooling

From the repository root:

./start.sh

Then open:

• Web interface: http://127.0.0.1:3000
• Interactive API documentation: http://127.0.0.1:8000/docs
• API health check: http://127.0.0.1:8000/health

The launcher creates .venv, installs the Python and Node dependencies, and starts both services. Press Ctrl+C to stop them.

Run the backend and interface separately

Backend:

python3 -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt
uvicorn backend.api:app --host 127.0.0.1 --port 8000

Interface, in a second terminal:

cd web
npm ci
npm start

Use different local ports

API_PORT=8100 UI_PORT=3100 ./start.sh

When the UI uses a different origin, allow it explicitly:

DROIDHUNTER_CORS_ORIGINS=http://127.0.0.1:3100 \
API_PORT=8100 UI_PORT=3100 ./start.sh

Update the API address from the interface’s Connection menu.

Using the interface

1. Open New scan.
2. Choose a source and provide exactly one target type.
3. Leave Scan settings at their defaults for a normal pass, or expand them for advanced options.
4. Select Start scan and follow the live progress card.
5. Open Scans to review summaries and generated files.
6. Use APKs for retained downloads and Automated for discovery jobs.

The Download only action is available for direct store-app targets. Downloaded APKs are removed after scanning unless Keep downloaded APK is enabled.

Scan sources

Source	Input	Extra requirement
Store app	Package ID or app name	Built Aurora downloader
Local APK or folder	Absolute APK path or directory on the API host	None
Firebase project IDs	Comma-separated IDs, ID file, DNS export, or prior result	None
Store keyword search	Search term and result limit	Built Aurora downloader
Automated discovery	Store charts, keyword discovery, or both	Built Aurora downloader
Connected ADB device	Optional device serial	ADB and device authorization

Note

Paths entered in the interface are resolved by the API process, not by the browser. Use paths that exist on the machine running the backend.

Advanced scan settings

Core

• Requests per second controls network request pacing.
• Request timeout limits individual scan operations.
• Keep downloaded APK retains an APK after the job finishes.
• Detect embedded secrets enables TruffleHog when installed.
• Check Remote Config includes Firebase Remote Config checks.

Extraction

• Fast DEX-only extraction favors speed over coverage.
• Use JADX deep extraction enables broader decompilation-based discovery.
• Allow JADX installation explicitly permits the configured tooling to install JADX.
• Extract certificates adds application signing-certificate information.
• Deep-scan preset enables JADX, signatures, Remote Config, collection fuzzing, and secret detection.

Network and authentication

• Proxy URL must use HTTP or HTTPS.
• Authenticated checks require both a test-account email and password.
• Resume auth data accepts a previous authentication-state file.
• Fuzz Firestore collections uses a configurable wordlist to check possible collection names.
• Reversible write checks are disabled by default and must be explicitly enabled.

Automated discovery applies deeper extraction defaults, but write checks remain opt-in.

Build the optional Aurora downloader

The downloader is not required for local APK, ADB, or Firebase-project scans.

./build-aurora.sh

The installed CLI is created at:

aurora-downloader/build/install/aurora-downloader/bin/aurora-downloader

Useful overrides:

AURORA_JAVA_HOME=/path/to/jdk-21 \
AURORA_TIMEOUT_SECONDS=120 \
AURORA_DOWNLOAD_RETRIES=3 \
./start.sh

Downloading applications may be subject to Google Play terms and local law. Do not redistribute downloaded APKs. The Aurora dependencies are GPL-3.0-or-later; review THIRD_PARTY_NOTICES.md before distributing a built downloader.

Interactive API documentation

FastAPI provides an interactive Swagger interface at http://127.0.0.1:8000/docs. It can inspect schemas, try local requests, and show validation errors without requiring a separate API client.

The raw OpenAPI document is available at http://127.0.0.1:8000/openapi.json.

API endpoint reference

Method	Endpoint	Purpose
GET	/health	Check API status and version
GET	/jobs	List jobs with current progress
POST	/jobs	Create a scan job
GET	/jobs/{job_id}	Read one job
POST	/jobs/{job_id}/stop	Stop a running job
DELETE	/jobs/{job_id}	Delete a stopped or finished job and its managed files
GET	/jobs/{job_id}/files?path=...	Download a generated result file
GET	/jobs/{job_id}/batch	List package results for search or automated jobs
POST	/jobs/{job_id}/apk/restore	Re-download a direct store-scan APK
GET	/apks	List retained APKs
GET	/apks/{job_id}/download	Download a retained APK
POST	/downloads	Download an APK without scanning it
POST	/aurora/top-charts	Test and list Aurora chart packages

Copy-ready API examples

Scan a local APK:

curl -X POST http://127.0.0.1:8000/jobs \
  -H 'Content-Type: application/json' \
  -d '{
    "apk_path": "/absolute/path/to/app.apk",
    "aurora_mode": "local"
  }'

Scan Firebase project IDs:

curl -X POST http://127.0.0.1:8000/jobs \
  -H 'Content-Type: application/json' \
  -d '{
    "project_id": "project-one,project-two",
    "scan_rate": 1.0
  }'

Read job progress:

curl http://127.0.0.1:8000/jobs/JOB_ID

Stop a job:

curl -X POST http://127.0.0.1:8000/jobs/JOB_ID/stop

Environment variables

Launcher and network

Variable	Default	Purpose
PYTHON_BIN	python3	Python used to create the virtual environment
VENV_PATH	.venv	Virtual-environment location
API_HOST	127.0.0.1	API bind address
API_PORT	8000	API port
UI_HOST	127.0.0.1	UI bind address
UI_PORT	3000	UI port used by start.sh
PORT	3000	UI port when starting web/server.js directly
DROIDHUNTER_CORS_ORIGINS	Local UI origins	Comma-separated allowed browser origins

Aurora

Variable	Purpose
AURORA_JAVA_HOME	JDK used by the installed downloader
AURORA_TIMEOUT_SECONDS	Downloader network timeout
AURORA_DOWNLOAD_RETRIES	Download retry count
AURORA_USER_AGENT	Play request user agent override
AURORA_DISPENSER_USER_AGENT	Dispenser request user agent override
AURORA_RANDOM_SOURCE	Automated source fallback: auto, charts, or search
AURORA_RANDOM_CHART	Default chart name
AURORA_RANDOM_CHART_TYPE	Default chart category
AURORA_RANDOM_CHART_LIMIT	Default chart pool size
AURORA_RANDOM_SEARCH_TIMEOUT_SECONDS	Automated search timeout

Values submitted by the interface take precedence over automated-scan environment fallbacks.

Results and local data

Runtime state is created below data/ and excluded from Git:

data/
├── apks/                 # retained or in-progress APK files
├── jobs/jobs.db          # local SQLite job history
└── results/<job_id>/     # scan output, progress, and runner logs

Common result files include targets.json, scan.json, summary.json, progress.json, and runner.log. Treat the entire directory as sensitive even though secret-detector matches are redacted.

Authenticated-scan credentials are written to a mode-0600 job file and removed as soon as the runner loads it. Test-account emails are not stored in job history or scan output.

Security model

• The application is designed for one trusted local operator.
• The API has no authentication or tenant isolation.
• Both services bind to loopback by default.
• CORS defaults to the local UI origins.
• Write checks are disabled until explicitly selected.
• Job deletion is limited to managed APK and result paths.
• Generated reports can still contain project identifiers, paths, and security findings.

For remote access, put an authenticated reverse proxy in front of both services and explicitly configure CORS. See SECURITY.md for reporting and deployment guidance.

Troubleshooting

The interface says the API is offline

Confirm http://127.0.0.1:8000/health responds, then verify the API address in Connection. If the UI uses another port or origin, set DROIDHUNTER_CORS_ORIGINS before starting the API.

Store scans say the downloader is missing

Install JDK 21 and Gradle, run ./build-aurora.sh, and confirm the installed CLI path shown above exists.

A local path is rejected

The path must exist on the backend host. APK paths must identify files; APK-directory and wordlist paths must identify the expected file type.

ADB finds no applications

Run adb devices, authorize the host on the device, and provide a serial when more than one device is connected.

Secret scanning reports that TruffleHog is unavailable

Install TruffleHog and ensure the trufflehog executable is available on the API process’s PATH.

Deep extraction cannot find JADX

Install JADX yourself or explicitly enable Allow JADX installation. Automatic installation is never enabled merely by selecting deep extraction.

Project layout

.
├── backend/
│   ├── api.py                    # FastAPI routes and job lifecycle
│   ├── runner.py                 # background runner and progress tracking
│   └── scanner/                  # extraction, scanning, storage, Aurora bridge
├── web/
│   ├── server.js                 # local static server and security headers
│   └── public/                   # dependency-free browser interface
├── aurora-downloader/            # optional Kotlin downloader
├── start.sh                      # local launcher
├── build-aurora.sh               # optional downloader build helper
├── SECURITY.md
└── THIRD_PARTY_NOTICES.md

Development checks

python3 -m compileall -q backend
ruff check backend
cd web
npm ci
npm audit --omit=dev
npm run check

License

droidHunter is available under the MIT license. Integrated and optional components remain subject to their own licenses and service terms; see THIRD_PARTY_NOTICES.md.