MahinKabir10/SentryLog

# SentryLog 一个最小的 **SIEM**（安全信息和事件管理）工具，构建在 阶段上。 ## 为什么选择这种设计 SIEM 的全部价值在于 **标准化**：一百种日志格式输入，一种干净的 事件形状输出。因此，第一阶段的设计围绕一个想法构建 — ``` raw log file ──▶ source-specific parser ──▶ normalized Event ──▶ summary/output (sentrylog/parsers/*) (sentrylog/event.py) (sentrylog/cli.py) ``` 每个解析器都输出相同的 `Event`，没有其他内容。例如，第二阶段规则 “60秒内来自一个 IP 的多次失败登录”将同样触发 SSH 暴力破解和 RDP 暴力破解，因为 在规则看到数据时，“SSH”和“RDP”都变成了 `action=login, outcome=failure`。 ## 项目布局 ``` SentryLog/ ├── sentrylog/ │ ├── __init__.py # package API (re-exports Event, enums) │ ├── __main__.py # enables `python -m sentrylog` │ ├── event.py # the normalized Event schema (the contract) │ ├── detect.py # --type auto source detection │ ├── table.py # dependency-free terminal table renderer │ ├── cli.py # argparse CLI: `sentrylog ingest ...` │ └── parsers/ │ ├── __init__.py # parser registry (SourceType -> parse_file) │ ├── base.py # ParseResult / ParseStats / UnparseableLine │ ├── linux_auth.py # /var/log/auth.log parser (sshd, sudo) │ └── windows_evtx.py # Windows .evtx parser (python-evtx) ├── sample_logs/ │ └── auth.log # realistic mixed-outcome sample (runs OOTB) ├── tests/ │ └── test_linux_auth.py # unit + end-to-end tests for the Linux parser ├── requirements.txt ├── pyproject.toml # installs the `sentrylog` console script ├── .gitignore └── README.md ``` ## 标准化事件模式 在 `sentrylog/event.py`（sentrylog/event.py）中定义一次。每个来源都映射到这个： | 字段 | 类型 | 备注 | |---------------|--------------------------|------------------------------------------------------------------| | `timestamp` | `datetime`（时区感知 UTC）| 严格强制执行 — 无时区的日期时间在构建时被拒绝。| | `source_type` | `SourceType` 枚举 | `linux_auth` / `windows_evtx`。 | | `event_id` | `str` 或 `None` | **源原生** id。Win：`"4625"`。Linux：合成助记符。 | | `host` | `str` 或 `None` | 事件发生的机器。 | | `user` | `str` 或 `None` | 事件涉及的主体。 | | `source_ip` | `str` 或 `None` | 网络操作的远程 IP；本地则为 `None`。 | | `action` | `Action` 枚举 | **标准化**类别：`login`、`privilege_escalation`、… | | `outcome` | `Outcome` 枚举 | `success` / `failure` / `unknown`。 | | `raw` | `str` | 原始行/记录 — 保持原样以供审计。 | | `metadata` | `dict` | 源特定额外信息（认证方法、登录类型、命令、…）。 | **`event_id` 与 `action` 是关键区别。** `event_id` 保留源所称呼的内容；`action` 是规则匹配的跨平台桶。它们故意分开。 ## 安装与运行 需要 **Python 3.9+**。核心路径是 **仅标准库** — 解析 Linux 日志不需要安装。 ### 最快开始（无需安装） ``` # 来自 SentryLog/ 目录 python -m sentrylog ingest sample_logs/auth.log ``` ### 安装 `sentrylog` 命令 ``` pip install -e . # core only pip install -e ".[evtx]" # + Windows .evtx support (python-evtx) sentrylog ingest sample_logs/auth.log ``` ### 使用 ``` sentrylog ingest [--type auto|linux_auth|windows_evtx] [--show N] [-v] path log file to ingest (.log/.txt for Linux, .evtx for Windows) --type source type; 'auto' (default) detects by extension + content --show N also print the first N normalized events -v, --verbose show DEBUG (skipped lines) and WARNING (unparseable lines) ``` ### 示例 ``` python -m sentrylog ingest sample_logs/auth.log --show 4 ``` 生成按来源类型 × 结果的计数摘要表，按操作分解，解析/跳过/错误统计，以及（使用 `--show`）查看标准化事件本身。 ## 解析器 ### Linux `auth.log` (`sentrylog/parsers/linux_auth.py`) 处理最重要的认证事件： - **SSH 接受**（`password`、`publickey`、…）→ `login` / `success` - **SSH 失败**（包括 `invalid user`）→ `login` / `failure` - **SSH 无效用户**通知 → `login` / `failure` (`ssh_invalid_user`) - **sudo** 成功（运行命令）→ `privilege_escalation` / `success` - **sudo** 失败（`user NOT in sudoers`、密码错误）→ `privilege_escalation` / `failure` 它以两层进行解析：一个 **syslog 骨架** 正则表达式（时间戳/主机/程序） 然后是 **程序特定** 正则表达式，带有命名组。不匹配骨架的行被记录为警告并跳过 —— **解析器永远不会在错误输入上崩溃**。有效 syslog 但来自我们不建模的程序（CRON、 systemd）的行被静默跳过（使用 `-v` 可见）。 ### Windows `.evtx` (`sentrylog/parsers/windows_evtx.py`) 使用 `python-evtx`（https://pypi.org/project/python-evtx/）读取二进制 EVTX 格式，将每个记录渲染为 XML，并映射四个核心安全 ID： | 事件 ID | 含义 | action | outcome | |----------|-------------------------------|------------------------|-----------| | 4624 | 账户已登录 | `login` | `success` | | 4625 | 账户登录失败 | `login` | `failure` | | 4672 | 分配了特殊权限 | `privilege_escalation` | `success` | | 4688 | 创建了新进程 | `process_creation` | `unknown` | 它从事件 XML 中提取用户、源 IP 和登录类型（例如，类型 `10` 映射到 `RemoteInteractive`/RDP）。`python-evtx` 导入是 **延迟的** — 只有当您实际摄取 `.evtx` 文件时才需要安装该包。 **尝试 Windows 解析器：** 存储库中没有 `.evtx`（它们是二进制的）。 在 Windows 主机上，您可以复制一个并摄取它： ``` pip install -e ".[evtx]" Copy-Item C:\Windows\System32\winevt\Logs\Security.evtx .\sample.evtx python -m sentrylog ingest .\sample.evtx ``` （就地读取 `Security.evtx` 需要 admin 权限；先复制它以避免共享冲突。） ## 测试 ``` pytest tests/ # if pytest is installed python tests/test_linux_auth.py # zero-dependency fallback runner ``` 该套件涵盖了每个 Linux 模式（接受/失败/无效用户/sudo），严格的时区感知时间戳保证，对格式错误的行的优雅处理，以及针对提供的样本的端到端计数检查。 ## 路线图 - **第一阶段 — 摄取 & 标准化** ✅ *(此存储库)* - **第二阶段 — 检测** — 在标准化流上执行关联规则（暴力破解、不可能的旅行、权限提升链）。 - 之后 — 更多来源、持久化存储、警报路由。

标签：DNS解析, Linux 日志, Python 工具, Python 库, Python 开发, Python 模块, Python 社区, Python 脚本, SIEM 工具, Windows 日志, 事件规范化, 命令行界面, 子域名暴力破解, 安全事件检测, 安全信息管理, 开源项目, 日志格式转换, 日志解析, 源代码解析, 终端渲染, 自动化检测, 证书伪造, 逆向工具