ParshwaBhavsar/sshwatch

# sshwatch     **从 auth 日志中检测 SSH 暴力破解。** 将 `sshwatch` 指向 Linux `auth.log`（或 journald JSON 导出文件），它会对每一个身份验证事件运行五个行为检测器——从而发现暴力破解、分布式攻击、用户名枚举、无效用户名洪泛，以及最高优先级的信号：在经历一连串失败后的成功登录。每个告警都附带 MITRE ATT&CK 映射，并且该工具可以生成供您审查的防火墙拦截规则。 `sshwatch` 读取日志并生成发现结果。它将防火墙规则生成为**供审查的文本**——它从不执行特权命令，从不触碰运行中的防火墙，也从不联系任何主机。 ## 目录 - [为什么要有这个工具](#why-this-exists) - [检测器](#detectors) - [安装](#install) - [快速开始](#quick-start) - [用法](#usage) - [输出示例](#example-output) - [防火墙规则生成](#firewall-rule-generation) - [工作原理](#how-it-works) - [支持的日志格式](#supported-log-formats) - [测试](#testing) - [项目结构](#project-structure) - [演示的概念](#concepts-demonstrated) - [局限性](#limitations) - [道德与范围](#ethics--scope) ## 为什么要有这个工具 任何暴露在互联网上的 SSH 服务器都在不断遭受自动化攻击——暴力破解机器人、撞库脚本和用户名喷洒字典会在主机上线几分钟内攻击 22 端口。证据都在 `auth.log` 中，但手动阅读成千上万行日志无法扩展，而且最重要的一个事件——埋藏在大量失败中的*成功*登录——恰恰是人类最容易忽略的。 `sshwatch` 自动化了这一分拣过程。它应用了 SOC 分析师手动执行的滑动窗口统计分析，根据 MITRE ATT&CK 对每种攻击模式进行分类，并返回一个可操作的列表——包括针对违规 IP 的可供审查的防火墙规则。 它是 DNS 层和应用层日志分析的 SSH/主机日志兄弟工具：相同的检测工程原则，应用于每台 Linux 主机都会生成的身份验证日志。 ## 检测器 | 检测器 | 信号 | MITRE | 严重性 | |----------|--------|-------|----------| | **暴力破解** | 在一个滑动窗口内来自同一 IP 的多次失败尝试 | T1110.001 | HIGH | | **分布式暴力破解** | 跨多个 IP 的失败爆发——僵尸网络保持在单 IP 限制之下 | T1110 | CRITICAL | | **用户名枚举** | 一个 IP 尝试许多不同的用户名——账户探测 | T1110, T1589.001 | MEDIUM | | **无效用户名洪泛** | 针对不存在账户的大量尝试（常见用户名字典） | T1110.001 | MEDIUM | | **可能发生的入侵** | 来自同一 IP 的多次失败后的**成功**登录 | T1110, T1078 | CRITICAL | 每个告警都包含来源、定量证据（尝试次数、时间窗口、不同用户数）、补救建议以及误报指引。 ## 安装 ``` git clone https://github.com/ParshwaBhavsar/sshwatch.git cd sshwatch pip install -r requirements.txt pip install -e . ``` 需要 Python 3.10+。运行时依赖项：`rich`。 ## 快速开始 ``` # 1. 生成一个模拟的 auth.log（所有 IP 均为 RFC-5737 测试范围） python -m sshwatch generate-logs --output sample_auth.log # 2. 分析它 python -m sshwatch analyze --logfile sample_auth.log # 3. 为违规者生成防火墙规则（应用前请审查！） python -m sshwatch gen-rules --logfile sample_auth.log --rule-format iptables ``` ## 用法 ``` # 分析真实的 auth log python -m sshwatch analyze --logfile /var/log/auth.log # 用于 SIEM 的 JSON 输出 python -m sshwatch analyze --logfile /var/log/auth.log --output-format json # 仅显示 HIGH 及以上级别 python -m sshwatch analyze --logfile /var/log/auth.log --min-severity high # 分析 journald JSON 导出 journalctl -u ssh -o json | python -m sshwatch analyze --logfile /dev/stdin --format json # 生成各种格式的 block 规则 python -m sshwatch gen-rules --logfile /var/log/auth.log --rule-format nftables python -m sshwatch gen-rules --logfile /var/log/auth.log --rule-format ufw python -m sshwatch gen-rules --logfile /var/log/auth.log --rule-format hosts.deny ``` ## 输出示例 对合成样本（186 个事件，5 种攻击场景）运行的结果： ``` Parsed 186 SSH events from sample_auth.log sshwatch — 8 alert(s) ┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓ ┃ Sev ┃ Detector ┃ Source ┃ Finding ┃ ┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩ │ 🔴 CRITICAL│ ssh_possible_breach │ 198.51.100.150 │ Possible │ │ │ │ │ Successful │ │ │ │ │ SSH Breach │ │ │ │ │ [MITRE] │ │ │ │ │ T1110, T1078 │ │ 🔴 CRITICAL│ ssh_distributed_brute_for… │ 20 sources │ Distributed │ │ │ │ │ SSH Brute │ │ │ │ │ Force │ │ 🟠 HIGH │ ssh_brute_force │ 198.51.100.23 │ High failure │ │ │ │ │ rate, 15 in │ │ │ │ │ 60s │ └────────────┴────────────────────────────┴────────────────────┴───────────────┘ ╭────────── Summary ──────────╮ │ Events analysed: 186 │ │ Total alerts: 8 │ │ 🔴 CRITICAL 2 │ │ 🟠 HIGH 3 │ │ 🟡 MEDIUM 3 │ ╰─────────────────────────────╯ ``` ## 防火墙规则生成 `sshwatch gen-rules` 从告警中收集违规 IP，并以您选择的格式输出拦截规则： ``` # sshwatch 为 14 个 IP 生成了 iptables 规则。 # 应用前请审查这些规则。验证它们均非合法来源 # （您自己的 NAT gateway、monitoring 或 admin jump hosts）。 iptables -A INPUT -s 198.51.100.23 -p tcp --dport 22 -j DROP iptables -A INPUT -s 198.51.100.77 -p tcp --dport 22 -j DROP ... ``` 支持的格式：`iptables`、`nftables`、`ufw`、`hosts.deny`。 **这是一项建议，而不是一项操作。** 该工具将规则打印到 stdout 供您检查和应用。它故意不执行这些规则：日志分析器不适合用来进行特权网络更改，盲目拦截 IP 有可能导致合法的 NAT 网关或跳板机被锁死。请审查列表，然后应用适当的内容——或者将其输入到像 fail2ban 这样专门构建的响应程序中。 ## 工作原理 ``` auth.log / journald JSON │ ▼ parsers.py normalise every sshd line to an SSHEvent │ (timestamp · src_ip · user · outcome · method) ▼ detectors/ ├── brute_force.py single-IP + distributed sliding-window failure counts └── enumeration.py username spread · invalid-user volume · breach indicator │ ▼ model.py Alert with evidence + MITRE ATT&CK + recommendation │ ├── report.py rich terminal table / NDJSON └── firewall.py review-only block rules (iptables/nftables/ufw/hosts.deny) ``` 每个检测器都使用**滑动时间窗口**：事件按来源排序，并且指针会前进以仅保留配置窗口内的事件，因此无论日志总长度如何，“60 秒内 10 次失败”都能被正确评估。入侵检测器反转了这一逻辑——对于每次*成功*，它会向后*回溯*整个窗口，计算同一 IP 在此之前的失败次数。 ## 支持的日志格式 | 格式 | 解析器 | 自动检测条件 | |--------|--------|-----------------| | syslog `auth.log` / `secure` | `AuthLogParser` | 默认 | | journald JSON / NDJSON | `JSONParser` | 以 `{` 开头的行 | sshd 消息词汇表（`Failed password for…`、`Accepted publickey for…`、`Invalid user…`）在 Debian/Ubuntu/RHEL 上是稳定的，因此同一个解析器可以处理所有这些系统的日志。 ## 测试 ``` pip install pytest pytest -q ``` ``` 31 passed in 0.09s ``` 测试范围涵盖了每个解析器分支、所有五个检测器（正向和反向用例、时间窗口、按 IP 分组）、防火墙规则生成器（包括一项回归测试，确保分布式检测器的 `"N sources"` 标记永远不会泄漏到规则中），以及针对合成日志的端到端运行测试。 ## 项目结构 ``` sshwatch/ ├── sshwatch/ │ ├── model.py # SSHEvent, Alert, Outcome, Severity │ ├── parsers.py # auth.log + journald JSON parsers │ ├── report.py # rich terminal + JSON + log generator │ ├── firewall.py # review-only block-rule generation │ ├── cli.py # analyze / gen-rules / generate-logs │ └── detectors/ │ ├── base.py │ ├── brute_force.py # single-IP + distributed │ └── enumeration.py # user enum · invalid-user · breach ├── tests/ │ └── test_sshwatch.py # 31 tests ├── requirements.txt ├── pyproject.toml └── README.md ``` ## 演示的概念 - **SSH / PAM 身份验证日志记录** —— sshd 日志词汇表及其对安全性的含义 - **滑动窗口检测** —— 基于速率告警的核心原语，基于来源实现并带有正确的时间窗口剔除机制 - **MITRE ATT&CK** —— T1110（暴力破解）及其子技术，T1078（有效账户），T1589.001（凭证收集） - **入侵指标逻辑** —— 认识到失败*之后*的成功在本质上比任何单一事件都重要得多 - **防御性响应设计** —— 生成防火墙规则作为可审查的输出而不是自动执行，以及为什么这个边界很重要 - **日志标准化** —— 将多种日志格式映射到一个事件模型，使检测器与格式无关 ## 局限性 - **阈值需要调整** —— 默认值适用于典型的单台主机。具有许多合法用户的繁忙堡垒机可能需要更高的阈值；每个检测器的窗口和阈值都是构造函数参数。 - **仅限日志视图** —— `sshwatch` 只能看到 sshd 记录的内容。从未到达 sshd 的攻击（网络层洪泛）或日志记录减少的主机将无法完全可见。 - **尚不支持实时追踪** —— 它以批处理方式分析日志文件。持续监控需要追踪文件或从日志转发器中消费数据（已在路线图上）。 - **不包含 IP 信誉** —— 该工具报告其观察到的行为；它不会结合外部威胁情报进行丰富（这是一个自然的扩展功能）。 ## 道德与范围 专为防御性用途而构建：监控您自己的主机、事件响应和安全教育。`sshwatch` 读取您有权访问的日志文件，不进行任何网络连接，并且从不执行特权命令——防火墙规则以文本形式输出，供人类审查和应用。请仅分析您有权管理的系统的日志。 ## 许可证 MIT

标签：AMSI绕过, Python, SSH, 威胁检测, 安全, 安全规则引擎, 无后门, 红队行动, 超时处理, 逆向工具