# PentestLab AI

**AI-native security research operating environment for mobile banking reverse engineering.**

PentestLab AI is a platform where AI agents reason, execute, observe, verify, correlate, and document security research inside an authorized laboratory environment. It combines 11 specialized agents, 50+ MCP tools, a Frida instrumentation engine with 18+ hook templates, banking malware detection across 13 families, Play Integrity API bypass detection, and no-root traffic interception — all wired through a unified CLI, MCP server, and multi-agent supervisor system.

> **Disclaimer**: This tool is designed exclusively for authorized security research, penetration testing engagements, CTF competitions, and educational purposes. Unauthorized access to computer systems is illegal. Always obtain written authorization before testing.

## Key Features

- **Multi-Agent Supervisor** — 11 specialized agents (Profiler, Static, Dynamic, Network, Auth, Evidence, Reporter, Malware, Protection, PIA, NoRoot) orchestrated through investigation phases
- **MCP Server** — 50+ tools across 15 namespaces, compatible with Qoder, Claude, and any MCP client
- **Frida Engine** — 18+ pre-built hook templates including SSL pinning bypass, anti-Frida evasion, direct SSL capture, Dart socket bypass, and Smali patching
- **Banking Malware Analyzer** — 13 malware family signatures (BeatBanker, GoldDigger, TrickMo, ClipBanker, Hook v3, Overlay Phantom, FluBot, Manic, Cerberus, Hydra), capability risk matrix, extended C2 pattern detection
- **Play Integrity Detector** — PIA SDK usage detection, 6 bypass technique identifiers (TrickyStore, ReZygisk, PlayIntegrityFix, Keybox Spoofing, Property Spoofing, Zygisk Injection), runtime Frida detection hook
- **No-Root Interceptor** — 6 capture modes (VPN/PCAPdroid, Frida Gadget, Gateway Redirect, LSPatch, TCP Sniffer, APK Unpinner), SSL unpinning smali patches, capture strategy recommendation engine
- **Protection Detector** — 17 detection categories including overlay abuse, accessibility abuse, in-memory DEX loading, kernel root frameworks (KernelSU, APatch, Zygisk)
- **Advanced Checker Framework** — 8 checker modes: intercept, modify return, brute force, replay, fuzz, header injection, proxy rotation, response tampering
- **Flutter RE Engine** — libapp.so analysis, Blutter integration, MethodChannel discovery, BoringSSL pinning bypass
- **Native Binary Analyzer** — ELF/PE/Mach-O format detection, symbol extraction, crypto/network reference scanning
- **Knowledge Graph** — Entity relationship mapping across findings, classes, endpoints, and evidence
- **Evidence Engine** — SHA-256 integrity hashing, tamper verification, chain-of-custody tracking
- **Web Dashboard** — Real-time investigation monitoring via Streamlit

## Architecture

```
pentestlab/
├── cli.py                          # Typer-based CLI (25+ commands)
├── mcp/server.py                   # MCP server (50+ tools, 15 namespaces)
├── agents/supervisor.py            # Multi-agent orchestration (11 agents)
├── engines/
│   ├── android/
│   │   ├── analyzer.py                 # Main APK analysis pipeline
│   │   ├── frida_engine.py             # Frida hooks & instrumentation
│   │   ├── jadx_engine.py              # JADX decompilation engine
│   │   ├── manifest_analyzer.py        # AndroidManifest.xml parser
│   │   ├── framework_detector.py       # Framework fingerprinting
│   │   ├── protection_detector.py      # Anti-analysis detection (17 categories)
│   │   ├── play_integrity_detector.py  # PIA bypass detection
│   │   └── noroot_interceptor.py       # Rootless traffic capture
│   ├── flutter/analyzer.py             # Flutter/Dart RE engine
│   ├── native/binary_analyzer.py       # ELF/PE/Mach-O analysis
│   ├── malware/banking_analyzer.py     # Banking malware detection (13 families)
│   ├── checkers/advanced_checker.py    # Automated checker framework (8 modes)
│   ├── authentication/                 # Login flow, OTP, token, OAuth
│   └── web/                            # Recon, API testing
├── core/                           # Scope, sessions, evidence, tools
├── graph/knowledge_graph.py        # Finding correlation graph
├── reports/engine.py               # Report generation (MD/HTML/JSON)
├── dashboard/app.py                # Streamlit web dashboard
└── benchmarks/suite.py             # Performance & accuracy benchmarks
```

## Installation

```bash
git clone https://github.com/ny0x696/PentestLab-AI.git
cd PentestLab-AI

pip install -e ".[dev]"

pentestlab doctor
```

### External Tools (Optional)

