SuriyaBoon/LogWatcher

# LogWatcher — Windows 事件日志异常检测器 一个 PowerShell + Python 混合工具，用于摄取 Windows 安全事件 日志，并近乎实时地检测暴力破解登录尝试、账户锁定以及 意外的权限提升事件——完美复刻了 Tier-1 SOC 分析师的日常 工作流程。 ## 为什么采用这种分离架构 - **PowerShell** 负责特定于 Windows 的工作：通过 `Get-WinEvent` 从 安全日志中提取事件，并将重要字段导出为 JSON Lines 格式。 - **Python** 负责检测、告警和报告逻辑—— 它与操作系统完全无关，无需真实的 Windows 机器或 Domain Controller 即可进行完整的单元测试。 这也意味着检测引擎可以针对任何 历史导出数据进行重放，用于测试、调整阈值或演示，而完全 无需触碰生产环境基础设施。 ## 功能特性 - **暴力破解检测 (Event 4625)** — 针对每个 源 IP 的滑动窗口计数器（对于本地控制台登录，则退化为基于用户名）。当失败次数在可配置的 窗口内超过可配置的阈值时触发，随后进入冷却期，以防止持续的攻击 在随后的每次失败中都发送重复的 垃圾告警。 - **账户锁定检测 (Event 4740)** — 立即触发； 每次锁定都绝对值得排查。 - **权限提升检测 (Event 4672)** — 标记接收到 特权登录的账户，前提是该账户*不*在已配置的 管理员/服务账户白名单中。 - **IP 白名单** — 抑制来自已知 漏洞扫描器、跳板机等的暴力破解噪音。 - **多渠道通知** — Slack webhook 和/或 SMTP 邮件， 两者均为可选且可独立配置。不稳定的邮件服务器 不会导致日志监控瘫痪——投递失败仅会被记录，并非 致命错误。 - **两种运行模式**： - `watch` — 实时跟踪事件导出并在事件发生时发出告警。 - `report` — 批量处理一段时间内的事件，生成 每日摘要（主要违规 IP、最受关注的账户、锁定 频率）。 - **一键安装程序** — `Install-LogWatcher.ps1` 会为 导出器和监视器注册计划任务，因此整个 pipeline 能够在重启后自动恢复运行，无需人工干预。 ## 安装 ``` git clone https://github.com/SuriyaBoon/logwatcher.git cd logwatcher pip install -e . cp config.example.json config.json # then edit thresholds / webhook / SMTP ``` 无需任何第三方 Python 依赖——完全基于 标准库构建（`smtplib`、`urllib`、使用 `collections.deque` 实现 滑动窗口）。只有在运行测试套件时才需要 `pytest`。 ## 使用说明 ### 报告模式（批量/每日总结） ``` logwatcher report --events events.jsonl --config config.json -o summary.json ``` ``` ============================================================ LogWatcher Daily Summary Period: 2026-07-03T02:14:01 → 2026-07-03T19:22:16 ============================================================ Total events processed : 20 Failed logons (4625) : 17 Account lockouts (4740): 1 Privilege events (4672): 2 Alerts fired : 3 Top offending source IPs: 203.0.113.45 7 failed logon(s) 10.0.0.5 6 failed logon(s) <- allowlisted, no alert fired ... ``` ### 监视模式（近乎实时的告警） ``` logwatcher watch --events events.jsonl --config config.json --alert-log alerts.jsonl ``` 在 PowerShell 将新事件追加到导出文件时实时跟踪 JSONL 导出，一旦某个模式越过阈值，便会立即 通过 Slack/邮件触发告警。 ### 在 Windows 上：完整 pipeline ``` # One-time setup (run as Administrator) — registers scheduled tasks # for both the exporter and the watcher. .\scripts\Install-LogWatcher.ps1 -InstallDir C:\LogWatcher # Or run the exporter manually / on a schedule of your choosing: .\scripts\Export-SecurityEvents.ps1 -OutputPath C:\LogWatcher\events.jsonl ``` `Export-SecurityEvents.ps1` 使用书签文件，因此重复运行只会 导出新事件——完全可以安全地通过 Task Scheduler 每分钟调度执行一次。 ## 配置 `config.json`: ``` { "detection": { "brute_force_threshold": 5, "brute_force_window_minutes": 5, "brute_force_cooldown_minutes": 15, "ip_allowlist": ["10.0.0.5"], "admin_allowlist": ["administrator", "svc-backup"] }, "notifications": { "slack_webhook_url": "https://hooks.slack.com/services/...", "email": { "enabled": false, "smtp_host": "smtp.gmail.com", "smtp_port": 587, "username": "alerts@example.com", "password": "app-password-here", "from_addr": "alerts@example.com", "to_addrs": ["soc-team@example.com"] } } } ``` ## 在没有 Windows 机器的情况下进行尝试 `sample_data/sample_events.jsonl` 包含一天的合成事件—— 一次暴力破解攻击、一次账户锁定、一次意外的权限 提升，以及一个白名单内的服务账户产生的 看似误报的噪音（它会被正确抑制）： ``` logwatcher report --events sample_data/sample_events.jsonl --config config.example.json ``` ## 项目结构 ``` logwatcher/ ├── logwatcher/ │ ├── cli.py # argparse entrypoint — watch & report subcommands │ ├── ingest.py # JSONL event parsing + file tailing │ ├── detectors.py # brute-force / lockout / privilege-escalation logic │ ├── notifier.py # Slack webhook + SMTP email │ └── report.py # daily summary aggregation ├── scripts/ │ ├── Export-SecurityEvents.ps1 # Get-WinEvent → JSONL, bookmark-based │ └── Install-LogWatcher.ps1 # registers Scheduled Tasks ├── sample_data/ │ └── sample_events.jsonl # synthetic demo dataset ├── tests/ │ └── test_logwatcher.py # pytest suite (15 tests) ├── config.example.json ├── requirements.txt └── setup.py ``` ## 测试 ``` pip install pytest pytest tests/ -v ``` 全部 15 个测试均在纯 Python 环境中运行，不依赖 Windows——滑动 窗口暴力破解逻辑、冷却期行为、IP 白名单、锁定 和权限提升检测，以及报告聚合，均已通过 合成事件进行了覆盖测试。 ## 作者 Suriya Boonsanong — [github.com/SuriyaBoon](https://github.com/SuriyaBoon)

标签：AI合规, AMSI绕过, PB级数据处理, 威胁检测, 安全运维, 红队行动, 逆向工具