frangelbarrera/aegistrace-threat-intelligence

# AegisTrace [](https://www.python.org/) [](LICENSE) [](https://github.com/frangelbarrera/aegistrace-threat-intelligence/actions/workflows/ci.yml) [](https://github.com/frangelbarrera/aegistrace-threat-intelligence) [](https://github.com/frangelbarrera/aegistrace-threat-intelligence) [](https://github.com/frangelbarrera/aegistrace-threat-intelligence) **AegisTrace** 是一个模块化的**网络威胁情报 (CTI)** pipeline，从开源来源收集威胁数据，提取诸如 IP 地址、域名和文件哈希等入侵指标，通过外部情报源对其进行丰富，并使用 ARIMA 时间序列模型预测威胁活动。 它专为**SOC 分析师、威胁猎人、事件响应人员和安全研究人员**构建，他们需要一个单一且可重现的 pipeline，将原始的开源情报源转化为交互式仪表板以及包含丰富指标的 CSV 文件。 ## 核心功能 - **多源收集** - RSS 源、URLhaus、MalwareBazaar、FeodoTracker 以及可选的 AlienVault OTX。 - **NLP 处理** - 基于 spaCy 的实体提取、关键词驱动的威胁分类和简短摘要。 - **IoC 提取** - 基于正则表达式检测 IPv4 地址、域名、MD5/SHA1/SHA256 哈希，并进行跨威胁去重。 - **尽力而为的丰富** - AbuseIPDB（IP 信誉）、VirusTotal（文件哈希分析）和 Pulsedive（标签、活动状态）。当缺少 API key 或请求失败时，pipeline 绝不会崩溃。 - **ARIMA 预测** - 使用本地 SQLite 数据库中的真实历史计数进行 7 天威胁趋势预测，并在历史记录为空时提供确定性的合成回退机制。 - **交互式仪表板** - KPI、三个 Plotly 图表、近期威胁表和丰富 IoC 表，并导出为独立的 HTML 文件。 - **CLI + 库** - 在 `pip install` 后运行 `python -m aegistrace` 或 `aegistrace`，或者从您自己的代码中导入 `aegistrace.run`。 ## 架构 ``` flowchart TD A[Data Sources
RSS / URLhaus / MalwareBazaar
FeodoTracker / OTX] --> B[Collectors] B --> C[NLP Processor
spaCy en_core_web_sm] C --> D[IoC Extractor
IPv4 / domains / hashes] D --> E[IoC Enricher
AbuseIPDB / VirusTotal / Pulsedive] E --> F[Storage
SQLite + CSV export] C --> G[Predictor
ARIMA 7-day forecast] F --> H[Dashboard
Plotly HTML] G --> H ``` ## 快速开始 ### 1. 克隆并安装 ``` git clone https://github.com/frangelbarrera/aegistrace-threat-intelligence.git cd aegistrace-threat-intelligence python -m venv venv source venv/bin/activate # Linux/macOS # venv\Scripts\activate # Windows pip install -r requirements-dev.txt pip install -e . python -m spacy download en_core_web_sm ``` ### 2. 运行 pipeline ``` # 运行每个 source 并启用 enrichment 和 forecasting python -m aegistrace # 限制为特定的 source，跳过 enrichment python -m aegistrace --sources urlhaus,feodotracker --no-enrich # 跳过 ARIMA forecast（更快，dashboard 显示空的 forecast chart） python -m aegistrace --no-forecast --output my_dashboard.html ``` ### 3. 打开输出内容 - `dashboard.html` - 交互式 Plotly 仪表板。 - `iocs_enriched.csv` - 丰富后的 IoC，可直接导入 SIEM 或工单系统。 - `threatintel.db` - 包含 `threats` 和 `iocs` 表的 SQLite 数据库。 ### 4.（可选）配置 API key 所有 key 均从环境变量中读取。pipeline 可以在没有任何 key 的情况下运行；配置后将解锁更丰富的数据补充功能。 ``` cp .env.example .env # 编辑 .env 并填入你的真实 keys export $(grep -v '^#' .env | xargs) # Linux/macOS ``` 支持的变量包括：`OTX_API_KEY`、`ABUSEIPDB_API_KEY`、`VIRUSTOTAL_API_KEY`、`PULSEDIVE_API_KEY`。详情请参阅 `.env.example`。 ## 项目结构 ``` aegistrace-threat-intelligence/ ├── aegistrace/ # Main package (importable, pip-installable) │ ├── __init__.py # Package metadata (__version__) │ ├── __main__.py # python -m aegistrace entry point │ ├── cli.py # argparse CLI │ ├── config.py # Env-driven configuration │ ├── collectors.py # Source fetchers + fetch_all_sources │ ├── nlp_processor.py # spaCy entity extraction + classification │ ├── ioc_extractor.py # Regex-based IoC extraction │ ├── enricher.py # Best-effort external API enrichment │ ├── predictor.py # ARIMA 7-day forecast │ ├── storage.py # SQLite persistence │ ├── dashboard_generator.py # Plotly HTML dashboard │ ├── logging_config.py # Shared logging setup │ └── main.py # Pipeline orchestrator (run()) ├── tests/ # pytest suite, 91% coverage │ ├── conftest.py # Shared fixtures │ ├── test_collectors.py │ ├── test_config_and_package.py │ ├── test_cli_and_main.py │ ├── test_dashboard_generator.py │ ├── test_enricher.py │ ├── test_ioc_extractor.py │ ├── test_nlp_processor.py │ ├── test_predictor.py │ └── test_storage.py ├── .github/workflows/ci.yml # CI: ruff + pytest on Python 3.10/3.11/3.12 ├── .pre-commit-config.yaml # ruff + ruff-format + sanity hooks ├── .gitignore ├── .env.example # API keys template ├── main.py # Backward-compat shim (python main.py) ├── pyproject.toml # PEP 621 packaging + tool config ├── requirements.txt # Runtime deps (version-pinned) ├── requirements-dev.txt # Dev deps (pytest, ruff, mypy, responses) ├── setup_aegistrace.bat # One-click Windows setup ├── CONTRIBUTING.md ├── CHANGELOG.md ├── LICENSE └── README.md ``` ## CLI 参考 ``` usage: aegistrace [-h] [--version] [--sources SOURCES] [--no-enrich] [--no-forecast] [--output OUTPUT] [--csv CSV] [--verbose] AegisTrace - Cyber Threat Intelligence pipeline. options: -h, --help show this help message and exit --version show program's version number and exit --sources SOURCES Comma-separated subset: otx,rss,urlhaus,malwarebazaar,feodotracker --no-enrich Skip IoC enrichment (faster, no external API calls) --no-forecast Skip ARIMA forecasting --output OUTPUT HTML dashboard output path (default: dashboard.html) --csv CSV Enriched IoCs CSV output path (default: iocs_enriched.csv) --verbose Enable DEBUG logging ``` 退出代码：`0` 成功，`1` 警告（例如：所有源失败并使用了模拟数据），`2` 错误。 ## 将 AegisTrace 作为库使用 ``` from aegistrace.main import run result = run( sources=["urlhaus", "rss"], enrich=True, forecast=True, output="dashboard.html", csv_path="iocs.csv", ) print(f"Collected {len(result.threats)} threats") print(f"Extracted {len(result.iocs_enriched)} IoCs") print(f"Dashboard: {result.dashboard_path}") ``` 每个模块中的公开函数均记录了 Google 风格的 docstring 和类型提示；详情请参阅 `aegistrace/` 源代码。 ## 输出示例 运行 pipeline 时的控制台输出：  包含 KPI、图表和 IoC 表的交互式仪表板：  丰富后的 IoCs CSV 导出：  ## 技术栈 | 层级 | 技术 | |------------------|---------------------------------------------| | 语言 | Python 3.10+（已在 3.10、3.11、3.12 上测试） | | NLP | spaCy `en_core_web_sm` | | 可视化 | Plotly | | 数据处理 | pandas | | 预测 | statsmodels (ARIMA) | | 存储 | SQLite (标准库 `sqlite3`) | | HTTP | requests | | 测试 | pytest + pytest-cov + responses | | 代码检查 | ruff | | 类型提示 | mypy（尽力而为） | ## 开发 ### 运行测试套件 ``` pytest -v --cov=aegistrace --cov-report=term-missing ``` ### Lint 与格式化 ``` ruff check aegistrace tests ruff format aegistrace tests ``` ### 安装 pre-commit 钩子（推荐） ``` pip install pre-commit pre-commit install ``` 完整的开发工作流请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 路线图 计划中（不作保证，暂无时间表）： - [ ] 为提取的 IoC 提供 MITRE ATT&CK 技术映射。 - [ ] 提供 STIX 2.1 输出，以实现 SIEM/SOAR 互操作性。 - [ ] MISP 源集成（OTX 的替代方案）。 - [ ] Dockerfile + docker-compose 实现一键部署。 - [ ] FastAPI 只读 API，用于以编程方式访问仪表板。 - [ ] 对 URLhaus / MalwareBazaar 记录的行业推断（目前为 `"Unknown"`）。 ## 许可证 MIT - 请参阅 [LICENSE](LICENSE)。

标签：Python, 妥协指标, 威胁情报, 安全规则引擎, 安全运营中心, 开发者工具, 无后门, 时序预测, 网络映射, 逆向工具