SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsnmap-network-scan

nmap-network-scan

Security & auditing

View repository

Updated 10-15 17:21

About this skill

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:

# SYN scan — faster, requires cap_net_raw
python3 $MCP_CALL "python3 -u $NMAP_MCP_SCRIPT" nmap_syn_scan '{"target":"192.168.1.1","ports":"1-65535"}'

# TCP connect — works without special privileges
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 range
  • count (optional): Number of top ports to scan (default 100, max 65535)

nmap_syn_scan

  • target (required): IP, hostname, or CIDR range
  • ports (optional): Port range (default "1-1024", use "common" for top 1000)

nmap_tcp_scan

  • target (required): IP, hostname, or CIDR range
  • ports (optional): Port range (default "1-1024")

nmap_udp_scan

  • target (required): IP, hostname, or CIDR range
  • ports (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 later
  • target — what was scanned
  • hosts_up / per_host — discovered hosts with open ports
  • count / 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

Failure Behavior

  • If a tool call fails with an authentication or connection error, check that NMAP_MCP_SCRIPT is set and valid before assuming a data or device problem.
  • On a tool error (timeout, unreachable host, malformed response), report the failure and its error message directly to the user rather than fabricating or guessing at results.
  • For a confirmed read-only call, check connectivity and retry once if appropriate. For any call that changes state or sends a message, a timeout does not prove the action failed: inspect current state or delivery status before retrying, preserve the required approval/change gates, and do not repeat an action whose outcome is unknown.