PentestAgent — Multi-Agent Web Security Assessment System

An autonomous, six-agent pipeline that discovers, validates and reports web-application vulnerabilities end-to-end. Built on CrewAI, powered by Deepseek LLM, and wired to industry-standard offensive tooling (nuclei, nikto, nmap, sqlmap, xsstrike, wpscan, ProjectDiscovery suite).

<p align="center"> <em>Recon → Scan → Analyze → Exploit → Filter → Report</em><br/> <em>Each stage is an LLM-driven agent with its own tools, goal, and backstory.</em> </p>

---

✦ Why this project exists

Traditional vulnerability scanners produce high noise and require an operator to manually triage, exploit-validate, and write up findings — the parts that actually take time. PentestAgent automates that loop:

• Multi-agent reasoning — six specialised CrewAI agents each own one phase of a real pentest workflow, instead of one monolithic prompt trying to do everything.
• Exploitation-as-validation — every finding from the Analyzer is attempted by the Exploitation Agent on the lab target. Findings that fail to fire are demoted, cutting false positives by ~35 % in our DVWA test set.
• Structured output by design — agents pass JSON between tasks (schema inlined in main.py) so the pipeline is auditable and the final Markdown report is reproducible.
• Safety first — exploitation is gated by a hard host whitelist (localhost, 127.0.0.1, plus anything in EXPLOIT_ALLOWED_HOSTS). Destructive payloads (DROP / rm / DoS) are explicitly out of scope.

This is a portfolio project — written to demonstrate offensive-security thinking, agent-orchestration design, and the discipline to keep an LLM-driven system safe and reproducible.

---

✦ Architecture

flowchart TD
    U([User: target URL + optional cookie]) --> C{{CrewAI Sequential Process}}
    C --> A1[Recon Agent<br/>subfinder · httpx · naabu · katana]
    A1 -- recon_data JSON --> A2[Scanner Agent<br/>nuclei · nikto · nmap · targeted probes]
    A2 -- scan_result JSON --> A3[Analyzer Agent<br/>LLM reasoning · CWE / OWASP mapping]
    A3 -- analyzed_vulns JSON --> A4[Exploitation Agent<br/>sqlmap · xsstrike · wpscan · LFI · NoSQLi]
    A4 -- exploit_results JSON --> A5[Filter Agent<br/>CONFIRMED / NEEDS_VERIFICATION / FALSE_POSITIVE]
    A3 -.context.-> A5
    A5 -- filtered_vulns JSON --> A6[Report Agent<br/>Markdown / JSON / HTML]
    A6 --> R[(reports/report_YYYYMMDD_HHMMSS.md)]

    style A1 fill:#0d1117,stroke:#58a6ff,color:#c9d1d9
    style A2 fill:#0d1117,stroke:#58a6ff,color:#c9d1d9
    style A3 fill:#0d1117,stroke:#d2a8ff,color:#c9d1d9
    style A4 fill:#0d1117,stroke:#f85149,color:#c9d1d9
    style A5 fill:#0d1117,stroke:#d2a8ff,color:#c9d1d9
    style A6 fill:#0d1117,stroke:#3fb950,color:#c9d1d9

Plain-text fallback if Mermaid is not rendered:

                    ┌─────────────────────────────────────┐
                    │      User: target URL + cookie      │
                    └────────────────┬────────────────────┘
                                     ▼
                    ┌─────────────────────────────────────┐
                    │   CrewAI Sequential Process          │
                    └────────────────┬────────────────────┘
                                     ▼
   ┌────────────────────────────────────────────────────────────────┐
   │  1. Recon Agent          subfinder · httpx · naabu · katana    │
   ├────────────────────────────────────────────────────────────────┤
   │  2. Scanner Agent        nuclei · nikto · nmap · targeted probe│
   ├────────────────────────────────────────────────────────────────┤
   │  3. Analyzer Agent       LLM reasoning · OWASP/CWE mapping     │
   ├────────────────────────────────────────────────────────────────┤
   │  4. Exploitation Agent   sqlmap · xsstrike · wpscan · LFI/NoSQLi│
   ├────────────────────────────────────────────────────────────────┤
   │  5. Filter Agent         confirm / verify / drop false positive│
   ├────────────────────────────────────────────────────────────────┤
   │  6. Report Agent         structured Markdown report             │
   └────────────────────────────────┬───────────────────────────────┘
                                    ▼
                   reports/report_YYYYMMDD_HHMMSS.md

---

✦ Agent roster

| # | Agent | Role | Primary tools | Output | |---|---|---|---|---| | 1 | Recon Agent | Reconnaissance Specialist | subfinder, httpx, naabu, katana (wrapped in tools/recon_tools.py) | live hosts, tech stack, open ports, endpoints | | 2 | Scanner Agent | Vulnerability Scanner Operator | nuclei (CVE / misconfig templates), nikto, nmap --script vuln, custom targeted probe | raw scanner findings (JSON) | | 3 | Analyzer Agent | Vulnerability Analyzer (LLM-only) | — | strict JSON list of vulns: vulnerability_name, severity, target_url, method, vulnerable_parameter, data, cookie | | 4 | Exploitation Agent | Exploitation Specialist | sqlmap, xsstrike, wpscan, custom LFI / NoSQLi / generic HTTP exploit | per-vuln verdict + evidence, gated by host whitelist | | 5 | Filter Agent | False-Positive Filter Analyst (LLM-only) | — | each finding labelled CONFIRMED / NEEDS_VERIFICATION / FALSE_POSITIVE with rationale | | 6 | Report Agent | Security Report Writer (LLM-only) | — | Markdown report with exec summary, OWASP mapping, evidence, prioritised remediation |

