arthurcamargo03/contego-threat-intel

# Contego Threat Intel 一个简单的 **Threat Intelligence** Web 平台，用于查询威胁指标 （IOCs）。用户输入一个 **IP**、**域名** 或 **文件 hash**， 应用会查询 [AlienVault OTX](https://otx.alienvault.com/) 的 API，将 信誉/威胁数据整理成易于阅读的 dashboard，保存本地历史记录，并且——作为 特色——通过 **Claude API** 生成自然语言（PT-BR）摘要，格式 类似于给客户的简报。 ## 技术栈 - **后端：** Python + [FastAPI](https://fastapi.tiangolo.com/) - **前端：** HTML/CSS/JS 结合 Jinja2 模板（不使用 JS 框架） - **数据库：** SQLite（查询历史） - **外部 API：** - [AlienVault OTX](https://otx.alienvault.com/) — 威胁/信誉数据 - [Anthropic Claude](https://www.anthropic.com/) — 自然语言摘要（可选） ## 功能特性 - 统一输入：输入 IP、域名或 hash —— 类型通过 regex **自动检测**。 - 根据类型查询 OTX 并构建清晰的对象（屏幕上不显示原始 JSON）。 - 带有**颜色判定**（安全 / 可疑 / 恶意）的 dashboard，基于 pulse 数量得出。 - 按类型显示详情：相关 pulse、地理位置（IP/域名）、关联的恶意软件和 URL 、文件分析（hash）。 - 持久化存储在 SQLite 中的**历史记录**，包含重新打开每个查询的链接。 - **AI 摘要**（特色，可选）：通过 Claude 生成 2-3 段 PT-BR 语言简报。 ## 演示 查询一个**恶意 hash**（WannaCry）—— 判定结果、相关 pulse 以及 为非技术客户生成的自然语言 **AI 摘要**：  查询一个**安全 IP**（8.8.8.8）—— 绿色判定、摘要和地理位置：  之前查询的**历史记录**，带有重新打开每个结果的链接：  主屏幕：  ## 如何获取 API 密钥 ### AlienVault OTX（必需） 1. 在 创建一个免费账号。 2. 访问 **Settings → API Integration**。 3. 复制您的 **OTX API Key**。 ### Anthropic Claude（可选） 自然语言摘要是一个**可选**的特色功能：没有此密钥，应用程序 仍可正常运行，只是不会显示“AI 摘要”部分。 1. 在 创建一个账号。 2. 在 **API Keys** 中，生成一个新密钥。 3. 添加付款方式（按 token 计费；摘要使用的是便宜的 模型 —— 每次查询的成本仅为几分钱）。 ## 如何在本地运行 前置条件：**Python 3.10+**。 ``` # 1. 克隆仓库 git clone https://github.com/arthurcamargo03/contego-threat-intel.git cd contego-threat-intel # 2. 创建并激活虚拟环境 python3 -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate # 3. 安装依赖（版本固定在 requirements.txt 中） pip install -r requirements.txt # 4. 配置环境变量 cp .env.example .env # 打开 .env 并填写 OTX_API_KEY（如果需要摘要，请填写 ANTHROPIC_API_KEY） # 5. 运行服务器 uvicorn main:app --reload ``` 在浏览器中访问 。 ### 环境变量（`.env`） | 变量 | 必需 | 描述 | | ------------------- | :---------: | ---------------------------------------------------------------- | | `OTX_API_KEY` | 是 | AlienVault OTX 的 API 密钥。 | | `ANTHROPIC_API_KEY` | 否 | Claude API 的密钥。如果缺失，AI 摘要将被禁用。 | | `ANTHROPIC_MODEL` | 否 | 摘要使用的模型（默认：`claude-haiku-4-5`）。 | | `DATABASE_PATH` | 否 | SQLite 文件的路径（默认：`threat_intel.db`）。 | ## 文件夹结构 ``` contego-threat-intel/ ├── main.py # App FastAPI: rotas e orquestração (camada de apresentação) ├── services/ │ ├── otx.py # Consulta ao OTX: detecção de tipo + montagem do objeto limpo │ └── ai.py # Resumo em linguagem natural via Claude (opcional/degradável) ├── database/ │ └── db.py # Camada de acesso ao SQLite (isolada do resto da app) ├── templates/ │ ├── index.html # Formulário + dashboard do resultado │ └── history.html # Lista do histórico de consultas ├── static/ │ └── style.css # Estilos (tema escuro; veredito em semáforo) ├── .env.example # Nomes das variáveis de ambiente (sem valores) ├── .gitignore # Ignora .env, *.db, __pycache__, venv/ ├── requirements.txt # Dependências com versões fixadas └── README.md ``` 分层的分离是有意为之的：**路由**（`main.py`）只负责调度；**业务逻辑** 存在于 `services/` 中；所有**对数据库的访问**都隔离在 `database/db.py` 中。 这使得每个部分都易于测试和替换（例如：将 SQLite 换成另一个数据库只需 修改 `db.py`）。 ## 应用程序流程 1. 用户在 `/` 输入一个指标并提交表单（`POST /`）。 2. `services/otx.py` 通过 regex **检测类型**（IPv4、域名或 hash）。 3. 查询正确的 OTX endpoint，并使用相关数据构建一个**清晰的对象**。 4. pulse 的数量决定了**判定结果**：`0 = 安全`，`1-3 = 可疑`，`4+ = 恶意`。 5. 如果存在 `ANTHROPIC_API_KEY`，`services/ai.py` 会生成 **PT-BR 摘要**；否则为 `None`。 6. 查询保存在**历史记录**（`database/db.py`）中，并渲染 **dashboard**。 7. 在 `/history` 中，用户可以查看之前的查询并**重新打开**每个结果 —— 直接从数据库读取，无需重新查询 OTX。 ## 错误处理 错误会在页面上转化为友好的消息，不会泄露 stack trace： - **无效指标**（无法识别的格式）→ 提示预期的格式。 - **在 OTX 中未找到**（404）→ 明确的提示消息。 - **API 宕机 / timeout / rate limit** → 友好的提示消息，不会导致应用程序崩溃。 - **AI 摘要失败** → 静默降级（对 OTX 的查询不受影响）。

标签：AV绕过, FastAPI, IOC分析, Python, SQLite, Web平台, 威胁情报, 开发者工具, 无后门, 逆向工具