fant3k/ssh-log-analyzer

# SSH Log Analyzer [](https://github.com/fant3k/ssh-log-analyzer/actions/workflows/tests.yml)    一个小型的防御性工具，用于解析 OpenSSH 身份验证日志，并对可疑登录进行初步关联。它可以标准化来自 `auth.log`、`secure` 以及 journald 文本输出的事件，生成摘要，并标记出在 triage（分类排查）期间需要检查的事件序列。 该工具不会将每一次失败的登录都宣告为攻击：只有在有限的时间窗口内达到明确指定的阈值时，才会创建 finding（发现结果）。  ## 分析内容 - 通过 password、public key 和 keyboard-interactive 进行的失败与成功登录； - 尝试使用不存在的用户进行登录； - IPv4 和 IPv6 来源； - 单次运行处理多个文件或来自 stdin 的流； - RFC 3164 时间戳（`Feb 8 10:00:00`）和 ISO 8601 journald 时间戳。 ## 关联规则 | 规则 ID | 机制 | 默认阈值 | 严重程度 | |---|---|---:|---| | `ssh_brute_force` | 来自单一 IP 的一系列失败尝试 | 5 分钟内 5 次 | high | | `ssh_password_spray` | 单一 IP 尝试多个不同用户 | 5 分钟内 4 个用户 | high | | `ssh_distributed_account_attack` | 单个账户遭到多个不同 IP 攻击 | 5 分钟内 4 个 IP | high | | `ssh_success_after_failures` | 在同一 IP/用户对的一系列失败后成功登录 | 5 分钟内 5 次失败 | critical | 最后一条规则是用于紧急检查的信号，而不是遭到入侵的自动证明：合法用户也可能会输错几次然后成功登录。 ## 快速开始 ``` git clone https://github.com/fant3k/ssh-log-analyzer.git cd ssh-log-analyzer python3 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip pip install . ssh-log-analyzer --version ``` 该项目仅使用 Python standard library，没有 runtime 依赖。 ## 在演示日志上进行测试 ``` ssh-log-analyzer sample_logs/example_auth.log --year 2026 ``` Fixture 仅使用专为文档保留的 IP 范围。 预期结果：20 行，19 个 authentication events 和 5 个 findings，覆盖所有四条规则。 ## 处理真实日志 单个文件： ``` ssh-log-analyzer /var/log/auth.log ``` 轮替文件将被一起分析： ``` ssh-log-analyzer /var/log/auth.log.1 /var/log/auth.log ``` journald 流： ``` journalctl -u ssh --since today -o short-iso | ssh-log-analyzer - ``` 如果 syslog 行不属于当前年份，则需要显式指定： ``` ssh-log-analyzer archived-auth.log --year 2025 ``` ## JSON 和 CSV ``` ssh-log-analyzer /var/log/auth.log \ --json-out reports/ssh-analysis.json \ --csv-out reports/ssh-findings.csv ``` JSON 包含 schema 版本、摘要、高频 IP/用户以及 findings。默认情况下不写入标准化的事件，因为 usernames 和 IP 可能属于敏感信息。在进行本地调查时，您可以显式添加它们： ``` ssh-log-analyzer /var/log/auth.log \ --json-out reports/with-events.json \ --include-events ``` ## 配置检测 ``` ssh-log-analyzer /var/log/auth.log \ --window-minutes 10 \ --brute-force-threshold 8 \ --spray-user-threshold 6 \ --distributed-ip-threshold 5 ``` 如果发现至少一个信号，`--fail-on-findings` 将返回 exit code `2`。这允许在本地 pipeline 中使用该分析器，而不会将执行错误与检测到的事件混淆。 ## 架构 ``` ssh_log_analyzer/ parser.py OpenSSH parsing и нормализация detection.py window-based correlation rules models.py типизированные events, findings и result reporting.py console, JSON и CSV cli.py аргументы, входные лимиты и orchestration sample_logs/ синтетический безопасный fixture tests/ unit и CLI integration tests ``` ## 项目检查 ``` scripts/test.sh ``` 测试涵盖了真实的 OpenSSH 字符串变体、IPv4/IPv6、两种 timestamp 格式、每条关联规则、时间窗口、报告、CLI 以及针对行数的防御性限制。GitHub Actions 会在 Python 3.9、3.11 和 3.13 上重复执行这些检查。 ## 限制 - 这是一个 triage 工具，不是 SIEM，也不能替代手动调查； - RFC 3164 不包含年份 —— 需通过 `--year` 指定； - ISO 时间戳会转换为 UTC，RFC 3164 则保留在主机的本地时间； - 经发行版修改过的非标准消息可能需要添加新的 parser rule； - 在解释结果时，必须考虑 NAT、bastion hosts 和公共 egress IP； - severity 反映的是检查的优先级，而不是已证实的 impact。 ## 文档 - [English README](README_EN.md) - [安全和数据处理政策](SECURITY.md) - [MIT 许可证](LICENSE)

标签：Python, SSH, 异常检测, 文档结构分析, 无后门, 红队行动, 逆向工具