# Pentest-Suite

<p align="center">
  <img src="assets/banner.png" alt="pentest-suite banner" width="100%">
</p>

<p align="center">
  <strong>Modular Attack Surface Discovery & Vulnerability Intelligence in Pure Python Standard Library</strong>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/python-3.15+-blue.svg" alt="Python 3.15+">
  <img src="https://img.shields.io/badge/dependencies-zero%20(stdlib%20only)-success.svg" alt="Zero Dependencies">
  <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License MIT">
  <img src="https://img.shields.io/badge/MCP-JSON--RPC%202.0-blueviolet.svg" alt="MCP Server">
  <img src="https://img.shields.io/badge/threat%20intel-CISA%20KEV%20%7C%20cve.now-orange.svg" alt="Threat Intel">
  <img src="https://img.shields.io/badge/taxonomy-MITRE%20ATT%26CK-red.svg" alt="MITRE ATT&CK">
</p>

---

**Pentest-Suite** is a lightweight, zero-dependency cybersecurity toolkit designed for attack surface reconnaissance, active host qualification, port enumeration, content discovery, template-based vulnerability scanning, and threat intelligence enrichment.

Built in pure Python standard library (`urllib`, `concurrent.futures`, `socket`, `ssl`), it runs everywhere with zero compilation, no external package bloat, and predictable execution. It is the offensive security counterpart of `osint-suite` (sharing the same core engine, session models, correlation logic, and Markdown/Mermaid reporting).

---

## ⚡ Key Highlights

