Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@pentest-suite probe example.com and scan its common ports for open services"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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).
Pure Python Standard Library: Zero third-party dependencies. No pip install, no C/Rust toolchains. Runs with Python ≥ 3.15 or via 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 (CVSS scores, Exploit-DB links, EPSS probability, AI summaries) and official CISA KEV 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/.
Related MCP server: mcp-shodan
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 |
Detection logic decoupled into declarative JSON templates with | ||
Concurrent HTTP host qualification: status code, HTML title, server header, technology markers | ||
Multi-threaded TCP connect scan, service identification, banner grabbing, and flagged port classification | ||
Wordlist content discovery with soft-404 baseline calibration and response size filtering ( | ||
Real-time threat intelligence lookup (CVSS, EPSS, Exploit-DB, CISA KEV) and critical technology feeds | ||
Deterministic OODA loop orchestration, stdio MCP server for autonomous agents, MITRE ATT&CK taxonomy |
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.
Managed with uv (Python ≥ 3.15, committed uv.lock):
git clone https://github.com/laurentvv/pentest-suite.git
cd pentest-suite
uv sync
uv run pentest-suite --versionAlternative without uv (using your system Python 3.15+ directly):
python -m pentest_suite --versionprobe)Sondes a comma-separated list of targets over HTTPS and HTTP:
uv run pentest-suite probe example.com,api.example.comports)Performs a benign multi-threaded TCP connect scan:
uv run pentest-suite ports example.com
uv run pentest-suite ports example.com --ports 80,443,8000-8100 --workers 50dirs)Discovers hidden endpoints, calibrating against soft-404 behaviors:
uv run pentest-suite dirs https://example.com
uv run pentest-suite dirs https://example.com --filter-size 150032,155455 --workers 12tmpl)Scans against embedded nuclei-style JSON checks (git-exposed, env-exposed, actuator-exposed, server-status, etc.):
uv run pentest-suite tmpl https://example.com
uv run pentest-suite tmpl https://example.com --only git-exposed,env-exposedNote: Returns exit code 2 if high or critical vulnerabilities are detected.
kev)Queries cve.now and CISA KEV feeds (100% passive, read-only):
# 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 cisachain)Executes the deterministic Observe-Orient-Decide-Act workflow:
uv run pentest-suite chain example.comHow the OODA loop decides:
Observe: Probes host reachability. If unreachable, halts immediately to prevent futile scans.
Orient: Identifies open ports and detected server technologies.
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.
Orient Final: Detected technologies are cross-referenced with CISA KEV and cve.now feeds.
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.json or .mcp.json):{
"mcpServers": {
"pentest-suite": {
"command": "uv",
"args": ["run", "--directory", "/path/to/pentest-suite", "pentest-suite", "mcp"]
}
}
}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.
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.mdCreate a JSON file in pentest_suite/config/templates/:
{
"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 }
]
}Subclass BaseModule and decorate with @register:
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 []Run the full offline test suite:
uv run python -m unittest discover -s tests -vAll 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.
This project is licensed under the MIT License.
Découverte de chemins (wordlist + filtre soft-404). Cible autorisée uniquement.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| filter_size | No | tailles à ignorer, ex. 150032,155455 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses that the tool uses a wordlist and filters soft-404 responses, and that it requires an authorized target, but it omits request volume, read-only implications, rate limits, and result behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short clauses with the purpose front-loaded and zero wasted words. It is efficient, though the parenthetical and fragmentary authorization note are slightly terse for a security tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No annotations or output schema exist, and one of two parameters lacks schema documentation. The description does not explain result format, wordlist behavior, request characteristics, or sibling-tool distinctions, leaving too much implicit for confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%: filter_size has a schema description, but url does not. The tool description alludes to soft-404 filtering but does not explain either parameter, so it fails to compensate for the undocumented url parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource: 'Découverte de chemins', and adds the technique (wordlist + soft-404 filter). It does not explicitly distinguish itself from sibling tools like probe or tmpl, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Cible autorisée uniquement' provides an authorization precondition, but the description gives no guidance on when to choose this tool over probe, ports, tmpl, or kev. Usage is implied for authorized targets only, not explicitly compared to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recherche dans CISA KEV et cve.now (vulns critiques / activement exploitées). Lecture seule.
| Name | Required | Description | Default |
|---|---|---|---|
| cve | No | CVE exacte, ex. CVE-2021-44228 | |
| keyword | No | mot-clé vendor/produit/techno ou CVE |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden; 'Lecture seule' is a useful disclosure that substitutes for readOnlyHint. It says nothing about how results from the two sources are combined, whether auth or rate limits apply, or what happens when called with zero arguments (both parameters are optional) — a meaningful gap for a federation of two external data sources.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, with the scope front-loaded and no wasted wording. It is terse to the point of under-specification rather than verbose, but the structure itself is clean.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter, no-output-schema lookup tool this covers the essentials of what it searches, but leaves unstated the merged return shape of two separate sources and the no-argument behavior. Adequate, with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters documented including an exact-CVE example, so the schema does the heavy lifting. The description adds no semantics about parameter interaction or precedence (e.g., cve vs keyword), so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the specific resource (CISA KEV and cve.now) and the operation (recherche) plus the domain (vulns critiques / activement exploitées), which rescues the opaque tool name 'kev'. It doesn't explicitly contrast with siblings probe/ports/dirs/tmpl, but those are clearly a different domain (scanning vs. vulnerability lookup).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Lecture seule' implies this is a safe lookup rather than an active scan, and the parenthetical scope hints at the use case. However, there is no explicit statement of when to call this versus when not to, no note on whether both sources are always queried, and no guidance on choosing between the cve and keyword parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan TCP connect + bannières sur les ports courants. Cible autorisée uniquement.
| Name | Required | Description | Default |
|---|---|---|---|
| ports | No | 'default' ou ex. 80,443,8000-8100 | |
| target | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden and does not meet it. It reveals the technique (TCP connect) and that banners are collected, but says nothing about noise/rate, whether the scan is logged by the target, timeouts, or what a result contains. The authorization note is the only behavioral guardrail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action and followed by the safety constraint; nothing is padded. It is efficient, though the brevity is part of why the other dimensions are thin.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and an undescribed required 'target' parameter, the description should explain the return shape (open ports plus banners) and how results are bounded. It instead stops at the action and a legal caveat, leaving an agent unable to predict output or side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: 'ports' is documented with a 'default' sentinel and a range example, while 'target' has no schema description. The description's phrase "ports courants" weakly reinforces the default behavior, but it adds no format or constraint detail for 'target' beyond the authorization caveat.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a concrete verb and resource: a TCP connect scan with banner grabbing against common ports. That is enough for an agent to know it is a port-scanning tool. It does not, however, distinguish itself from the sibling 'probe', which an agent could easily confuse with it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Cible autorisée uniquement" is an authorization prerequisite, not usage guidance: it says who may be scanned, not when to pick this tool over probe/dirs/tmpl/kev. There are no exclusion conditions or alternative routing, so the agent must infer that 'probe' covers whatever this does not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sonde HTTP d'hôtes : statut, titre, bannière, technologies. Cible autorisée uniquement.
| Name | Required | Description | Default |
|---|---|---|---|
| targets | Yes | hôtes séparés par des virgules |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It discloses the collected data types and requires an authorized target, but omits whether probing is active or passive, what HTTP requests are made, rate limits, or possible side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences front-load the core purpose and then state the authorization constraint. Every phrase earns its place with no redundant explanation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only one parameter and no output schema, so the description reasonably lists the returned fields. However, for an HTTP probing tool it lacks important context about target format (host vs URL), protocol handling, and whether HTTPS or specific ports are attempted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the single 'targets' parameter is already documented as comma-separated hosts. The description adds no further syntax, format, or protocol guidance beyond the schema, making 3 the appropriate baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Sonde HTTP d'hôtes') and lists the outputs it collects: status, title, banner, and technologies. This clearly distinguishes it from non-HTTP siblings such as ports and dirs, though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It includes the authorization constraint 'Cible autorisée uniquement', which is useful when-not guidance. However, it does not explain when to choose probe over sibling tools like ports, dirs, tmpl, or kev.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Détections par templates JSON façon nuclei. Cible autorisée uniquement.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| only | No | ids de templates, ex. git-exposed,env-exposed |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations at all, so the description carries the full burden. It hints that only authorized targets may be scanned, but never states whether the scan is intrusive, whether templates can modify the target, expected runtime, or what a detection result looks like. For a scanning tool with zero structured safety metadata this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no padding or redundancy, and the nuclei analogy is front-loaded. But the second sentence is an ambiguous constraint that reads almost as a restatement of the 'only' parameter, so the terseness comes at the cost of clarity rather than being purely economical.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema and half the parameters undescribed, the burden falls entirely on two short sentences that omit what the tool returns, how templates are selected, and how it relates to the other scanning tools. For an inherently complex detection tool this is far from complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: 'only' has an example value in the schema, while 'url' is completely undocumented. The description adds nothing – it never mentions 'only', and the phrase 'cible autorisée uniquement' is easily confused with the 'only' parameter in French. The description does not compensate for the undocumented target parameter or clarify the template-id format beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description says it performs detections via JSON templates in the manner of nuclei, which does let an agent infer a template-driven vulnerability/detection scan. But the verb is nominal ('Détections') and the tool name 'tmpl' is opaque, so the resource being operated on (a target URL) is only implicitly conveyed by the required 'url' param. It is not distinguished from siblings probe/dirs/ports, all of which also take a target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Cible autorisée uniquement' is a legal/permission constraint, not usage guidance – it never says when to prefer tmpl over probe, dirs or kev, nor what preconditions (e.g. target must be enumerated first) apply. An agent gets no routing signal from this text.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0dirskevportsprobetmplScored across 5 tools
Each tool targets a fairly distinct recon phase (HTTP probe, port scan, path discovery, template checks, vuln lookup). Minor overlap exists between probe and ports since both grab banners, and 'tmpl' is vague without reading its description.
All five names are single lowercase noun-like tokens following a consistent terse style. They deviate from a verb_noun convention, but the pattern itself is uniform and predictable.
Five tools is a lean but reasonable set for a recon/vuln-detection suite, and each earns its place. It's on the thin side for a 'pentest suite' but not mismatched.
Covers host probing, port scanning, dir discovery, template detections, and KEV lookup, but notable gaps remain: no subdomain/host enumeration, no exploitation/validation step, and no reporting or result aggregation.
CVE lookups (NVD) and dependency-manifest audits (OSV) for AI agents. No API keys.
CVE lookups (NVD) and dependency-manifest audits (OSV) for AI agents. No API keys.
AI pentesting: run scans, triage vulnerabilities, review PRs, manage schedules and assets.
Real-time CVE, exploit, and vulnerability intelligence for AI assistants (350K+ CVEs, 115K+ PoCs)