| Tool | Purpose | Install |
|------|---------|---------|
| JADX | APK decompilation | `brew install jadx` / [GitHub](https://github.com/skylot/jadx) |
| apktool | APK decoding/rebuilding | `brew install apktool` |
| Frida | Runtime instrumentation | `pip install frida-tools` |
| Blutter | Flutter Dart decompilation | [GitHub](https://github.com/worawit/blutter) |
| readelf/rabin2 | Native binary analysis | `brew install binutils` / `radare2` |
| httpx | Web technology detection | `go install github.com/projectdiscovery/httpx@latest` |
| subfinder | Subdomain enumeration | `go install github.com/projectdiscovery/subfinder@latest` |

Run `pentestlab doctor` to check tool availability.

## Quick Start

### Analyze an APK

```bash
pentestlab android analyze app.apk --workflow full
pentestlab android diff old.apk new.apk
```

### Detect Protections

```bash
pentestlab protect detect app.apk -o protections.json
```

### Banking Malware Analysis

```bash
pentestlab malware analyze suspicious.apk
pentestlab malware compare suspicious.apk
```

### Play Integrity Detection

```bash
pentestlab integrity detect app.apk
pentestlab integrity hook
```

### No-Root Traffic Interception

```bash
pentestlab noroot modes
pentestlab noroot setup vpn --package com.target.app
pentestlab noroot ssl-patches
```

### Generate Security Checkers

```bash
pentestlab checker generate brute_force --function com.app.OTPValidator
pentestlab checker generate modify_return --function com.app.SecurityCheck
pentestlab checker orchestrator com.target.app --hooks ssl_bypass,crypto_monitor
```

### Authentication Research

```bash
pentestlab auth discover https://target.com
pentestlab auth tokens eyJhbGciOiJIUzI1NiIs...
pentestlab auth otp target-app
```

### Sessions & Reports

```bash
pentestlab session create "target.apk" --scope lab
pentestlab report generate SES-abc123 --format markdown
pentestlab evidence list
```

## MCP Integration

All capabilities are exposed through the Model Context Protocol for AI agent integration.

### Namespaces

| Namespace | Tools | Description |
|-----------|-------|-------------|
| `pentestlab.core` | 4 | Sessions, scope, environment |
| `pentestlab.android` | 4 | APK analysis, framework detection |
| `pentestlab.frida` | 4 | Device enumeration, hook generation |
| `pentestlab.jadx` | 3 | Decompilation, endpoint/secret extraction |
| `pentestlab.web` | 3 | Recon, API testing, OpenAPI parsing |
| `pentestlab.auth` | 4 | Login flows, tokens, OTP, OAuth |
| `pentestlab.evidence` | 3 | Evidence creation, listing, verification |
| `pentestlab.reporting` | 2 | Report generation, session export |
| `pentestlab.malware` | 3 | Banking malware analysis, family comparison |
| `pentestlab.protection` | 1 | Anti-analysis protection detection |
| `pentestlab.checker` | 2 | Hook generation, orchestrator templates |
| `pentestlab.flutter` | 2 | Flutter analysis, SSL bypass scripts |
| `pentestlab.native` | 1 | Binary format/symbol analysis |
| `pentestlab.pia` | 3 | Play Integrity detection, bypass info |
| `pentestlab.noroot` | 4 | Capture modes, setup, SSL patches |

### Configuration

```json
{
  "mcpServers": {
    "pentestlab": {
      "command": "python",
      "args": ["-m", "pentestlab.mcp.server"]
    }
  }
}
```

## Multi-Agent System

The supervisor orchestrates 11 agents through investigation phases:

```
Phase 1:  Profiler     → Target fingerprinting, framework detection
Phase 2:  Static       → Code review, protection detection
Phase 2b: Malware      → Banking malware family scanning
Phase 2c: Protection   → Anti-analysis protection cataloging
Phase 2d: PIA          → Play Integrity API detection
Phase 2e: NoRoot       → Capture strategy recommendation
Phase 3:  Dynamic      → Frida instrumentation planning
Phase 4:  Network      → Traffic analysis, endpoint discovery
Phase 5:  Auth         → Authentication mechanism analysis
Phase 6:  Evidence     → Finding correlation, gap identification
Phase 7:  Reporter     → Professional report generation
```

## Testing

```bash
pytest tests/ -v                    # Full suite (176 tests)
pytest tests/test_phase_b.py -v     # Phase B/D/E tests only
pentestlab benchmark run --suite all # Benchmarks
```

## Documentation

- [Architecture](docs/ARCHITECTURE.md) — System design and component interactions
- [Progress](docs/PROGRESS.md) — Implementation status, phase history, competitive analysis

## Competitive Position

PentestLab AI combines five dimensions that no single existing project covers:

1. **Mobile banking specialization** — 13 malware families, overlay/accessibility abuse, Play Integrity bypass
2. **Multi-agent supervisor** — 11 coordinated agents with phased investigation
3. **Native MCP server** — 50+ tools for AI agent integration
4. **Integrated Frida engine** — 18+ hook templates with anti-detection
5. **Research-driven development** — Techniques from 2026 papers and RE communities as executable code

See [Competitive Analysis](docs/PROGRESS.md#competitive-analysis-2026-09-05) for detailed comparison with PentestGPT, MobSF, BlacksmithAI, Strix, Ostorlab, and pentestMCP.

## License

This project is provided for authorized security research and educational purposes only. Users are responsible for ensuring they have proper authorization before using this tool against any target system.