| name | nmap-network-scan |
| description | Host discovery and port scanning using nmap — ICMP/ARP host discovery, SYN/TCP/UDP port scanning with scope enforcement and audit logging. Use when discovering live hosts on a subnet, scanning for open ports, verifying firewall rules, or doing pre/post-change port scans |
| license | Apache-2.0 |
| user-invocable | true |
| metadata | {"openclaw":{"requires":{"bins":"[Truncated]","env":"[Truncated]"}}} |
Network Scanning with nmap
How to Call the nmap MCP Tools
python3 $MCP_CALL "python3 -u $NMAP_MCP_SCRIPT" TOOL_NAME '{"param":"value"}'
When to Use
- Discover what hosts are alive on a subnet before deeper analysis
- Find open ports on network devices, servers, or lab infrastructure
- Verify firewall rules by checking which ports are reachable
- Pre-change/post-change port scans to confirm expected service exposure
- Asset discovery on RFC1918 or lab networks
Available Tools
| Tool | Purpose | Privileges |
|---|
nmap_ping_scan | ICMP+TCP host discovery (no port scan) | none |
nmap_arp_discovery | ARP host discovery (LAN only) | cap_net_raw |
nmap_top_ports | Fast scan of N most common ports | none |
nmap_syn_scan | SYN half-open port scan (fast, stealthy) | cap_net_raw |
nmap_tcp_scan | Full TCP connect scan (no root needed) | none |
nmap_udp_scan | UDP port scan (DNS, SNMP, NTP, etc.) | cap_net_raw |
Workflow: Subnet Discovery
When asked "what's on this network?" or "scan this subnet":
Step 1: Host Discovery
Find live hosts first — avoids wasting time port-scanning dead IPs.
python3 $MCP_CALL "python3 -u $NMAP_MCP_SCRIPT" nmap_ping_scan '{"target":"192.168.1.0/24"}'
On directly-connected LANs, ARP discovery is more reliable:
python3 $MCP_CALL "python3 -u $NMAP_MCP_SCRIPT" nmap_arp_discovery '{"target":"192.168.1.0/24"}'
Step 2: Quick Port Scan
Scan the top 100 common ports on discovered hosts:
python3 $MCP_CALL "python3 -u $NMAP_MCP_SCRIPT" nmap_top_ports '{"target":"192.168.1.1","count":100}'
Step 3: Targeted Port Scan
For deeper scanning, use SYN scan (faster) or TCP connect scan:
python3 $MCP_CALL "python3 -u $NMAP_MCP_SCRIPT" nmap_syn_scan '{"target":"192.168.1.1","ports":"1-65535"}'
python3 $MCP_CALL "python3 -u $NMAP_MCP_SCRIPT" nmap_tcp_scan '{"target":"192.168.1.1","ports":"22,80,443,8080"}'
Step 4: UDP Services
Check for UDP services (DNS, SNMP, TFTP, NTP, syslog):
python3 $MCP_CALL "python3 -u $NMAP_MCP_SCRIPT" nmap_udp_scan '{"target":"192.168.1.1","ports":"53,67,68,69,123,161,162,500,514,1900"}'
Tool Parameters
nmap_ping_scan
target (required): IP, hostname, or CIDR range
nmap_arp_discovery
target (required): CIDR range or IP (LAN segment only)
nmap_top_ports
target (required): IP, hostname, or CIDR rangecount (optional): Number of top ports to scan (default 100, max 65535)
nmap_syn_scan
target (required): IP, hostname, or CIDR rangeports (optional): Port range (default "1-1024", use "common" for top 1000)
nmap_tcp_scan
target (required): IP, hostname, or CIDR rangeports (optional): Port range (default "1-1024")
nmap_udp_scan
target (required): IP, hostname, or CIDR rangeports (optional): Port list or range (default: common UDP service ports)
Scope Enforcement
All targets are validated against the CIDR allowlist in config.yaml. Targets outside the allowed ranges are hard-rejected before nmap runs. Default allowed ranges:
127.0.0.0/8 (loopback)10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 (RFC1918)fd00::/8 (IPv6 ULA)
Output Format
All tools return structured JSON with:
scan_id — unique identifier for retrieving results latertarget — what was scannedhosts_up / per_host — discovered hosts with open portscount / total_open — summary counts
Important Rules
- Always start with host discovery before port scanning large ranges
- SYN scan is faster but requires cap_net_raw on the nmap binary
- UDP scans are inherently slow — keep port lists targeted
- Every scan is logged in the audit log for compliance
- Scan results are persisted and retrievable via
nmap_list_scans / nmap_get_scan
