AI-Powered Agentic Android Security Testing Platform
DroidGuard AI is an autonomous security testing platform for Android applications. It uses specialized AI agents to discover, validate, and report vulnerabilities - designed for daily use by bug bounty hunters and security engineers.
| Feature | Description |
|---|---|
| Multi-Agent Architecture | 4 specialized agents (Recon, Attack, Exploit, Report) with intelligent handoffs |
| User-Controlled Autonomy | Choose from Manual → Guided → Semi-Auto → Full-Auto |
| Mandatory Approval Gate | System STOPS before exploitation and asks for your decision |
| Non-Aggressive by Default | Only safe PoCs automated; advanced attacks generate offline guides |
| Bug Bounty Ready | Reports formatted for HackerOne, Bugcrowd, etc. |
┌─────────────────────────────────────────────────────────────────┐
│ USER INTERFACE │
│ Web UI │ CLI │ REST API │
└─────────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────────┐
│ MISSION CONTROL │
│ (Agent Orchestration) │
└─────────────────────────────────────────────────────────────────┘
│
┌───────────────────────┼───────────────────────┐
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ RECON │────────▶│ ATTACK │────────▶│ EXPLOIT │
│ AGENT │ │ AGENT │ │ AGENT │
│ │ │ │ │ │
│ • APK Analysis │ • Detection │ │ • Safe PoCs │
│ • Attack Surface │ • Tests │ │ • Evidence │
│ • Tech Fingerprint │ • Exploita- │ ┌───▶│ • Guides │
└─────────────┘ │ bility │ │ └─────────────┘
└─────────────┘ │ │
│ │ ▼
▼ │ ┌─────────────┐
┌─────────────┐ │ │ REPORT │
│ USER GATE │────┘ │ AGENT │
│ (Approval) │ │ │
└─────────────┘ │ • CVSS │
│ • Walkthroughs
│ • Remediation│
└─────────────┘
| Level | Name | Behavior |
|---|---|---|
| 0 | Manual | Agent suggests, you execute everything |
| 1 | Guided | Agent executes with approval at each step |
| 2 | Semi-Auto | Agent runs tests, stops at exploitation gate |
| 3 | Full-Auto | Agent runs everything, reports at end |
Note: The exploitation gate is MANDATORY at all levels. You always decide what gets exploited.
| Tier | Automation | Risk | Example |
|---|---|---|---|
| 0 | ✅ Auto | None | Pattern found in code |
| 1 | ✅ Auto (after approval) | Minimal | Basic validation test |
| 2 | ✅ Auto (after approval) | Low | Extract 1 row, screenshot |
| 3 | ❌ Guide Only | Medium | Full extraction guide |
| 4 | ❌ Guide Only | High | RCE chain documentation |
| Category | Tests | Description |
|---|---|---|
| STORAGE | 8 | SharedPrefs, SQLite, External, Clipboard, Logs |
| PLATFORM | 8 | Exported Components, Deep Links, WebView |
| NETWORK | 6 | Cleartext, SSL Pinning, Certificate Validation |
| CRYPTO | 6 | Hardcoded Keys, Weak Algorithms, ECB Mode |
| AUTH | 6 | Biometric Bypass, Session Management |
| CODE | 6 | Debug Mode, Obfuscation, Logging |
| RESILIENCE | 6 | Root Detection, Emulator Detection |
| API | 10+ | Auth, Injection, IDOR, Rate Limiting |
| BINARY | 6 | Native Library Analysis |
- Python 3.11+
- Node.js 20+
- Docker & Docker Compose
- Android device/emulator with ADB
- Ollama with
qwen2.5-coder:7bmodel
Automated Setup (Recommended):
# Clone repository
git clone https://github.com/your-org/droidguard-ai.git
cd droidguard-ai
# Run automated setup script
./setup_dev.shThis script automatically:
- Starts Docker services (PostgreSQL, Redis, MobSF, Qdrant)
- Creates Python virtual environments for backend and CLI
- Installs all dependencies
- Runs database migrations
- Sets up the CLI package
Manual Setup:
# Clone repository
git clone https://github.com/your-org/droidguard-ai.git
cd droidguard-ai
# Start Docker services
docker compose up -d
# Backend setup
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload --port 8000
# Frontend setup (new terminal)
cd frontend
npm install
npm run dev
# CLI setup (optional)
cd cli
python3 -m venv venv
source venv/bin/activate
pip install -e .
droidguard --helpNote for macOS users: Use virtual environments due to PEP 668 restrictions.
- Open http://localhost:3000
- Register an account
- Connect your Android device
- Upload an APK
- Configure scan settings:
- Select categories
- Choose autonomy level
- Select build type
- Start scan
- Review findings at the decision gate
- Select exploitation actions per finding
- Generate report
# Login
droidguard auth login
# List devices
droidguard devices list
# Run scan
droidguard scan app.apk \
--device emulator-5554 \
--autonomy semi_auto \
--categories STORAGE,PLATFORM,NETWORK \
--output report.mddroidguard-ai/
├── CLAUDE.md # Instructions for Claude Code
├── README.md # This file
├── docker-compose.yml # Service definitions
├── .env.example # Environment template
│
├── docs/ # All specifications
│ ├── REQUIREMENTS.md
│ ├── ARCHITECTURE.md
│ ├── AGENTS.md
│ ├── DATABASE.md
│ ├── API_SPEC.md
│ ├── MCP_REGISTRY.md
│ ├── PROMPTS.md
│ ├── EXPLOITATION.md
│ ├── FRONTEND.md
│ ├── TASKS.md
│ └── TEST_CASES.md
│
├── backend/ # FastAPI backend
│ ├── app/
│ │ ├── agents/ # AI agents
│ │ ├── api/ # Route handlers
│ │ ├── core/ # Config, DB, Security
│ │ ├── mcp/ # MCP adapters
│ │ ├── models/ # SQLAlchemy models
│ │ ├── orchestrator/ # Agent coordination
│ │ └── services/ # Business logic
│ └── tests/
│
├── frontend/ # React frontend
│ └── src/
│
├── cli/ # Command-line interface
├── prompts/ # LLM prompt templates
├── frida_scripts/ # Pre-built Frida scripts
└── checkpoints/ # Scan state (auto-generated)
| Variable | Description | Default |
|---|---|---|
DATABASE_URL |
PostgreSQL connection | Required |
REDIS_URL |
Redis connection | redis://localhost:6379 |
JWT_SECRET |
Token signing key | Required |
OLLAMA_BASE_URL |
Ollama API URL | http://localhost:11434 |
OLLAMA_MODEL |
LLM model to use | qwen2.5-coder:7b |
MOBSF_URL |
MobSF instance URL | http://localhost:8001 |
RAG_ENABLED |
Enable RAG features | false |
EXPLOITATION_ENABLED |
Allow exploitation | true |
| Type | Behavior |
|---|---|
development |
Skip hardening bypass tests |
staging |
Auto-detect hardening level |
production |
Full testing including bypasses |
custom |
User-defined settings |
┌─────────────────────────────────────────────────────────────────┐
│ EXPLOITATION DECISION REQUIRED │
├─────────────────────────────────────────────────────────────────┤
│ Detection complete. Found 15 vulnerabilities. │
│ │
│ Critical: 2 │ High: 5 │ Medium: 6 │ Low: 2 │
│ │
│ Please select an action for each finding: │
│ [ ] Skip - Report as-is │
│ [ ] Simple PoC - Safe automated exploitation │
│ [ ] Offline Guide - Generate manual exploitation guide │
└─────────────────────────────────────────────────────────────────┘
# Security Assessment Report
## com.example.app v1.0.0
### Executive Summary
- **Critical:** 2 findings
- **High:** 5 findings
- **Medium:** 6 findings
- **Low:** 2 findings
### Critical Findings
#### 1. SQL Injection in UserContentProvider
- **CVSS:** 9.1 (Critical)
- **Status:** Confirmed (PoC executed)
- **Evidence:** Screenshot, extracted data sample
- **Remediation:** Use parameterized queries...- Always get authorization before testing any application
- Use on test devices only - never on devices with real user data
- Review offline guides carefully before manual exploitation
- Store reports securely - they contain sensitive vulnerability details
- Rate limiting is enforced to prevent accidental DoS
| Document | Description |
|---|---|
| REQUIREMENTS.md | Functional requirements |
| ARCHITECTURE.md | System architecture |
| AGENTS.md | Agent specifications |
| API_SPEC.md | REST API reference |
| EXPLOITATION.md | Exploitation tiers & Frida scripts |
| TASKS.md | Implementation roadmap |
- Fork the repository
- Create a feature branch
- Make your changes
- Run tests:
pytest - Submit a pull request
MIT License - see LICENSE for details.
- OWASP MASTG/MASVS for security testing standards
- MobSF for static analysis
- Frida for dynamic instrumentation
- The bug bounty community for real-world insights
Built with ❤️ for the security community