Chalasani-Venkata-Satya-Sai/soc-toolkit

# 🛡️ SOC Toolkit **一个面向 SOC / 安全分析师的 Python 一体化自动化工具包。** 支持 IOC 富化、钓鱼分诊以及基于 YARA 的恶意软件扫描——提供 CLI 和 Web 仪表板双模式，并内置开箱即用的 JSON/HTML 报告功能。 [](https://github.com/Chalasini-Venkata-Sai/soc-toolkit/actions/workflows/ci.yml)    ## 为什么会有这个项目 SOC 分析师每天都会在同样重复的枯燥工作中浪费数小时：把一个 IP 粘贴到五个浏览器标签页中、手动阅读邮件标头以检查伪造情况，或者凭肉眼审查可疑文件。**SOC Toolkit** 将这种 Tier-1 级别的枯燥工作自动化，整合为三个可组合的模块。这些模块镜像了真实的 SOAR 平台（Shuffle、Cortex/TheHive）和 CLI 工具（Sooty、IntelOwl）的功能，但它是作为一个完全由你掌控的、单一且可自托管、可魔改的 Python 项目存在的。 ## ✨ 功能特性 | 模块 | 功能说明 | |---|---| | 🔍 **IOC 富化** | 识别指标类型（IP / domain / URL / hash），并行查询 **VirusTotal**、**AbuseIPDB** 和 **Shodan**，随后将结果汇总为单一的风险评分 + 判定结论 | | 📧 **钓鱼分诊** | 解析原始的 `.eml` 文件：检测 `From` / `Return-Path` / `Reply-To` 伪造，标记基于紧迫感的社工话术，提取 URLs/IPs/domains，对附件进行哈希处理，并标记高风险的附件类型 | | 🧬 **YARA 扫描** | 使用内置（或自定义）的 YARA 规则集扫描单个文件或整个目录树——这与用于端点实时分诊的工作流程相同 | | 📄 **报告生成** | 每个模块都可以输出机器可读的 JSON 报告（供 SIEM/工单系统摄取）或带样式的、易于分享的 HTML 报告 | | 🖥️ **双操作界面** | 提供基于 `click` 的可脚本化 CLI，适用于 pipeline/cron/SOAR playbook；同时提供 Streamlit 仪表板，便于分析师进行点击式操作 | | 🧠 **天然的健壮性设计** | 缺少 API key？会跳过该来源，而不是导致程序崩溃。触及速率限制？会记录日志并继续执行。每次成功的查询都会进行磁盘缓存，以保护免费额度 | ## 🏗️ 架构 ``` soc_toolkit/ ├── cli.py # click CLI — enrich / phishing / yara-scan / dashboard ├── config.py # .env-driven settings, single source of truth for API keys ├── core/ │ ├── enrichment.py # VirusTotal / AbuseIPDB / Shodan lookups + verdict scoring │ ├── phishing.py # .eml parsing, spoofing heuristics, IOC extraction │ ├── yara_scan.py # YARA rule compilation + file/dir scanning │ └── report.py # JSON + Jinja2 HTML report generation ├── utils/ │ ├── validators.py # IOC type detection (ip/domain/url/hash/email) │ ├── cache.py # TTL disk cache to protect API rate limits │ └── logger.py # rich-based console logging ├── dashboard/app.py # Streamlit UI wrapping the same core modules as the CLI ├── rules/sample_rules.yar # starter YARA detection rules └── templates/report.html # shared HTML report template ``` CLI 和仪表板都是 `soc_toolkit/core/*` 的轻量级封装——每种检测都有且仅有一种实现，因此两个接口之间的行为永远不会产生偏差。 ## 🚀 快速开始 ### 1. 安装 ``` git clone https://github.com/YOUR_USERNAME/soc-toolkit.git cd soc-toolkit python -m venv venv && source venv/bin/activate # optional but recommended pip install -r requirements.txt pip install -e . ``` ### 2. 配置 API keys（可选，但强烈推荐） ``` cp .env.example .env ``` 然后填入你拥有的 key——它们都是免费额度的： - VirusTotal: https://www.virustotal.com/gui/my-apikey - AbuseIPDB: https://www.abuseipdb.com/account/api - Shodan: https://account.shodan.io/ ### 3. 使用 ``` # Enrich indicators soc-toolkit enrich 8.8.8.8 example.com 44d88612fea8a8f36de82e1278abb02f # Triage 钓鱼邮件提交（试试内置的样本！） soc-toolkit phishing sample_data/sample_phishing.eml --enrich-iocs # 使用 YARA 扫描文件或目录 soc-toolkit yara-scan ./suspicious_folder # 启动 dashboard soc-toolkit dashboard # -> http://localhost:8501 ``` 每个命令都支持 `--format json|html`（或 `table`/`summary`），因此可以直接无缝接入 SOAR playbook、cron job 或作为工单附件。 ### 4. 或者使用 Docker 运行 ``` docker compose up --build # Dashboard: http://localhost:8501 # 一次性 CLI 用法： docker compose run soc-toolkit-cli enrich 8.8.8.8 ``` ## 🧪 使用示例 ``` # 从文件批量 enrich IOC 列表，同时保存 JSON + HTML 报告 cat sample_data/sample_iocs.txt | xargs soc-toolkit enrich --save # JSON 输出，用于通过管道传递给另一个工具 / SIEM webhook soc-toolkit enrich 1.2.3.4 --format json | jq . # 带有自动 IOC enrichment 和 HTML 报告的完整钓鱼邮件 triage soc-toolkit phishing incoming.eml --enrich-iocs --format html # 扫描整个 downloads 文件夹以查找 malware indicators soc-toolkit yara-scan ~/Downloads --rules soc_toolkit/rules/sample_rules.yar ``` ## 🖥️ 仪表板 Streamlit 仪表板（`soc-toolkit dashboard`）暴露了同样的三个模块，支持拖拽上传 `.eml` 文件和待扫描文件，侧边栏提供实时的 API-key 状态显示，并支持一键导出 HTML 报告——日常分诊完全无需使用终端。 ## 🔧 功能扩展 - **添加新的富化来源** —— 在 `core/enrichment.py` 中按照现有的模式添加一个 `check_()` 函数（返回一个包含 `source`/`status` 的字典，成功时进行缓存），然后将其包含在 `enrich_ioc()` 中。 - **添加你所在组织的 YARA 规则** —— 将 `.yar`/`.yara` 文件放入 `soc_toolkit/rules/` 中（或者使用 `--rules` 指向任意外部目录）。 - **将其接入 SOAR playbook** —— 每个命令都支持 `--format json`，这使得通过 Shuffle、TheHive/Cortex responders 或由 webhook 触发的 Lambda 来调用它变得轻而易举。 ## 🧵 测试 ``` pip install -e ".[dev]" pytest -v ``` 测试涵盖了 IOC 类型检测、针对内置合成样本的钓鱼邮件标头伪造启发式检测，以及富化逻辑（API 调用均已被 mock，运行测试套件无需真实的 key）。 ## ⚠️ 负责任的使用说明 本项目仅供**授权的安全操作**使用——用于富化你已观察到的指标、分诊提交到你自有邮箱的钓鱼报告，以及扫描经授权可检查的系统/文件。内置的 YARA 规则仅供说明使用的入门模式，不能替代经过精心策划且持续维护的检测规则集。 ## 📄 许可证 MIT —— 详情见 [LICENSE](LICENSE)。 ## 🤝 贡献 欢迎提交 Issues 和 PR。如果你添加了新的富化来源或检测模块，请附上相应的测试（mock 任何外部的 API 调用，正如在 `tests/test_enrichment.py` 中所做的那样）。

标签：DNS 反向解析, IOC富化, Kubernetes, Python, SOC工具箱, YARA扫描, 威胁情报, 开发者工具, 无后门, 请求拦截, 逆向工具, 钓鱼分析