IOCParser
用于威胁情报工作流的工业级 IOC 提取、富化、持久化及 pipeline 工具
## 概述
**IOCParser** 从报告、订阅源、URL、stdin 和目录树中提取失陷标示。它支持 refanging、MISP warning-list 富化、结构化 renderer、持久化运行历史记录、IOC 搜索、运行 diff 以及由队列支持的分布式处理。
### 核心功能
| 功能 | 描述 |
|---------|-------------|
| **多源摄取** | 解析 PDF、HTML、文本、stdin、URL、URL 列表、多文件批处理以及目录 |
| **IOC 提取** | 检测哈希、网络标示、Windows artifacts、威胁情报 ID、加密货币地址、YARA 等 |
| **Warning-list 富化** | 支持 MISP warning-list 匹配，区分常规与警告，并提供 evidence 上下文 |
| **结构化输出** | 渲染 text、summary、JSON、JSONL、CSV 和 STIX 2.1 |
| **持久化** | 将运行记录存储在 SQLite 或兼容 MariaDB 的 SQLAlchemy 后端中 |
| **搜索与 diff** | 查询持久化的 IOC、导出运行记录、进行运行 diff，并与同一来源最近一次成功的运行进行比较 |
| **批处理操作** | 支持 URL 重试、退避、速率限制、并发以及失败项重放报告 |
| **分布式 pipeline** | 提供 Filesystem、RabbitMQ、SQS 和 Celery 队列适配器，支持持久化的作业生命周期 |
| **插件接口** | 支持自定义 renderer、enricher、extractor、postprocessor 以及 IOC 类型 |
### 支持的输出
```
Human reports text, summary
Data formats JSON, JSONL, CSV
Threat intel STIX 2.1 bundles
Persistence run exports, IOC search pages, structured run diffs
Operations URL batch reports, pipeline job results, schema artifacts
```
### 支持的 IOC 族
```
Hashes MD5, SHA1, SHA256, SHA512, SSDEEP, IMPHASH
Network Domains, Hosts, IPv4, IPv6, URLs, Emails, ASNs
Windows Registry keys, mutexes, named pipes, service names
Artifacts Filenames, filepaths, certificate serials, JWT, user agents
Threat intel CVEs, MITRE ATT&CK techniques, YARA rules
Crypto Bitcoin, Ethereum, Monero
Other MAC addresses
```
## 安装说明
### 从 PyPI 安装（推荐）
```
pip install iocparser-tool
```
### 从源码安装
```
git clone https://github.com/seifreed/IOCParser.git
cd IOCParser
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -e .
```
### 开发附加组件
```
pip install -e ".[dev]"
```
## 快速开始
```
# 初始化 warning lists
iocparser --init
# 从 file、URL 或 stdin 提取
iocparser -f report.pdf
iocparser -u https://example.com/report.html
cat report.txt | iocparser --stdin --json
# 持久化并稍后查询
iocparser -f report.txt --persist --db-uri "sqlite:///iocparser.db"
iocparser --list-runs --db-uri "sqlite:///iocparser.db"
```
## 使用说明
### 命令行界面
```
# 单个输入
iocparser -f report.pdf
iocparser https://example.com/report.html
iocparser --stdin < report.txt
# 批量处理文件和 URL feeds
iocparser -m report1.txt report2.txt report3.txt
iocparser -d reports --recursive --glob "*.html"
iocparser --url-file feeds.txt --url-workers 8 --url-retries 2 --batch-report-json batch.json
# 输出格式
iocparser -f report.txt --json
iocparser -f report.txt --jsonl
iocparser -f report.txt --csv
iocparser -f report.txt --stix --stix-types domains,urls,ips
iocparser -f report.txt --summary
# Analyst filters
iocparser -f report.txt --only urls,domains --severity medium --with-context
iocparser -f report.txt --exclude yara,registry --only-normal
iocparser -f report.txt --sort-by severity --max-evidence 1
```
### 可用选项（主要工作流）
| 工作流 | 描述 |
|----------|-------------|
| `-f, --file` | 解析单个文件或使用 `-` 代表 stdin |
| `-u, --url` | 下载并解析一个 URL |
| `--stdin` | 从 stdin 读取 IOC 文本 |
| `-m, --multiple` | 解析多个文件并合并结果 |
| `-d, --directory` | 从目录解析文件，支持配合 `--recursive` 和 `--glob` 使用 |
| `--url-file` | 使用 worker、重试、退避和速率限制解析 URL feed |
| `--streaming` | 分块处理大文件 |
| `--persist` | 将提取运行的元数据和 IOC 保存到数据库 |
| `--list-runs` | 列出持久化的运行记录 |
| `--search-ioc` | 搜索持久化的 IOC 值，支持 `auto`、`fts` 或 `like` 后端 |
| `--export-run` | 将持久化的运行记录导出为 text、JSON、JSONL、CSV 或 STIX |
| `--diff-runs` | 比较两次持久化的运行记录 |
| `--diff-latest` | 将某次运行与同一来源中最近一次成功的运行进行比较 |
| `--retry-failed-from` | 根据之前的批处理报告重放失败的 URL 项 |
| `--schema-version`, `--migrate` | 检查或迁移持久化 schema |
### 持久化示例
```
# 搜索已持久化的 IOC
iocparser --search-ioc evil.example --db-uri "sqlite:///iocparser.db"
iocparser --search-ioc evil.example --ioc-type urls --severity informational --tag warning-list-match
# 导出和对比运行结果
iocparser --export-run 42 --json --db-uri "sqlite:///iocparser.db"
iocparser --diff-runs 40 42 --diff-only added --json --db-uri "sqlite:///iocparser.db"
iocparser --diff-latest 42 --summary --db-uri "sqlite:///iocparser.db"
# 维护
iocparser --delete-run 42 --db-uri "sqlite:///iocparser.db"
iocparser --prune-before 2026-01-01T00:00:00 --keep-latest 10 --db-uri "sqlite:///iocparser.db"
```
### HTTP 与批处理参数
| 选项 | 描述 |
|--------|-------------|
| `--url-workers` | 并发 URL worker 数量 |
| `--url-retries` | 单个 URL 的重试次数 |
| `--url-backoff` | URL 重试之间的退避时间 |
| `--rate-limit` | URL 获取之间的延迟 |
| `--user-agent` | 自定义 HTTP user agent |
| `--header`, `--cookie`, `--proxy` | HTTP 请求自定义配置 |
| `--allow-redirects`, `--tls-verify`, `--tls-cert`, `--ca-bundle` | 重定向与 TLS 策略 |
| `--connect-timeout`, `--read-timeout` | HTTP 超时策略 |
## Python 库
### 提取 API
```
from iocparser import extraction
normal_iocs, warning_iocs = extraction.extract_iocs_from_file("report.pdf")
normal_iocs, warning_iocs = extraction.extract_iocs_from_text("evil.example 198.51.100.10")
normal_iocs, warning_iocs = extraction.extract_iocs_from_url(
"https://example.com/report.html",
only="urls,domains",
exclude="registry",
)
result = extraction.extract_result_from_file("report.pdf")
print(result.total_count())
```
### 持久化 API
```
from iocparser import persistence
db_uri = "sqlite:///iocparser.db"
runs = persistence.list_persisted_runs(db_uri=db_uri, limit=10)
hits = persistence.search_persisted_iocs(
db_uri=db_uri,
value="evil.example",
ioc_type="urls",
min_severity="medium",
tag="network",
)
exported = persistence.export_persisted_run(db_uri=db_uri, run_id=42)
diff = persistence.diff_persisted_runs(db_uri=db_uri, left_run_id=40, right_run_id=42)
```
### 分布式 Pipeline API
```
from iocparser import pipeline
client = pipeline.DistributedPipelineClient(
db_uri="sqlite:///iocparser.db",
queue_backend="filesystem",
queue_path=".iocparser-queue",
)
job = client.submit(
pipeline.PipelineJobRequest(
input_kind="text",
source_value="IOC hxxp://evil.example",
persist=True,
db_uri="sqlite:///iocparser.db",
check_warnings=False,
),
queue_name="ingest",
)
client.process_next(queue_name="ingest")
state = client.get_job(job_id=job.job_id)
```
### 底层组件
```
from iocparser.infrastructure.extraction import IOCExtractor
from iocparser.infrastructure.file_parser import PDFParser
from iocparser.infrastructure.warninglists import MISPWarningLists
text = PDFParser("report.pdf").extract_text()
raw_iocs = IOCExtractor(defang=True).extract_all(text)
warning_lists = MISPWarningLists()
```
## 配置
IOCParser 按以下顺序解析配置：
1. CLI 参数
2. 环境变量
3. INI 文件
```
export IOCPARSER_PERSIST=1
export IOCPARSER_DB_URI="sqlite:///iocparser.db"
```
```
[database]
persist = true
uri = sqlite:///iocparser.db
[defaults]
only = urls,domains
exclude = yara
output_format = json
with_context = true
severity = medium,high
[network]
url_workers = 8
url_retries = 2
url_backoff = 0.25
rate_limit = 0.10
```
内置的部署配置文件：
- [deploy/iocparser.local.example.ini](deploy/iocparser.local.example.ini)
- [deploy/iocparser.scale.example.ini](deploy/iocparser.scale.example.ini)
- [deploy/iocparser.production.example.ini](deploy/iocparser.production.example.ini)
## Pipeline 与 Schema
IOCParser 暴露了版本化的机器可读契约，用于批处理报告和由队列支持的处理流程。
| 文档 | 范围 |
|----------|-------|
| [docs/PIPELINE_CONTRACT.md](docs/PIPELINE_CONTRACT.md) | Worker 输入/输出契约及资源限制 |
| [docs/DISTRIBUTED_PIPELINE.md](docs/DISTRIBUTED_PIPELINE.md) | 基于 Filesystem、RabbitMQ、SQS 和 Celery 队列的执行机制 |
| [docs/WORKER_DEPLOYMENT.md](docs/WORKER_DEPLOYMENT.md) | Worker 部署指南 |
| [docs/SCHEMA_ARTIFACTS.md](docs/SCHEMA_ARTIFACTS.md) | JSON schema artifacts 及发布版本 |
| [docs/SECURITY_OPERATIONS.md](docs/SECURITY_OPERATIONS.md) | 密钥处理与操作指南 |
独立 Worker：
```
IOCPARSER_WORKER_QUEUE_BACKEND=filesystem \
IOCPARSER_WORKER_QUEUE_PATH=.iocparser-queue \
IOCPARSER_WORKER_QUEUE_NAME=ingest \
IOCPARSER_WORKER_DB_URI=sqlite:///iocparser.db \
iocparser-worker
```
## 环境要求
- Python 3.13 或 3.14
- 用于文件类型检测的 libmagic runtime 支持
- 请参阅 [pyproject.toml](pyproject.toml) 了解依赖项及可选的 pipeline 附加组件
## 许可证
本项目基于 MIT 许可证授权。请参阅 [LICENSE](LICENSE)。
**署名信息**
- 作者：**Marc Rivero López** | [@seifreed](https://github.com/seifreed)
- 仓库：[github.com/seifreed/IOCParser](https://github.com/seifreed/IOCParser)
专为实用的 IOC 提取、威胁情报自动化和安全运营而构建