karthik13-bot/shivora
GitHub: karthik13-bot/shivora
Shivora 是 DRACARYS 网络安全平台的威胁关联与情报融合模块，通过确定性规则引擎对已评分威胁事件进行加权关联打分、攻击活动检测和 IOC 融合，帮助安全团队构建统一的攻击链和威胁视图。
Stars: 0 | Forks: 0
# DRACARYS – Shivora
**模块 3：威胁关联与情报融合引擎**
Shivora 是 DRACARYS 网络安全平台 pipeline 的第三个模块。它接收来自 Renzai（模块 2）的已评分和分类的威胁事件，并应用确定性关联规则、攻击活动检测算法和情报融合，以构建统一的威胁视图、攻击链和攻击活动情报报告。
## Pipeline 位置
```
Aryuken → Renzai → Shivora → Takshira → ...
↑ Ingest ↑ Score ↑ Correlate
```
| 模块 | 角色 | 输出 |
|---|---|---|
| Aryuken | 网络事件摄取与标准化 | 验证后的事件 |
| Renzai | 威胁评分与指纹识别 | `threat_score`, `severity`, `risk_level` |
| **Shivora** | **关联与情报融合** | **攻击活动，攻击链，IOC 映射** |
## 架构
```
shivora/
├── backend/
│ ├── core/ # Config, database, exceptions, logging
│ ├── models/ # SQLAlchemy ORM models (Correlation, Campaign)
│ ├── schemas/ # Pydantic v2 request/response schemas
│ ├── repositories/ # Database access layer
│ ├── services/ # Business logic layer
│ ├── routes/ # FastAPI route handlers
│ └── utils/
│ ├── correlation_engine.py # Deterministic scoring engine
│ └── intelligence_fusion.py # IOC merging & campaign construction
├── tests/
│ ├── unit/ # Engine, fusion, schema unit tests
│ └── integration/ # Route, repository, service integration tests
├── main.py
├── requirements.txt
└── pyproject.toml
```
### 分层模式
```
Route → Service → Repository → Database
↓
Engine/Fusion utilities
```
## 关联引擎
### 规则与权重
| 规则 | 匹配字段 | 分数 |
|---|---|---|
| 相同的 Source IP | `source_ip` | +30 |
| 相同的 Payload Hash | `payload_hash` | +40 |
| 相同的 Domain | `domain` | +25 |
| 相同的 Malware 家族 | `malware_family` | +35 |
| 相同的国家 | `country` | +10 |
| **最高分数** | | **100** |
### 风险分类
| 分数范围 | 风险等级 |
|---|---|
| 0 – 24 | LOW |
| 25 – 49 | MEDIUM |
| 50 – 74 | HIGH |
| 75 – 100 | CRITICAL |
## API Endpoint
### 关联
| 方法 | 路径 | 描述 |
|---|---|---|
| `POST` | `/api/v1/correlations` | 提交事件进行关联分析 |
| `GET` | `/api/v1/correlations` | 列出关联（分页 + 过滤） |
| `GET` | `/api/v1/correlations/{id}` | 通过 ID 检索关联 |
### 攻击活动
| 方法 | 路径 | 描述 |
|---|---|---|
| `POST` | `/api/v1/campaigns/detect` | 将关联融合为攻击活动 |
| `GET` | `/api/v1/campaigns` | 列出攻击活动（分页 + 过滤） |
| `GET` | `/api/v1/campaigns/{id}` | 通过 ID 检索攻击活动 |
### 健康状况
| 方法 | 路径 | 描述 |
|---|---|---|
| `GET` | `/` | 模块状态 |
| `GET` | `/health` | 健康检查 |
## 安装
### 前置条件
- Python 3.12+
- PostgreSQL 14+（生产环境）— 测试中自动使用 SQLite
### 设置
```
git clone https://github.com/your-org/dracarys-shivora.git
cd dracarys-shivora
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# 使用您的数据库凭据编辑 .env
```
### 运行
```
uvicorn main:app --host 0.0.0.0 --port 8002 --reload
```
交互式文档：`http://localhost:8002/docs`
## 测试
```
# 包含覆盖率的所有测试
pytest tests/
# 仅单元测试
pytest tests/unit/ --no-cov
# 仅集成测试
pytest tests/integration/ --no-cov
# 特定测试类
pytest tests/unit/test_correlation_engine.py -v
# 覆盖率报告
pytest tests/ --cov=backend --cov-report=html
open htmlcov/index.html
```
### 测试结果 (v1.0.0)
| 指标 | 结果 |
|---|---|
| 测试总数 | **282** |
| 通过 | **282** |
| 失败 | **0** |
| 覆盖率 | **93%** |
## 请求与响应示例
### POST /api/v1/correlations
**请求：**
```
{
"events": [
{ "event_id": "evt001", "source_ip": "10.0.0.5", "severity": "HIGH" },
{ "event_id": "evt002", "source_ip": "10.0.0.5", "severity": "HIGH" },
{ "event_id": "evt003", "source_ip": "10.0.0.5", "malware_family": "trojan" }
]
}
```
**响应 (201)：**
```
{
"id": 1,
"correlation_id": "a3f7c2e1-...",
"correlation_score": 65.0,
"risk_level": "HIGH",
"campaign_detected": true,
"campaign_name": "Trojan High Campaign",
"related_events": ["evt001", "evt002", "evt003"],
"source_ips": ["10.0.0.5"],
"malware_families": ["trojan"],
"domains": [],
"countries": [],
"payload_hashes": [],
"correlation_factors": {
"same_source_ip": 30,
"same_payload_hash": 0,
"same_domain": 0,
"same_malware_family": 35,
"same_country": 0
},
"attack_chain": [
{ "step": 1, "event_id": "evt001", "severity": "HIGH", "action": "High-Severity Network Event" },
{ "step": 2, "event_id": "evt002", "severity": "HIGH", "action": "High-Severity Network Event" },
{ "step": 3, "event_id": "evt003", "malware": "trojan", "action": "T1204 – User Execution" }
],
"ioc_summary": {
"ips": ["10.0.0.5"],
"domains": [],
"hashes": [],
"malware_families": ["trojan"],
"countries": []
},
"created_at": "2026-06-20T10:00:00Z",
"updated_at": "2026-06-20T10:00:00Z"
}
```
### POST /api/v1/campaigns/detect
**请求：**
```
{
"correlation_ids": ["a3f7c2e1-..."],
"campaign_name": "Trojan Recon Campaign"
}
```
**响应 (201)：**
```
{
"id": 1,
"campaign_id": "b9d4e1f0-...",
"campaign_name": "Trojan Recon Campaign",
"threat_level": "HIGH",
"confidence_score": 65.0,
"related_events": ["evt001", "evt002", "evt003"],
"correlation_ids": ["a3f7c2e1-..."],
"kill_chain_phase": "Installation",
"indicators_of_compromise": {
"ips": ["10.0.0.5"],
"domains": [],
"hashes": [],
"malware_families": ["trojan"],
"countries": [],
"total_ioc_count": 2
},
"attack_techniques": ["High-Severity Network Event", "T1204 – User Execution"],
"threat_actors": ["Operator of Trojan"],
"campaign_summary": "Campaign 'Trojan Recon Campaign' identified across 1 correlation(s) involving 3 event(s). Observed 1 unique source IP(s) and 0 domain(s). Malware families identified: trojan.",
"is_active": true,
"first_seen": "2026-06-20T10:00:00Z",
"last_seen": "2026-06-20T10:00:00Z",
"created_at": "2026-06-20T10:00:00Z",
"updated_at": "2026-06-20T10:00:00Z"
}
```
## 数据库模型
### 关联
| 字段 | 类型 | 描述 |
|---|---|---|
| `id` | Integer PK | 自增主键 |
| `correlation_id` | String UUID | 唯一关联引用 |
| `correlation_score` | Float | 0–100 加权分数 |
| `risk_level` | String | LOW / MEDIUM / HIGH / CRITICAL |
| `campaign_name` | String? | 推断得出或为空 |
| `campaign_detected` | Boolean | 分数 ≥ 阈值且事件数 ≥ 2 |
| `related_events` | JSON | 输入事件 ID 列表 |
| `correlation_factors` | JSON | 各规则得分明细 |
| `source_ips` | JSON | 去重后的 IP |
| `attack_chain` | JSON | 有序步骤序列 |
| `ioc_summary` | JSON | 合并的指标 |
### 攻击活动
| 字段 | 类型 | 描述 |
|---|---|---|
| `id` | Integer PK | 自增主键 |
| `campaign_id` | String UUID | 唯一攻击活动引用 |
| `campaign_name` | String | 易读的攻击活动标签 |
| `threat_level` | String | 相关关联中的最高风险等级 |
| `confidence_score` | Float | 加权平均置信度 |
| `related_events` | JSON | 跨关联的所有事件 ID |
| `indicators_of_compromise` | JSON | 融合的 IOC 数据 |
| `attack_techniques` | JSON | MITRE ATT&CK 技术标签 |
| `kill_chain_phase` | String? | Lockheed Martin Kill Chain 阶段 |
| `campaign_summary` | Text | 易读的叙述文本 |
| `is_active` | Boolean | 攻击活动活跃状态 |
## 环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
| `DATABASE_URL` | `postgresql+asyncpg://...` | 生产数据库 |
| `TEST_DATABASE_URL` | `sqlite+aiosqlite:///:memory:` | 测试隔离 |
| `APP_ENV` | `development` | 环境 |
| `LOG_LEVEL` | `INFO` | 日志详细程度 |
| `CORRELATION_THRESHOLD` | `25` | 标记攻击活动的最低分数 |
| `CAMPAIGN_MIN_EVENTS` | `2` | 检测攻击活动的最少事件数 |
## DRACARYS 模块状态
| 模块 | 名称 | 状态 | 测试 |
|---|---|---|---|
| 1 | Aryuken | ✅ 完成 | 94 |
| 2 | Renzai | ✅ 完成 | 111 |
| **3** | **Shivora** | ✅ **完成** | **282** |
| 4 | Takshira | 🔜 计划中 | – |
| 5 | Seyon | 🔜 计划中 | – |
| 6 | Maayon | 🔜 计划中 | – |
| 7 | Smriti | 🔜 计划中 | – |
| 8 | Anveshanam | 🔜 计划中 | – |
| 9 | kotravai | 🔜 计划中 | – |
*DRACARYS – Shivora v1.0.0 | Python 3.12 | FastAPI | SQLAlchemy 2.x | Pydantic v2*
标签：AMSI绕过, AV绕过, FastAPI, SQLAlchemy, 关联分析, 威胁情报, 威胁检测, 安全, 开发者工具, 测试用例, 超时处理, 逆向工具