SeifMoussa/secure-incident-api-lab

# 安全事件管理 API 用于防御性安全事件管理的生产级 FastAPI 后端。 这是一个防御性作品集实验项目，而非已部署的生产级 SOC 平台。它仅使用合成/演示数据。请勿使用真实的凭证、真实的 token、真实的客户事件数据或真实的证据文件。 ## 本项目展示的内容 安全事件管理 API 展示了安全运营工作流的后端与应用安全工程模式： - FastAPI 应用工厂。 - SQLAlchemy ORM 模型与 Alembic 基线迁移。 - 带有 access 和 refresh token 的 JWT 认证。 - Refresh-token JTI 黑名单。 - 密码哈希、密码策略以及常见密码拒绝。 - 针对 ADMIN、ANALYST、VIEWER 和 AUDITOR 角色的 RBAC。 - 仅限 ADMIN 的用户管理。 - 事件 CRUD、过滤、分页与软删除。 - 嵌套工单、证据备注、仅元数据附件以及修复任务。 - 中间件驱动的审计日志和事件时间线。 - 速率限制、安全标头、CORS 白名单以及生产环境文档开关。 - 严格校验、防止批量赋值以及安全的校验错误。 - STRIDE 威胁模型与 API 参考。 - OpenAPI 导出。 - Pytest 覆盖率、Ruff lint/格式检查、GitHub Actions 配置、CodeQL 配置以及 Dependabot 配置。 ## 目标角色 本项目专为以下相关角色设计： - 后端开发人员。 - 初级安全工程师。 - SOC 自动化分析师。 - 蓝队分析师。 - 应用安全实习生。 - DevSecOps 实习生。 ## 功能摘要 已实现的端点分组： - 常规：`/`, `/health` - 认证：`/auth/register`, `/auth/login`, `/auth/refresh`, `/auth/logout`, `/auth/me` - 管理员用户：`/admin/users/`, `/admin/users/{uid}`, `/admin/users/{uid}/role` - 事件：`/incidents/`, `/incidents/{incident_id}`, `/incidents/{incident_id}/timeline` - 工单：`/incidents/{incident_id}/tickets/` - 证据备注：`/incidents/{incident_id}/evidence/` - 修复任务：`/incidents/{incident_id}/remediation/` - 审计读取：`/audit/` 证据附件仅包含元数据。没有二进制上传、文件存储以及针对证据的磁盘文件读取。 ## 架构概览 ``` app/ admin/ ADMIN-only user management audit/ audit middleware, sanitizer, schemas, read API auth/ registration, login, refresh, logout, JWT helpers common/ shared enums, pagination, dependencies, validation, errors evidence/ evidence notes and metadata-only attachment workflows incidents/ incident CRUD and timeline remediation/ remediation task workflows security/ headers, CORS, rate limiting, middleware registration tickets/ ticket workflows alembic/ baseline migration docs/ security, API, testing, Agile, CI/CD, release docs tests/ unit, integration, security, docs, workflow tests ``` 该应用在 API 边界使用严格的 Pydantic schema，在服务层使用业务规则，并结合了 SQLAlchemy ORM/查询构建器模式，以及在开发和测试中使用本地 SQLite。 ## 安全模型 - JWT bearer 认证保护运营端点。 - Refresh token 是有类型的，并在注销时通过 JTI 加入黑名单。 - 授权使用当前的数据库用户状态，因此停用和角色更改会立即生效。 - RBAC 控制 ADMIN、ANALYST、VIEWER 和 AUDITOR 的权限。 - 写入请求通过中间件记录审计日志，并包含经过净化的元数据。 - 敏感字段会从响应、校验错误、审计日志、文档和测试中排除或脱敏。 - CORS 默认使用明确的本地白名单以及安全的生产环境空白白名单。 - API 响应会应用安全标头。 - 在正常配置下，速率限制会保护登录和常规端点。 - 生产环境设置会禁用交互式 API 文档，并拒绝占位符 JWT 密钥。 ## RBAC 矩阵 | 功能 | ADMIN | ANALYST | VIEWER | AUDITOR | | --- | --- | --- | --- | --- | | 登录/refresh/logout/me | 是 | 是 | 是 | 是 | | 列出/查看用户 | 是 | 否 | 否 | 否 | | 更改用户角色 | 是 | 否 | 否 | 否 | | 停用用户 | 是 | 否 | 否 | 否 | | 创建事件 | 是 | 是 | 否 | 否 | | 读取事件 | 是 | 是 | 是 | 是 | | 更新事件 | 是 | 是 | 否 | 否 | | 软删除事件 | 是 | 否 | 否 | 否 | | 查看事件时间线 | 是 | 是 | 是 | 是 | | 创建/更新/删除工单 | 是 | 是 | 否 | 否 | | 读取工单 | 是 | 是 | 是 | 是 | | 创建证据备注 | 是 | 是 | 否 | 否 | | 更新证据备注 | 是 | 仅限自己 | 否 | 否 | | 删除证据备注 | 是 | 否 | 否 | 否 | | 读取证据备注 | 是 | 是 | 是 | 是 | | 创建/更新/删除修复任务 | 是 | 是 | 否 | 否 | | 读取修复任务 | 是 | 是 | 是 | 是 | | 读取审计日志 | 是 | 否 | 否 | 是 | ## 审计日志 针对写入请求，审计日志由中间件驱动。它会记录安全的元数据，例如操作者、动作、资源类型、资源 ID、时间戳、可用时的客户端主机、结果以及经过净化的更改摘要。 审计日志绝不会故意存储密码、密码哈希、access token、refresh token、authorization header、API 密钥、JWT 密钥、cookie、原始 token 或类似机密的值。审计读取权限仅限 ADMIN/AUDITOR。不存在任何审计修改路由。 ## 本地设置 ``` python -m venv .venv .venv\Scripts\activate python -m pip install --upgrade pip python -m pip install -e ".[dev]" ``` 请仅使用占位符本地设置。请勿在 `.env` 中放入真实的机密。 ``` copy .env.example .env ``` ## 本地质量检查命令 ``` python scripts/export_openapi.py python scripts/check-docs.py python -m py_compile scripts/export_openapi.py scripts/check-docs.py python -m pytest python -m pytest --cov=app --cov-report=term-missing --cov-fail-under=95 python -m ruff check . python -m ruff format --check . python -m uvicorn app.main:create_app --factory --help python -m alembic upgrade head python -m alembic current ``` ## 当前本地质量状态 最新的本地阶段 12 验证： - 测试：248 通过。 - 覆盖率：95.60%。 - 覆盖率门槛：95%。 - Ruff：通过。 - 格式检查：通过。 - 文档安全性：通过。 - OpenAPI 导出：通过。 - Alembic SQLite upgrade/current：通过。 托管的 GitHub Actions 和托管的 CodeQL 已在本地配置，但由于仓库尚未发布，因此尚未验证。 ## 文档 - [STRIDE 威胁模型](docs/threat_model.md) - [API 参考](docs/api_reference.md) - [OpenAPI JSON](docs/openapi.json) - [CI/CD 配置](docs/ci-cd.md) - [发布检查清单](docs/release-checklist.md) - [敏捷规划文档](docs/agile/README.md) - [安全范围](docs/security-scope.md) - [测试计划](docs/testing-plan.md) ## 限制 - 这是一个作品集实验项目，而非已部署的生产级 SOC 平台。 - 不包含真正的生产环境部署、监控、备份、灾难恢复或合规性审查。 - 开发和测试使用本地 SQLite。 - 内存中的速率限制不是分布式的。 - 审计日志通过 API 设为仅可追加，但未实现外部不可变审计存储。 - GitHub 托管的 CI、CodeQL、Dependabot PR、分支保护、tag、release、活跃的 Issue 以及活跃的 Project 均有待发布后进行。 ## 路线图 - 阶段 12：本地敏捷与发布准备材料已完成。 - 阶段 13：初始化 git，发布至 GitHub，验证托管的 CI/CodeQL，创建活跃的 Issue/Project，配置分支保护，标记 `v0.1.0`，并创建 GitHub release。 ## 许可证 MIT。详见 [LICENSE](LICENSE)。

标签：AV绕过, DevSecOps, FastAPI, 上游代理, 后端开发, 安全事件管理, 应用安全工程, 身份认证与权限控制, 逆向工具