Thebul500/portsentinel

# PortSentinel [](https://github.com/Thebul500/portsentinel/actions/workflows/ci.yml) [](LICENSE) [](https://nodejs.org/) 具备变更检测功能的实时端口扫描器和服务指纹识别工具。监控网络主机，检测新开放的端口，识别运行中的服务，并对变更发出警报。将扫描历史存储在 SQLite 中，支持 JSON/CSV 导出。 ## 快速开始 ``` git clone https://github.com/Thebul500/portsentinel.git cd portsentinel npm install # 使用默认端口扫描主机 node bin/portsentinel.js scan 192.168.1.1 # 扫描 1-1024 端口并进行 service fingerprinting node bin/portsentinel.js scan 192.168.1.1 -r 1-1024 -f # 将结果保存到 database，在下次运行时检测变更 node bin/portsentinel.js scan 192.168.1.1 -r 1-1024 -d scans.db ``` 或者使用 Docker： ``` docker compose build docker compose run --rm portsentinel scan 192.168.1.1 -r 1-1024 -f ``` ## 功能特性 - **TCP 端口扫描** — 扫描单个端口、端口列表或范围，支持可配置的超时和并发 - **服务指纹识别** — 通过 Banner 抓取和模式匹配来识别服务（SSH、HTTP、MySQL、Redis 等） - **变更检测** — 比较扫描结果以发现新开放/关闭的端口和服务变更 - **基于严重程度的警报** — 针对高风险端口（FTP、Telnet、SMB、RDP、VNC）自动进行风险评估，分为 critical/warning/info 级别 - **SQLite 历史** — 持久化扫描存储，启用 WAL 模式以实现快速并发读取 - **JSON/CSV 导出** — 将结果导出到文件或标准输出 - **Docker 支持** — 使用 docker-compose 的多阶段 Alpine 构建 ## 安装说明 ### 从源码安装 ``` git clone https://github.com/Thebul500/portsentinel.git cd portsentinel npm install ``` ### 全局 CLI 安装 ``` npm install -g . portsentinel --help ``` ### Docker ``` docker compose build ``` **系统要求：** Node.js 18+（已在 18、20、22 版本上测试） ## 使用方法 ### 扫描主机（默认为常用端口） ``` portsentinel scan 192.168.1.1 ``` ### 扫描端口范围 ``` portsentinel scan 10.0.0.1 -r 1-1024 ``` ### 扫描特定端口 ``` portsentinel scan example.com -p 22,80,443,3306,8080 ``` ### 对开放端口进行指纹识别 ``` portsentinel scan 10.0.0.1 -r 1-1024 -f ``` ### 设置连接超时 ``` portsentinel scan 10.0.0.1 -t 5000 ``` ### 导出结果 ``` # 输出 JSON 到 stdout portsentinel scan 10.0.0.1 --json # 输出 CSV 到 stdout portsentinel scan 10.0.0.1 --csv # 写入文件 portsentinel scan 10.0.0.1 -o results.json portsentinel scan 10.0.0.1 -o results.csv --csv ``` ### 将结果存储在 SQLite 中并检测变更 ``` # 首次扫描 — 保存到 database portsentinel scan 10.0.0.1 -r 1-1024 -d scans.db # 第二次扫描 — 与之前的结果进行比较，变更时发出警报 portsentinel scan 10.0.0.1 -r 1-1024 -d scans.db ``` ### 查看扫描历史 ``` portsentinel history 10.0.0.1 -d scans.db portsentinel history 10.0.0.1 -d scans.db -n 20 ``` ### Docker ``` # 扫描 localhost 1-1024 端口（默认） docker compose up # 自定义扫描 docker compose run --rm portsentinel scan 192.168.1.1 -r 1-1024 -f -d /data/scans.db ``` ## CLI 参考 ### `portsentinel scan ` | 选项 | 描述 | 默认值 | |---|---|---| | `-p, --ports ` | 逗号分隔的端口列表 | 常用端口（26 个） | | `-r, --range ` | 端口范围，例如 `1-1024` | — | | `-t, --timeout ` | 连接超时时间（毫秒） | `2000` | | `-f, --fingerprint` | 对开放端口进行指纹识别 | 关闭 | | `-d, --db ` | SQLite 数据库路径 | — | | `--json` | 输出为 JSON | — | | `--csv` | 输出为 CSV | — | | `-o, --output ` | 将输出写入文件 | — | ### `portsentinel history ` | 选项 | 描述 | 默认值 | |---|---|---| | `-d, --db ` | SQLite 数据库路径 | `portsentinel.db` | | `-n, --limit ` | 记录数量 | `10` | ## 配置 ### 默认端口 当未指定端口时，PortSentinel 会扫描这 26 个常见的目标端口： ``` 21 (FTP), 22 (SSH), 23 (Telnet), 25 (SMTP), 53 (DNS), 80 (HTTP), 110 (POP3), 111 (RPCBind), 135 (MSRPC), 139 (NetBIOS), 143 (IMAP), 443 (HTTPS), 445 (SMB), 993 (IMAPS), 995 (POP3S), 1433 (MSSQL), 1521 (Oracle), 3306 (MySQL), 3389 (RDP), 5432 (PostgreSQL), 5900 (VNC), 6379 (Redis), 8080 (HTTP Proxy), 8443 (HTTPS Alt), 9090 (Web Admin), 27017 (MongoDB) ``` ### 高风险端口 当这些端口新开放时，会触发 `CRITICAL` 严重级别警报： ``` 21 (FTP), 23 (Telnet), 135 (MSRPC), 139 (NetBIOS), 445 (SMB), 1433 (MSSQL), 3389 (RDP), 5900 (VNC) ``` ### 扫描并发 默认情况下，端口以 100 个并发连接为一批进行扫描。这可以通过 `concurrency` 选项以编程方式进行配置。 ### 服务指纹识别 指纹识别器使用双层方法识别服务： 1. **Banner 匹配**（高置信度）— 连接到开放端口，发送特定协议的探测包（HTTP `HEAD`，Redis `PING`），并将响应与已知模式进行匹配 2. **基于端口的查找**（低置信度）— 当未收到 Banner 时，回退到已知端口分配规则 可识别的服务包括：SSH、FTP、SMTP、HTTP、POP3、IMAP、MySQL、PostgreSQL、Redis、MongoDB、VNC、RDP、SMB、MSSQL、Oracle 等。 ### 警报严重级别 | 严重程度 | 触发条件 | |---|---| | `CRITICAL` | 新开放的高风险端口（FTP、Telnet、RDP、SMB、VNC 等） | | `WARNING` | 任何新开放的端口或服务发生变更 | | `INFO` | 端口关闭或无重大变更 | ## 架构 ``` portsentinel/ ├── bin/ │ └── portsentinel.js # CLI entry point (Commander.js) ├── src/ │ ├── index.js # Module exports │ ├── scanner.js # TCP port scanning (net.Socket) │ ├── fingerprinter.js # Banner grabbing & service identification │ ├── detector.js # Change detection between scans │ ├── database.js # SQLite storage (better-sqlite3, WAL mode) │ ├── exporter.js # JSON/CSV export │ └── alerts.js # Severity calculation & alert formatting ├── test/ # Mocha + Chai + Sinon test suite ├── Dockerfile # Multi-stage Alpine build ├── docker-compose.yml # Docker Compose with host networking └── .github/workflows/ └── ci.yml # CI: lint, test, coverage, security audit ``` ### 流水线 ``` Host/Ports (CLI input) │ ▼ ┌─────────┐ ┌───────────────┐ │ Scanner │─────▶│ Fingerprinter │ │ (TCP) │ │ (banners) │ └─────────┘ └───────────────┘ │ │ ▼ ▼ ┌──────────┐ ┌──────────┐ │ Database │ │ Exporter │ │ (SQLite) │ │ (JSON/ │ └──────────┘ │ CSV) │ │ └──────────┘ ▼ ┌──────────┐ ┌────────┐ │ Detector │─────▶│ Alerts │ │ (diff) │ │ (severity)│ └──────────┘ └────────┘ ``` ### 模块概述 **scanner** — 使用 `net.Socket` 进行核心 TCP 扫描。支持单端口、端口列表和范围扫描，具有可配置的超时和批量并发。返回包含端口状态和延迟的结构化结果。 **fingerprinter** — 连接到开放端口，发送特定协议的探测包（HTTP HEAD、Redis PING），并将响应 Banner 与已知模式匹配。返回服务名称、Banner 和置信水平（high/medium/low/none）。 **detector** — 比较两次扫描结果，识别新开放的端口、新关闭的端口和服务变更。生成带有 `hasChanges` 标志的结构化变更报告。 **alerts** — 获取变更报告并根据变更的端口计算严重程度。高风险端口（FTP、Telnet、RDP、SMB、VNC）触发 critical 警报。格式化警报以供控制台输出。 **database** — 通过 `better-sqlite3` 实现的 SQLite 持久化，启用 WAL 日志。将完整扫描数据存储为 JSON，并提供规范化的 `scan_ports` 表以供查询。支持历史检索、主机列表和清理。 **exporter** — 将扫描结果转换为 JSON（美化打印）或 CSV 格式。写入文件时自动创建目录。 ### 编程 API ``` const { scanner, fingerprinter, detector, ScanDatabase, exporter, alerts } = require('portsentinel'); // Scan ports const result = await scanner.scanHost('10.0.0.1', [22, 80, 443]); // Fingerprint open ports const fp = await fingerprinter.fingerprintScan(result); // Store in database const db = new ScanDatabase('./scans.db'); db.saveScan(result); // Detect changes const previous = db.getLatestScan('10.0.0.1'); const changes = detector.detectChanges(previous, result); // Generate alerts if (changes.hasChanges) { const alert = alerts.createAlert(changes); console.log(alerts.formatAlert(alert)); } // Export exporter.exportScan(result, 'output.json', 'json'); db.close(); ``` ## 开发 ``` # 安装依赖项 npm install # 运行测试 npm test # 运行测试并生成覆盖率 npm run test:coverage # Lint npm run lint ``` ## 许可证 MIT

标签：AES-256, Banner Grabbing, Docker, GNU通用公共许可证, MITM代理, Node.js, Scrypt密钥派生, SQLite, TCP扫描, 变化检测, 安全防御评估, 实时监测, 插件系统, 数据导出, 数据统计, 服务指纹识别, 漏洞评估, 端口扫描, 网络安全, 自定义脚本, 请求拦截, 防御绕过, 隐私保护, 风险告警