OrwaMian/Network-Sentinel

# Network Sentinel Network Sentinel 会监控本地计算机的网络活动，并在检测到端口扫描、暴力破解身份验证尝试、连接到已知的恶意 IP 或异常连接速率激增时发出警报——并且可以选择采取自动化操作。它被设计为一个功能性的安全工具，同时也是蓝队检测工程原理的作品集演示。 ## 此工具不是什么 对范围的诚实是蓝队的美德。Network Sentinel **不是**： - **不是 DDoS 防御工具。** 大流量的 DDoS 攻击由上游的 ISP 或 CDN 级别进行处理。当真正的 DDoS 到达您的主机时，您的上行链路已经饱和，基于主机的工具无能为力。Network Sentinel 处理的是主机具有有效应对能力的那类攻击：侦察、凭据攻击和恶意出站连接。 - **不能替代端点保护。** Windows Defender、Microsoft Defender for Endpoint 或商业 EDR 产品提供更深层次的内核级可见性。Network Sentinel 是一个补充层，而不是替代品。 - **不是 SIEM。** 它会生成兼容 SIEM 的 JSON Lines 日志，但它本身不是一个日志聚合、关联或警报平台。 - **不是商业级产品。** 这是一个展示蓝队检测思维的教育和作品集项目。在没有进行大量额外的强化和测试之前，不应将其视为生产环境的安全控制手段。 ## 架构 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ Network Sentinel │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌───────────┐ │ │ │ Port Scan │ │Brute Force │ │ Threat Feed │ │ Rate │ │ │ │ Detector │ │ Detector │ │ Detector │ │ Anomaly │ │ │ │ (psutil) │ │ (pywin32) │ │(local/API) │ │ Detector │ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └─────┬─────┘ │ │ │ │ │ │ │ │ ┌──────┴────────────────┴────────────────┴───────────────┴──────┐ │ │ │ Python logging pipeline │ │ │ │ (log_event() → handlers fan out to all consumers) │ │ │ └──────┬─────────────────────────┬──────────────────────────────┘ │ │ │ │ │ │ ┌──────▼──────┐ ┌────────▼────────┐ ┌──────────────────┐ │ │ │ Firewall │ │ Structured │ │ Live Terminal │ │ │ │ Responder │ │ Logger │ │ Dashboard │ │ │ │ (netsh) │ │(.log + .jsonl) │ │ (rich) │ │ │ └─────────────┘ └─────────────────┘ └──────────────────┘ │ └─────────────────────────────────────────────────────────────────────┘ ``` 每个检测器都在自己的 daemon 线程中运行，因此没有单个检测器会阻塞其他检测器。警报通过标准的 Python `logging` pipeline 流动——结构化的 `log_event()` 调用将元数据附加到日志记录中，多个 handler 独立消费它：一个轮转的文本日志、一个 JSON Lines 日志、仪表板的内存警报存储，以及（可选的）防火墙响应器。 ## 检测器 | 检测器 | 数据源 | 警报级别 | 事件类型 | |---|---|---|---| | 端口扫描 | `psutil.net_connections()` | WARNING | `PORT_SCAN_DETECTED` | | 暴力破解 | Windows Event Log (4625/4624) | WARNING / CRITICAL | `BRUTE_FORCE_DETECTED` / `BRUTE_FORCE_SUCCESS` | | 威胁情报源 | `psutil` + 本地黑名单 / AbuseIPDB | CRITICAL | `THREAT_FEED_HIT` | | 速率异常 | `psutil.net_connections()` delta | WARNING | `RATE_ANOMALY_DETECTED` | ## 安装说明 ### 前置条件 - **Windows 11**（也支持 Windows 10；未在更旧版本上测试） - **Python 3.10 或更高版本** — 从 [python.org](https://www.python.org/downloads/) 下载 - **管理员权限** — 访问 Event Log 和管理防火墙规则必需 ### 启用 Windows 高级审核策略（暴力破解检测必需） Network Sentinel 会读取 Windows Security Event Log 中的登录失败（Event ID 4625）条目。这需要配置审核策略。请在管理员 PowerShell 中运行： ``` auditpol /set /subcategory:"Logon" /failure:enable /success:enable ``` 或通过 GUI 操作：**Local Security Policy** (`secpol.msc`) → **Security Settings → Advanced Audit Policy Configuration → Logon/Logoff → Audit Logon → Failure**。 ### 安装依赖 ``` # 克隆仓库 git clone https://github.com/muhammadmian/network-sentinel.git cd network-sentinel # 创建并激活 virtual environment（推荐） python -m venv venv venv\Scripts\activate # 安装依赖 pip install -r requirements.txt ``` ## 快速开始 ``` # 使用实时 dashboard 运行（默认） python -m network_sentinel.main # 仅日志模式 — 无 dashboard，适合作为后台进程运行 python -m network_sentinel.main --no-dashboard # 指定自定义 config 文件 python -m network_sentinel.main --config my_config.yaml ``` **测试端口扫描检测：** 工具运行后，从另一台机器或 VM 使用 Nmap： ``` nmap -sS -p 1-1000 ``` 在配置的时间窗口内（默认：60 秒），仪表板中应会出现警报。 ## 示例输出 仪表板（实时终端视图）： ``` ╔══════════════════════════════════════════════════════════════════╗ ║ Network Sentinel v0.1.0 — Live View ║ ╠══════════════════════════════════════════════════════════════════╣ ║ Uptime: 00:03:17 │ Alerts (total): 2 │ Blocked IPs: 0 ║ ╠═══════════════════════════════════╦══════════════════════════════╣ ║ RECENT ALERTS ║ ACTIVE DETECTORS ║ ║ ║ ● port-scan-detector ║ ║ 20:14:02 WARNING PORT_SCAN_… ║ ● brute-force-detector ║ ║ from 203.0.113.5 ║ ● threat-feed-detector ║ ║ ports: 23, 80, 443, 8080 (+7) ║ ● rate-anomaly-detector ║ ║ ║ ║ ╚═══════════════════════════════════╩══════════════════════════════╝ ``` JSON Lines 日志条目（每个事件一行，适合 SIEM 摄取）： ``` { "timestamp": "2026-05-25T20:14:02.831Z", "level": "WARNING", "event_type": "PORT_SCAN_DETECTED", "source_ip": "203.0.113.5", "detector": "port_scan", "severity": "HIGH", "details": { "distinct_ports": 10, "window_seconds": 60, "sample_ports": [23, 80, 443, 8080, 3389, 22, 21, 25, 110, 8443] } } ``` ## 配置参考 所有设置都位于 `config.yaml` 中。该文件包含大量注释——请阅读它以获取完整详细信息。 ### 常规 | 设置 | 默认值 | 描述 | |---|---|---| | `general.poll_interval_seconds` | `5` | 每个检测器检查新事件的频率（秒） | | `general.ip_whitelist` | `[127.0.0.1, ::1]` | 永不触发警报的 IP —— 添加您的路由器、VPN 网关等。 | ### 端口扫描检测器 | 设置 | 默认值 | 描述 | |---|---|---| | `port_scan.enabled` | `true` | 启用或禁用此检测器 | | `port_scan.threshold_ports` | `10` | 在窗口内被探测的不同端口达到此数量前不报警 | | `port_scan.window_seconds` | `60` | 用于端口计数的滑动时间窗口 | | `port_scan.tracked_states` | `[ESTABLISHED, SYN_SENT, ...]` | 计入探测的连接状态 | ### 暴力破解检测器 | 设置 | 默认值 | 描述 | |---|---|---| | `brute_force.enabled` | `true` | 启用或禁用此检测器 | | `brute_force.threshold_failures` | `5` | 触发警报前的登录失败次数（Event ID 4625） | | `brute_force.window_seconds` | `120` | 用于失败计数的滑动时间窗口 | | `brute_force.alert_on_success_after_failure` | `true` | 如果在失败后登录成功，则发出 CRITICAL 警报 | ### 威胁情报源检测器 | 设置 | 默认值 | 描述 | |---|---|---| | `threat_feed.enabled` | `true` | 启用或禁用此检测器 | | `threat_feed.local_blocklist_path` | `data/known_bad_ips.txt` | 本地 IP 黑名单的路径（每行一个 IP，`#` 用于注释） | | `threat_feed.abuseipdb.enabled` | `false` | 启用 AbuseIPDB 实时源（需要 API key） | | `threat_feed.abuseipdb.api_key` | `""` | 您的 AbuseIPDB 免费层 API key | | `threat_feed.abuseipdb.confidence_threshold` | `75` | 最低 AbuseIPDB 置信度分数（0–100） | | `threat_feed.abuseipdb.refresh_interval_seconds` | `3600` | 刷新 AbuseIPDB 源的频率 | ### 速率异常检测器 | 设置 | 默认值 | 描述 | |---|---|---| | `rate_anomaly.enabled` | `true` | 启用或禁用此检测器 | | `rate_anomaly.max_connections_per_second` | `20` | 触发警报前来自单个 IP 的每秒新连接数 | | `rate_anomaly.baseline_period_seconds` | `60` | 警报开始前的启动静默期 | ### 防火墙响应器（自动拦截） | 设置 | 默认值 | 描述 | |---|---|---| | `firewall.auto_block_enabled` | **`false`** | **必须显式设置为 `true` 才能启用自动拦截** | | `firewall.block_on_detectors` | `[port_scan, brute_force, threat_feed]` | 哪些检测器可以触发拦截 | | `firewall.rule_name_prefix` | `NetSentinel_Block` | 防火墙规则名称的前缀（使其易于查找和清理） | | `firewall.block_duration_seconds` | `3600` | 自动拦截在经过这么多秒后过期；`0` = 永久 | ## 本地威胁情报源格式 编辑 `data/known_bad_ips.txt` 以添加已知的恶意 IP： ``` # 以 # 开头的行是注释 # 每行一个 IP — 同时支持 IPv4 和 IPv6 # 也支持内联注释 198.51.100.1 # known C2 server 203.0.113.42 # malware distribution 2001:db8::bad # IPv6 example ``` 要使用 AbuseIPDB 实时源代替（或补充）本地列表，请设置 `threat_feed.abuseipdb.enabled: true` 并添加您的 API key。免费层的 AbuseIPDB 账户每天提供 1,000 次 API 调用，这足以满足默认的每小时刷新。 ## 限制与已知注意事项 - **无法洞察加密隧道。** 如果攻击者的 C2 流量已加密，且使用看起来正常的端口（例如 443），除非目标 IP 在黑名单中，否则威胁情报源检测器将无法捕获它。 - **psutil 连接状态准确性。** 在 Windows 上，`psutil` 读取的数据源与 `netstat` 相同。根据 OS 和驱动程序版本的不同，仅 SYN 扫描（没有完整的 TCP 握手）可能不会出现。 - **暴力破解源 IP。** Windows Event ID 4625 包含网络登录尝试的源 IP，但本地交互式登录失败（坐在键盘前的人）将没有源 IP。检测器会通过跳过这些事件来优雅地处理。 - **无数据包捕获。** Network Sentinel 不使用原始数据包捕获。它依赖于连接表和事件日志。这是一个刻意的设计选择——数据包捕获需要内核级驱动程序，这超出了此类基于主机的工具的范围。 - **速率异常首次轮询静默。** 速率异常检测器无法在其第一次轮询时标记连接，因为它没有先前的快照可供比较。在配置的 `baseline_period_seconds` 期间，它也将保持静默。这是设计使然。 - **自动拦截的副作用。** 配置错误的白名单可能会拦截合法流量。请务必先在仅检测模式下进行测试。默认情况下禁用自动拦截。 - **需要管理员权限。** 如果没有管理员权限，Windows 上的 `psutil.net_connections()` 将返回部分视图，并且对 Event Log 的访问将被拒绝。该工具会通过记录警告来优雅地处理此问题，但覆盖范围将会减少。 ## 运行测试 ``` # 运行完整的 test suite python -m unittest discover -s tests -v # 运行单个 test module python -m unittest tests.test_port_scan -v ``` 该套件包含跨 8 个模块的 194 个测试，涵盖所有检测器、config loader、logger、仪表板和防火墙响应器。所有测试完全离线——没有真实的网络连接，没有调用 Windows 防火墙，也没有读取 Event Log。外部依赖项被隔离在可注入边界之后，并被替换为测试替身。 ## Linux 可移植性说明 | 功能 | 兼容 Linux？ | 注意事项 | |---|---|---| | 端口扫描检测 | 是 | `psutil` 是跨平台的 | | 连接速率异常 | 是 | `psutil` 是跨平台的 | | 威胁情报源匹配 | 是 | 无特定于 OS 的依赖项 | | 暴力破解检测 | 部分 | 需要读取 `/var/log/auth.log` 或使用 `journalctl` 代替 Windows Event Log | | 自动拦截 | 部分 | 需要使用 `iptables`/`nftables` 代替 `netsh advfirewall` | | 仪表板 | 是 | `rich` 是跨平台的 | ## 未来增强 - [ ] Email / webhook 警报（在发生 CRITICAL 事件时将警报发送到 Slack、Teams 或 email） - [ ] 将拦截的 IP 列表和警报历史记录导出为 CSV，用于事后审查 - [ ] Windows Service 包装器（在启动时作为后台服务运行） - [ ] 用于警报增强的 GeoIP 查询（可疑 IP 的来源国家/地区） - [ ] 警报上的 MITRE ATT&CK 技术标记（例如，用于端口扫描的 T1046） - [ ] 用于速率异常检测的机器学习基准（代替静态阈值） - [ ] 通过将 syslog 转发到中央收集器来进行跨主机关联 ## 开发 ``` # 运行 tests python -m unittest discover -s tests -v # 检查代码风格（需要 ruff） pip install ruff python -m ruff check network_sentinel/ # 检查类型（需要 mypy） pip install mypy python -m mypy network_sentinel/ ``` ## 鸣谢 由 **Muhammad Mian** 作为作品集项目构建。灵感来源于基于主机的 IDS 原理。 Muhammad 是墨尔本斯威本科技大学网络安全专业的近期学士毕业生，目前正在学习 ISC2 Certified in Cybersecurity (CC) 认证。 *MIT 许可证 — 详情请参阅 [LICENSE](LICENSE)。*

标签：IP 地址批量处理, 主机入侵检测, 插件系统, 红队行动, 自动拦截, 逆向工具, 防火墙