dong-quan-tran/SentinelTI
GitHub: dong-quan-tran/SentinelTI
一个结合机器学习与启发式规则的 URL 威胁情报评分工具，通过 CLI 和 FastAPI 接口对可疑链接进行快速分类并提供可解释的风险判定。
Stars: 1 | Forks: 0
# SentinelTI
SentinelTI 是一个基于 Python 的 URL 威胁评分工具。它摄取威胁情报源（目前是 URLhaus），将指标存储在 SQLite 中，并使用经过训练的 ML 模型和启发式规则对 URL 进行评分。您可以通过 CLI 或 FastAPI HTTP API 与 SentinelTi 交互，将 URL 分类为良性、可疑或恶意，并提供人类可读的解释。
## 快速开始
### 环境要求
- Python 3.10+
- Git
- 建议：用于依赖项的虚拟环境
- 位于 `sentinelti/models/url_classifier.joblib` 的已训练模型文件（或训练一个模型；参见下文的“训练模型”）
### 1. 克隆仓库
```
git clone https://github.com/dong-quan-tran/SentinelTI.git
cd SentinelTI
```
### 2. 创建并激活虚拟环境
在 Windows (PowerShell) 上：
```
python -m venv .venv
.venv\Scripts\Activate.ps1
```
在 Windows (cmd) 上：
```
python -m venv .venv
.\.venv\Scripts\activate.bat
```
在 Linux/macOS 上：
```
python -m venv .venv
source .venv/bin/activate
```
### 3. 安装依赖项
```
pip install --upgrade pip
pip install -r requirements.txt
```
### 4. 运行 CLI 或 API
CLI：
```
python -m sentinelti.cli --help
```
API：请参阅下文的 **HTTP API 使用方法** 以运行 FastAPI 服务器。
## CLI 使用方法
SentinelTi 附带一个 CLI，用于初始化数据库、摄取威胁情报和对 URL 进行评分。
### 初始化数据库
```
python -m sentinelti.cli init
```
这将创建用于存储 URLhaus 指标的本地 SQLite 数据库。
### 摄取 URLhaus 源
```
python -m sentinelti.cli ingest urlhaus
```
这将下载最新的 URLhaus 源，并将恶意 URL 指标更新/插入 (upsert) 到数据库中。
### 对单个 URL 进行评分
人类可读输出：
```
python -m sentinelti.cli score-url "http://example.com"
```
JSON 输出：
```
python -m sentinelti.cli score-url "http://example.com" --json
python -m sentinelti.cli score-url "http://example.com" --json-pretty
```
每个结果包括：
- `url`
- `label` (原始 ML 标签: `0` 良性, `1` 恶意)
- `prob_malicious` (模型判定该 URL 为恶意的概率)
- `heuristic` (来自基于规则分析的分数和原因)
- `final_label` (`benign` / `suspicious` / `malicious`)
- `risk` (`low` / `medium` / `high`)
- `reasons` (人类可读的解释)
### 对多个 URL 进行评分
人类可读输出：
```
python -m sentinelti.cli score-urls "http://example.com" "http://192.168.0.1/login"
```
JSON 输出：
```
python -m sentinelti.cli score-urls "http://example.com" "http://192.168.0.1/login" --json
python -m sentinelti.cli score-urls "http://example.com" "http://192.168.0.1/login" --json-pretty
```
这将返回一个包含丰富信息的列表结果，每个 URL 对应一个，字段与上述相同。
## HTTP API 使用方法
SentinelTi 暴露了一个 FastAPI HTTP API，它复用了与 CLI 相同的 `enrich_score(url)` 逻辑。
### 环境变量
为受保护的端点设置 API 密钥：
```
# Linux/macOS
export SENTINELTI_API_KEY="your-secret-key"
# PowerShell
$env:SENTINELTI_API_KEY="your-secret-key"
```
如果未设置，应用程序将回退到默认的 `"change-me"` 密钥（仅限本地开发）。
### 启动 API 服务器
从项目根目录：
```
uvicorn sentinelti.api:app --host 0.0.0.0 --port 8000 --reload
```
- Base URL: `http://localhost:8000`
- 文档 (Swagger UI): `http://localhost:8000/docs`
### `GET /health`
简单的健康检查，无需认证。
```
{
"status": "ok",
"version": "0.1.0"
}
```
将此用于本地或外部正常运行时间检查。
### `POST /score-url`
对单个 URL 进行评分。
- 认证：需要包含有效密钥的 `X-API-KEY` 头。
- 请求体：
```
{
"url": "https://example.com"
}
```
示例 `curl` (Windows 友好引号)：
```
curl -X POST "http://localhost:8000/score-url" ^
-H "Content-Type: application/json" ^
-H "X-API-KEY: your-secret-key" ^
-d "{\"url\": \"https://example.com\"}"
```
响应 (简化版)：
```
{
"schema_version": "1.0",
"url": "https://example.com",
"label": 0,
"prob_malicious": 0.02,
"heuristic": {
"score": 0.0,
"reasons": []
},
"final_label": "benign",
"risk": "low",
"reasons": [
"No strong malicious indicators detected by model or heuristics."
],
"meta": {
"model": "xgb",
"source": "kaggle+urlhaus"
}
}
```
关键字段：
- `label`: 原始模型输出 (`0` 良性, `1` 恶意)
- `prob_malicious`: 模型判定该 URL 为恶意的概率
- `heuristic`: 结构化 URL 检查 (分数 + 原因)
- `final_label`: 综合判定 (`"benign" | "suspicious" | "malicious"`)
- `risk`: 人类可读的风险等级 (`"low" | "medium" | "high"`)
- `reasons`: 结合模型和启发式规则的解释列表
### `POST /score-urls`
对多个 URL 进行批量评分。
- 认证：需要 `X-API-KEY`。
- 请求体：
```
{
"urls": [
"https://example.com",
"https://phishy.example/login"
]
}
```
示例 `curl`：
```
curl -X POST "http://localhost:8000/score-urls" ^
-H "Content-Type: application/json" ^
-H "X-API-KEY: your-secret-key" ^
-d "{\"urls\": [\"https://example.com\", \"https://phishy.example/login\"]}"
```
响应：
```
{
"results": [
{ /* ScoreResponse for first URL */ },
{ /* ScoreResponse for second URL */ }
]
}
```
`results` 中的每个项目具有与 `/score-url` 响应相同的结构。
## 概念
SentinelTi 响应一致地使用几个核心字段：
- `label` – 原始 ML 预测 (`0` = 良性, `1` = 恶意)。
- `prob_malicious` – 模型判定该 URL 为恶意的概率 (介于 0 和 1 之间)。
- `heuristic.score` – 来自基于规则检查的数值分数 (IP 主机、可疑令牌、TLD 等)；越高表示越可疑。
- `heuristic.reasons` – 描述触发了哪些启发式规则的简短文本片段。
- `final_label` – 来自 ML + 启发式规则的综合判定: `"benign"`, `"suspicious"`, 或 `"malicious"`。
- `risk` – 源自 `final_label` 和分数的人类可读风险等级: `"low"`, `"medium"`, 或 `"high"`。
- `reasons` – 总结 URL 为何被如此分类的高级解释列表 (模型置信度 + 关键启发式指标)。
## 工作原理 (高层概览)
SentinelTi 结合了经过训练的 ML 分类器和基于规则的启发式方法，以判定 URL 是良性、可疑还是恶意。
1. **威胁情报摄取 (URLhaus)**
- SentinelTi 从 URLhaus 源摄取最近的恶意 URL 数据，并将其存储在本地 SQLite 数据库中。
- 数据库跟踪可用于模型训练、更新和分析的指标 (URL、时间戳、标签等)。
2. **机器学习 URL 分类器**
- 一个基于 Python 的 ML 模型被训练为使用标记数据集 (例如，Kaggle 良性 URL + URLhaus 恶意 URL) 将 URL 分类为良性或恶意。
- 模型被保存到磁盘 (例如，在 `sentinelti/models/url_classifier.joblib`)，并由一个小的服务层加载，该服务层暴露一个 `score_url(url)` 函数，返回 `url`、`label` 和 `prob_malicious`。
3. **启发式分析层**
- 在 ML 模型之上，SentinelTi 应用了手工制定的启发式规则，寻找网络钓鱼和恶意软件 URL 中常见的模式，例如：
- 用作主机的原始 IP 地址。
- URL 授权部分中的 `@`。
- 路径或查询中的可疑令牌 (如 `login`、`verify`、`account`、`paypal`、`payment` 等)。
- 不常见或滥用严重的 TLD (例如，`.xyz`、`.top`、`.club`、`.click`)。
- 异常长的域名或非常深的路径。
- 每个启发式规则都会贡献一个数值启发式分数和一个人类可读的原因列表，解释为什么该 URL 看起来有风险。
4. **核心评分与丰富**
- 一个核心函数 `enrich_score(url)` 结合了：
- ML 输出 (`label`, `prob_malicious`)，以及
- 启发式分数和原因。
- 然后它推导出：
- `final_label`: `"benign"`, `"suspicious"`, 或 `"malicious"`,
- `risk`: `"low"`, `"medium"`, 或 `"high"`,
- 一个适用于 CLI/API 响应的统一 `reasons` 列表。
- 此丰富后的结果是 CLI 和 HTTP API 共用的单一事实来源。
5. **接口 (CLI 和 API)**
- **CLI**: 用于初始化 DB、摄取 URLhaus、并以人类可读或 JSON 格式对单个或多个 URL 进行评分的命令。
- **FastAPI HTTP API**: 诸如 `/health`、`/score-url` 和 `/score-urls` 之类的端点，复用 `enrich_score(url)` 进行编程访问。
训练模型
SentinelTi 在 `sentinelti/ml/` 下包含一个 ML 管道，用于从 Kaggle 数据集或 URLhaus + 良性 URL 的组合训练 URL 分类器。
### 先决条件
- 已安装依赖项：
```
pip install -r requirements.txt
```
- 一个标记的 URL CSV (例如，Kaggle “malicious and benign URLs”) 放置在：
```
data/urldata.csv
```
必需的列：
- `url`
- `label`，值为 `benign` 或 `malicious`
### 训练命令
训练通过 `--model` 和 `--source` 标志控制：
- 在 Kaggle 上训练 **XGBoost**：
```
python -m sentinelti.ml.train --model xgb --source kaggle --csv-path data/urldata.csv
```
- 在 Kaggle 上训练 **Logistic Regression**：
```
python -m sentinelti.ml.train --model logreg --source kaggle --csv-path data/urldata.csv
```
- 在 URLhaus 恶意 + Kaggle 良性数据上训练 **XGBoost**：
```
python -m sentinelti.ml.train --model xgb --source urlhaus --csv-path data/urldata.csv
```
- 使用内置的小型虚拟数据集 (用于快速测试)：
```
python -m sentinelti.ml.train --model logreg --source dummy
```
模型产物保存到：
```
sentinelti/models/url_classifier.joblib
```
这些由 SentinelTi ML 评分服务 (`score_url`) 和核心 `enrich_score(url)` 逻辑加载。
### 模型指标
每次训练运行都会将指标保存到 `docs/model_metrics/`：
- 文件名格式：`url_model___.json`
- 包含：
- 模型类型 (`logreg` 或 `xgb`)
- 数据源 (`kaggle`, `urlhaus`, 或 `dummy`)
- 训练/测试类别计数
- 作为 JSON 字典的完整 `classification_report`
## 项目结构
仓库的高层布局：
- `sentinelti/`
- `cli.py` – CLI 入口点 (init, ingest, `score-url`, `score-urls`)。
- `heuristics.py` – 基于规则的 URL 分析 (IP 主机、可疑令牌、TLD 等)。
- `scoring.py` – 核心 `enrich_score(url)`，将 ML 和启发式规则结合为最终结果。
- `ml/` – ML 模型加载和 `score_url()` 服务以及训练脚本。
- `db.py` – SQLite 初始化和连接逻辑。
- `feeds/urlhaus.py` – URLhaus 摄取工具。
- `api.py` – 暴露 `/health`、`/score-url` 和 `/score-urls` 的 FastAPI 应用程序。
- `tests/` – pytest 测试套件。
- `docs/` – 进度日志、设计说明、截图和模型指标。
作者
SentinelTi 由以下人员开发和维护：
姓名：Dong Quan Tran (Johnny)
角色 / 隶属：所有者，合作者
联系方式 (可选)：dxt9721@mavs.uta.edu (University of Texas at Arlington)
GitHub：https://github.com/dong-quan-tran
标签：Apex, AV绕过, FastAPI, Python, SQLite, T1059, T1071, T1574, URLhaus, URL评分, 信标分析, 威胁情报, 开发者工具, 恶意URL检测, 数据摄取, 无后门, 机器学习, 网络安全, 网络测绘, 逆向工具, 隐私保护