splitfireai-hue/sentinelx402
GitHub: splitfireai-hue/sentinelx402
一款专为AI智能体设计的免费威胁情报API，提供快速的钓鱼检测、IP信誉查询和CVE漏洞风险分析。
Stars: 0 | Forks: 0
# SentinelX402
**在 300 毫秒内检测恶意域名和 IP，准确率高达 95%。**
为 AI 智能体提供的免费威胁情报 API。提供实时钓鱼检测、CVE 风险分析和 IP 信誉评分。由实时威胁情报源驱动。1,000 次免费请求 —— 无需注册，无需 API 密钥。
**在线 API：** https://sentinelx402-production.up.railway.app/info
## 使用场景
### 1. 钓鱼检测智能体
您的智能体可以扫描来自电子邮件、聊天消息或网页抓取的 URL。在打开任何链接之前，它会先通过 SentinelX402 进行检查：
```
from sentinelx import SentinelX
client = SentinelX(base_url="https://sentinelx402-production.up.railway.app")
risk = client.domain_lookup("login-secure-paypal.com")
if risk.is_malicious:
print(f"BLOCKED: {risk.domain} — {risk.threat_type} (score: {risk.risk_score})")
# → BLOCKED: login-secure-paypal.com — phishing (score: 94.0)
else:
print("Safe to proceed")
```
**价值：** 一次 API 调用即可防止造成数千美元损失的钓鱼事件。
### 2. SOC 自动化 / SIEM 富化
您的安全运营管道每天处理数千个警报。自动对每个 IOC 进行富化：
```
# 从防火墙告警中丰富 IP 信息
ip = client.ip_lookup("185.220.101.42")
if ip.is_malicious:
trigger_alert(f"C2 server detected: {ip.threat_types}")
# → C2 server detected: ['c2'] — tags: cobalt-strike
# 批量域名扫描
suspicious_domains = ["amaz0n-verify.com", "google.com", "hdfc-netbanking-secure.xyz"]
for domain in suspicious_domains:
risk = client.domain_lookup(domain)
print(f"{domain}: {risk.risk_score} ({risk.threat_type})")
```
**价值：** 用亚秒级的自动化评分取代分析师数小时的手工分类。
### 3. 漏洞优先级排序智能体
您的智能体监控新的 CVE，并决定哪些需要立即修补：
```
# 检查特定 CVE
cve = client.cve_lookup("CVE-2024-3400")
print(f"CVSS: {cve.cvss}, Exploit probability: {cve.exploit_probability}")
print(f"Patch urgency: {cve.patch_urgency}, Ransomware risk: {cve.ransomware_risk}")
# → CVSS: 10.0, 漏洞利用概率: 1.0
# → 补丁紧急程度: critical, 勒索软件风险: False
# 获取本周的严重漏洞
recent = client.recent_cves(limit=5)
for cve in recent.cves:
if cve.is_critical:
create_jira_ticket(cve.cve_id, cve.description, priority="P0")
```
**价值：** 结合漏洞利用概率和勒索软件风险评分，超越了原始的 CVSS 评分。
### 4. 印度金融科技欺诈检测
检测 UPI 欺诈域名、印度银行钓鱼以及 Aadhaar/PAN 诈骗：
```
risk = client.domain_lookup("sbi-online-banking-verify.com")
# → score: 96.0, type: phishing, tags: [india, banking, sbi, credential-theft]
risk = client.domain_lookup("upi-paytm-cashback-claim.com")
# → score: 97.0, type: phishing, tags: [india, upi, paytm, cashback-scam]
risk = client.domain_lookup("aadhaar-ekyc-verification.in")
# → score: 98.0, type: phishing, tags: [india, government, aadhaar, identity-theft]
```
**价值：** 提供全球 API 所缺乏的针对印度特定威胁的覆盖。
## 快速入门
### 1. 配置环境
```
cp .env.example .env
# 使用你的设置编辑 .env（默认值开箱即用）
```
### 2. 安装依赖
```
pip install -e .
```
### 3. 初始化威胁数据并启动
```
python -m app.data.seed_threats
uvicorn app.main:app --reload
```
访问 `http://localhost:8000/docs` 查看交互式 API 文档。
## 生产部署
### Docker (推荐)
```
docker compose up -d
```
这将启动包含 PostgreSQL、Redis、gunicorn (4 个 worker)、健康检查和自动重启功能的 API 服务器。
### 手动部署
```
pip install ".[production]"
# 在 .env 中设置 DATABASE_URL, REDIS_URL, ENVIRONMENT=production
gunicorn app.main:app \
--worker-class uvicorn.workers.UvicornWorker \
--bind 0.0.0.0:8000 \
--workers 4
```
## API 参考
| 端点 | 方法 | 描述 |
|----------|--------|-------------|
| `/api/v1/threats/lookup?domain=` | GET | 域名威胁风险查询 —— 实时钓鱼检测 |
| `/api/v1/threats/ip?ip=` | GET | IP 信誉检查 —— C2 和僵尸网络检测 |
| `/api/v1/threats/feed` | GET | 最新威胁指标源 |
| `/api/v1/cves/{cve_id}` | GET | CVE 风险分析，包含漏洞利用概率 |
| `/api/v1/cves/recent` | GET | 来自 NVD 的最新严重 CVE |
| `/api/v1/cves/search?keyword=` | GET | 通过关键字搜索 CVE |
| `/health` | GET | 健康检查 |
| `/info` | GET | API 信息和端点 |
所有端点前 1,000 次请求免费。无需注册。
## 使用示例
### Python
```
import httpx
client = httpx.Client(base_url="http://localhost:8000")
# 域名风险查询
resp = client.get("/api/v1/threats/lookup", params={"domain": "login-secure-paypal.com"})
print(resp.json())
# {
# "domain": "login-secure-paypal.com",
# "risk_score": 94.0,
# "threat_type": "phishing",
# "confidence": 0.95,
# "related_domains": ["secure-paypa1-login.com", "paypal-auth-secure.net"]
# }
# CVE 风险分析
resp = client.get("/api/v1/cves/CVE-2024-3400")
print(resp.json())
# {
# "cve_id": "CVE-2024-3400",
# "cvss": 10.0,
# "exploit_probability": 1.0,
# "risk": "critical",
# "patch_urgency": "critical",
# "ransomware_risk": false
# }
```
### curl
```
curl "http://localhost:8000/api/v1/threats/lookup?domain=suspicious-site.xyz"
curl "http://localhost:8000/api/v1/threats/ip?ip=185.220.101.42"
curl "http://localhost:8000/api/v1/threats/feed?page=1&page_size=10"
curl "http://localhost:8000/api/v1/cves/CVE-2024-3400"
curl "http://localhost:8000/api/v1/cves/recent?limit=5"
curl "http://localhost:8000/api/v1/cves/search?keyword=apache"
```
## x402 支付流程
当设置 `X402_ENABLED=true` 时，情报端点需要付费：
```
Agent sends GET /api/v1/threats/lookup?domain=example.com
|
Server returns HTTP 402 + payment requirements (USDC amount, wallet, network)
|
Agent wallet signs USDC payment via EIP-3009
|
Agent retries request with PAYMENT-SIGNATURE header
|
Server verifies payment via facilitator, returns intelligence response
```
在开发/测试环境中，可设置 `X402_ENABLED=false` 以禁用支付功能。
## 生产特性
- **输入验证** —— 域名格式、IP 地址格式、CVE ID 格式验证
- **速率限制** —— 可通过 `THREAT_RATE_LIMIT` / `CVE_RATE_LIMIT` 为每个端点进行配置
- **安全标头** —— X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, Referrer-Policy, Cache-Control
- **CORS** —— 可通过 `ALLOWED_ORIGINS` 进行配置
- **结构化日志** —— 请求方法、路径、状态、持续时间 (毫秒)
- **错误处理** —— 优雅的 400/404/502/504 响应，不暴露堆栈跟踪
- **NVD 超时** —— 可通过 `NVD_TIMEOUT_SECONDS` 进行配置 (默认 15 秒)
- **缓存容错** —— 缓存失败会被记录，但不会阻塞请求
- **健康检查** —— 深度健康检查，用于验证数据库连接性
- **Docker** —— 多阶段构建，非 root 用户，健康检查，带有 4 个 worker 的 gunicorn
## 架构
```
sentinelx402/
├── app/
│ ├── main.py # FastAPI app + middleware stack
│ ├── config.py # Environment configuration
│ ├── database.py # Async SQLAlchemy engine
│ ├── cache.py # Redis / in-memory cache layer
│ ├── x402_setup.py # Payment route configuration
│ ├── models/ # SQLAlchemy ORM models
│ ├── schemas/ # Pydantic request/response models
│ ├── routers/ # API route handlers + validation
│ ├── services/ # Business logic + scoring + NVD integration
│ └── data/ # Mock threat data + seed scripts
├── tests/ # 31 tests (unit + integration)
├── docker-compose.yml # Production: API + PostgreSQL + Redis
├── docker-compose.dev.yml # Dev: just PostgreSQL + Redis
├── Dockerfile # Multi-stage, non-root, health checks
└── mcp.json # Agent discovery metadata
```
## 配置
所有设置均通过环境变量 (或 `.env` 文件) 进行：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `DATABASE_URL` | `sqlite+aiosqlite:///./sentinelx402.db` | 数据库连接字符串 |
| `REDIS_URL` | (空) | Redis URL，为空则使用内存缓存 |
| `X402_ENABLED` | `false` | 启用 x402 支付中间件 |
| `WALLET_ADDRESS` | — | 您的 USDC 收款钱包地址 |
| `FACILITATOR_URL` | `https://x402.org/facilitator` | x402 协调器端点 |
| `NETWORK_ID` | `eip155:84532` | Base Sepolia (测试网) |
| `NVD_API_KEY` | (空) | 用于提高速率限制的 NVD API 密钥 |
| `ENVIRONMENT` | `development` | `development` / `production` |
| `LOG_LEVEL` | `INFO` | 日志级别 |
| `ALLOWED_ORIGINS` | (空) | CORS 源，以逗号分隔 |
| `THREAT_RATE_LIMIT` | `60/minute` | 威胁端点的速率限制 |
| `CVE_RATE_LIMIT` | `30/minute` | CVE 端点的速率限制 |
| `NVD_TIMEOUT_SECONDS` | `15` | NVD API 请求超时时间 |
## 测试
```
pip install ".[dev]"
pytest -v
```
31 个测试，覆盖评分算法、输入验证、API 端点、安全标头和错误处理。
## 技术栈
- **后端**：FastAPI + Uvicorn (开发) / Gunicorn (生产)
- **数据库**：SQLite (开发) / PostgreSQL 16 (生产)
- **缓存**：内存 (开发) / Redis 7 (生产)
- **支付**：x402 协议 (基于 Base 链的 USDC)
- **CVE 数据**：通过 nvdlib 调用 NVD API
- **速率限制**：slowapi
## 许可证
AGPL-3.0 —— 您可以自由使用和修改本代码，但如果您将修改后的版本作为网络服务部署，则必须公开您的源代码。
托管版 SentinelX402 服务所使用的专有评分算法、扩展品牌数据集、多源情报源集成以及针对印度的威胁数据不包含在本代码库中。
**需要完整的生产版本？** 请使用托管的 API：https://sentinelx402-production.up.railway.app —— 前 1,000 次请求免费。
标签：AI安全代理, C2服务器检测, CISA项目, CVE风险分析, DAST, IP信誉, IP 地址批量处理, SIEM丰富, SOC自动化, 免费API, 域名安全检测, 威胁情报, 安全API, 安全合规, 开发者工具, 恶意软件分析, 情报IOC, 搜索引擎查询, 无密钥API, 无线安全, 测试用例, 漏洞优先级评估, 网络代理, 网络安全, 网络钓鱼检测, 自动化防御, 请求拦截, 逆向工具, 隐私保护, 风险评分