cortexc0de/netmcp
GitHub: cortexc0de/netmcp
一个基于 MCP 协议的专业级网络分析服务器，将 Wireshark 和 Nmap 的能力通过自然语言接口暴露给 AI 客户端。
Stars: 0 | Forks: 0
# 🌐 NetMCP
**专业级网络分析 MCP 服务器 — Wireshark/TShark + Nmap + 威胁情报**
[](https://github.com/cortexc0de/netmcp/actions/workflows/ci.yml)
[](https://github.com/cortexc0de/netmcp)
[](https://github.com/cortexc0de/netmcp/actions/workflows/codeql.yml)
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://pypi.org/project/netmcp/)
[](https://ghcr.io/cortexc0de/netmcp)
[](https://modelcontextprotocol.io/)
NetMCP 弥合了原始网络数据与 AI 理解之间的鸿沟。它赋予 Claude、Cursor 以及任何兼容 MCP 的客户端通过自然语言捕获数据包、扫描网络、检测威胁和提取凭据的能力。
[快速开始](#-quick-start) • [功能特性](#-features) • [配置说明](#-configuration) • [API 参考](docs/API.md) • [架构设计](docs/ARCHITECTURE.md)
## 🚀 快速开始
```
# 安装系统依赖
sudo apt-get install -y tshark nmap # Ubuntu/Debian
# brew install wireshark nmap # macOS
# 安装 NetMCP
pip install netmcp
# 运行
netmcp
```
就是这样。服务器默认在 **stdio** 传输协议上启动，已为任何 MCP 客户端做好准备。
## ✨ 功能特性
- 📡 **数据包捕获** — 实时捕获、BPF 过滤、针对性流量、快速捕获模式
- 🔬 **深度分析** — PCAP 解析、协议统计、HTTP 流量分析、DNS 分析、专家信息、GeoIP 丰富化
- 🔄 **流重建** — 跟踪 TCP/UDP 会话、枚举流
- 📤 **灵活导出** — JSON、CSV、pcap/pcapng 格式转换
- 🔍 **Nmap 集成** — 端口扫描、服务检测、OS 指纹识别、漏洞扫描
- 🛡️ **威胁情报** — URLhaus + AbuseIPDB IP 信誉检查、PCAP 全局威胁扫描
- 🔑 **凭据提取** — HTTP Basic、FTP、Telnet、Kerberos（兼容 hashcat）
- 🌍 **GeoIP 映射** — MaxMind GeoLite2 IP 地理定位，用于流量分析
- 🔒 **5 层安全防护** — 输入验证、shell=False、速率限制、路径遍历保护、审计日志
- 💬 **引导式工作流** — 安全审计、事件响应、故障排查、流量分析、网络基线提示词
### 高级功能
- 🔀 **PCAP Diff/Merge/Slice** — 比较捕获内容、通过 mergecap 合并文件、通过 editcap 提取数据包范围
- 📊 **流可视化** — 网络会话的 ASCII 艺术图和 Mermaid 序列图
- 🔓 **TLS 解密** — 使用 SSLKEYLOGFILE（NSS Key Log Format）解密 HTTPS 流量
- 🎨 **Wireshark 配置文件** — 列出配置文件、应用配置设置、解析着色过滤器、使用配置文件捕获
- 🧬 **DNS 隧道检测** — 分析 DNS 流量并标记可疑的超长子域名
- 📦 **数据包解码** — 详细的单包分析，包含完整协议层剖析
- 🏥 **专家信息** — 提取 Wireshark 的专家警告、错误和协议违规说明
## 📊 工具分类
NetMCP 跨越 **9 个类别**提供了 **48 个工具**，以及 **3 个资源**和 **5 个提示词**：
| 类别 | 工具 | 描述 |
|----------|-------|-------------|
| 📡 **捕获与分析** | 5 | `get_network_interfaces` · `capture_live_packets` · `quick_capture` · `save_capture_to_file` · `analyze_large_pcap` |
| 🔬 **协议分析** | 10 | `analyze_pcap_file` · `get_protocol_statistics` · `get_capture_file_info` · `capture_targeted_traffic` · `analyze_http_traffic` · `detect_network_protocols` · `analyze_http_headers` · `geoip_lookup` · `analyze_dns_traffic` · `get_expert_info` |
| 📊 **网络流** | 2 | `visualize_network_flows` (ASCII + Mermaid) · `decrypt_tls_traffic` |
| 🔧 **PCAP 工具** | 4 | `diff_pcap_files` · `merge_pcap_files` · `slice_pcap` · `decode_packet` |
| 🔄 **流** | 3 | `follow_tcp_stream` · `follow_udp_stream` · `list_tcp_streams` |
| 📤 **导出** | 3 | `export_packets_json` · `export_packets_csv` · `convert_pcap_format` |
| 🔍 **Nmap** | 6 | `nmap_port_scan` · `nmap_service_detection` · `nmap_os_detection` · `nmap_vulnerability_scan` · `nmap_quick_scan` · `nmap_comprehensive_scan` |
| 🛡️ **安全** | 3 | `extract_credentials` · `check_ip_threat_intel` · `scan_capture_for_threats` |
| 🎨 **Wireshark 配置文件** | 4 | `list_wireshark_profiles` · `apply_profile_capture` · `get_color_filters` · `capture_with_profile` |
## 🔌 传输选项
NetMCP 支持所有 MCP 传输协议：
| 传输方式 | 命令 | 使用场景 |
|-----------|---------|----------|
| **stdio** (默认) | `netmcp` | Claude Desktop, Cursor, 本地客户端 |
| **SSE** | `netmcp --transport sse` | 基于 Web 的客户端，远程访问 |
| **Streamable HTTP** | `netmcp --transport streamable-http` | 现代 HTTP 客户端 |
## ⚙️ 配置说明
### Claude Desktop
编辑您的配置文件：
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
```
{
"mcpServers": {
"netmcp": {
"command": "netmcp",
"env": {
"ABUSEIPDB_API_KEY": "your_api_key_here"
}
}
}
}
```
### Cursor
编辑项目根目录下的 `.cursor/mcp.json`：
```
{
"mcpServers": {
"netmcp": {
"command": "netmcp"
}
}
}
```
### Windsurf / VS Code
编辑 `.vscode/mcp.json`：
```
{
"servers": {
"netmcp": {
"command": "netmcp",
"env": {
"ABUSEIPDB_API_KEY": "your_api_key_here"
}
}
}
}
```
### 环境变量
| 变量 | 是否必需 | 默认值 | 描述 |
|----------|----------|---------|-------------|
| `ABUSEIPDB_API_KEY` | 否 | — | 用于威胁情报的 AbuseIPDB API 密钥。[获取免费密钥](https://www.abuseipdb.com/) |
| `NETMCP_TSHARK_PATH` | 否 | 自动检测 | tshark 二进制文件的自定义路径 |
| `NETMCP_MAX_PACKETS` | 否 | `10000` | 每次捕获操作的最大数据包数 |
| `NETMCP_MAX_FILE_SIZE` | 否 | `104857600` | 最大 PCAP 文件大小（字节）（100 MB） |
## 📋 系统要求
| 依赖项 | 是否必需 | 安装命令 |
|------------|----------|---------|
| **Python** | 3.11+ | `sudo apt install python3.11` |
| **TShark** | 是 | `sudo apt install tshark` |
| **Nmap** | 可选 | `sudo apt install nmap` |
### macOS
```
brew install wireshark nmap
```
### Linux 权限
```
# 选项 1: 设置 capabilities (推荐)
sudo setcap cap_net_raw,cap_net_admin=eip /usr/bin/dumpcap
# 选项 2: 将用户添加到 wireshark 组
sudo usermod -aG wireshark $USER && newgrp wireshark
```
## 🛡️ 安全模型
NetMCP 实施了 **5 层深度防御**：
| 层级 | 机制 | 防护目标 |
|-------|-----------|----------|
| **1. 输入验证** | 正则表达式、`ipaddress` 模块、Pydantic | 格式错误的输入、注入攻击载荷 |
| **2. 命令构建** | 列表参数、全面使用 `shell=False` | 命令注入、Shell 扩展 |
| **3. 子进程执行** | 超时、仅捕获输出 | 进程失控、资源耗尽 |
| **4. 文件系统** | `Path.resolve()`、扩展名白名单、大小限制 | 路径遍历、符号链接攻击 |
| **5. 速率限制** | 滑动窗口、按操作跟踪 | 滥用、DoS 攻击 |
额外保护措施：
- 🔒 绝不自动提升权限
- 📝 所有操作均带时间戳审计日志
- 🚫 拒绝危险的 nmap 标志（`--script-args`、`--interactive` 等）
- ⚠️ 针对权限问题提供清晰的错误信息
## 🎯 使用示例
### 实时数据包捕获
```
You: Capture 100 packets from eth0 and analyze the protocols.
Claude: [capture_live_packets(interface="eth0", packet_count=100)]
[get_protocol_statistics(filepath="capture.pcap")]
Found 8 protocols: TCP (62%), UDP (24%), DNS (8%), HTTP (4%)...
```
### 安全审计
```
You: Perform a security audit on suspicious.pcap
Claude: 1. [get_protocol_statistics] → traffic breakdown
2. [extract_credentials] → found HTTP Basic Auth credentials
3. [scan_capture_for_threats] → 2 malicious IPs detected
4. Generated full security report with IOCs
```
### Nmap 漏洞扫描
```
You: Scan 192.168.1.100 for vulnerabilities
Claude: [nmap_quick_scan("192.168.1.100")] → ports 22, 80, 443 open
[nmap_service_detection("192.168.1.100")] → nginx 1.18.0, OpenSSH 8.2
[nmap_vulnerability_scan("192.168.1.100")] → no critical CVEs found
```
## 🧠 MCP 资源与提示词
### 资源
| URI | 描述 |
|-----|-------------|
| `netmcp://interfaces` | 可用网络接口的动态列表 |
| `netmcp://captures` | 公共目录中可用的 PCAP 文件 |
| `netmcp://system/info` | 系统能力：工具版本、功能特性 |
### 提示词（引导式工作流）
| 提示词 | 描述 |
|--------|-------------|
| `security_audit` | 包含 IOC 提取的全面 PCAP 安全分析 |
| `network_troubleshooting` | 逐步网络诊断 |
| `incident_response` | 安全事件调查工作流 |
| `traffic_analysis` | 结合 GeoIP 映射的深度流量分析 |
| `network_baseline` | 建立正常流量模式 |
## 🧪 开发指南
```
# 克隆并设置
git clone https://github.com/cortexc0de/netmcp.git
cd netmcp
python -m venv .venv
source .venv/bin/activate
# 安装 dev 依赖
pip install -e ".[dev]"
# 运行测试
pytest tests/ -v
# 运行 coverage
pytest tests/ --cov=netmcp --cov-report=html
# Linting
ruff check src/netmcp/ tests/
ruff format --check src/netmcp/
mypy src/netmcp/
```
### 项目结构
```
src/netmcp/
├── server.py # FastMCP server entry point
├── core/
│ ├── security.py # 5-layer input validation + rate limiting
│ └── formatter.py # MCP response formatting
├── interfaces/
│ ├── tshark.py # TShark async CLI wrapper
│ ├── nmap.py # python-nmap wrapper
│ └── threat_intel.py # URLhaus + AbuseIPDB clients
├── tools/ # 48 MCP tools across 11 modules
├── resources/ # 3 MCP resources
└── prompts/ # 5 MCP prompts
```
## 📄 许可证
MIT 许可证 — 详情见 [LICENSE](LICENSE)。
## 🙏 致谢
- [Wireshark/TShark](https://www.wireshark.org/) — 数据包分析工具套件
- [Nmap](https://nmap.org/) — 网络扫描器
- [URLhaus](https://urlhaus.abuse.ch/) & [AbuseIPDB](https://www.abuseipdb.com/) — 威胁情报
- [Model Context Protocol](https://modelcontextprotocol.io/) — AI 工具框架
**通过 AI 驱动的数据包捕获、扫描和威胁情报，变革您的网络分析方式。**
标签：Claude, Claude, CTI, Cursor, CVE检测, CVE检测, Docker, LLM集成, MCP服务器, Nmap, Python, TLS解密, TShark, Wildcard支持, Wireshark, 云存储安全, 人工智能工具, 凭证提取, 协议分析, 句柄查看, 嗅探, 威胁情报, 安全防御评估, 密码管理, 开发者工具, 攻击面映射, 数据统计, 无后门, 权限提升, 端口扫描, 系统分析, 网络分析, 网络安全, 网络扫描, 虚拟驱动器, 请求拦截, 逆向工具, 防御绕过, 隐私保护