LLM-Powered Deep Penetration Testing Agent

An opinionated web-app penetration-testing orchestrator: 46 vulnerability scanners across 11 categories, run in parallel against a target you own, and folded into a single Excel + summary report with remediation steps.

It runs a 7-phase pipeline (Init → Auth → Recon → Obstacles → Parallel Vulnerability Assessment → LLM Analysis → Report) guided by an LLM (Anthropic Claude by default, with openai, ollama, and mock providers supported).

==============================================================
  LLM-Powered Deep Penetration Testing Agent  v1.0
  Plan-aligned orchestrator + 46 scanners / 11 categories
  https://rashedtech.com/
==============================================================

---

⚠️ Authorized Use Only

This tool actively probes target applications and may trigger real vulnerabilities. Only run it against:

• A target you own, or
• A target you have explicit written authorization to test (signed engagement, bug-bounty in-scope asset, etc.), or
• A legal practice target such as OWASP Juice Shop, DVWA, or bWAPP.

On startup the agent asks you to type exactly:

I CONFIRM I AM AUTHORIZED

You can bypass this with --yes, but only use that in non-interactive scripts where you've already done the authorization step. The maintainers are not responsible for misuse.

---

Features

46 scanner modules grouped into 11 categories (scanner_registry.py is the single source of truth):

Category	Scanners
Injection	sql_injection, nosql_injection, command_injection, xxe_injection
Auth & access	authentication, authorization, session_fixation, jwt_attacks, oauth_attacks
XSS / CSRF	xss_testing, csrf_testing, dom_xss, clickjacking
Advanced	ssrf_testing, path_traversal, race_conditions, deserialization, cache_poisoning, request_smuggling, prototype_pollution, http_host_header
API testing	rest_api_tester, graphql_tester, websocket_tester, api_auth_tester
Business logic	workflow_analyzer, price_manipulation, state_violation, logic_flaw_tester
File upload	upload_tester, mime_validation, file_execution
Info disclosure	error_handling, source_code_disclosure, metadata_extraction, backup_files, hardcoded_secrets
CORS / CSP	cors_analyzer, csp_analyzer, x_frame_options
Cryptography	ssl_tls_analyzer, weak_cipher_detection, certificate_validator
LLM attacks	prompt_injection, model_extraction, data_leakage

You can disable individual scanners in config.yaml under modules.<category>.<scanner>: false.

---

Installation

git clone <your-repo-url> vapt-agent
cd vapt-agent
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt

Python 3.10+ is recommended (3.11/3.12 confirmed working).

Some scanners optionally use selenium (headless browser), pytesseract (OCR), and DB drivers. They're already in requirements.txt; install system deps only if you actually run those scanners:

# Optional — only needed for browser-based / OCR scanners
# Ubuntu/Debian:
sudo apt-get install chromium-browser tesseract-ocr
# macOS:
brew install --cask chromium tesseract

---

Configuration

Configuration is layered: environment variables → config.yaml → built-in defaults. Environment variables always win (so secrets stay out of disk).

Environment variables

Set the ones you need in your shell, in .env (loaded automatically by python-dotenv), or in your CI secret store. Do not put ANTHROPIC_API_KEY in config.yaml.

Variable	Default	Purpose
ANTHROPIC_API_KEY (or VAPT_LLM_API_KEY)	(none)	Required for live LLM-driven scans.
VAPT_LLM_PROVIDER	anthropic	One of anthropic, openai, ollama, mock.
VAPT_LLM_MODEL	MiniMax-M3-Claude	Any Anthropic-compatible model id.
VAPT_LLM_BASE_URL	https://api.anthropic.com	Override for self-hosted / proxy endpoints.
VAPT_LLM_TEMPERATURE	0.2	LLM sampling temperature.
VAPT_LLM_MAX_TOKENS	2048	LLM response token cap.
VAPT_LLM_TIMEOUT	180	LLM request timeout (seconds).
VAPT_RATE_LIMIT	5	Max requests per second per target.
VAPT_MAX_CONCURRENCY	8	Parallel scanner workers.
VAPT_MAX_ITER	4	Max agentic iterations per scanner.
VAPT_REQ_TIMEOUT	30	Per-HTTP-request timeout (seconds).
VAPT_USER_AGENT	VAPTAgent/1.0	Outbound User-Agent header.
VAPT_SMTP_PASSWORD	(none)	SMTP password for --email delivery.

config.yaml

For non-secret overrides (module toggles, scan behavior, output format), edit config.yaml. Anything you set here overrides the built-in default; environment variables still beat this file. See config.yaml for the full schema — common edits:

llm:
  provider: "mock"                # run with no API key (limited LLM reasoning)

scan:
  request_rate_limit_per_sec: 10  # dial down for fragile targets
  max_concurrency: 4

modules:
  llm_attacks:
    prompt_injection: false       # skip scanners by id
  api_testing:
    websocket_tester: false

output:
  formats: ["excel", "json"]      # add/remove output kinds

safeguards:
  respect_robots_txt: true
  max_requests_per_second: 5

---

Usage

Interactive (default — recommended for first run)

python3 main.py

You'll be walked through 5 steps:

1. Authorization — type the phrase.
2. Target URL — https://example.com.
3. Test mode — [1] black box or [2] gray box.
4. Credentials (gray box only) — username / password / bearer.
5. Scan guidance (optional) — directives like focus path: /api, exclude: prompt_injection, delay: 0.5.

