# nmap-mcp 技能 将 nmap 封装为结构化工具的 MCP server，具备作用域强制、审计日志和持久化扫描结果功能。 ## 前置条件 - 已安装 nmap（位于 /usr/bin/nmap 或在 config.yaml 中配置路径） - Python 3.10+ 并安装 fastmcp、python-nmap、pyyaml - 若需 SYN/OS/ARP 扫描：为 nmap 二进制文件授予 cap_net_raw 能力（见 Setup） ## 设置 ``bash # 1. 安装 Python 依赖 pip install fastmcp python-nmap pyyaml # 2. 授予 nmap 原始套接字能力（SYN + OS 检测必需） # 仅需执行一次，升级 nmap 后需重新执行 sudo setcap cap_net_raw+ep $(which nmap) # 3. 验证是否生效 getcap $(which nmap) # 预期输出：/usr/bin/nmap cap_net_raw=ep # 4. 配置作用域（编辑 config.yaml —— 设置允许的 CIDR） # 5. 注册到 mcporter（见下方 mcporter.json 条目） ` ## mcporter.json 条目 `json { "nmap": { "command": "python3", "args": ["-u", "/path/to/nmap-mcp/server.py"], "type": "stdio", "env": { "NMAP_CONFIG": "/path/to/nmap-mcp/config.yaml" } } } ` ## 配置 (config.yaml) `yaml # 作用域强制 —— 超出这些 CIDR 的目标将被拒绝 allowed_cidrs: - "127.0.0.0/8" - "192.168.1.0/24" # 你的本地网络 # 路径（如省略则使用相对路径） audit_log: "./audit.log" scan_dir: "./scans" nmap_bin: "/usr/bin/nmap" # 超时时间（秒） timeouts: quick: 120 standard: 300 deep: 600 ` ## 工具 | 工具 | 用途 | 所需权限 | |------|---------|-----------| | nmap_ping_scan | ICMP+TCP 主机发现 | 无 | | nmap_arp_discovery | ARP 主机发现（局域网） | cap_net_raw | | nmap_top_ports | 快速扫描 N 个常见端口 | 无 | | nmap_syn_scan | SYN 半开端口扫描 | cap_net_raw | | nmap_tcp_scan | 完整 TCP 连接端口扫描 | 无 | | nmap_udp_scan | UDP 端口扫描 | cap_net_raw | | nmap_service_detection | 服务/版本检测 | 无 | | nmap_os_detection | OS 指纹识别 | cap_net_raw | | nmap_script_scan | 运行指定 NSE 脚本 | 无 | | nmap_vuln_scan | 运行 vuln NSE 类别 | 无 | | nmap_full_recon | SYN+服务+OS+脚本 | cap_net_raw | | nmap_custom_scan | 任意 flags（受作用域限制并记录） | 视参数而定 | | nmap_list_scans | 列出最近保存的扫描 | 无 | | nmap_get_scan | 按 ID 获取扫描结果 | 无 | ## 运行测试 ``bash python3 -m pytest tests/ -v # 28 项测试，覆盖作用域强制、审计日志、 # 扫描持久化、注入防护与实时扫描
# 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
``
bash
# 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
`
json
{
"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)
`
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
`
bash
python3 -m pytest tests/ -v
# 28 tests covering scope enforcement, audit logging,
# scan persistence, injection guards, and live scans
``
by