PKHarsimran/SwiftIOC-Automated-Threat-Intelligence-Collector

# ⚡ SwiftIOC – 开源自动化威胁情报收集器 [](https://github.com/PKHarsimran/SwiftIOC-Automated-Threat-Intelligence-Collector/actions/workflows/ci.yml) [](https://github.com/PKHarsimran/SwiftIOC-Automated-Threat-Intelligence-Collector/actions/workflows/codeql.yml) [](./SECURITY.md) SwiftIOC 是一个开源的 Python 威胁情报自动化工具包，它以机器可读的格式保存最新的威胁指标。轻量级收集器 (`swiftioc.py`) 通过 YAML 配置获取威胁源，对指标进行规范化和去重处理，并将其导出为 CSV、TSV、JSON、JSON Lines 和 STIX 2.1 格式，同时生成可搜索的运行诊断信息。 SwiftIOC 专为安全运营团队、SOC 分析师和网络威胁搜寻者设计，可在任何支持 Python 的环境中运行——本地工作站、CI/CD 流水线、GitHub Actions 或自动化 cron 作业。输出默认位于 `public/` 目录下，因此可以直接通过 GitHub Pages 发布，集成到 SIEM 和 SOAR 工具中，或归档用于合规性报告。该存储库包含现成的示例，便于在现代 DevSecOps 工作流中快速部署。 ## 📚 目录 - [SwiftIOC 概览](#-swiftioc-at-a-glance) - [功能特性](#-features) - [GitHub 项目健康状况](#-github-project-health) - [支持的威胁情报源](#-supported-threat-intelligence-sources) - [用例与 SEO 友好关键词](#-use-cases--seo-friendly-keywords) - [仓库布局](#-repository-layout) - [工作原理](#-how-it-works) - [快速入门](#-quick-start) - [配置源](#-configuring-sources) - [CLI 参考](#-cli-reference) - [输出与诊断](#-outputs--diagnostics) - [在 GitHub Actions 中运行](#-running-in-github-actions) - [GitHub Pages 预览与发布](#-github-pages-preview--publishing) - [自动生成的 IOC 摘要](#auto-generated-ioc-summary) ## 🔍 SwiftIOC 概览 SwiftIOC 帮助网络安全团队自动从权威来源收集和发布高保真 IOC。该项目强调： - **自动化威胁源聚合**，通过基于 YAML 的配置。 - **一致的 IOC 丰富化**，为 SIEM、SOAR、IDS 和 DFIR 工具做好准备。 - **Git 友好的工件**，专为 GitHub Pages、GitHub Actions 和其他 CI/CD 环境量身定制。 ## 🚀 功能特性 - **YAML 驱动的源** – 源元数据位于 `sources.yml` 中，因此无需修改 Python 代码即可更改收集配置。示例文件包含适用于 CISA KEV、URLhaus、MalwareBazaar、ThreatFox、Feodo Tracker、SSLBL JA3、Spamhaus DROP、OpenPhish、CINS Army 和 Tor 出口列表的适配器。 - **指标规范化** – 每个指标都由 `Indicator` 数据类表示，并在写入磁盘之前进行分类（IPv4/IPv6、URL、域名、哈希、CVE 等）。 - **失效处理与去重** – 辅助函数对 URL/域名进行失效处理（Defanging）并移除重复指标，确保下游工具接收到安全、唯一的值。 - **多种导出格式** – 每次运行都会生成 CSV、TSV、JSON、JSON Lines、STIX 2.1 包和 Markdown 更新日志。 - **丰富的诊断信息** – 自动生成 JSON 运行摘要、Markdown 报告和每个源的计数，用于审计和仪表板。 - **可选的 RSS 收集** – 安装 `feedparser` 后即可处理 RSS 源；使用 `--skip-rss`（或 `--ci-safe`）可在没有该依赖项的情况下运行。 - **对 CI 友好的默认设置** – JSON 日志记录、确定的输出路径以及防护标志（`--fail-on-empty`、`--fail-if-stale`、`--grace-on-404`）使收集器在自动化环境中表现可预测。 ## 🛡️ GitHub 项目健康状况 - **持续集成** – `CI – SwiftIOC` 工作流在每次推送和拉取请求时对 Python 代码库进行 lint 检查、类型验证、依赖项审计，并对收集器进行端到端测试。 - **CodeQL 扫描** – GitHub 的 CodeQL 工作流分析存储库中常见的安全问题，以确保收集器在自动化环境中的安全性。 - **安全策略** – 通过 [`SECURITY.md`](SECURITY.md) 处理协调漏洞披露，其中包含针对维护者的直接联系指导。 ## 🌐 支持的威胁情报源 SwiftIOC 附带了解析器和适配器，用于处理 SOC 团队和托管安全提供商广泛引用的网络威胁情报源： - **CISA 已知被利用漏洞 (KEV)** – 通过监控官方 CISA KEV 目录来优先安排补丁修补工作。 - **URLhaus** – 获取恶意 URL 指标以保护 Web 网关和代理。 - **MalwareBazaar** – 追踪恶意文件哈希，用于 EDR、AV 和沙箱工具。 - **ThreatFox** – 添加由 abuse.ch 策划的 IP、域名、URL 和哈希。 - **Feodo Tracker 与 SSLBL JA3 指纹** – 检测与银行木马和恶意 TLS 指纹相关的 C2 流量。 - **Spamhaus DROP/EDROP** – 在网络边缘封锁已知的僵尸网络控制器。 - **OpenPhish、CINS Army、Tor 出口列表等** – 利用钓鱼、扫描和匿名器指标扩展覆盖范围。 每个源都可通过 `sources.yml` 进行配置，允许团队根据需要微调收集频率、回溯窗口和身份验证。 ## 🎯 用例与 SEO 友好关键词 SwiftIOC 支持广泛的网络安全自动化工作流。常见用例包括： - **安全运营中心 (SOC) 自动化** – 安排 IOC 收集作业，使 SIEM 和 IDS 规则与开源威胁情报保持同步。 - **数字取证与事件响应 (DFIR)** – 导出经过失效处理的指标以用于调查，而不会有意外激活的风险。 - **DevSecOps 流水线** – 将威胁源丰富化集成到 CI/CD、GitOps 或基础设施即代码项目中。 - **威胁搜寻手册** – 生成可供 MISP、OpenCTI 和其他 CTI 平台使用的 STIX 2.1 包。 - **合规性报告与高管仪表板** – 利用 Markdown 和 JSON 诊断信息生成对利益相关者友好的报告。 提高可发现性的关键词：“automated threat intelligence collector”（自动化威胁情报收集器）、“open source IOC feed aggregator”（开源 IOC 源聚合器）、“Python threat hunting toolkit”（Python 威胁搜寻工具包）、“cyber threat intelligence automation”（网络威胁情报自动化）、“STIX export for SOC”（用于 SOC 的 STIX 导出）和“GitHub Actions threat feed workflow”（GitHub Actions 威胁源工作流）。 ## 🗂️ 仓库布局 ``` ├── public/ # Default output directory for generated feeds │ ├── iocs/ # CSV, JSON, JSONL, TSV, and STIX artifacts │ ├── diagnostics/ # Run report, JSON diagnostics, and auto summary │ └── changelog/ # Markdown changelog between runs ├── scripts/ # Utility helpers for post-processing │ └── summarize_iocs.py # Generates Markdown summaries for Pages & artifacts ├── requirements.txt # Python dependencies ├── sources.example.yml # Sample feed configuration ├── swiftioc.py # Main collector implementation & CLI ├── index.html # Optional GitHub Pages entry point ├── README.md # This document └── SECURITY.md # Security reporting policy ``` ## 🧠 工作原理 1. **加载配置** – `swiftioc.py` 读取 `sources.yml`（必要时回退到 `sources.example.yml`）并设置日志记录、用户代理和输出目录。 2. **按源收集** – 每个 API 或 RSS 源被路由到通过 `@register_parser` 注册的解析器，该解析器获取原始源数据并将其转换为 `Indicator` 对象。 3. **去重与过滤** – 指标根据配置的回溯窗口进行合并、去重和过滤。 4. **发布输出** – 所有格式、诊断信息和更新日志条目都写入所选的输出目录下。 ## 🏁 快速入门 前置条件： - Python 3.10 或更新版本（在 Linux 和 GitHub Actions 上使用 CPython 测试） - 用于依赖项管理的 `pip` ``` # 克隆并进入仓库 git clone https://github.com/PKHarsimran/SwiftIOC-Automated-Threat-Intelligence-Collector.git cd SwiftIOC-Automated-Threat-Intelligence-Collector # （可选）创建并激活虚拟环境 python -m venv .venv source .venv/bin/activate # Linux/macOS .venv\Scripts\activate # Windows PowerShell # 安装依赖项 pip install -r requirements.txt # 使用示例源运行收集器 python -m swiftioc --sources sources.example.yml --out-dir public ``` 工件将出现在 `public/` 下。添加 `--verbose` 以显示进度日志，或添加 `--self-test` 以在不访问网络的情况下运行内置健全性检查。 ## 🧾 配置源 创建一个 `sources.yml` 来描述你关心的源。该文件反映了 `sources.example.yml` 中的结构，并支持针对每个源的选项。`window_hours` 定义全局回溯窗口；可以使用 CLI 上的 `--source-window name=HOURS` 为单个源覆盖此设置。 ``` window_hours: 48 apis: - name: cisa_kev kind: json parse: kev url: https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json reference: https://www.cisa.gov/known-exploited-vulnerabilities-catalog - name: urlhaus_recent_urls kind: csv parse: urlhaus url: https://urlhaus.abuse.ch/downloads/csv_recent/ reference: https://urlhaus.abuse.ch/ # Optional filter supplied via --urlhaus-status rss: - name: google_tag url: https://blog.google/threat-analysis-group/rss/ reference: https://blog.google/threat-analysis-group/ ``` 每个解析器都可以接受在 `options:` 下定义的附加关键字参数。通过 Python 虚线路径支持自定义解析器（例如，`parse: my_package.parsers:parse_feed`）。 对于没有专用适配器的源，可以通过设置 `parse: universal` 回退到通用收集器。它将自动检测 JSON、CSV 或纯文本负载，发现常见的时间戳/标签字段，并通过用于 RSS 内容的相同启发式方法提取指标。 ## 📋 CLI 参考 运行 `python -m swiftioc --help` 获取开关的完整列表。要点： | 标志 | 用途 | | --- | --- | | `--out-dir PATH` | 写入工件的目录（默认为 `public/`）。 | | `--sources PATH` | YAML 配置（`sources.yml`，回退到 `sources.example.yml`）。 | | `--window-hours N` | 全局回溯窗口（以小时为单位）。 | | `--skip-rss` | 完全禁用 RSS 处理。 | | `--max-per-source N` | 限制从每个源获取的指标数量。 | | `--urlhaus-status {any,online,offline}` | 按状态过滤 URLhaus 指标。 | | `--source-window name=N` | 覆盖特定源的回溯窗口。 | | `--grace-on-404 name…` | 将列出源的 HTTP 404 视为非致命的空结果。 | | `--fail-on-empty name…` | 如果任何列出的源返回零个指标，则运行失败。 | | `--fail-if-stale name=N` | 当来自 `name` 的最新指标早于 `N` 小时时失败。 | | `--save-raw-dir PATH` | 保存原始源响应以供后续检查。 | | `--diag-json PATH` | 写入诊断 JSON（默认为 `public/diagnostics/run.json`）。 | | `--report PATH` | 写入 Markdown 运行报告（默认为 `public/diagnostics/REPORT.md`）。 | | `--ua-file PATH` | 提供自定义用户代理池（每行一个 UA）。 | | `--ci-safe` | CI 运行的便利标志（JSON 日志，确保诊断目录存在，容忍缺失的 RSS 依赖）。 | | `--self-test` | 在不获取源的情况下执行内置断言。 | | `-v/--verbose` | 增加控制台日志记录（`-vv` 用于调试）。 | | `--log-file PATH` | 将日志发送到文件。 | | `--log-format {text,json}` | 选择控制台/文件日志格式。 | | `--log-file-level LEVEL` | 控制文件日志级别（默认 `DEBUG`）。 | ## 📦 输出与诊断 收集器生成以下结构（路径相对于 `--out-dir`）： ``` public/ ├── index.md ├── iocs/ │ ├── latest.csv │ ├── latest.tsv │ ├── latest.json │ ├── latest.jsonl │ └── stix2.json ├── changelog/ │ └── CHANGELOG.md └── diagnostics/ ├── REPORT.md ├── run.json ├── summary.md └── raw/ # present when --save-raw-dir is used ``` 诊断信息包括每个源的计数、重复统计信息、最早和最新时间戳以及任何记录的故障。这些摘要对于 CI 状态检查和仪表板非常有用。 ## 🌍 GitHub Pages 预览与发布 SwiftIOC 附带了一个适配 Pages 的仪表板，因此无需额外工具即可浏览收集的指标。该项目使用 `public/` 作为工件目录和发布的站点根目录： - `public/index.html` 使用 `swiftioc.py` 生成的 JSON/JSONL 输出呈现实时预览、源细分、标签计数和导出链接。 - 存储库根目录下的 `index.html` 提供了一个品牌着陆页，该页面在短暂延迟后重定向到 `public/`，同时提供用于手动导航的快速链接。 在 GitHub Pages 上发布： 1. 在本地或 CI 中运行收集器以填充 `public/`（参见 [快速入门](#-quick-start))。 2. 提交生成的工件或将其作为工作流工件上传（如 [在 GitHub Actions 中运行](#-running-in-github-actions) 所示）。 3. 启用 GitHub Pages 并选择 **GitHub Actions** 作为源，以便部署自动获取最新的 `public/` 输出。 仪表板通过按最新时间戳首先对预览行进行排序，然后按置信度排序来优先显示新鲜度，确保访问者在源顶部看到最新的 IOC。移动断点将预览表转换为卡片式行，以提供适合手机的体验，并且所有元数据都经过失效处理，以确保随意浏览时的安全性。 ## ⚙️ 在 GitHub Actions 中运行 SwiftIOC 在 GitHub Actions 内部运行良好，并生成可通过 GitHub Pages 发布的工件。以下工作流每小时收集一次 IOC 并部署 `public/`： ``` name: SwiftIOC – Threat Intel Collector on: schedule: - cron: "0 * * * *" # Run every hour workflow_dispatch: # Allow manual runs from the Actions tab permissions: contents: read pages: write id-token: write concurrency: group: "pages" cancel-in-progress: true jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: "3.11" - name: Install dependencies run: pip install -r requirements.txt - name: Collect recent IOCs run: python -m swiftioc --ci-safe --window-hours 48 --out-dir public - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: path: ./public deploy: environment: name: github-pages runs-on: ubuntu-latest needs: build steps: - id: deployment uses: actions/deploy-pages@v4 ``` `--ci-safe` 启用 JSON 日志记录，确保存在诊断目录，并在缺少可选 RSS 依赖项时抑制硬性失败。 ## 🧪 自动生成的 IOC 摘 辅助脚本 [`scripts/summarize_iocs.py`](scripts/summarize_iocs.py) 将诊断信息和 JSONL 输出转换为 Markdown 摘要。它在“Collect – SwiftIOC”工作流中自动运行，也可以手动执行： ``` python scripts/summarize_iocs.py \ --diag public/diagnostics/run.json \ --ioc-jsonl public/iocs/latest.jsonl ``` 覆盖 `--out` 或 `--index` 以控制摘要的写入位置。当存储库使用 GitHub Pages 发布时，`public/` 下的所有内容都会成为站点内容。 有关安全披露，请参阅 [SECURITY.md](SECURITY.md)。

标签：DevSecOps, ESC4, GitHub Actions, IOC收集, IP黑名单, JSON格式, Linux安全, OSINT, Python安全工具, SIEM集成, SOC工具, STIX 2.1, URL威胁源, 上游代理, 信标提取, 哈希校验, 威胁情报, 安全编排与自动化, 实时处理, 密码管理, 开发者工具, 指标失陷, 数据清洗, 漏洞发现, 网络安全, 自动化流水线, 自动笔记, 逆向工具, 隐私保护