- **Pure Python Standard Library**: Zero third-party dependencies. No `pip install`, no C/Rust toolchains. Runs with Python ≥ 3.15 or via [uv](https://docs.astral.sh/uv/).
- **Safe & Benign Active Probing**: Non-destructive full TCP-connect scans, soft-404 baseline calibration, conservative wordlists, and strict authorization banners.
- **Threat Intelligence Engine**: Integrated live lookups via [sazabi/cve.now](https://cve.now) (CVSS scores, Exploit-DB links, EPSS probability, AI summaries) and official [CISA KEV](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) feeds without requiring API keys.
- **Autonomous OODA Loop**: Deterministic **Observe-Orient-Decide-Act** orchestration (`chain`) that dynamically adapts scan depth based on observed target signals.
- **Native AI Agent MCP Server**: Stdio JSON-RPC 2.0 Model Context Protocol server exposing `probe`, `ports`, `dirs`, `tmpl`, and `kev` as first-class tools for AI coding assistants (Claude Code, Cursor, Codex).
- **MITRE ATT&CK Tagging**: Automated tagging of findings and recon phases to Enterprise ATT&CK techniques (T1595, T1046, T1552, T1190).
- **CI/CD Security Gate**: Exits with return code `2` on high or critical findings for automated DevSecOps pipelines.
- **Multi-Format Deliverables**: Every run produces structured session JSON, executive Markdown briefings, and interactive Mermaid topology graphs in `reports/`.

---

## 🧭 Architecture & Upstream Inspirations

`pentest-suite` faithfully re-implements the core mechanics and operating principles of industry-standard tools within the Python standard library:

| Upstream Project | Re-implemented Concept | Implementation |
|---|---|---|
| [projectdiscovery/nuclei](https://github.com/projectdiscovery/nuclei) | Detection logic decoupled into declarative JSON templates with `status`, `contains`, and `regex` matchers | [`modules/tmpl/`](file:///d:/GIT/pentest-suite/pentest_suite/modules/tmpl) + [`config/templates/`](file:///d:/GIT/pentest-suite/pentest_suite/config/templates) |
| [projectdiscovery/httpx](https://github.com/projectdiscovery/httpx) | Concurrent HTTP host qualification: status code, HTML title, server header, technology markers | [`modules/probe/`](file:///d:/GIT/pentest-suite/pentest_suite/modules/probe) |
| [projectdiscovery/naabu](https://github.com/projectdiscovery/naabu) + [nmap/nmap](https://github.com/nmap/nmap) | Multi-threaded TCP connect scan, service identification, banner grabbing, and flagged port classification | [`modules/ports/`](file:///d:/GIT/pentest-suite/pentest_suite/modules/ports) + [`config/ports.json`](file:///d:/GIT/pentest-suite/pentest_suite/config/ports.json) |
| [ffuf/ffuf](https://github.com/ffuf/ffuf) / [feroxbuster](https://github.com/epi052/feroxbuster) | Wordlist content discovery with soft-404 baseline calibration and response size filtering (`--filter-size`) | [`modules/dirs/`](file:///d:/GIT/pentest-suite/pentest_suite/modules/dirs) + [`config/wordlist.txt`](file:///d:/GIT/pentest-suite/pentest_suite/config/wordlist.txt) |
| [sazabi/cve.now](https://github.com/sazabi/cve.now) + [CISA KEV](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) | Real-time threat intelligence lookup (CVSS, EPSS, Exploit-DB, CISA KEV) and critical technology feeds | [`modules/intel/`](file:///d:/GIT/pentest-suite/pentest_suite/modules/intel) |
| [irraz/vulnerator-ai](https://github.com/irraz/vulnerator-ai) | Deterministic OODA loop orchestration, stdio MCP server for autonomous agents, MITRE ATT&CK taxonomy | [`core/chain.py`](file:///d:/GIT/pentest-suite/pentest_suite/core/chain.py), [`mcp_server.py`](file:///d:/GIT/pentest-suite/pentest_suite/mcp_server.py), [`core/attack.py`](file:///d:/GIT/pentest-suite/pentest_suite/core/attack.py) |

---

## ⚠️ Responsible Use

> **CRITICAL**: This toolkit is strictly intended for security testing against systems you have explicit, documented authorization to assess (your own infrastructure, authorized penetration testing scopes, or bug bounty programs within scope).
>
> Active probes are deliberately non-destructive: standard TCP handshakes only (no raw sockets or forged packets by default), safe wordlists, and no exploit payloads. Every active command requires and displays an authorization banner.

---

## 🚀 Installation

Managed with [uv](https://docs.astral.sh/uv/) (Python ≥ 3.15, committed `uv.lock`):

```bash
git clone https://github.com/laurentvv/pentest-suite.git
cd pentest-suite
uv sync
uv run pentest-suite --version
```

*Alternative without uv (using your system Python 3.15+ directly)*:
```bash
python -m pentest_suite --version
```

---

## 🛠️ Usage & CLI Reference

### 1. HTTP Host Qualification (`probe`)
Sondes a comma-separated list of targets over HTTPS and HTTP:
```bash
uv run pentest-suite probe example.com,api.example.com
```

### 2. TCP Port Scanning & Banner Grabbing (`ports`)
Performs a benign multi-threaded TCP connect scan:
```bash
uv run pentest-suite ports example.com
uv run pentest-suite ports example.com --ports 80,443,8000-8100 --workers 50
```

### 3. Path Discovery with Soft-404 Baseline (`dirs`)
Discovers hidden endpoints, calibrating against soft-404 behaviors:
```bash
uv run pentest-suite dirs https://example.com
uv run pentest-suite dirs https://example.com --filter-size 150032,155455 --workers 12
```

### 4. Template-Based Detection (`tmpl`)
Scans against embedded nuclei-style JSON checks (`git-exposed`, `env-exposed`, `actuator-exposed`, `server-status`, etc.):
```bash
uv run pentest-suite tmpl https://example.com
uv run pentest-suite tmpl https://example.com --only git-exposed,env-exposed
```
*Note: Returns exit code `2` if `high` or `critical` vulnerabilities are detected.*

### 5. Threat Intelligence & Vulnerability Lookup (`kev`)
Queries [cve.now](https://cve.now) and [CISA KEV](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) feeds (100% passive, read-only):
```bash
# Instant enriched CVE lookup (CVSS score, Exploit-DB IDs, EPSS, summary)
uv run pentest-suite kev CVE-2024-6387
uv run pentest-suite kev --cve CVE-2021-44228

# Critical vulnerabilities feed for a specific tracked technology
uv run pentest-suite kev nginx
uv run pentest-suite kev spring

# Search the official CISA KEV catalog by vendor or keyword
uv run pentest-suite kev tomcat --source cisa
```

### 6. Full Autonomous OODA Chain (`chain`)
Executes the deterministic Observe-Orient-Decide-Act workflow:
```bash
uv run pentest-suite chain example.com
```

**How the OODA loop decides**:
1. **Observe**: Probes host reachability. If unreachable, halts immediately to prevent futile scans.
2. **Orient**: Identifies open ports and detected server technologies.
3. **Decide / Act**: Web port open? Run template checks. If a high/critical issue is found, prioritizes alerting and skips brute-force directory discovery. Otherwise, proceeds to directory fuzzing.
4. **Orient Final**: Detected technologies are cross-referenced with CISA KEV and `cve.now` feeds.

---

## 🤖 Model Context Protocol (MCP) Server

`pentest-suite` includes a built-in stdio MCP server (JSON-RPC 2.0) that allows AI coding agents (Claude Code, Cursor, Codex, Windsurf) to pilot penetration testing workflows safely.

### Claude Code Configuration (`~/.claude.json` or `.mcp.json`):
```json
{
  "mcpServers": {
    "pentest-suite": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/pentest-suite", "pentest-suite", "mcp"]
    }
  }
}
```

### Exposed MCP Tools:
- `probe`: Qualifies HTTP hosts (status, title, banner, technologies).
- `ports`: Multi-threaded TCP connect port scanner.
- `dirs`: Wordlist path discovery with soft-404 size filtering.
- `tmpl`: Nuclei-style JSON template scanner.
- `kev`: CISA KEV and cve.now vulnerability intelligence lookup.

*Security Invariant: The tool registry is strictly bounded. No arbitrary shell execution tools are exposed.*

---

## 📁 Repository Structure

```
pentest-suite/
├── assets/
│   └── banner.png             # Project banner
├── pentest_suite/
│   ├── cli.py                 # CLI entry points and command handlers
│   ├── mcp_server.py          # Stdio JSON-RPC 2.0 MCP server implementation
│   ├── config/
│   │   ├── attack.json        # MITRE ATT&CK taxonomy mapping
│   │   ├── ports.json         # Default & flagged sensitive ports list
│   │   ├── wordlist.txt       # Embedded path discovery wordlist
│   │   └── templates/         # Nuclei-style JSON detection templates
│   ├── core/                  # Engine shared with osint-suite
│   │   ├── attack.py          # MITRE ATT&CK session tagger
│   │   ├── chain.py           # Deterministic OODA loop orchestrator
│   │   ├── engine.py          # Session runner and event dispatcher
│   │   ├── models.py          # Entity, Finding, and Session models
│   │   ├── plugin.py          # Module registry and base classes
│   │   └── report.py          # Markdown dossier & Mermaid graph generators
│   ├── modules/
│   │   ├── probe/             # HTTP host qualification
│   │   ├── ports/             # TCP connect port scanner
│   │   ├── dirs/              # Soft-404 path discovery
│   │   ├── tmpl/              # Template matcher engine
│   │   └── intel/             # CISA KEV & cve.now threat intelligence
│   └── utils/
│       └── http.py            # Stdlib HTTP client & thread pool runner
├── tests/
│   └── test_core.py           # Offline unit tests
├── pyproject.toml             # Project metadata & packaging configuration
└── README.md
```

---

## 🧩 Extending Pentest-Suite

### Adding a Detection Template
Create a JSON file in `pentest_suite/config/templates/`:
```json
{
  "id": "custom-check",
  "info": {
    "name": "Exposed Configuration File",
    "severity": "high",
    "remediation": "Restrict public access to this path."
  },
  "requests": [
    { "path": "/config.json", "method": "GET" }
  ],
  "matchers": [
    { "type": "status", "status": [200] },
    { "type": "contains", "words": ["\"database\":", "\"secret\":"], "any": false }
  ]
}
```

### Adding a Custom Module
Subclass `BaseModule` and decorate with `@register`:
```python
from pentest_suite.core.plugin import BaseModule, register

@register
class MyScannerModule(BaseModule):
    name = "myscan"
    description = "Custom passive analyzer."
    target_hint = "<target>"

    def run(self, target: str, session, options: dict):
        session.add_entity("custom", target, "myscan")
        session.note("Custom scan completed.")
        return []
```

---

## 🧪 Testing

Run the full offline test suite:
```bash
uv run python -m unittest discover -s tests -v
```

All unit tests run completely offline and verify models, deduplication, correlation, report generation, soft-404 logic, template matchers, and threat intelligence fallbacks in under 0.1s.

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).