Share
## https://sploitus.com/exploit?id=D8A31A04-0F59-5C9A-943B-1C54B80FE425
# pentest-storm
Automated penetration testing exploitation engine for the [Tarmo](https://github.com/Tarmo-Technologies) ecosystem.
pentest-storm orchestrates exploit selection, session management, lateral movement, and credential attacks through a unified CLI. Pentesters define scope and objectives; the engine handles phased tool execution, MSF integration, and auto-ingestion into pentest-scribe.
## Features
- **Host authorization** β database-backed, per-campaign enforcement prevents exploits from targeting unauthorized hosts. Supports individual IPs, hostnames, and CIDRs.
- **Phased scan orchestration** β runs nmap, nikto, gobuster, sqlmap, hydra, and more in dependency order across dns/ports/services/ssl/web/vuln/auth phases.
- **Scan intensity control** β `gentle`, `normal` (default), and `aggressive` modes adjust timing and aggressiveness to avoid crashing fragile targets.
- **Tool dependency management** β discovers installed tools on PATH, validates functionality, and installs missing dependencies.
- **Exploit mapping** β CVE/CWE to Metasploit module mapping with CISA KEV coverage.
- **MSF integration** β Metasploit RPC orchestration for exploit execution and session management.
- **Exploit store** β curated PoC library with Docker-sandboxed execution.
- **Reproduction step generation** β extracts attack-specific repro steps (endpoint, method, payload) from exploit output; includes target URL in verify text.
- **Resume support** β `--resume` re-runs FAILED, TIMEOUT, and SKIPPED tools from a previous run; partial nikto output is recovered on scan timeout.
- **Auto-ingest to pentest-scribe** β scan findings are written into a pentest-scribe SQLite database with engagement tagging via `--scribe-db` and `--scribe-engagement`.
- **MCP server** β 14 workflow-oriented tools for AI agent integration.
- **Idempotent design** β safe re-run with checkβexploitβverifyβcleanup lifecycle.
- **Async execution** β concurrent exploit operations via asyncio.
## Quick Start
```bash
uv venv && uv pip install -e ".[dev]"
pentest-storm --help
```
### New campaign
```bash
pentest-storm init my-engagement
# Edit campaign.yaml: add targets, scope, MSF credentials
# Authorize targets before scanning
pentest-storm targets authorize 10.0.0.1 10.0.0.2/24 --reason "in scope per rules of engagement"
# Verify tool readiness
pentest-storm tools discover
pentest-storm tools check
# Run scans
pentest-storm scan --scope scope.txt --intensity normal --scribe-db findings.db --scribe-engagement my-engagement
```
## CLI Reference
### Top-level commands
```
pentest-storm [OPTIONS] COMMAND [ARGS]...
Options:
--version / -V Show version and exit.
--dangerously-allow-executions Skip confirmation prompts for safe/moderate exploit executions.
```
| Command | Description |
|---|---|
| `init NAME` | Scaffold a new campaign directory with `campaign.yaml` |
| `plan NMAP_XML` | Generate an attack plan from an Nmap XML scan |
| `scan [TARGET]` | Run phased scanning tools against targets |
### `scan`
```
pentest-storm scan [TARGET] [OPTIONS]
Options:
--output-dir, -o PATH Directory for scan output (default: ./scan-output)
--scope PATH Scope file β one target per line; supports IPs, CIDRs, hostnames, host:port
--phase TEXT Phases to run: dns, ports, services, ssl, web, vuln, auth
--intensity TEXT Scan aggressiveness: gentle, normal, aggressive (default: normal)
--resume Re-run FAILED, TIMEOUT, and SKIPPED tools from a previous run
--dry-run Show which tools would run without executing them
--scribe-db PATH Auto-ingest findings into a pentest-scribe database
--scribe-engagement TEXT Engagement tag for ingested findings
--lessons-db PATH Path to a pentest-scribe DB to load lessons-learned context before scanning
--yes, -y Skip confirmation prompt
```
Phases run in order: `dns β ports β services β ssl β web β vuln β auth`. Targets are resolved from the positional argument, `--scope` file, or `campaign.yaml` targets list.
### `targets`
Manages host authorization state in `storm.db`. Scans against unauthorized hosts are blocked at runtime.
```
pentest-storm targets COMMAND [ARGS]...
```
| Command | Description |
|---|---|
| `authorize HOST [HOST...]` | Authorize one or more IPs, hostnames, or CIDRs for attack within the campaign |
| `deny HOST [HOST...]` | Deny targets, blocking them until re-authorized |
| `list` | List all authorization records (address, status, authorized-by, reason) |
| `authorize-scope` | Bulk-authorize all scope entries from `campaign.yaml` |
```
# Options available on authorize and deny:
--campaign, -c TEXT Campaign name (default: read from campaign.yaml)
--db PATH Path to storm.db (default: ./storm.db)
--reason, -r TEXT Reason for the authorization or denial
```
### `tools`
```
pentest-storm tools COMMAND [ARGS]...
```
| Command | Description |
|---|---|
| `discover` | Scan PATH for all known pentest tools and write tool config |
| `list` | Show all tools with status, version, and path |
| `check` | Validate that found tools are functional and dependencies are satisfied |
| `install-deps [--yes] [--tool NAME]` | Install missing tool dependencies |
Run `tools discover` first; `tools check` and `tools install-deps` depend on the saved config.
### `msf`
```
pentest-storm msf COMMAND [ARGS]...
```
| Command | Description |
|---|---|
| `suggest [--cve CVE] [--cwe CWE]` | Suggest Metasploit modules for a CVE or CWE |
| `sessions [--host HOST] [--port PORT] [-p PASSWORD]` | List active Metasploit sessions |
MSF password can be set via the `MSF_PASSWORD` environment variable.
### `exploit`
```
pentest-storm exploit COMMAND [ARGS]...
```
| Command | Description |
|---|---|
| `list` | List all available PoC exploits in the library |
| `search [--cve CVE] [--service SERVICE]` | Search PoC library by CVE or service name |
### `discover`
```
pentest-storm discover COMMAND [ARGS]...
```
| Command | Description |
|---|---|
| `parse NMAP_XML` | Parse an Nmap XML file and save `inventory.json` |
| `inventory [--dir DIR]` | Show the persisted asset inventory |
### `crack`
```
pentest-storm crack COMMAND [ARGS]...
```
| Command | Description |
|---|---|
| `identify HASH` | Identify the hash type of a hash string, file, or stdin (`-`) |
| `build-cmd HASH_FILE [--hash-type TYPE] [--wordlist PATH] [--rules PATH]` | Build a hashcat command |
### `privesc`
```
pentest-storm privesc match BINARY [BINARY...]
```
Matches SUID binary paths against GTFOBins for privilege escalation vectors. Comma-separated entries are accepted.
### `graybox`
```
pentest-storm graybox parse-users LDAP_FILE
```
Parses AD users from LDAP output.
## Architecture
pentest-storm sits alongside [pentest-scribe](https://github.com/Tarmo-Technologies/pentest-scribe) (reporting) and a separate scan-orchestration component, sharing [tarmo-vuln-core](https://github.com/Tarmo-Technologies/tarmo-vuln-core) models.
```
tarmo-vuln-core (shared models)
βββ pentest-scribe (reporting)
βββ pentest-storm (exploitation) β this repo
```
### Module layout
```
pentest_storm/
βββ cli.py # Typer entry point
βββ mcp_server.py # MCP server (14 tools, stdio transport)
βββ host_auth.py # Database-backed host authorization
βββ config.py # Campaign config (campaign.yaml)
βββ msf/ # Metasploit RPC client and module mapper
βββ exploits/ # PoC runner and Docker sandbox
βββ exploit_library/ # Curated PoC library (manifest + payloads)
βββ tools/ # Tool registry, scanner, dependency management
βββ discovery/ # Nmap XML parsing, asset inventory
βββ privesc/ # GTFOBins matcher, Linux enumeration
βββ cracking/ # Hash identification, hashcat orchestration
βββ pivoting/ # SSH tunneling, lateral movement
βββ chain/ # Attack chain recording and diff
βββ embedded/ # Firmware analysis, default creds, protocol scanning
βββ graybox/ # AD enumeration, Kerberoast, BloodHound
βββ verification/ # Exploit result verification and repro step generation
βββ validation/ # Result/payload validation helpers
βββ planning/ # Attack plan generation from Nmap data
βββ scope/ # Scope enforcement
βββ evidence/ # Evidence capture and storage
βββ audit/ # Audit logging
βββ integration/ # pentest-scribe ingest bridge
βββ data/ # Bundled data files (GTFOBins, mappings)
βββ models/ # Pydantic/SQLModel data models
```
### Tech stack
| Component | Library |
|---|---|
| CLI framework | Typer |
| Data validation | Pydantic v2 |
| Local storage | SQLModel (SQLite) |
| Config | PyYAML |
| MSF integration | pymetasploit3 |
| SSH/tunneling | paramiko |
| Async orchestration | asyncio |
| MCP server | fastmcp |
## MCP Server
The MCP server exposes 14 workflow-oriented tools over stdio transport. Each tool covers a complete workflow domain; sub-operations are selected via an `action` parameter.
```bash
# Start the server (stdio transport β configure in your MCP client)
pentest-storm-mcp
# or: python -m pentest_storm.mcp_server
```
| Tool | Actions / Description |
|---|---|
| `manage_campaign` | `init`, `status` β create and inspect campaign config |
| `msf` | `suggest` (CVE/CWE β MSF modules), `sessions` (list active sessions) |
| `msf_suggest` | Suggest Metasploit modules for a CVE or CWE |
| `exploits` | `list`, `search` β browse and filter the PoC library |
| `exploit_list` | List all PoC exploits in the library |
| `exploit_search` | Search PoC exploits by service name or CVE |
| `discover` | `parse` (Nmap XML β assets), `inventory` |
| `manage_tools` | `discover`, `list`, `check`, `install_deps` |
| `scan` | Run phased scans; modes: `run`, `dry_run`, `resume` |
| `plan_attack` | Generate attack stages from Nmap XML |
| `crack` | `identify` (hash type detection), `build_cmd` (hashcat command) |
| `privesc` | Match SUID binaries against GTFOBins |
| `graybox` | `parse_users` β extract AD users from LDAP output |
| `manage_targets` | `list_authorizations`, `authorize` (two-step with confirmation token), `deny`, `scope` |
`manage_targets` uses a two-step confirmation flow for `authorize` and `deny`: the first call returns a `confirmation_token`; a second call with the token executes the change.
## campaign.yaml
`pentest-storm init ` creates a `campaign.yaml` with these fields:
```yaml
name: "my-engagement"
targets: [] # list of IPs/hostnames/CIDRs to scan
scope: [] # scope entries for host auth enforcement
msf_host: "127.0.0.1"
msf_port: 55553
msf_password: "" # or set MSF_PASSWORD env var
docker_network: "pentest-storm-net"
max_concurrent: 5
output_dir: "./results"
dependency_policy: "ask" # ask | auto
```
Scan targets and scope can be set here or overridden via `--scope` and positional arguments.
## Development
```bash
# Setup
uv venv && uv pip install -e ".[dev]"
# Test
pytest tests/ -q --tb=short
# Lint / format / type check
ruff check . && ruff format --check .
mypy pentest_storm/
# Security scan
bandit -r pentest_storm/ -ll
```
Coverage target: β₯80%. CI enforces `--cov-fail-under=80`.
Run all four checks locally before `git push`.
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and the PR flow, and
[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). To report a vulnerability, see
[SECURITY.md](SECURITY.md).
## License
Released under the [Apache License 2.0](LICENSE). Β© 2025 Tarmo Technologies.