Siddhu007006/Sentinal

# Sentinel — 威胁情报与数字资产分析平台 一个全面的威胁情报平台，用于通过集成多供应商威胁情报来分析、丰富和管理数字资产。 ## 项目概述 **Sentinel** 采用可扩展、面向微服务的架构构建，具有以下特性： - RESTful API 后端 (Python/FastAPI) - 具有全面 schema 的 PostgreSQL 数据库 - 实时威胁情报增强 - 多供应商 OSINT 集成 - 全面的审计日志和合规性跟踪 ## Epic 3：数据库基础（当前重点） 此 epic 实现了用于威胁情报分析的完整数据库 schema 和 ORM 层： | 任务 | 状态 | 描述 | |---|---|---| | **E3.T1** | ✅ 完成 | 带有身份验证的 User ORM 模型 | | **E3.T2** | ✅ 完成 | Alembic 迁移框架设置 | | **E3.T3** | ✅ 完成 | User 表和 FK 约束 | | **E3.T4** | ✅ 完成 | Upload 模型和文件处理 | | **E3.T5** | ✅ 完成 | DigitalAsset ORM 模型和索引 | | **E3.T6** | ✅ 完成 | **Analysis ORM 模型** (20 个字段，8 个索引，完整测试) | ## 主要功能 ### E3.T6 — Analysis ORM 模型 Analysis 模型代表威胁情报分析结果： - **20 个 ORM 字段** (18 个显式 + 2 个继承自 BaseModel) - **5 种生命周期状态**：PENDING, RUNNING, COMPLETED, FAILED, CANCELLED - **2 个 FK 关系**：DigitalAsset 和 User，采用 selectin 延迟加载 - **5 个 CHECK 约束**：状态验证、分数范围、严重性级别 - **8 个数据库索引**：针对常见访问模式进行查询优化 - **幂等性保证**：部分唯一索引强制每个分析器仅有一个完成的结果 ### Analysis 字段 | 类别 | 字段 | |---|---| | **标识符** | id (UUID), digital_asset_id (FK), requested_by (FK) | | **分析器信息** | analyzer_key, analyzer_version, analyzer_slugs | | **生命周期** | status, started_at, completed_at | | **结果** | threat_score, confidence, severity | | **数据** | reasoning_payload (JSONB), enrichment_data (JSONB) | | **重试** | retry_count, celery_task_id | | **错误** | error_message, error_code | | **时间戳** | created_at (继承), updated_at (继承) | ## 入门指南 ### 前置条件 - Python 3.12+ - PostgreSQL 15+ - Docker & Docker Compose (推荐) ### 安装说明 1. **克隆代码库：** git clone https://github.com/Siddhu007006/sentinal.git cd sentinal 2. **设置环境：** cp .env.example .env # 编辑 .env 文件以配置您的参数 3. **安装依赖：** cd backend pip install -r requirements.txt 4. **初始化数据库：** docker-compose up -d postgres cd backend alembic upgrade head 5. **运行测试：** pytest backend/tests/unit/test_analysis_model.py -v ## 架构 ### 数据库 Schema **核心实体：** - `users` — 具有角色的用户账户 (ADMIN, ANALYST, VIEWER) - `digital_assets` — 域名、IP 地址、URL、文件哈希等 - `analyses` — 威胁情报分析结果 (E3.T6) - `uploads` — 用于批量处理的文件上传 - `audit_logs` — 全面的审计跟踪 ### ORM 层 基于 SQLAlchemy 2.0+ 构建： - 带有类型提示的声明式模型 - 具有预加载/延迟加载策略的关系 - 在 schema 级别强制执行的数据库约束 - 通过 Alembic 管理迁移 ### API 设计 基于 FastAPI 的 REST API： - 请求/响应验证 - 基于角色的访问控制 - 全面的错误处理 - API 文档 (Swagger/OpenAPI) ## 测试策略 ### 单元测试 (E3.T6) **覆盖率：analysis.py 达到 100%** - ORM 模型实例化和字段验证 - 关系导航 - 枚举验证 - 服务器默认值和可空约束 - Repr 和字符串表示 **运行：** ``` pytest backend/tests/unit/test_analysis_model.py -v --cov=app.models.analysis ``` ### 集成测试 (E3.T6) **需要配置了 DATABASE_MIGRATION_URL 的 PostgreSQL** - 迁移升级/降级幂等性 - FK 约束强制执行 (ON DELETE RESTRICT) - CHECK 约束验证 (status, scores, severity) - 部分唯一索引 (幂等性保证) - 索引使用和查询性能 **运行：** ``` export DATABASE_MIGRATION_URL="postgresql://user:pass@localhost/sentinal_test" pytest backend/tests/integration/test_analysis_*.py -v ``` ## 质量保证 ### 代码质量 - **Linting：** Ruff (0 个问题) - **类型检查：** MyPy (0 个错误) - **测试覆盖率：** E3.T6 ORM 模型达到 100% ### Pre-Commit 检查 ``` cd backend ruff check app/models/analysis.py mypy app/models/analysis.py pytest backend/tests/unit/test_analysis_model.py ``` ## 项目结构 ``` sentinal/ ├── backend/ │ ├── app/ │ │ ├── models/ │ │ │ ├── __init__.py │ │ │ ├── analysis.py (E3.T6 — ORM model) │ │ │ ├── digital_asset.py (E3.T5) │ │ │ ├── upload.py (E3.T4) │ │ │ └── user.py (E3.T1) │ │ └── ... │ ├── migrations/ │ │ └── versions/ │ │ └── 20260721_1416_*.py (E3.T6 migration) │ ├── tests/ │ │ ├── unit/ │ │ │ └── test_analysis_model.py (103 tests, 100% coverage) │ │ └── integration/ │ │ ├── test_analysis_migration.py │ │ ├── test_analysis_constraints.py │ │ └── test_analysis_performance.py │ ├── ALEMBIC_SETUP.md │ ├── README.md │ └── pyproject.toml ├── .kiro/ │ └── specs/ │ └── epic-3-database-foundation-analyses-t6/ │ ├── requirements.md │ ├── design.md │ └── tasks.md ├── .github/ │ ├── E3-T6-FINAL-AUDIT.md │ ├── E3-T6-MIGRATION-REVIEW.md │ └── workflows/ │ └── ci.yml └── docs/ ├── 00-Project-Context.md └── 22-Engineering-Backlog.md ``` ## 文档 - **需求：** `.kiro/specs/epic-3-database-foundation-analyses-t6/requirements.md` - **设计：** `.kiro/specs/epic-3-database-foundation-analyses-t6/design.md` - **任务：** `.kiro/specs/epic-3-database-foundation-analyses-t6/tasks.md` - **迁移审查：** `.github/E3-T6-MIGRATION-REVIEW.md` (24 个检查点) - **审计：** `.github/E3-T6-FINAL-AUDIT.md` ## 后续步骤 - **E3.T7：** 查询层和 repository 模式 - **E3.T8：** 用于分析端点的 API 端点 - **E4：** 事件驱动的 enrichment pipeline ## 许可证 专有 — 保留所有权利。 ## 联系方式 **维护者：** Siddharth Reddy (Siddhu007006) **状态：** E3.T6 完成 ✅ — 已准备好投入生产环境 **最后更新：** 2026 年 7 月 21 日

标签：AV绕过, FastAPI, PostgreSQL, 威胁情报, 安全合规, 开发者工具, 微服务架构, 数字资产分析, 测试用例, 网络代理, 请求拦截, 逆向工具