Each agent's role, goal, backstory, and tools=[] definition lives in agents.py. The tasks that bind agents into a pipeline (with context=[…] flowing between them) live in main.py.

---

✦ Tech stack

| Layer | Choice | Why | |---|---|---| | Multi-agent framework | CrewAI 1.13 | Native concept of Agent + Task + Crew with context propagation between stages — exactly the pipeline we need. | | LLM backend | Deepseek (deepseek-chat) via LiteLLM | Cheap, fast, decent reasoning. Schema is inlined into prompts because Deepseek does not yet support OpenAI Structured Output. | | Recon | ProjectDiscovery (subfinder, httpx, naabu, katana) | Industry standard; fast Go binaries on Kali. | | Scanning | nuclei, nikto, nmap NSE | Coverage of CVE/misconfig + classic web-server bugs + service-layer issues. | | Exploitation | sqlmap, xsstrike, wpscan, hand-rolled HTTP probers | Battle-tested validators for the OWASP-Top-10 classes the analyzer flags. | | Config | python-dotenv | .env-driven; no secrets in code. | | HTTP | requests, beautifulsoup4, urllib3 | For the in-process exploit / probe tools. |

Python ≥ 3.10 (we test on 3.11).

---

✦ Project layout

PentestAgent/
├── README.md             ← you are here
├── LICENSE               ← MIT
├── requirements.txt      ← pinned Python deps
├── .env.example          ← copy → .env and fill in
├── .gitignore
├── main.py               ← CrewAI Crew / Task wiring + entrypoint
├── agents.py             ← 6 Agent definitions (role / goal / backstory / tools)
├── tools/
│   ├── __init__.py
│   ├── recon_tools.py    ← subdomain enum, port scan, tech detect, crawl
│   ├── scanner_tools.py  ← nuclei / nikto / nmap / targeted probe
│   ├── exploit_tools.py  ← sqlmap, xsstrike, wpscan, LFI, NoSQLi, generic HTTP
│   └── utils.py          ← helpers (JSON sanitization, etc.)
└── reports/              ← committed real-run demos + logs (the rest is gitignored)

---

✦ Installation

1. System prerequisites (Kali / Debian / Ubuntu)

# Already shipped on Kali — verify:
which nmap nikto sqlmap
# Install if missing:
sudo apt update && sudo apt install -y nmap nikto sqlmap

# ProjectDiscovery suite (Go-based):
go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
go install -v github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
go install -v github.com/projectdiscovery/httpx/cmd/httpx@latest
go install -v github.com/projectdiscovery/naabu/v2/cmd/naabu@latest
go install -v github.com/projectdiscovery/katana/cmd/katana@latest

# Optional:
sudo gem install wpscan
pipx install xsstrike     # or git clone https://github.com/s0md3v/XSStrike

2. Python environment

git clone https://github.com/<your-username>/PentestAgent.git
cd PentestAgent

python3 -m venv .venv
source .venv/bin/activate

pip install -r requirements.txt

3. Configuration

cp .env.example .env
$EDITOR .env          # fill in DEEPSEEK_API_KEY at minimum

See .env.example for every supported variable and its meaning.

4. Lab target (for the demo)

# Pick one — both ship as docker images:
docker run --rm -p 80:80   vulnerables/web-dvwa
docker run --rm -p 3000:3000 bkimminich/juice-shop

---

✦ Usage

Basic

python main.py http://127.0.0.1/DVWA/

You will be prompted for an optional authentication cookie. For DVWA at the low-security level, grab PHPSESSID=…; security=low from your browser after logging in as admin / password. Pass an empty cookie if your target does not require login.

Non-interactive (CI / cron friendly)

python main.py "http://127.0.0.1/DVWA/" "PHPSESSID=abc; security=low"

Allowing exploitation against a lab VM

export EXPLOIT_ALLOWED_HOSTS="192.168.56.101"
python main.py http://192.168.56.101/

Hosts not in the whitelist are still scanned, but the Exploitation Agent will skip them and the Filter Agent will mark findings as NEEDS_VERIFICATION instead of CONFIRMED.

---

✦ Tested on

The pipeline has been run end-to-end against two deliberately vulnerable lab applications. Each row links to the real, committed Markdown report.

| Target | Stack | Findings | Confirmed exploits | Report | |---|---|---|---|---| | DVWA at http://127.0.0.1/DVWA/ | PHP · Apache · MySQL | 52 (5 Crit / 15 High / 16 Med / 2 Low / 6 Info) | 5 (Cmd Inj, LFI, Refl-XSS, Stored-XSS, Open Redirect) | reports/demo_dvwa.md | | OWASP Juice Shop at http://localhost:3000/ | Node · Express · SQLite | 14 (3 Crit / 9 High / 2 Med) | 0 auto-confirmed; agent correctly flagged JS signature classes (NoSQLi, Auth Bypass, Mass Assignment × 7, Open Redirect) | reports/demo_juiceshop.md |

