DrVerzide/sentinelhub

# SentinelHub [](https://github.com/DrVerzide/sentinelhub/actions/workflows/ci.yml) [](https://www.python.org) [](LICENSE) 一个使用 FastAPI 构建的轻量级**威胁情报平台**：管理入侵指标 (IOC)，从传感器摄取安全事件，自动将它们关联成警报，并对 URL 风险进行评分——所有这些都置于 JWT 身份验证之后，并配备了完整的测试套件、Docker 打包和 CI。 ``` flowchart LR S[Sensors / log shippers] -->|POST /events| API[FastAPI] A[Analyst] -->|JWT auth| API API --> C{Correlation engine} C -->|IOC match| AL[(Alerts)] C -->|URL heuristics| AL API --> DB[(SQLAlchemy / SQLite)] A -->|GET /alerts, /stats| API ``` ## 为什么开发这个项目 它模拟了真实 SOC 平台 (安全运营中心) 的核心循环： 1. 分析员维护 **IOC**——已知的恶意 IP、域名、URL、文件哈希。 2. 基础设施发送**事件** (防火墙连接、邮件网关 URL 点击、代理请求)。 3. 每个事件都会**在摄取时进行关联**：精确的 IOC 匹配加上词法 URL 风险启发式检测 (原始 IP 主机、`@` 技巧、punycode、易被滥用的 TLD、可疑令牌)。 4. 匹配项会变成具有严重程度的**警报**，分析员对其进行分诊 (`open → acknowledged → closed`)。 5. `/stats/summary` 为仪表板提供支持。 ## API 概览 | 方法 | Endpoint | 描述 | 认证 | |--------|----------|-------------|------| | POST | `/auth/register` | 创建分析员账户 | – | | POST | `/auth/token` | OAuth2 密码流程 → JWT | – | | GET | `/health` | 存活探针 | – | | POST/GET/DELETE | `/iocs` | 管理指标 (`ip`, `domain`, `url`, `hash`) | JWT | | POST/GET | `/events` | 摄取并列出事件 (在摄取时关联) | JWT | | GET/PATCH | `/alerts` | 列出 (按状态/严重程度过滤) 并分诊警报 | JWT | | POST | `/analyze/url` | 按需 URL 风险评分 | JWT | | GET | `/stats/summary` | 仪表板聚合数据 | JWT | 运行后，可在 `/docs` 访问交互式文档 (Swagger UI)。 ## 快速开始 ``` git clone https://github.com//sentinelhub.git cd sentinelhub pip install -e ".[dev]" uvicorn sentinelhub.main:app --reload ``` 然后，在另一个终端中： ``` # 注册 + 获取 token curl -s -X POST localhost:8000/auth/register -H "Content-Type: application/json" \ -d '{"username": "analyst", "password": "S3curePass!x"}' TOKEN=$(curl -s -X POST localhost:8000/auth/token \ -d "username=analyst&password=S3curePass!x" | python -c "import sys,json;print(json.load(sys.stdin)['access_token'])") # 添加 IOC curl -s -X POST localhost:8000/iocs -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"ioc_type": "ip", "value": "203.0.113.66", "severity": "critical", "description": "Known C2"}' # Ingest 一个命中它的事件 -> 自动创建 alert curl -s -X POST localhost:8000/events -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"source": "firewall-01", "event_type": "connection", "src_ip": "203.0.113.66"}' # Triage curl -s localhost:8000/alerts?status=open -H "Authorization: Bearer $TOKEN" ``` ## Docker ``` docker compose up --build # API 位于 http://localhost:8000，data 持久化在 named volume 中 ``` ## 安全设计决策 - **PBKDF2-HMAC-SHA256 (60万次迭代，每用户独立盐值)** 用于密码存储——使用标准库，没有脆弱的本地依赖。 - **JWT (HS256)** 访问令牌具有过期时间；密钥和生命周期可通过环境变量进行配置。 - **对于未知用户和密码错误返回相同的 401**——防止在登录时进行用户名枚举。 - 密码永远不会出现在响应或日志中；Pydantic 响应模型显式地对字段进行了白名单过滤。 - Docker 镜像以**非特权用户**身份运行。 ## 测试与 CI ``` pytest ``` 大约 40 个测试覆盖了认证流程 (包括负面用例)、IOC CRUD、关联规则 (IOC 匹配、URL 中的域名匹配、URL 启发式检测、良性流量)、警报分诊和统计数据聚合——所有这些都针对内存数据库进行，因此该套件能在几秒钟内运行完毕。GitHub Actions 会在每次推送时于 Python 3.11–3.13 上运行该套件。 ## 技术栈 FastAPI · SQLAlchemy 2.0 (类型化 ORM) · Pydantic v2 · PyJWT · pytest · Docker · GitHub Actions ## 许可证 MIT

标签：AV绕过, FastAPI, IOC管理, IP 地址批量处理, SOC平台, 事件关联分析, 威胁情报, 安全规则引擎, 安全运营, 开发者工具, 扫描框架, 请求拦截, 逆向工具