haroonk2607/arzens-assignment4-threat-intel

# THE ARZENS Assignment 4 - 威胁情报富化 - **实习生:** mharoonkhan - **方向:** AI、自动化与安全工程 (初级) - **作业:** API 集成与威胁情报基础 ## 项目摘要 本项目自动化对 IP 地址、域名、文件哈希和 URL 进行威胁情报查询。它支持 VirusTotal、AbuseIPDB 和 AlienVault OTX，将提供商的结果整合为简单的风险评分，并导出 JSON、CSV 和文本报告。 该项目还包括： - 创建事件报告的单个告警富化工作流。 - 针对 50 个或以上指标 (indicator) 的批量分析工作流。 - 用于在没有 API 密钥的情况下进行安全测试的确定性 `--demo` 模式。 - 输入验证、带有指数退避 (exponential backoff) 的重试、密钥轮换、速率限制、JSON 缓存以及优雅的提供商错误处理。 ## 关于样本输出的重要说明 提供的 `sample_output.*` 文件以及 `incidents_demo/` 和 `bulk_outputs_demo/` 下的文件均是在 **demo 模式**下生成的。它们是合成的训练结果，不得视为真实的信誉数据。实时查询需要用户自己的 API 密钥。 ## 文件 | 文件 | 用途 | |---|---| | `ArzensIntern_mharoonkhan_threat_intel_tool.py` | 主要富化工具 | | `ArzensIntern_mharoonkhan_alert_enricher.py` | 单个告警工作流 | | `ArzensIntern_mharoonkhan_bulk_analyzer.py` | 批量分析工作流 | | `config.yaml` | Endpoint、延迟、缓存和重试设置 | | `.env.example` | 安全的 API 密钥模板 | | `sample_indicators.txt` | 10+ 个混合指标 | | `sample_output.json`, `.csv`, `.txt` | 富化输出示例 | | `sample_indicators_bulk.csv` | 50+ 个批量指标 | | `sample_alert.json` | SOC 告警示例 | | `incidents_demo/` | 单个告警的事件报告示例 | | `bulk_outputs_demo/` | 批量 CSV、JSON 和 HTML 报告示例 | | `screenshots/` | 程序输出证据 | | `ArzensIntern_mharoonkhan_ResearchNote.pdf` | 任务 1 研究报告 | | `ArzensIntern_mharoonkhan_AIAssistanceNote.pdf` | AI 使用披露 | | `WORKFLOWS.md` | 工作流和风险评分文档 | | `test_assignment4.py` | 针对性自动化测试 | ## 设置 建议使用 Python 3.10 或更高版本。 ``` python -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install -r requirements.txt ``` 复制密钥模板： ``` Copy-Item .env.example .env ``` 打开 `.env` 并添加您自己的密钥。切勿提交或分享此文件。 ``` VT_API_KEYS=your_virustotal_key ABUSEIPDB_API_KEYS=your_abuseipdb_key OTX_API_KEYS=your_otx_key ``` 多个密钥可以用逗号分隔。在遇到速率限制或身份验证响应后，该工具将轮换到下一个配置的密钥。 ## API 注册 - VirusTotal 社区及 API 密钥：https://www.virustotal.com/gui/join-us - VirusTotal API 文档：https://docs.virustotal.com/ - AbuseIPDB 账户/API 页面：https://www.abuseipdb.com/account/api - AbuseIPDB API 文档：https://docs.abuseipdb.com/ - AlienVault OTX 注册：https://otx.alienvault.com/ - OTX 信息及 DirectConnect API：https://levelblue.com/open-threat-exchange ## 安全的 Demo 命令 针对提供的指标列表运行主工具： ``` python ArzensIntern_mharoonkhan_threat_intel_tool.py ` --input-file sample_indicators.txt ` --demo --no-cache ` --output-dir sample_outputs ` --output-prefix sample_output ``` 运行告警工作流： ``` python ArzensIntern_mharoonkhan_alert_enricher.py ` --alert sample_alert.json ` --demo --no-cache ` --output-dir incidents_demo ``` 运行批量工作流： ``` python ArzensIntern_mharoonkhan_bulk_analyzer.py ` --input sample_indicators_bulk.csv ` --demo --no-cache ` --output-dir bulk_outputs_demo ``` ## 实时查询示例 在 `.env` 中添加密钥后，省略 `--demo`： ``` python ArzensIntern_mharoonkhan_threat_intel_tool.py ` --ip 8.8.8.8 ` --config config.yaml ` --env-file .env ` --output-dir live_outputs ``` 其他支持的输入： ``` python ArzensIntern_mharoonkhan_threat_intel_tool.py --domain example.com python ArzensIntern_mharoonkhan_threat_intel_tool.py --hash SHA256_VALUE python ArzensIntern_mharoonkhan_threat_intel_tool.py --url https://example.com/ python ArzensIntern_mharoonkhan_threat_intel_tool.py --interactive ``` ## 输入文件格式 每行一个指标，可自动检测： ``` 8.8.8.8 example.com https://example.com/login ``` 推荐的显式格式为： ``` ip,8.8.8.8 domain,example.com url,https://example.com/login hash,275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f ``` ## 测试 ``` python -m pytest -q ``` 这些测试使用 demo 模式，不会联系外部服务。 ## 安全性与限制 - API 密钥从 `.env` 读取，且绝不打印。 - `.env` 和缓存目录已被 `.gitignore` 排除。 - 输入在创建 URL 之前会进行验证。 - 请求使用 HTTPS、超时、提供商延迟、重试和退避。 - 良好的信誉结果并不能证明某个指标是安全的。 - 风险评分支持分析师分流 (triage)，但不能代替人工判断。 - 免费层级的配额和提供商数据可能会发生变化。请查看当前的官方条款。 - 提交的样本结果中不包含实时 API 执行，因为本次提交中未存储任何个人 API 密钥。 ## Git 仓库 https://github.com/haroonk2607/arzens-assignment4-threat-intel 提交包中的 `ArzensIntern_mharoonkhan_GitRepositoryLink.txt` 文件内也提供了相同的链接。

标签：API集成, GitHub, Python, 可观测性, 威胁情报, 安全规则引擎, 安全运营, 实时处理, 开发者工具, 扫描框架, 无后门, 网络调试, 自动化, 逆向工具