nmap MCP server for AI-assisted network security auditing

Network scanning MCP server wrapping nmap. Provides 14 purpose-built tools for host discovery, port scanning (SYN/TCP/UDP), service & OS detection, NSE scrip...

Security Scan

The skill's code, documentation, and runtime instructions are consistent with an nmap MCP wrapper for scoped network scanning; its requirements and behaviors match the stated purpose, though there are a few operational notes you should be aware of before installing.

Purpose & Capability

The skill is an nmap MCP server and the included server.py, tests, README, and SKILL.md implement that functionality (scope enforcement, audit logging, scan persistence, and structured JSON output). Minor metadata mismatch: registry lists 'required binaries: none' and 'instruction-only', but the SKILL.md and code clearly require nmap and Python packages (fastmcp, python-nmap, pyyaml). This is explainable (install left to the user) but worth noting.

Instruction Scope

SKILL.md and server.py limit actions to scanning with nmap, scope checks, logging, and persistence. Instructions explicitly require configuring allowed CIDRs and warn about granting cap_net_raw only to nmap. The code includes input validation, hostname resolution with 'fail closed' behavior, and an injection guard for custom flags. No instructions or code paths were found that read unrelated system secrets or exfiltrate data to external endpoints.

Install Mechanism

No install spec is provided (skill is treated as instruction-only), which is lower risk but means the user must run pip install and configure mcporter/clawhub manually. The README and SKILL.md instruct pip install of dependencies and setcap on nmap; dependencies come from PyPI (requirements.txt). No unusual download URLs or archive extraction are used.

Credentials

The skill does not request credentials or sensitive environment variables. It uses a single optional NMAP_CONFIG env var to point to config.yaml (documented). It persists scans and audit logs to local disk as expected for this tool; these files will contain scan outputs and should be protected accordingly.

Persistence & Privilege

The skill persists scan results and an audit log to disk (SCAN_DIR and AUDIT_LOG) and therefore requires filesystem write access to its working directory. It also requires granting cap_net_raw capability to the nmap binary for SYN/OS/ARP scans — a privileged operation that the README documents and justifies, but which increases host attack surface if misused. 'always' is false and autonomous invocation is allowed (platform default).

Assessment

This skill is coherent with its stated purpose (an nmap MCP wrapper) and includes sensible safeguards (CIDR allowlist, target validation, audit logging, injection guards). Before installing: 1) confirm you actually want an on-host nmap service (it will execute nmap subprocesses and write scan results/audit logs to disk); 2) review and tighten config.yaml allowed_cidrs to your precise scope — do not leave broad RFC1918 ranges enabled in shared environments; 3) understand the host change required: granting cap_net_raw to the nmap binary (setcap) is necessary for SYN/ARP/OS scans and should be applied only if you trust this code and the environment; 4) protect the scan and audit directories (they may contain sensitive host/service info); 5) note the metadata mismatch (registry says no required binaries / instruction-only while the code requires nmap and Python packages) — installation is manual. If you want stronger assurance, run the bundled tests locally (they exercise scope enforcement, logging, persistence, and injection guards) and audit server.py end-to-end for any remaining truncated functions before deploying on production hosts.

nmap-mcp Skill

MCP server that exposes nmap as structured tools with scope enforcement, audit logging, and persistent scan results.

Prerequisites

• nmap installed (/usr/bin/nmap or configure path in config.yaml)
• Python 3.10+ with fastmcp, python-nmap, pyyaml
• For SYN/OS/ARP scans: cap_net_raw capability on the nmap binary (see Setup)

Setup

# 1. Install Python dependencies
pip install fastmcp python-nmap pyyaml

# 2. Grant nmap raw socket capability (required for SYN + OS detection)
#    Only needs to be done once. Re-run after nmap upgrades.
sudo setcap cap_net_raw+ep $(which nmap)

# 3. Verify it worked
getcap $(which nmap)
# Expected: /usr/bin/nmap cap_net_raw=ep

# 4. Configure scope (edit config.yaml — set your allowed CIDRs)
# 5. Register with mcporter (see mcporter.json entry below)

mcporter.json Entry

{
  "nmap": {
    "command": "python3",
    "args": ["-u", "/path/to/nmap-mcp/server.py"],
    "type": "stdio",
    "env": {
      "NMAP_CONFIG": "/path/to/nmap-mcp/config.yaml"
    }
  }
}

Configuration (config.yaml)

# Scope enforcement — targets outside these CIDRs are rejected
allowed_cidrs:
  - "127.0.0.0/8"
  - "192.168.1.0/24"   # your local network

# Paths (defaults to relative paths if omitted)
audit_log: "./audit.log"
scan_dir: "./scans"
nmap_bin: "/usr/bin/nmap"

# Timeouts in seconds
timeouts:
  quick: 120
  standard: 300
  deep: 600

Tools

Tool	Purpose	Privileges
nmap_ping_scan	ICMP+TCP host discovery	none
nmap_arp_discovery	ARP host discovery (LAN)	cap_net_raw
nmap_top_ports	Fast scan of N common ports	none
nmap_syn_scan	SYN half-open port scan	cap_net_raw
nmap_tcp_scan	Full TCP connect port scan	none
nmap_udp_scan	UDP port scan	cap_net_raw
nmap_service_detection	Service/version detection	none
nmap_os_detection	OS fingerprinting	cap_net_raw
nmap_script_scan	Run named NSE scripts	none
nmap_vuln_scan	Run vuln NSE category	none
nmap_full_recon	SYN+service+OS+scripts	cap_net_raw
nmap_custom_scan	Arbitrary flags (scoped+logged)	varies
nmap_list_scans	List recent saved scans	none
nmap_get_scan	Retrieve scan by ID	none

Running Tests

python3 -m pytest tests/ -v
# 28 tests covering scope enforcement, audit logging,
# scan persistence, injection guards, and live scans