SeifMoussa/host-based-intrusion-detection-lab

# 基于主机的入侵检测实验 [](https://github.com/SeifMoussa/host-based-intrusion-detection-lab/actions/workflows/ci.yml) [](https://github.com/SeifMoussa/host-based-intrusion-detection-lab/actions/workflows/codeql.yml) [](LICENSE) 用于基于主机的入侵检测概念的防御性蓝队 / SOC 组合实验。 这是一个仅用于实验的项目，基于合成的本地数据构建。它不监控真实端点，不收集真实 OS 进程列表，不扫描真实系统路径，不收集凭据，也不执行修复。CI/CodeQL 已配置，但尚未通过 GitHub 验证。 ## 项目概述 该实验演示了安全的基于主机的入侵检测工作流，使用了： - 合成的 JSON/CSV 主机事件样本。 - 无害的本地样本文件。 - JSON 文件完整性基线。 - SHA-256 文件完整性比对。 - 透明的合成检测规则。 - 针对预期误报的显式抑制处理。 - Markdown 和 JSON 报告。 - 本地测试、覆盖率、文档检查以及已配置的 GitHub 工作流。 该项目具有确定性，并适合在公开的 GitHub 上发布。 ## 目标岗位相关性 该项目对应于： - SOC 分析师 - 蓝队分析师 - 检测工程师 - 安全自动化分析师 它展示了对告警分诊、文件完整性监控、检测逻辑、误报处理、报告撰写、测试自动化以及安全工程实践的实际掌握程度。 ## 项目演示内容 - 构建和验证 JSON 基线。 - 将当前样本文件与已保存的基线进行比对。 - 检测未更改、已修改、已添加和已删除的文件。 - 解析静态合成的 JSON/CSV 主机事件记录。 - 运行透明的、基于规则的主机事件检测。 - 将事件检测和 FIM 发现结果标准化为告警。 - 在不删除证据的情况下抑制预期的合成误报。 - 生成 Markdown 和 JSON 报告。 - 测试安全边界和负面输入处理。 ## 技术栈 - Python 3.12 - pytest - pytest-cov - ruff - argparse CLI - JSON 基线存储 - JSON/CSV 合成事件样本 - Markdown/JSON 报告 - 本地配置的 GitHub Actions CI - 本地配置的 CodeQL - 本地配置的 Dependabot ## 安全边界 允许： - 位于 `samples/host_events/` 下的合成主机事件记录。 - 位于 `samples/files/` 下的安全文本样本文件。 - 此代码库内的显式本地样本路径。 - 基于本地实验数据生成的 JSON 基线和报告。 不允许： - 恶意软件。 - 漏洞利用代码。 - 持久化或逃避检测逻辑。 - 真实的凭据、API 密钥或令牌。 - 真实的日志或真实的威胁指标。 - 真实的 OS 进程收集。 - 后台代理。 - 真实的系统路径监控。 - 破坏性修复。 - 第三方扫描。 这不是一个生产环境的 HIDS、EDR 或 SIEM。 ## 文件完整性监控 FIM 工作流为： 1. 从显式样本目录创建 JSON 基线。 2. 存储相对于代码库的文件路径、SHA-256、大小、修改时间和基线状态。 3. 将当前的显式样本目录与已保存的基线进行比对。 4. 将文件分类为 `unchanged` (未更改)、`modified` (已修改)、`added` (已添加) 或 `deleted` (已删除)。 示例： ``` python -m hids_lab baseline create --root samples/files/clean --output baselines/generated_baseline.json python -m hids_lab fim compare --baseline baselines/generated_baseline.json --root samples/files/clean ``` ## 主机事件检测 主机事件检测仅对静态合成的 JSON/CSV 记录进行操作。 内置规则包括： - `HIDS-PROC-001`：合成可疑命令标记。 - `HIDS-PROC-002`：伪造的实验调度器父进程标记。 - `HIDS-FILE-001`：合成配置修改事件。 - `HIDS-AUTH-001`：重复的伪造身份验证失败记录。 - `HIDS-LAB-001`：已知实验可疑标记。 示例： ``` python -m hids_lab events validate --input samples/host_events/clean_events.json python -m hids_lab events detect --input samples/host_events/suspicious_events.json --format json python -m hids_lab events detect --input samples/host_events/mixed_events.csv --format text ``` ## 抑制工作流 抑制项是位于 `suppressions/` 下的显式 JSON 条目。它们可以将预期的合成误报从正常输出中隐藏，同时保留证据和原因元数据。 示例： ``` python -m hids_lab events detect --input samples/host_events/false_positive_events.json --suppressions suppressions/example_suppressions.json --format json --include-suppressed ``` 被抑制的告警包含： - `suppressed` - `suppression_id` - `suppression_reason` ## 报告 报告支持 Markdown 和 JSON 输出。 示例： ``` python -m hids_lab report events --input samples/host_events/suspicious_events.json --output reports/events_report.md --format markdown python -m hids_lab report fim --baseline baselines/generated_baseline.json --root samples/files/clean --output reports/fim_report.md --format markdown python -m hids_lab report combined --events samples/host_events/suspicious_events.json --baseline baselines/generated_baseline.json --root samples/files/clean --output reports/combined_report.md --format markdown ``` 稳定的示例报告： - [events_suspicious_report.md](reports/examples/events_suspicious_report.md) - [fim_clean_report.md](reports/examples/fim_clean_report.md) - [combined_lab_report.md](reports/examples/combined_lab_report.md) - [combined_lab_report.json](reports/examples/combined_lab_report.json) 所有报告示例均由合成本地实验数据生成。 ## CLI 快速参考 ``` python -m hids_lab --help python -m hids_lab baseline create --root samples/files/clean --output baselines/generated_baseline.json python -m hids_lab fim compare --baseline baselines/generated_baseline.json --root samples/files/clean python -m hids_lab events validate --input samples/host_events/clean_events.json python -m hids_lab events detect --input samples/host_events/suspicious_events.json --format json python -m hids_lab events detect --input samples/host_events/false_positive_events.json --suppressions suppressions/example_suppressions.json --format json --include-suppressed python -m hids_lab report events --input samples/host_events/suspicious_events.json --output reports/events_report.md --format markdown python -m hids_lab report fim --baseline baselines/generated_baseline.json --root samples/files/clean --output reports/fim_report.md --format markdown python -m hids_lab report combined --events samples/host_events/suspicious_events.json --baseline baselines/generated_baseline.json --root samples/files/clean --output reports/combined_report.md --format markdown ``` ## 测试 本地验证状态： - `pytest`：97 项通过。 - 覆盖率：95.59%。 - 覆盖率阈值：90%。 - `ruff check`：已通过。 - `ruff format --check`：已通过。 - `python scripts/check-docs.py`：已通过。 - CLI 冒烟命令：已在本地通过。 运行： ``` python -m pytest python -m pytest --cov=hids_lab --cov-report=term-missing --cov-fail-under=90 python -m ruff check . python -m ruff format --check . python scripts/check-docs.py ``` CI/CodeQL 已配置，但尚未通过 GitHub 验证。 ## 项目结构 ``` src/hids_lab/ Python package samples/ Synthetic host-event records and safe sample files baselines/ Example JSON baseline reports/examples/ Stable synthetic report examples suppressions/ Explicit suppression examples docs/ Project documentation tests/ Unit, integration, safety, docs, and workflow tests scripts/ Documentation safety checker .github/workflows/ CI and CodeQL workflow configuration ``` ## 已知局限性 - CI 和 CodeQL 尚未在 GitHub 上运行。 - 尚未创建任何发布版本或标签。 - 根据设计，不收集实时端点遥测数据。 - 根据设计，未实现后台监控。 - 根据设计，不扫描真实的系统路径。 - 根据设计，不执行破坏性修复。 - SQLite 基线存储是可选的未来工作；JSON 是主要格式。 ## 许可证 MIT。参见 [LICENSE](LICENSE)。

标签：CodeQL, DNS 解析, GitHub Actions, Homebrew安装, JSON基线, pytest, Python, Ruff, SHA-256校验, SOC分析师, TCP/UDP协议, x64dbg, 主机事件日志, 主机入侵检测, 云计算, 合成数据, 告警分诊, 子域名变形, 安全实验室, 安全报告, 安全规则引擎, 安全评估工具, 安全运营中心, 无后门, 检测逻辑, 网络映射, 自动笔记, 蓝队实验, 规则引擎, 误报抑制, 防御加固