hamzaashur22/SOAR-Threat-Intelligence-Automation-Lab
GitHub: hamzaashur22/SOAR-Threat-Intelligence-Automation-Lab
一个用 Python 从零构建的轻量级 SOAR 家庭实验室，实现对 IOC 指标的自动分类、威胁情报富化、置信度评分和结构化报告生成。
Stars: 0 | Forks: 0
# SOAR 威胁情报自动化实验室
这是一个从头开始构建轻量级 SOAR（安全编排、自动化和响应）管道的家庭实验室项目，使用 Python 实现。该脚本导入威胁指标 列表，通过开源威胁情报 API 对其进行富化，按置信度进行评分，并输出结构化结果供分析师审查——所有这些均通过 Windows Task Scheduler 自动执行。
## 展示的技能
- 用于安全自动化的 Python 脚本编写
- REST API 集成
- IOC 分类和规范化（IP、域名、URL、哈希）
- 威胁富化和置信度评分
- 去重逻辑
- 结构化输出生成（CSV blocklist、Markdown 情报简报、审计日志）
- 使用 `.env` 进行环境变量管理
- Windows Task Scheduler 用于自动执行
- 错误处理和弹性管道设计
## 工具与技术
| 工具 / 服务 | 用途 |
|---|---|
| Python 3 | 核心脚本语言 |
| VirusTotal API | 域名、URL 和哈希富化 |
| AbuseIPDB API | IP 信誉和滥用置信度评分 |
| python-dotenv | 安全的 API 密钥管理 |
| VMware Workstation | 虚拟化实验室环境 |
| Windows Task Scheduler | 自动化计划执行 |
| PowerShell | 脚本执行和环境导航 |
## 架构
```
Iocs_seed.txt
|
v
read_seed_iocs() -- reads raw IOC strings from file
|
v
classify_and_normalize() -- detects type: ip | domain | url | hash | unknown
|
v
filter unknowns
|
v
dedupe_iocs() -- removes duplicates by (type, normalized) composite key
|
v
enrichment loop
|-- IP --> AbuseIPDB API
|-- domain --> VirusTotal API
|-- URL --> VirusTotal API (base64 encoded)
|-- hash --> VirusTotal API (/files/ endpoint)
|
v
score_indicator() -- malicious x20, suspicious x10, abuse confidence added
|
v
confidence buckets: HIGH (>=60) | MED (>=20) | LOW (<20)
|
v
+-----------------+------------------+----------+
| | | |
blocklist.csv intel_brief.md run.log (stdout)
(full results) (summary view) (audit trail)
```
## 实验环境搭建
### 第 1 步 — 创建共享文件夹（实际上不必是共享文件夹，你可以在一个虚拟机上完成整个实验）
但是，如果你选择使用共享文件夹，请确保它可以从你的主机 visible 到虚拟机。
在 VMware Workstation 中转到：
```
VM → Settings → Options → Shared Folders → Always enabled
```
添加你指定的文件夹并启用它。这使得它可以在虚拟机内部的以下位置访问：
```
\\vmware-host\Shared Folders\SOAR_output
```
### 第 2 步 — 验证主机/虚拟机可见性
*可选*
在虚拟机内创建一个写入共享文件夹的测试脚本，并确认它出现在主机上（反之亦然）。这验证了你的管道输出将可从两个环境读取。
### 第 3 步 — 获取 API 密钥
在以下网站注册免费账户：
- [VirusTotal](https://www.virustotal.com) — 提供域名、URL 和哈希信誉数据
- [AbuseIPDB](https://www.abuseipdb.com) — 提供 IP 滥用置信度评分和社区报告
### 第 4 步 — 创建你的 `.env` 文件
在你的共享文件夹中创建一个名为 `.env` 的文件，包含：
```
VT_API_KEY=your_virustotal_key_here
ABUSEIPDB_API_KEY=your_abuseipdb_key_here
```
### 第 5 步 — 创建你的 IOC 种子文件
在共享文件夹中创建 `Iocs_seed.txt`。每行添加一个指标。
*请注意，这些是真实的恶意 IP 和域名，请谨慎处理*
```
# 已知恶意 IP
177.52.87.237
172.184.139.225
# domains
google.com
codeproofs[.]com
verify-lastpass[.]com
google.com # duplicate -- will be deduplicated automatically
```
### 第 6 步 — 运行脚本
打开 PowerShell，导航到你的共享文件夹，然后运行：
```
cd "\\vmware-host\Shared Folders\SOAR_output"
python soar_script.py
```
会自动创建三个输出文件：
```
blocklist.csv -- full enriched IOC results
intel_brief_.md -- confidence summary for analysts
run.log -- timestamped audit trail of the entire run
```
### 第 7 步 — 使用 Task Scheduler 自动化
打开 Windows Task Scheduler 并创建一个基本任务：
```
Name: SOAR Intel Run
Trigger: Daily
Action: Start a program
Program: script
Arguments: "\\vmware-host\Shared Folders\SOAR_output\soar_script.py"
```
脚本现在将按计划自动运行，无需手动干预。
## 示例输出
*如果一切顺利*
### blocklist.csv
### 情报简报 md
## 关键发现
针对小型测试种子文件运行脚本产生了真实的威胁情报结果：
**`verify-lastpass[.]com` — 评分：300 / 高**
被 14 个 VirusTotal 引擎标记为恶意，另有 2 个可疑检测。这是一个已知的冒充 LastPass 密码管理器的钓鱼域名——一种现实世界中的凭证窃取攻击载体。
**`177.52.87.237` — 评分：100 / 高**
AbuseIPDB 置信度评分为 100，有 577 条社区滥用报告。该 IP 已被报告为恶意 577 次。任何进出此地址的流量都值得立即调查。
**`codeproofs[.]com` — 评分：90 / 高**
被 4 个 VT 引擎标记为恶意，另有 1 个可疑命中。
**`google.com` — 评分：0 / 低**
未返回信号——这是已知良性域名的预期行为。确认评分引擎正确处理了无 false positives 的良性指标。
## 挑战与经验教训
**VMware 网络隔离**
虚拟机的网络适配器未配置出站互联网访问。脚本的错误处理优雅地捕获了每个 `ConnectionError` 并继续处理而不是崩溃——验证了 `try/except` 设计的弹性。
**Z: 驱动器未在 PowerShell 中映射**
脚本一开始不工作，因为 powershell 找不到 Z: 驱动器。为了解决这个问题，我更新了文件顶部的路径，以准确地指向我们的文件夹，使 powershell 能够找到它。
**Windows 隐藏文件扩展名**
Windows 静默地将 `.txt` 添加到 `.env` 文件中，使其变为 `.env.txt`。在通过 PowerShell 重命名更正扩展名之前，脚本无法找到该文件。教训：始终使用 `dir -Force` 验证实际文件名，以避免令人头疼的小问题。
**Run.log**
这是故障排除过程和整个实验室的关键部分。脚本创建了一个文件，用于审计和记录运行期间采取的每个操作。每个处理过的 IOC、每个尝试过的 API 调用、每个捕获的错误，以及确认输出文件已写入，所有这些都带有 UTC 时间戳。如果没有这个文件，很难 pinpoint 和调试我脚本中的问题。
## 脚本结构
```
soar_script.py
│
├── Constants OUT_DIR, SEED_FILE, ENV_FILE, timeouts
│
├── Data Models IOC, Enrichment, ResultRow (dataclasses)
│
├── Utilities now_utc_iso(), load_keys(), read_seed_iocs(), log_line()
│
├── Classifiers is_ip(), is_url(), is_hash()
│ normalize_domain(), normalize_url()
│ classify_and_normalize(), dedupe_ioc()
│
├── API Headers vt_headers(), abuse_headers()
│
├── API Lookups vt_lookup_domain(), vt_lookup_url(),
│ vt_lookup_hash(), abuse_lookup_ip()
│
├── Scoring score_indicator()
│
└── main() Orchestrates the full pipeline end to end
```
## 未来改进
这个实验室可以进一步增强，使其看起来像一个实际的 SOC 工作流程，想到的一些关键更改是：
- **实时威胁源集成** — 用每次运行自动拉取的 AlienVault OTX 或 Abuse.ch 源替换静态种子文件
- **SIEM 集成** — 将 `blocklist.csv` 导入 Splunk 或 Elastic，并编写检测规则，当实时流量与高置信度 IOC 匹配时触发
- **电子邮件警报** — 当检测到高置信度 IOC 时发送自动摘要电子邮件
### 第 3 步 — 获取 API 密钥
在以下网站注册免费账户：
- [VirusTotal](https://www.virustotal.com) — 提供域名、URL 和哈希信誉数据
- [AbuseIPDB](https://www.abuseipdb.com) — 提供 IP 滥用置信度评分和社区报告
### 第 4 步 — 创建你的 `.env` 文件
在你的共享文件夹中创建一个名为 `.env` 的文件，包含：
```
VT_API_KEY=your_virustotal_key_here
ABUSEIPDB_API_KEY=your_abuseipdb_key_here
```
### 第 5 步 — 创建你的 IOC 种子文件
在共享文件夹中创建 `Iocs_seed.txt`。每行添加一个指标。
*请注意，这些是真实的恶意 IP 和域名，请谨慎处理*
```
# 已知恶意 IP
177.52.87.237
172.184.139.225
# domains
google.com
codeproofs[.]com
verify-lastpass[.]com
google.com # duplicate -- will be deduplicated automatically
```
### 第 6 步 — 运行脚本
打开 PowerShell，导航到你的共享文件夹，然后运行：
```
cd "\\vmware-host\Shared Folders\SOAR_output"
python soar_script.py
```
会自动创建三个输出文件：
```
blocklist.csv -- full enriched IOC results
intel_brief_
### 第 7 步 — 使用 Task Scheduler 自动化
打开 Windows Task Scheduler 并创建一个基本任务：
```
Name: SOAR Intel Run
Trigger: Daily
Action: Start a program
Program: script
Arguments: "\\vmware-host\Shared Folders\SOAR_output\soar_script.py"
```
脚本现在将按计划自动运行，无需手动干预。
## 示例输出
*如果一切顺利*
### blocklist.csv
### 情报简报 md
## 关键发现
针对小型测试种子文件运行脚本产生了真实的威胁情报结果：
**`verify-lastpass[.]com` — 评分：300 / 高**
被 14 个 VirusTotal 引擎标记为恶意，另有 2 个可疑检测。这是一个已知的冒充 LastPass 密码管理器的钓鱼域名——一种现实世界中的凭证窃取攻击载体。
**`177.52.87.237` — 评分：100 / 高**
AbuseIPDB 置信度评分为 100，有 577 条社区滥用报告。该 IP 已被报告为恶意 577 次。任何进出此地址的流量都值得立即调查。
**`codeproofs[.]com` — 评分：90 / 高**
被 4 个 VT 引擎标记为恶意，另有 1 个可疑命中。
**`google.com` — 评分：0 / 低**
未返回信号——这是已知良性域名的预期行为。确认评分引擎正确处理了无 false positives 的良性指标。
## 挑战与经验教训
**VMware 网络隔离**
虚拟机的网络适配器未配置出站互联网访问。脚本的错误处理优雅地捕获了每个 `ConnectionError` 并继续处理而不是崩溃——验证了 `try/except` 设计的弹性。
**Z: 驱动器未在 PowerShell 中映射**
脚本一开始不工作，因为 powershell 找不到 Z: 驱动器。为了解决这个问题，我更新了文件顶部的路径，以准确地指向我们的文件夹，使 powershell 能够找到它。
**Windows 隐藏文件扩展名**
Windows 静默地将 `.txt` 添加到 `.env` 文件中，使其变为 `.env.txt`。在通过 PowerShell 重命名更正扩展名之前，脚本无法找到该文件。教训：始终使用 `dir -Force` 验证实际文件名，以避免令人头疼的小问题。
**Run.log**
这是故障排除过程和整个实验室的关键部分。脚本创建了一个文件，用于审计和记录运行期间采取的每个操作。每个处理过的 IOC、每个尝试过的 API 调用、每个捕获的错误，以及确认输出文件已写入，所有这些都带有 UTC 时间戳。如果没有这个文件，很难 pinpoint 和调试我脚本中的问题。
## 脚本结构
```
soar_script.py
│
├── Constants OUT_DIR, SEED_FILE, ENV_FILE, timeouts
│
├── Data Models IOC, Enrichment, ResultRow (dataclasses)
│
├── Utilities now_utc_iso(), load_keys(), read_seed_iocs(), log_line()
│
├── Classifiers is_ip(), is_url(), is_hash()
│ normalize_domain(), normalize_url()
│ classify_and_normalize(), dedupe_ioc()
│
├── API Headers vt_headers(), abuse_headers()
│
├── API Lookups vt_lookup_domain(), vt_lookup_url(),
│ vt_lookup_hash(), abuse_lookup_ip()
│
├── Scoring score_indicator()
│
└── main() Orchestrates the full pipeline end to end
```
## 未来改进
这个实验室可以进一步增强，使其看起来像一个实际的 SOC 工作流程，想到的一些关键更改是：
- **实时威胁源集成** — 用每次运行自动拉取的 AlienVault OTX 或 Abuse.ch 源替换静态种子文件
- **SIEM 集成** — 将 `blocklist.csv` 导入 Splunk 或 Elastic，并编写检测规则，当实时流量与高置信度 IOC 匹配时触发
- **电子邮件警报** — 当检测到高置信度 IOC 时发送自动摘要电子邮件标签：AbuseIPDB, AI合规, Ask搜索, DAST, DNS 反向解析, ESC4, HTTP工具, IOC富化, IPv6, IP信誉检测, Markdown报告, OSINT, PowerShell, Python, REST API集成, SOAR, VirusTotal, Windows任务计划程序, 代码示例, 威胁情报, 安全实验室, 开发者工具, 恶意软件分析, 数字取证, 数据分析, 无后门, 漏洞指标, 环境变量管理, 网络安全, 网络安全审计, 自动化脚本, 虚拟化环境, 隐私保护