Web Pentest MCP Server

README.md

# 🛡️ Controlled Web Pentest & Bug Bounty MCP Framework

[English](README.md) | [Tiếng Việt](README.vi.md)

[![OWASP WSTG v4.2](https://img.shields.io/badge/OWASP-WSTG%20v4.2%20(115%20Tests)-007acc.svg)](https://owasp.org/www-project-web-security-testing-guide/)
[![Model Context Protocol](https://img.shields.io/badge/MCP-FastMCP%20Integrated-green.svg)](https://modelcontextprotocol.io/)
[![Architecture](https://img.shields.io/badge/Architecture-Ontology%20%26%20IPOD%20Cycle-orange.svg)](#core-philosophy-ontology-driven-security)
[![Evidence Standard](https://img.shields.io/badge/Forensics-SHA256%20Cryptographic%20Evidence-purple.svg)](#evidence-first-forensics)
[![License](https://img.shields.io/badge/License-Proprietary%20%2F%20Commercial-red.svg)](#license)

> **Controlled, Evidence-First AI Security Agent for Professional Bug Bounty Hunters & Enterprise Web Application Penetration Testing.**

---

## 🌟 Core Philosophy: Ontology-Driven Security

Traditional automated vulnerability scanners and LLM-wrapper scripts suffer from severe hallucination, noisy false positives, and dangerous out-of-scope probes.

This Framework is architected upon **Security Ontology & the IPOD Cycle**:
* **Constants vs Variables:** Security is the preservation of invariant system constants. Vulnerabilities are missing constraints (*Missing Constants*) at specific execution junctures.
* **The IPOD Cycle:** Every finding is mapped directly across **Input** (Parameters/Headers) $\rightarrow$ **Process** (Auth/Parser/Query) $\rightarrow$ **Output** (Leak/Crash/Reflection) $\rightarrow$ **Data** (PII/Secret/State) $\rightarrow$ **Loop** (Stored drift).
* **Deterministic Boundary Protection:** Pure Python non-LLM gatekeepers (`ScopeGuard` & `ToolGateway`) strictly enforce boundary permissions, preventing session self-destruction (`/logout`) and third-party SaaS pollution.

---

## 🎯 Human-in-the-Loop Architecture: The 3 Checkpoints

```
[Target Program] ──► [Checkpoint 1: Scope & Rules Authorization]
                             │ (Approved)
                             ▼
                     [Reconnaissance Pipeline] (crt.sh, subfinder, dnsrecon, httpx)
                             │
                             ▼
                     [Noise Filter & Parameter Normalization]
                             │
                             ▼
                     [Checkpoint 2: Attack Surface Triage] ◄── [Senior Pentester Review]
                             │ (Approved Entry Points)
                             ▼
                     [Granular WSTG Security Scanners]
                             │
                             ▼
                     [Checkpoint 3: Safe PoC Execution & Evidence Lock]
                             │
                             ▼
                     [OWASP Risk Engine & Dual-Rating] (CVSS v3.1 + VRT P1-P5)
```

1. **Checkpoint 1 (Scope Guardrail):** Authorizes program boundary, wildcards, CIDR networks, and strict out-of-scope exclusions.
2. **Checkpoint 2 (Surface Triage):** Filters static noise (`.png`, `.css`), deduplicates dynamic paths (`/item?id={val}`), and surfaces flagged sensitive entry points (`auth`, `upload`, `admin`, `idor`) for human approval before scanning.
3. **Checkpoint 3 (PoC & Evidence Verification):** Requires explicit human confirmation prior to firing active payloads, locking raw HTTP responses and CLI output with cryptographic SHA-256 signatures.

---

## 🚀 Key Technical Features

* **Full OWASP WSTG v4.2 Coverage:** 115 test cases pre-seeded with official documentation URLs and objectives.
* **Master Orchestrator Interface:** High-level FastMCP tools reducing token consumption by >80% while preserving deep forensic inspection.
* **Hybrid Evidence Engine:** Dual-layer recording supporting raw CLI execution stdout with SHA-256 hashes and 1-click reproducible `cURL` commands for one-shot Bug Bounty triage.
* **Contextual OWASP Risk Rating:** 16 granular threat/vulnerability factors adjusted dynamically by Asset Criticality (Tier 1-3) and Data Sensitivity (Level 1-4).
* **Enterprise SQLite Foundation:** Native WAL (Write-Ahead Logging) mode, enforced foreign key integrity, and zero-redundancy fingerprint deduplication (`UNIQUE(fingerprint_hash)`).

---

## 🛠️ MCP Tools Overview (9 Registered Tools)

| Tool Name | Type | Description |
| :--- | :---: | :--- |
| `manage_pentest_program` | Lifecycle | View, create, update, and manage bug bounty/client engagement programs. |
| `manage_scope_targets` | Scope | Manage in-scope whitelist, CIDR blocks, and out-of-scope restrictions. |
| `run_surface_recon` | Recon | Multi-source subdomain discovery and live HTTP probing with static noise filtering. |
| `triage_surface_entry_points` | **Checkpoint 2** | Inspect, approve, or reject discovered sensitive entry points. |
| `run_pentest_pipeline` | Pipeline | 1-Click execution across authorized surface profiles (`recon_quick`, `recon_deep`). |
| `run_wstg_test` | Granular | On-demand execution or re-testing of specific WSTG codes (`WSTG-INFO-01..08`, `CONF-07..14`, `CLNT-09`). |
| `get_pentest_dashboard` | Executive | Executive summary of findings distribution, WSTG progress %, and recent evidence. |
| `inspect_finding_or_evidence`| Forensics | Deep inspector retrieving full IPOD analysis and immutable SHA-256 raw logs. |
| `browse_wstg_catalog` | Catalog | Search and lookup 115 OWASP testing methodologies and official reference URLs. |

---

## 💻 Quick Start & Deployment

### 1. Prerequisites
* Kali Linux 2026.x or Debian-based Linux
* Python 3.11+
* Tools: `nmap`, `whatweb`, `wafw00f`, `subfinder`, `httpx-toolkit`

### 2. Installation
```bash
git clone git@github.com:vutiendat284/ai-security-agent-mcp.git
cd ai-security-agent-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

### 3. Launching FastMCP Server
```bash
# stdio mode (Claude Desktop, Antigravity IDE)
python3 -m web_pentest_mcp.server

# streamable-http mode
WEB_PENTEST_MCP_TRANSPORT=streamable-http python3 -m web_pentest_mcp.server
```

---

## 🔒 Confidentiality & Safe Harbors

This repository contains core framework orchestration, boundary enforcement, and reporting engines. Proprietary active exploit payloads, private vulnerability triage databases, and commercial Web SPA modules are maintained separately under commercial licensing.

---

## 📄 License & Author

* **Author:** Senior Web Penetration Tester & AI Security Architect (CPENT, LPT, eWPT, LPIC)
* **License:** Proprietary - All Rights Reserved. Contact author for enterprise commercial deployment.

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored 2026-10-30 15:40 across 10 tools

Disambiguation3/5

Most tools have distinct purposes, but there is meaningful overlap between run_pentest_pipeline and run_wstg_test because the pipeline can target a single WSTG objective while run_wstg_test also runs individual tests. run_surface_recon also partially overlaps with the pipeline's recon scan profiles. Descriptions help clarify when to use each, but an agent could still hesitate between them.

Naming Consistency5/5

All tool names use snake_case and generally follow a verb_noun pattern such as manage_pentest_program, run_wstg_test, get_pentest_dashboard, and export_bugbounty_report. The few compound names like inspect_finding_or_evidence remain readable and consistent with the set.

Tool Count5/5

The set contains 10 tools, which is well within the appropriate range for a focused pentest workflow. Each tool corresponds to a meaningful stage or operation: lifecycle management, scope, scanning, catalog lookup, evidence inspection, triage, and reporting.

Completeness4/5

The surface covers the core pentest lifecycle from program and scope management through scanning, triage, inspection, and reporting. Minor gaps remain around explicitly listing or managing findings beyond inspecting by ID, such as listing all findings or updating finding status, but these are workable given the dashboard and report tools.

Maintenance

ActivityMaintained

ResponsivenessNo issues

TDQS

Maintenance

Resources