What raven-nest-mcp does
raven-nest-mcp provides an MCP interface for authorized penetration testing. It wraps tools for reconnaissance, crawling, SMB and Active Directory enumeration, vulnerability scanning, web fuzzing, exploitation, password cracking, secret detection, and TLS testing. The supported tool set includes nmap, masscan, whatweb, httpx, subfinder, dnsx, dnsrecon, katana, enum4linux-ng, netexec, nuclei, nikto, wpscan, dalfox, feroxbuster, ffuf, sqlmap, hydra, john, gitleaks, trufflehog, and testssl.sh. Metasploit operations are available through separate search, module, exploit, auxiliary, session, and post endpoints when enabled.
Beyond individual commands, the server tracks scans, targets, findings, and engagements. Scan results can survive a server restart when a scan completes; interrupted scans are surfaced as failed. Findings and reports are available as MCP resources, and scan comparisons can identify changes between assessments.
How it works
An MCP host launches the server over standard input and output, then invokes its tools. The server does not run independently or listen on a network port. A Docker image packages the server with the wrapped tools on a Kali-based image, while local builds require Rust and the external security tools used by the selected operations.
Tool calls pass through multiple controls before execution. An allowlist limits which tools may run, target values are checked as IP addresses, hostnames, CIDRs, or URLs, and scan types use preset arguments rather than unrestricted command-line flags. Timeouts, concurrent-scan limits, output truncation, ANSI removal, and result-quality checks further constrain execution. Optional engagement scoping restricts targets to approved domains or CIDRs, with denied entries taking precedence and redirect hops checked against the scope.
Setup and configuration
The recommended deployment uses the published Docker image through an MCP client configured for stdio:
{
"mcpServers": {
"raven-nest": {
"command": "docker",
"args": ["run", "--rm", "-i", "ghcr.io/tidynest/raven-nest-mcp:latest"]
}
}
}
Local builds use Rust 1.93 or newer and cargo build --release. The resulting raven-server binary can be referenced directly from an MCP client configuration. Configuration is TOML-based and is selected from the path in RAVEN_CONFIG, a file beside the binary, a file in the working directory, or built-in defaults, in that order.
Important settings include permitted tools, context budget, expected tool calls, timeouts, maximum concurrent scans, output location, optional proxy settings, engagement scope, Metasploit connection details, and the gated netexec feature. Raw-socket operations such as masscan and nmap operating-system detection need NET_RAW and NET_ADMIN capabilities when run in Docker.
Tools and capabilities
- Run reconnaissance with nmap, masscan, whatweb, httpx, subfinder, dnsx, and dnsrecon.
- Crawl targets with katana and test web applications with nuclei, nikto, wpscan, dalfox, feroxbuster, and ffuf.
- Perform selected exploitation, authentication testing, password cracking, secret scanning, and TLS checks with the supported tools.
- Launch, monitor, list, compare, and cancel scans through dedicated scan-management endpoints.
- Save, retrieve, list, and delete findings, then generate Markdown, JSON, SARIF, or HTML reports.
- Track engagements and discovered targets, and use Metasploit endpoints when the feature is enabled.
Limitations and notes
Use is restricted to systems that the operator owns or is explicitly authorized to assess. The default Docker image excludes Metasploit, so an MSF-enabled build and corresponding configuration are needed for those endpoints. Credentialed netexec enumeration is gated and read-only. Wordlists are limited to approved directories, and tool-specific safety values such as sqlmap risk, hydra task counts, and masscan rates are range-checked. The server refuses unsafe startup configuration, including default Metasploit credentials.
The container runs as a dedicated non-root user. Granting the required capabilities directly to the container is necessary for raw-socket scans. Cookie and spill files use owner-only permissions, and audit entries are written under the configured output directory.