SeifMoussa/threat-detection-yara-log-lab

# 威胁检测与 YARA 风格规则 + 日志分析实验 [](https://github.com/SeifMoussa/threat-detection-yara-log-lab/actions/workflows/ci.yml) [](https://github.com/SeifMoussa/threat-detection-yara-log-lab/actions/workflows/codeql.yml) [](LICENSE) 纯防御型本地实验。本项目分析的是仅存于本仓库中的无害合成样本。它不分析恶意软件、不收集真实日志、不处理真实凭证、不扫描第三方系统，也不提供生产级别的 SOC、EDR 或 SIEM 能力。 ## 概述 本项目是一个用于检测工程实践的蓝队作品集实验。它使用了一个安全的 Python 备用规则引擎，并融入了 YARA 风格的理念：规则元数据、字符串和正则表达式匹配、阈值逻辑、告警分诊字段、误报抑制以及报告生成。 本项目刻意不要求真实的 YARA 支持。后续可能会将 YARA 适配器作为可选集成添加，但当前项目旨在无需 YARA 依赖的情况下，在 Windows 和对 CI 友好的环境中运行。 ## 目标岗位相关性 本实验适用于以下岗位： - SOC 分析师 - 蓝队分析师 - 检测工程师 - 威胁猎人 ## 展示内容 - 设计带有元数据和严重性级别的检测规则 - 加载 JSONL 和 CSV 日志样本 - 扫描本地文本样本 - 生成结构化告警 - 验证误报 - 应用显式抑制 - 生成 Markdown 和 JSON 报告 - 测试检测行为和样本安全性 - 确保安全项目适合公开审查 ## 功能 - 可移植的 Python 备用检测引擎 - 规则类型：`contains`、`regex`、`field_equals`、`threshold` - JSON 备用规则格式 - 支持 JSONL、CSV、TXT 和 LOG 输入 - 结构化告警模型 - 支持对已知误报进行抑制 - 包含扫描、列出规则、验证规则和生成报告的 CLI 命令 - Markdown 和 JSON 报告输出 - 合成样本安全性测试 - 规则质量测试 ## 技术栈 - Python 3.12 - argparse CLI - pytest - ruff - JSON 备用规则 - JSONL/CSV/文本合成样本 - Markdown 和 JSON 报告 ## 安全声明 所有样本均为合成且无害的。看起来可疑的字符串只是为测试检测行为而创建的虚假标记。样本数据仅使用保留域名（如 `.test`）和文档规定的 IP 范围。 严禁包含恶意软件、可运行的攻击代码、真实凭证、真实的生产日志、真实窃取的数据、真实威胁指标以及针对第三方的扫描。 ## 规则格式概述 备用规则是位于 `rules/fallback/` 下的 JSON 文件。每条规则包含： - `id` - `name` - `description` - `severity` - `tags` - `rule_type` - `target` - `pattern` 或 `condition` - `false_positive_notes` - `sample_references` - `enabled` 参见 [docs/rule-writing.md](docs/rule-writing.md)。 ## 安装 ``` python -m pip install -e ".[dev]" ``` ## CLI 用法 验证规则： ``` python -m yara_log_lab validate-rules --rules rules/fallback ``` 列出规则： ``` python -m yara_log_lab list-rules --rules rules/fallback ``` 扫描并输出 JSON： ``` python -m yara_log_lab scan --rules rules/fallback --input samples/logs/suspicious/auth_suspicious.jsonl --format json ``` 扫描并输出文本： ``` python -m yara_log_lab scan --rules rules/fallback --input samples/logs/suspicious/process_suspicious.csv --format text ``` 带抑制的扫描： ``` python -m yara_log_lab scan --rules rules/fallback --input samples/logs/false_positive/auth_false_positive.jsonl --suppressions suppressions/example_suppressions.json --format json --include-suppressed ``` 生成 Markdown 报告： ``` python -m yara_log_lab report --rules rules/fallback --input samples/logs/suspicious/auth_suspicious.jsonl --output reports/examples/auth_suspicious_report.md ``` 生成 JSON 报告： ``` python -m yara_log_lab report --rules rules/fallback --input samples/logs/suspicious/auth_suspicious.jsonl --output reports/examples/auth_suspicious_report.json --format json ``` ## 报告示例 由合成样本生成的报告： - [auth_suspicious_report.md](reports/examples/auth_suspicious_report.md) - [auth_false_positive_suppressed_report.md](reports/examples/auth_false_positive_suppressed_report.md) - [auth_suspicious_report.json](reports/examples/auth_suspicious_report.json) - [sample_summary.json](reports/examples/sample_summary.json) 这些文件是本地合成样本的真实生成输出，而非模拟截图。 ## 测试命令 ``` python -m pytest python -m ruff check . python -m ruff format --check . python scripts/check-docs.py ``` ## 当前验证状态 最新的本地阶段 9 发布准备状态： - `pytest`：88 个通过 - 覆盖率：96.07%，高于设定的 90% 阈值 - `ruff check`：通过 - `ruff format --check`：通过 - `scripts/check-docs.py`：通过 - `validate-rules`：通过 - CLI 扫描命令：通过 - CLI 报告命令：通过 - GitHub Actions 和 CodeQL：已配置，等待首次 GitHub 运行 GitHub Actions CI 和 CodeQL 工作流文件已在仓库中配置，但尚未在 GitHub 上验证，因为本项目尚未在此工作流中发布。 ## 项目结构 ``` src/yara_log_lab/ Python package rules/fallback/ JSON fallback rules rules/yara/ Placeholder for optional later YARA work samples/logs/ Synthetic JSONL and CSV logs samples/files/ Synthetic text samples suppressions/ JSON suppression examples reports/examples/ Generated example reports tests/ pytest test suite docs/ Project documentation .github/workflows/ CI and CodeQL workflow definitions ``` ## 已知限制 - 尚未提供真正的 YARA 适配器 - CI 和 CodeQL 已配置，但尚未在 GitHub 上验证 - 阈值匹配被有意设计为简单模式 - 报告仅为本地的教学产出物 - 目录扫描被有意设计为非递归 - 不收集生产环境遥测数据，不进行外部扫描 - 不包含虚假截图；示例报告是真实的本地生成输出 ## 许可证 MIT 许可证。参见 [LICENSE](LICENSE)。

标签：AMSI绕过, CodeQL, CSV, DNS信息、DNS暴力破解, Homebrew安装, JSON, JSONL, Markdown, pytest, Python, Ruff, YARA规则, 云计算, 合成日志, 告警研判, 威胁检测, 威胁猎人, 安全实验室, 安全报告, 安全规则引擎, 安全评估工具, 安全运营中心, 数据解析, 无后门, 时序数据库, 检测工程师, 网络映射, 蓝队分析师, 规则引擎, 误报抑制