# SOC Intelligence Command
用于透明检测、异常证据、告警优先级排序、实体关联以及人工审查响应建议的防御性安全运营研究基础设施。
## 研究目标
一个透明的多阶段 SOC pipeline 能否结合基于规则的检测、异常证据、告警优先级排序和实体级别的关联，从而在保持可见性、可解释性和响应问责制的同时减少分析师的工作量？
| 研究问题 | 仅在本地执行后生成的证据 |
| --- | --- |
| 可解释的规则能否呈现出与防御者相关的可疑模式？ | 规则命中、证据字符串以及合成标签回归指标 |
| 异常证据能否在不替代规则的情况下改善分诊上下文？ | 附加到告警的主机-小时异常分数 |
| 实体与时间关联能否将碎片化的告警转化为可审查的候选事件？ | 关联图和事件表 |
| 优先级排序能否提升分析师队列的可见性？ | 风险理由、优先级分布、告警时间线 |
| 响应指导能否在不进行不安全自动化的情况下保持实用性？ | 人工审查 playbook 和审计追踪 |
## 架构
该图像是一个文档图表。它不是操作性的 SOC 截图、对已部署能力的声明，也不是基于数据得出的结果。
| 层级 | 功能 | 信任控制 |
| --- | --- | --- |
| Telemetry 实验室 | 合成身份、endpoint、DNS 和网络事件 | 默认为虚构；真实日志保留在本地并已获授权 |
| 标准化 | 规范的时间戳、实体、事件类型和严重性 | 不捏造缺失的证据 |
| 检测 | 可解释的阈值和模式规则 | 每次命中的证据文本 |
| 异常证据 | 主机-小时行为评分 | 支持分诊；绝不仅凭此项作出裁决 |
| 优先级排序 | 严重性、置信度、关键性、异常、时效性 | 明确的风险理由和有界的评分 |
| 关联 | 共享实体加上时间上下文 | 候选事件，而非归因 |
| 响应 | 证据保留和审查步骤 | 影响较大的操作需要人工批准 |
| 可审计性 | 结构化结果和 hash 链式账本 | 可复现的 seed 和运行元数据 |
## 立即运行 — 无需数据集
该仓库包含一个确定性的 **synthetic SOC laboratory**。它会生成一个虚构的多源事件流，注入高级别的防御者相关场景，然后运行完整的 pipeline。
```
python scripts/run_synthetic_soc_lab.py
```
Windows 快速开始：
```
cd %USERPROFILE%\soc-intelligence-command
git pull
py -m venv .venv
.venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python scripts/run_synthetic_soc_lab.py
```
可选的可复现性控制：
```
python scripts/run_synthetic_soc_lab.py --days 21 --seed 42
```
该 synthetic laboratory 会生成实际的本地证据 artifact：
```
outputs/results/synthetic_events.csv
outputs/results/synthetic_host_hour_anomalies.csv
outputs/results/synthetic_alerts.csv
outputs/results/synthetic_incidents.csv
outputs/results/synthetic_response_recommendations.csv
outputs/results/synthetic_soc_summary.json
outputs/results/audit_ledger.jsonl
outputs/reports/synthetic_soc_brief.md
outputs/figures/synthetic_alert_volume_by_rule.png
outputs/figures/synthetic_alert_timeline.png
outputs/figures/synthetic_priority_distribution.png
outputs/figures/synthetic_incident_correlation_graph.png
```
所有生成的文件都保留了 **synthetic** 一词。它们仅演示可执行的工作流和可复现性；它们并不是关于真实组织的经验性主张。
## Synthetic laboratory 场景
| 场景 | 虚构的信号模式 | 检测证据 | 分析师解读 |
| --- | --- | --- | --- |
| 凭据压力 | 反复的认证失败，随后是一次成功的登录 | `AUTH-001`, `AUTH-002` | 验证账户上下文和源网络授权 |
| 权限更改 | 通过身份上下文链接的角色分配 | `ID-001` | 验证批准和业务目的 |
| 多主机远程访问 | 在短时间内的多次远程认证 | `NET-001` | 确定是经过批准的管理还是可疑的访问 |
| 异常 DNS | 长且字符多样化的 DNS 名称 | `DNS-001` | 审查查询上下文；启发式方法并非最终裁决 |
| 进程谱系 | 源自 email-client 谱系的未识别进程 | `END-001` | 保留 endpoint 证据并验证软件上下文 |
这些场景不是攻击方案、恶意软件模拟或真实事件。它们是专门为评估 pipeline 而设计的、范围受限的防御性模式。
## 关联逻辑
```
flowchart LR
A[Alert with rule evidence] --> C[Risk score]
B[Host-hour anomaly evidence] --> C
C --> D[Entity graph]
D --> E[Shared user / host / IP / process / domain]
E --> F[Temporal proximity window]
F --> G[Incident candidate]
G --> H[Analyst review playbook]
H --> I[Document decision and evidence]
```
候选事件是告警和实体节点图中的一个连通分量。它是一种分诊结构，而不是断定所有相关事件都有一个单一的根本原因。
## 检测与优先级排序方法
### 透明规则
| 规则 | 启发式证据 | 严重性 | 教育性战术标签 |
| --- | --- | --- | --- |
| `AUTH-001` | 用户/源在短时间窗口内重复登录失败 | 高 | Credential Access；Initial Access |
| `AUTH-002` | 在 synthetic 基准时间之外成功的认证 | 中 | Initial Access |
| `ID-001` | 成功的角色分配 | 高 | Privilege Escalation；Persistence |
| `DNS-001` | 长的高熵 DNS 名称 | 中 | Command and Control |
| `END-001` | 来自 email client 的未识别进程谱系 | 高 | Execution |
| `NET-001` | 跨多个目标的远程认证 | 高 | Lateral Movement |
战术标签是 **教育性的 MITRE 风格的注解**，并非官方的覆盖范围声明。
### 优先级分数
每个告警都会获得一个可解释的、范围在 0–100 之间的分数：
```
risk = severity + confidence + asset criticality + anomaly evidence + recency
```
实际的实现使用有文档记录的权重，并在每个告警中保存一个 `priority_rationale` 字段。它用于对分析师的注意力进行排序；它不允许自主响应。
### 异常证据
该项目使用事件计数、认证失败计数、DNS 量、远程认证计数、身份更改计数和不同域名计数来聚合主机-小时行为。Isolation Forest 在较早的 synthetic 时间线上进行训练，并对完整的运行进行评分。
异常输出是支持性上下文，而不是决策引擎。
## 响应安全边界
```
flowchart TD
A[Prioritized incident candidate] --> B[Preserve evidence]
B --> C[Validate user, asset, and business context]
C --> D[Review correlated identity, endpoint, DNS, and network records]
D --> E{Authorized and expected?}
E -->|Yes| F[Document rationale and monitor]
E -->|No or uncertain| G[Escalate to analyst / incident process]
G --> H[Containment only with explicit approval]
```
建议的响应包括保留记录、确认授权、审查 endpoint 和身份上下文以及升级。 **没有任何破坏性、干扰性或凭据/网络操作被自动化。** 阅读 [`docs/response_playbooks.md`](docs/response_playbooks.md) 以获取详细的分析师指南。
## 指标及其局限性
synthetic lab 包含带标签的虚构事件，从而支持回归测试指标：
| 测量指标 | 含义 | 局限性 |
| --- | --- | --- |
| Synthetic precision | 与 synthetic 标签匹配的事件链接告警的比例 | 不是真实的 SOC 误报率 |
| Synthetic recall | 链接到告警的 synthetic 带标签事件的比例 | 不是真实的检测覆盖率声明 |
| 告警量减少 | 未提升为告警的事件的比率 | 不能完全衡量分析师的工作量 |
| Synthetic MTTD | 从 synthetic 场景开始到第一个链接告警的时间 | 取决于虚构的时间戳和标签 |
| 事件计数 | 关联的告警组件 | 候选分组，而非确认的案例 |
不要将 synthetic 指标作为真实的网络安全性能证据包含在专业报告中。
## 仓库地图
```
.
├── assets/ Conceptual architecture and correlation diagrams
├── configs/ Reproducible synthetic-laboratory configuration
├── data/ Local telemetry boundary and schema guidance
├── docs/ Methodology, playbooks, synthetic-lab protocol, report template
├── matlab/ Local alert-timeline visualization
├── notebooks/ Runnable synthetic SOC walkthrough
├── outputs/ Local-only CSV, graph, report, and ledger artifacts
├── scripts/ One-command synthetic SOC laboratory
├── src/socintel/
│ ├── synthetic.py Fictional multi-source telemetry and labeled scenarios
│ ├── schema.py Canonical SOC normalization
│ ├── detections.py Interpretable defensive detection rules
│ ├── anomaly.py Host-hour anomaly evidence
│ ├── scoring.py Transparent analyst-priority score
│ ├── correlation.py Entity and timeline incident graph
│ ├── taxonomy.py Educational tactic labels
│ ├── playbooks.py Human-review response recommendations
│ ├── ledger.py Hash-chained experimental record
│ ├── reporting.py Local analyst briefing generator
│ └── visualization.py Executed-run charts and graph visualizations
└── tests/ Synthetic telemetry, detection, pipeline, and ledger tests
```
## MATLAB 集成
在运行 synthetic lab 之后：
```
addpath('matlab')
plot_alert_timeline('outputs')
```
`matlab/plot_alert_timeline.m` 会读取本地生成的 synthetic 告警表，并保存一个独立的 MATLAB 时间线图表。它特意依赖于已执行的 Python 输出。
## 可复现性
- 固定的 seed 贯穿 synthetic 生成器和异常模型。
- 确定性的 synthetic 事件 ID。
- 单元测试涵盖 synthetic 生成、检测族、优先级排序/关联以及账本完整性。
- GitHub Actions 运行无数据的测试套件。
- Hash 链式的本地账本记录实验元数据和指标。
在本地运行测试：
```
python -m pytest
```
## 真实 Telemetry 扩展策略
该项目有意以 synthetic 为先。以后若要添加真实的 telemetry，请创建一个已授权的本地 adapter，将字段映射到 `socintel.schema.normalize_events` 中，将日志保留在 Git 之外，记录数据授权，在适当的情况下移除或 hash 敏感标识符，并在操作性地使用任何输出之前执行分析师审查。
## 局限性
1. Synthetic telemetry 无法代表组织的日志质量、架构、用户、正常管理或对手行为。
2. 固定的规则和异常模型可能会产生误报和漏报。
3. 实体关联可能会过度链接或链接不足事件。
4. 教育性战术标签不能替代经过验证的检测分类法。
5. 人工审查对于解读、遏制和证据处理仍然是必要的。
6. 此仓库是研究基础设施，不是生产级的 SIEM、SOAR 平台或事件响应系统。
## 许可证
基于 [MIT License](LICENSE) 发布。不包含真实的安全 telemetry。