TheGr8Val/TGV-TimelineAnomalyHighlighter
GitHub: TheGr8Val/TGV-TimelineAnomalyHighlighter
基于 scikit-learn 的 DFIR 时间线异常检测工具，通过 IsolationForest 与 LOF 集成模型自动标记可疑事件并提供英文解释。
Stars: 0 | Forks: 0
# TGV Timeline 异常高亮器
[](https://github.com/TheGr8Val/TGV-TimelineAnomalyHighlighter/actions/workflows/ci.yml)
**由 ML 驱动的 DFIR timeline 异常检测。**
导入 DFIR timeline CSV → 返回经过统计异常评分的每一个事件，并为每个被标记的事件提供浅显易懂的英文解释说明。
基于 `scikit-learn`（IsolationForest + LocalOutlierFactor 集成）构建。无需 LLM / API key。
## 快速开始
```
pip install -e ".[dev]"
```
```
import timeline_anomaly as ta
df = ta.analyze("examples/sample_generic.csv")
flagged = df[df["is_anomaly"]]
print(flagged[["timestamp", "event_type", "anomaly_score", "anomaly_notes"]])
```
## 支持的输入格式
| 格式 | 如何使用 |
|--------|-----------|
| **通用 CSV** | 任何带有时间戳列 + 可选 event_type、description、user、host、filename 列的 CSV。可以通过 `TimelineConfig` 配置列名。 |
| **Plaso l2t_csv** | 通过 `MACB`、`sourcetype`、`inode` 头部标记自动识别。由 `psort.py -o l2tcsv` 生成。 |
默认情况下，这两种格式都会被自动识别：
```
df = ta.autodetect_and_load("my_timeline.csv")
```
对于列名不是默认值的通用 CSV：
```
from timeline_anomaly import TimelineConfig, autodetect_and_load
cfg = TimelineConfig(
timestamp_col="datetime",
event_type_col="activity",
user_col="account",
host_col="machine",
)
df = autodetect_and_load("custom.csv", config=cfg)
```
## 工作原理
### 特征工程 (`features.py`)
| 特征 | 描述 |
|---------|-------------|
| `hour` | 一天中的小时 (0–23) |
| `day_of_week` | 0=周一 … 6=周日 |
| `is_weekend` | 如果是周六/周日则为 1 |
| `inter_event_delta_s` | 距离上一个事件的秒数 |
| `inter_event_delta_log` | 上述指标的 log1p 值（处理极端离群值） |
| `burst_rate_60s` | 在以此事件结束的 60 秒窗口内的事件数 |
| `event_type_rarity` | 1 − 此事件类型的频率占比 |
| `user_rarity` | 1 − 此用户的频率占比 |
| `host_rarity` | 1 − 此主机的频率占比 |
| `hour_event_type_zscore` | 小时数相对于该事件类型小时分布的 Z-score |
### 检测 (`detector.py`)
由两个无监督评分器集成，每个评分器均归一化至 [0, 1]：
- **IsolationForest** — 基于隔离的离群值评分；对高维数据具有鲁棒性
- **LocalOutlierFactor** — 基于密度；能够捕捉在上下文中表现为离群值的局部簇
默认情况下，分数按 50/50 混合。集成评分 ≥ 0.65 的事件将被标记。
### 可解释性 (`explain.py`)
对于每个事件，相对于总体具有最高 Z-score 的前 N 个特征将被转化为浅显易懂的英文注释，例如：
## 配置
```
from timeline_anomaly import DetectorConfig, AnomalyDetector
cfg = DetectorConfig(
contamination=0.05, # Expected fraction of anomalies (default 0.05)
lof_n_neighbors=20, # k for LOF
if_weight=0.5, # IsolationForest ensemble weight
lof_weight=0.5, # LOF ensemble weight
flag_threshold=0.65, # Score ≥ this → is_anomaly = True
)
```
## 运行测试
```
pytest tests/ -v
```
## 项目结构
```
timeline_anomaly/
├── ingest.py # CSV parsers (generic + Plaso l2t_csv)
├── features.py # Feature engineering
├── detector.py # IsolationForest + LOF ensemble
├── explain.py # Per-event explainability notes
└── __init__.py # Public API + analyze() convenience function
examples/
├── sample_generic.csv # Realistic DFIR scenario (generic format)
└── sample_plaso.csv # Same scenario in Plaso l2t_csv format
tests/
├── conftest.py # Shared fixtures
├── test_ingest.py
├── test_features.py
└── test_detector.py
```
## 示例数据中内置的异常
示例 timeline 包含了一个用于演示的蓄意内部威胁场景：
| 时间戳 | 内容 | 异常原因 |
|-----------|------|--------------------|
| 2024-03-14 03:11–03:13 | 大量访问 Finance 共享 + USB 拷贝 | 凌晨 3 点的活动，2 分钟内爆发 7 个事件，罕见的事件类型 |
| 2024-03-14 22:47–22:48 | 注册表 Run key + 可疑进程 + 外部连接 | 深夜活动，罕见的事件类型（REGISTRY_WRITE, NETWORK_CONN），异常的主机活动 |
## 路线图
- [x] ML 核心（IsolationForest + LOF 集成，10 个 DFIR 特征）
- [x] CLI（`timeline-anomaly input.csv`）
- [x] 独立 HTML 报告（TGV 品牌，无 CDN）
- [ ] Medium 文章详解
标签：Apex, Python, Scikit-learn, 安全规则引擎, 异常检测, 数字取证, 无后门, 机器学习, 自动化脚本, 逆向工具