Scan starts, the .xlsx is written to reports/, and (if you're in a TTY) it opens in your default app.

Quick (default everything, just give the URL)

python3 main.py --quick --target https://example.com

Scripted / CI

python3 main.py \
  --target https://staging.example.com \
  --mode black_box \
  --yes \
  --no-open \
  --output reports

Gray box (authenticated testing)

python3 main.py \
  --target https://staging.example.com \
  --mode gray_box \
  --username alice --password 'hunter2' \
  --bearer 'eyJ...' \
  --yes

Scan guidance from a file

Save directives in scan-rules.txt:

focus path: /api, /admin
ignore path: /logout, /api/health
delay: 0.5
max requests: 2000
include only: sql_injection, xss_testing, hardcoded_secrets
exclude: prompt_injection, model_extraction
notes: Q4 re-test — focus on /api endpoints
header X-Engagement: pentest-2026-q1

Then:

python3 main.py --target https://staging.example.com --suggestions-file scan-rules.txt --yes

Mock / offline mode (no API key needed)

For testing the pipeline end-to-end without contacting an LLM:

# config.yaml
llm:
  provider: "mock"

Email the report

python3 main.py --target https://example.com --yes --email

Reads SMTP settings from config.yaml's email.* block (host, port, user, from, to); password from VAPT_SMTP_PASSWORD.

Programmatic

from config import load_config
from pentest_agent import PentestAgent
from core.scan_suggestions import ScanSuggestions

cfg = load_config()
agent = PentestAgent(cfg)
result = agent.run_pentest(
    target_url="https://example.com",
    test_mode="black_box",
    output_path="reports",
    output_format=["excel", "summary"],
    suggestions=ScanSuggestions(),
)
print(result["report_paths"])
print(f"Findings: {len(result['findings'])}")

---

CLI flags

Flag	What it does
--target URL	Skip target prompt.
--mode {black_box,gray_box}	Skip mode prompt.
--username / --password / --bearer	Skip credentials prompt (gray_box).
--suggestions-file PATH	Read scan guidance from a file.
--output DIR	Output directory (default reports).
--yes / -y	Skip the authorization confirmation. Use only in non-interactive scripts where authorization is already established.
--quick	Accept all defaults; only ask for the target URL.
--no-open	Don't auto-open the .xlsx after the scan.
--email	Email the report (requires email.* in config.yaml + SMTP password in env).

---

Output

After a scan finishes, three files land in reports/ (filenames are timestamped):

File	Contents
<target>_<timestamp>.xlsx	Multi-sheet workbook: Executive Summary, Findings (one row per issue with severity, endpoint, evidence, remediation), Statistics, Scanner Coverage (proves nothing was silently skipped), Technical Analysis.
<target>_<timestamp>.summary.txt	Human-readable summary with severity breakdown.
<target>_<timestamp>.json (optional)	Raw machine-readable findings, when enabled in config.yaml.

The .xlsx is verified as a valid zip before being reported as written — if generation crashes, the path is omitted from the result, not silently returned.

---

Safeguards

The agent takes several precautions by default. Configure under safeguards.* in config.yaml.

• Authorization gate — interactive phrase check; bypass requires --yes.
• Rate limiting — TokenBucket throttles outbound HTTP to VAPT_RATE_LIMIT req/s.
• Concurrency cap — VAPT_MAX_CONCURRENCY parallel workers max.
• robots.txt — safeguards.respect_robots_txt: true (default) honors target's robots.
• SSRF guard — HttpClient restricts outbound requests to the configured target host(s).
• Custom User-Agent — defaults to VAPTAgent/1.0; override with VAPT_USER_AGENT.
• Encrypted credentials — set safeguards.encrypt_credentials: true.

Always put ANTHROPIC_API_KEY in an env var or .env, never in config.yaml.

---

Project structure

newproject/
├── main.py                    # CLI entry point (interactive + flags)
├── pentest_agent.py           # 7-phase orchestrator
├── scanner_registry.py        # 46 scanner IDs → class mapping
├── config.py / config.yaml    # Layered config (env > yaml > defaults)
├── requirements.txt
├── LICENSE                    # MIT
├── core/                      # HTTP client, LLM interface, sessions, obstacles, suggestions
├── reconnaissance/            # App fingerprinting, endpoint mapping, header analysis, business logic
├── vulnerabilities/           # 11 scanner categories (46 modules + base.py)
├── reporting/                 # Excel generator, summary, JSON export, email delivery
├── utils/                     # Logger, helpers, payload generator, wordlists, secret patterns
└── reports/                   # Generated scan output (gitignored, .gitkeep preserved)

---

Development

After editing requirements.txt, regenerate the venv:

deactivate
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Adding a new scanner:

1. Create vulnerabilities/<category>/<your_scanner>.py with a class that inherits from vulnerabilities.base.BaseScanner.
2. Register it in scanner_registry.SCANNERS with a stable id.
3. Add it to config.yaml under modules.<category>.
4. Open a PR.

---

License

MIT — see LICENSE for the full text.

Project home: https://rashedtech.com/

---

Disclaimer

This software is provided for authorized security testing only. Running it against systems you do not own or are not explicitly authorized to test may violate computer-misuse laws in your jurisdiction (e.g., the U.S. Computer Fraud and Abuse Act, the EU Directive 2013/40/EU, the UK Computer Misuse Act, India's IT Act §66, etc.). The maintainers disclaim all liability for misuse.