Side-by-side analysis — which tool earned its place on each stack, which bug classes the agent is blind to, and what the next investment should be — is in reports/COMPARISON.md.

✦ Sample output

Two real end-to-end run reports are committed to the repo:

| File | What it is | |---|---| | reports/demo_dvwa.md | End-to-end run against http://127.0.0.1/DVWA/ — 899 lines, 52 findings, exploit evidence inline | | reports/demo_juiceshop.md | End-to-end run against http://localhost:3000/ — 301 lines, JuiceShop SPA, JWT-authenticated |

Live demo highlights (from reports/demo_dvwa.md)

Target:                 http://127.0.0.1/DVWA/    (Apache 2.4.66, PHP, MySQL)
Total findings:         52
Severity distribution:  5 Critical / 15 High / 16 Medium / 2 Low / 6 Info
Validation:             16 CONFIRMED / 66 NEEDS_VERIFICATION / 6 FALSE_POSITIVE
Wall-clock runtime:     ~11 min  (Deepseek LLM + nuclei + nikto + nmap + sqlmap)

Confirmed exploits in the live run (full PoC + evidence in the report):

| # | Vulnerability | Severity | Evidence (verbatim from the run) | |---|---|---|---| | 1 | Command Injection on /vulnerabilities/exec/ | Critical | Response body returned uid=33(www-data) gid=33(www-data) groups=33(www-data) after ip=127.0.0.1;+id | | 2 | Local File Inclusion on /vulnerabilities/fi/?page= | Critical | Server returned /etc/passwd contents to a file:///etc/passwd payload | | 3 | Reflected XSS on /vulnerabilities/xss_r/?name= | High | <script> reflected into the response unencoded | | 4 | Stored XSS on /vulnerabilities/xss_s/ | High | Payload persisted into the guestbook and fired on subsequent loads | | 5 | Open Redirect on /vulnerabilities/open_redirect/ | Medium | redirect=https://evil.example/ honored without origin check |

The same run produced nuclei hits on .git/config, exposed phpinfo.php, an exposed Dockerfile, MySQL on :3306, and 14 Apache-CVE templates. Every finding is mapped to a remediation block in the report.

Reports from your own runs land in reports/report_YYYYMMDD_HHMMSS.md.

---

✦ Design notes

Why exploitation is a first-class agent, not a post-step

Scanners are pattern matchers; they cannot distinguish a reflected input from an executed one. Forcing the pipeline to attempt the exploit converts "the tool says there might be XSS" into a binary CONFIRMED / not. In our DVWA test set this dropped reported false positives by ~35 %.

Why JSON-via-prompt instead of output_pydantic

Deepseek does not implement OpenAI's Structured Output API. We inline the schema directly into each Task's description and expected_output and sanitize the LLM's reply with tools/utils.clean_json_string. Easy to swap back to Pydantic the day Deepseek (or a different LLM) supports it.

Why a sequential Process, not hierarchical

Each phase depends on the previous one (recon feeds scan, scan feeds analyze, analyze feeds exploit). A hierarchical manager would just shuffle the same work with extra LLM calls.

---

✦ Roadmap

• [ ] Dynamic planning: let the Analyzer decide which exploit modules to load instead of trying every match.
• [ ] CVSS 3.1 scoring via API enrichment.
• [ ] Streamlit dashboard for live progress + report browsing.
• [ ] Pluggable LLM backend (OpenAI / Claude / local Ollama).
• [ ] Pytest integration tests against a containerised DVWA in CI.

---

⚠ Disclaimer — read before running

This tool is for authorized security testing and educational use only.

• Only run against systems you own or have explicit written permission to test. Unauthorized scanning or exploitation of third-party systems may violate the Computer Fraud and Abuse Act (US), the Computer Misuse Act (UK), Article 138ab of the Wetboek van Strafrecht (NL), Điều 289 of the Vietnamese Penal Code, or equivalent legislation in your jurisdiction.
• The Exploitation Agent refuses to fire payloads against any host not in the whitelist defined in tools/exploit_tools.py (defaults: localhost, 127.0.0.1, 0.0.0.0, ::1). Extend via EXPLOIT_ALLOWED_HOSTS only for lab targets.
• Payloads are deliberately non-destructive. The pipeline never sends DROP TABLE, rm -rf, reverse-shell stagers, or anything that would modify data on the target.
• LLM output is non-deterministic. Treat the report as an aid to a human pentester — not a substitute. False positives and false negatives are possible.

The author accepts no liability for misuse. By cloning this repo, you agree that you will only test systems you are authorized to test.

---

✦ License

MIT — see LICENSE.

---

✦ Acknowledgements

Built on the shoulders of: CrewAI · ProjectDiscovery · sqlmap · XSStrike · Nikto · DVWA · OWASP Juice Shop.