PKHarsimran/IOC-Inspector
GitHub: PKHarsimran/IOC-Inspector
面向 SOC 分析师的恶意文档静态扫描器，自动提取 IOC 并结合威胁情报给出风险评分与多格式报告。
Stars: 1 | Forks: 0
# IOC Inspector 🕵️♂️
[](https://github.com/PKHarsimran/IOC-Inspector/actions/workflows/ci.yml)
[](https://github.com/PKHarsimran/IOC-Inspector/actions/workflows/lint.yml)
[](https://codecov.io/gh/PKHarsimran/IOC-Inspector)
[](LICENSE)
[](https://github.com/PKHarsimran/IOC-Inspector/releases)
[](SECURITY.md)
**快速、SOC 就绪的恶意文档扫描器** — 将可疑的 PDF、DOC(X)、XLS(X) 和 RTF 转化为富含 IOC、适配 SIEM 的报告。
## ✅ 最新动态
- 跨平台 CI 支持 **Linux + Windows** 以及 **Python 3.10/3.11**
- 通过自定义 `ParserError` 改进了 parser 的错误处理
- 动态加载 API key 以提高测试的可靠性
- 覆盖率把关的 CI，单元测试覆盖率 **>80%**
- 最终的 README 润色 ✨
- 使用 `--threads` 进行并发目录扫描
## ⚡ 为什么选择 IOC Inspector？
| 🔑 | 对分析师的价值 |
|----|------------------|
| **一键分诊** | `ioc-inspector invoice.docx` → 即时判定结果与 Markdown 报告 |
| **可操作的评分** | 自定义启发式算法将宏标志、**自动执行/API 命中**、嵌入对象指标以及威胁情报源查询 (VirusTotal + AbuseIPDB) 整合为一个 **0-100 的风险评分** |
| **分析师优先的输出** | Markdown 用于工单，JSON / CSV 用于 Splunk 和 Elastic |
| **随处运行** | Linux • Windows • 在 GitHub Actions 中无头运行 |
| **可扩展** | 所有逻辑都位于 `ioc_inspector_core/` 中 — 替换 parser、添加情报源、调整权重 |
## 🔍 功能矩阵
| 类别 | 您将获得的内容 |
|---------------------|----------------------------------------------------------------------------------------------------|
| **格式** | PDF • DOC / DOCX • XLS / XLSX • RTF |
| **静态分析** | 宏转储、**深度自动执行与可疑 API 分析**、混淆查找器、嵌入对象计数器 |
| **IOC 提取** | URL • 域名 • IP • Base64 blob • 隐藏链接 |
| **威胁情报富化** | VirusTotal • AbuseIPDB |
| **评分引擎** | 启发式权重 + 规则修饰符 (可配置) |
| **报告** | Markdown、JSON、CSV、JSONL、HTML
|
| **自动化** | 递归目录扫描 • `--threads` 实现并发 • 静默/详细输出开关 • GitHub Actions 工作流 |
## 🚀 快速开始
```
# 1 – Clone
$ git clone https://github.com/PKHarsimran/IOC-Inspector.git
$ cd IOC-Inspector
# 2 – 安装 (Linux/macOS)
$ python -m venv venv && source venv/bin/activate
# 2 – 安装 (Windows)
> python -m venv venv && venv\Scripts\activate
# 3 – 安装 requirements
(venv) $ pip install -r requirements.txt
# 4 – 设置 API keys
(venv) $ cp .env.example .env
(venv) $ nano .env # Add your VT_API_KEY & ABUSEIPDB_API_KEY
# 5 – 运行
(venv) $ python main.py --file examples/sample_invoice.docx --report
```
## ⚙️ 配置亮点 (settings.py)
```
RISK_WEIGHTS = {
"macro": 25, # any VBA present
"autoexec": 15, # AutoOpen / Document_Open …
"obfuscation": 20, # long Base-64 blobs, XOR strings
"susp_call": 5, # CreateObject, Shell … (×3 capped at 15)
"malicious_url": 30, # VirusTotal consensus
"malicious_ip": 25, # AbuseIPDB ≥ confidence cutoff
}
VT_THRESHOLD = 5 # vendors that must flag URL/IP malicious
ABUSE_CONFIDENCE_CUTOFF = 70 # AbuseIPDB confidence to flag IP
REPORT_FORMATS = ["markdown", "json"]
```
🗂️ 仓库布局
```
ioc-inspector/
├── ioc_inspector_core/ ← all analysis logic
│ ├── __init__.py
│ ├── pdf_parser.py
│ ├── doc_parser.py
│ ├── macro_analyzer.py ← deep VBA heuristics
│ ├── url_reputation.py
│ ├── abuseipdb_check.py
│ ├── heuristics.py
│ └── report_generator.py
│
├── logger.py
├── main.py
├── settings.py
│
├── examples/
├── reports/ (git-ignored)
├── logs/ (git-ignored)
│
├── tests/
└── requirements.txt
```
## 📦 依赖项一览
| 类别 | 包 | 需要它的原因 |
|----------|---------|-----------------|
| 核心 | `oletools`, `pdfminer.six`, `PyMuPDF`, `requests`, `python-dotenv`, `tldextract` | 解析、富化、API 配置 |
| 报告| *(内置)* | Markdown/JSON/CSV/JSONL/HTML 渲染 |
| 可选 | `tabulate`, `rich`, `jinja2` | 美观的控制台输出、HTML 报告 |
### 🗺️ 代码流转过程
```
flowchart TD
CLI["CLI (main.py)"] --> DISPATCH["Dispatcher (__init__.analyze)"]
subgraph "Parsers"
DISPATCH --> PDF["pdf_parser.py"]
DISPATCH --> OFFICE["doc_parser.py"]
OFFICE --> MACRO["macro_analyzer.py"]
end
PDF --> ENRICH
MACRO --> ENRICH
subgraph "Reputation enrichment"
ENRICH --> VT["url_reputation.py"]
ENRICH --> ABIP["abuseipdb_check.py"]
end
ENRICH --> SCORE["heuristics.py"]
SCORE --> REPORT["report_generator.py"]
SCORE --> LOG["logger.py"]
REPORT --> OUTPUT["Markdown / JSON"]
```
**逐步发生的过程**
| 阶段 | 模块 | 任务 |
|-------|--------|-----|
| **CLI** | `main.py` | 读取标志，构建文件列表，打印标题。 |
| **调度器** | `ioc_inspector_core/__init__.py` | 将每个文件路由到对应的 parser。 |
| **Parser** | `pdf_parser.py` & `doc_parser.py` | 提取 URL、IP、宏、嵌入对象、JavaScript。 |
| **富化** | `url_reputation.py`, `abuseipdb_check.py` | 查询 VirusTotal & AbuseIPDB；附加判定结果。 |
| **评分** | `heuristics.py` | 应用权重，生成 0-100 的风险评分和判定结果。 |
| **报告** | `report_generator.py` | 编写包含 IOC 表格的 Markdown + JSON。 |
| **日志** | `logger.py` | 每个阶段的控制台 + 轮转文件日志追踪。 |
## 📊 覆盖率与可靠性
- ✅ **>80% 的测试覆盖率** (在 CI 中强制执行)
- ✅ 通过 Codecov 提供覆盖率徽章和报告
- ✅ 适用于 **Linux 和 Windows** runner
- ✅ CLI 冒烟测试验证了 API 使用和报告生成
# 🛣️ 迈向 v1.0.0 的路线图
这概述了将 IOC Inspector 从一个可靠的 prototype (v0.1.0) 打磨为成熟、生产就绪的 v1.0.0 版本的路径。
## ✅ 阶段 1：基础 (v0.1.0 – 已完成)
- [x] 静态 IOC 提取：PDF、DOCX、XLSX、RTF
- [x] 威胁情报富化：VirusTotal + AbuseIPDB
- [x] 基于启发式的评分引擎
- [x] Markdown + JSON 报告
- [x] 带有标志的命令行界面 (`--report`, `--quiet` 等)
- [x] 跨平台 CI (Linux + Windows)
- [x] 包含 CLI 冒烟测试的 80%+ 测试覆盖率
- [x] 最终的 README 润色和首个发布标签
## 🚧 阶段 2：稳定性与反馈 (`v0.2.x`)
重点：巩固产品并改进反馈循环
### 技术改进
- [x] 报告输出的 JSON schema 验证
- [ ] 通过文件上下文（例如，文件类型、使用的 parser）改进错误消息
- [ ] 将报告逻辑与 CLI 分离，以支持更多格式
### 开发者体验
- [x] 添加 `make test`、`make lint`、`make run` 快捷方式
- [ ] 添加 GitHub Discussions 或反馈模板
- [ ] 吸纳测试用户的反馈
## ✨ 阶段 3：导出与集成 (`v0.3.x`)
重点：SIEM 友好性和分析师的日常使用
- [x] 用于 Splunk 或 Excel 的 CSV 导出
- [x] 支持批量 pipeline 的 JSONL
- [x] 带有内嵌样式的 HTML 导出
- [ ] 规范化字段命名以供摄取（例如 `ioc.type`, `ioc.source`）
- [ ] (可选) 从富化后的 IOC 中标记已知的 MITRE ATT&CK 技术
## 🚀 阶段 4：生产化 (`v0.9.x`)
重点：分发与打包优化
- [ ] 发布到 PyPI 以便通过 `pipx` 安装
- [ ] 提供 Docker 镜像及 CLI entrypoint
- [ ] 通过 PyInstaller 构建 Windows 二进制文件
- [ ] 通过 GitHub Actions 自动化更新日志和发布
- [ ] 使用 SemVer 自动标签 (`release-please`)
## 🏁 v1.0.0 标准
当满足以下条件时，IOC Inspector 将被标记为 v1.0.0：
- [ ] 所有支持的格式都能可靠解析并具备测试覆盖率
- [ ] JSON / Markdown / CSV 输出具备稳定的 schema
- [ ] 测试覆盖率 >90%
- [ ] CLI 顺畅无阻且有完善的文档
- [ ] Docker + PyPI 构建开箱即用
- [ ] 用户通过反馈验证其有效性
## 🧩 1.0 之后的想法
1.0 之后可考虑的可选功能：
- [ ] 用于批量运行的 Ntfy/webhook 通知
- [ ] 使用 Streamlit 或 Flask 的 Web UI
- [ ] 威胁情报源导出器（例如导出到 MISP 或 CSV 转储）
- [ ] 为法语/西班牙语 SOC 团队提供语言支持
💬 有问题？有反馈？请提交一个 [Issue](https://github.com/PKHarsimran/IOC-Inspector/issues) 或发起一个讨论。
输出示例
examples/sample_invoice.docx: score=45 verdict=suspicious See reports/sample_invoice_report.md for full IOC tables.标签：DNS 反向解析, Python, 威胁情报, 安全运营, 开发者工具, 恶意文档扫描, 扫描框架, 搜索语句（dork）, 数字取证, 无后门, 自动化脚本, 逆向工具