rap1p1/detection-as-code
GitHub: rap1p1/detection-as-code
基于 ELK Stack 的多源日志检测工程实验室，集成 EQL/Sigma 规则、pytest 自动化测试、GitHub Actions CI 与告警富化通知，践行检测即代码工作流。
Stars: 0 | Forks: 0
# 多源日志流水线与检测即代码实验
一个生产级别的检测工程实验室，演示了多源日志摄取、ECS 规范化、带有自动化测试的检测即代码工作流程、告警富化以及 CI 集成。
## 架构
```
+-----------------+ +------------+ +------------------+ +---------+
| Windows Sysmon |---->| | | | | |
| (Winlogbeat) | | | | | | |
+-----------------+ | | | | | |
| Logstash |---->| Elasticsearch |---->| Kibana |
+-----------------+ | (ECS Map) | | (Storage) | | (UI) |
| Linux auth.log |---->| | | | | |
| Nginx access | | | | | | |
| (Filebeat) | | | | | | |
+-----------------+ | | +--------+---------+ +---------+
| | |
+-----------------+ | | v
| Mock Firewall |---->| | +--------+---------+
| (TCP/JSON) | +------------+ | Enrichment Script|
+-----------------+ | (Python) |
+--------+---------+
+------------------+ |
| GitHub Actions | v
| (CI: pytest) | +--------+---------+
+------------------+ | Telegram Notify |
| +------------------+
v
+------------------+
| rules/ + tests/ |
| (Detection-as- |
| Code repo) |
+------------------+
```
## 前置条件
- Docker 和 Docker Compose
- Python 3.10+
- Git
- (可选) 在安装了 Sysmon 的 Windows 主机上配置 Winlogbeat
## 快速开始
1. 克隆仓库:
git clone https://github.com//detection-as-code.git
cd detection-as-code
2. 启动 ELK stack:
docker-compose up -d
3. 验证服务是否正在运行:
- Elasticsearch: http://localhost:9200
- Kibana: http://localhost:5601
4. 安装 Python 依赖:
pip install -r scripts/requirements.txt
5. 运行检测规则测试:
pytest tests/ -v
## 仓库结构
```
detection-as-code/
├── .github/workflows/ GitHub Actions CI pipeline
│ └── validate-rules.yml
├── docker-compose.yml Docker Compose for ELK stack
├── logstash/
│ ├── pipelines.yml Multi-pipeline configuration
│ └── pipeline/
│ ├── 10-sysmon.conf Windows Sysmon ECS mapping
│ ├── 20-linux-auth.conf Linux auth.log parsing
│ ├── 30-nginx.conf Nginx access log parsing
│ └── 40-firewall.conf Firewall JSON log parsing
├── filebeat/
│ └── filebeat.yml Filebeat configuration
├── sample-logs/ Sample log data for testing
├── rules/
│ ├── eql/ EQL detection rules (TOML format)
│ └── sigma/ Sigma detection rules (YAML format)
├── tests/
│ ├── conftest.py Pytest fixtures
│ ├── test_rule_schema.py Schema validation tests
│ ├── test_eql_rules.py EQL rule functional tests
│ ├── test_sigma_rules.py Sigma rule functional tests
│ └── mock_data/ Test event data
├── scripts/
│ ├── enrich_alerts.py Alert enrichment (geo, threat intel)
│ ├── notify_telegram.py Telegram notification
│ └── requirements.txt Python dependencies
└── docs/
├── architecture.md Detailed architecture documentation
└── rule-development-guide.md Rule authoring guide
```
## 检测规则
### EQL 规则
EQL 规则采用 TOML 格式和结构化元数据：
| 规则 | MITRE ATT&CK | 严重性 | 日志源 |
|------|--------------|----------|------------|
| SSH 暴力破解 | T1110.001 | 高危 | Linux auth |
| Nginx SQL 注入 | T1190 | 高危 | Nginx |
| WMI 事件订阅持久化 | T1546.003 | 严重 | Sysmon |
| 可疑的出站连接 | T1571 | 中危 | Firewall |
### Sigma 规则
| 规则 | MITRE ATT&CK | 级别 | 日志源 |
|------|--------------|-------|------------|
| 可疑的 PowerShell 执行 | T1059.001 | 高危 | Windows Process Creation |
| 可疑的用户创建 + 登录 | T1136.001 | 高危 | Linux auth |
## 测试
所有检测规则都通过自动化测试进行验证，无需运行 Elasticsearch 实例：
- **Schema 校验**: 确保所有规则都具有必需的元数据字段、有效的 severity/status 枚举值、MITRE ATT&CK 映射以及唯一的 ID。
- **功能测试**: 针对模拟事件数据验证检测逻辑，同时检查真阳性检出和假阳性拒绝。
```
pytest tests/ -v
```
## CI 流水线
GitHub Actions 工作流在推送到 `rules/` 或 `tests/` 目录时触发，或针对这些目录发起 pull request 时触发。它会运行所有三个测试套件（schema、EQL、Sigma）并报告通过/失败状态。
## 告警富化
富化脚本会查询 Elasticsearch 中的近期告警，并添加：
- 通过 ip-api.com 获取 IP 地理位置（国家、城市、ISP）
- VirusTotal 信誉评分（可选，需要 API key）
- AbuseIPDB 滥用置信度评分（可选，需要 API key）
```
python scripts/enrich_alerts.py --index "logs-*" --minutes 60
python scripts/enrich_alerts.py --dry-run --index "logs-firewall-*" --minutes 30
```
## Telegram 通知
富化后的告警可以转发至 Telegram：
```
export TELEGRAM_BOT_TOKEN="your-bot-token"
export TELEGRAM_CHAT_ID="your-chat-id"
python scripts/notify_telegram.py --index "logs-*" --minutes 30
```
## 日志源与 ECS 映射
所有日志源均被规范化为 Elastic Common Schema (ECS)：
| 来源 | 关键 ECS 字段 |
|--------|---------------|
| Sysmon | `process.executable`, `process.command_line`, `user.name`, `source.ip`, `destination.ip` |
| Linux auth | `source.ip`, `user.name`, `event.action`, `event.outcome` |
| Nginx | `source.ip`, `http.request.method`, `url.path`, `http.response.status_code` |
| Firewall | `source.ip`, `destination.ip`, `destination.port`, `network.transport`, `event.action` |
## 参考
- [MITRE ATT&CK 框架](https://attack.mitre.org/)
- [Elastic Common Schema](https://www.elastic.co/guide/en/ecs/current/index.html)
- [Sigma 规范](https://github.com/SigmaHQ/sigma-specification)
- [Event Query Language (EQL)](https://www.elastic.co/guide/en/elasticsearch/reference/current/eql.html)
- [Logstash 过滤器插件](https://www.elastic.co/guide/en/logstash/current/filter-plugins.html)
标签：Elastic Stack, 内容过滤, 安全规则引擎, 安全运营, 开源框架, 扫描框架, 持续集成, 流量重放, 版权保护, 请求拦截, 越狱测试, 逆向工具