elyass1911-create/securevault
GitHub: elyass1911-create/securevault
一个基于Spring Boot的安全密钥管理API，集成JWT认证、AES加密存储和可解释AI安全监控功能。
Stars: 0 | Forks: 0
[](https://github.com/elyass1911-create/securevault/actions/workflows/ci.yml)
# SecureVault v2 - 具备 AI 安全监控的加密密钥管理 API
SecureVault 是一个 Spring Boot 后端项目，展示了实用的 API 安全模式：JWT 认证、用户级授权、加密数据存储、审计日志以及专注于安全的集成测试。
本项目作为作品集项目构建，旨在通过真实可运行的代码库展示后端和应用安全基础。
核心功能 (v1)：安全的加密密钥库，具备 JWT 认证、AES-256-GCM 加密和严格的基于所有权的访问控制。
新增功能 (v2)：可解释的 AI 安全监控，包含结构化事件、风险评分、异常检测和管理员监控端点。
## 安全监控版 (v2)
此版本通过本地、可解释的监控管道扩展了原始密钥库：
- 针对认证/访问/密钥操作的结构化 `security_events`
- 针对用户/IP 主体的可解释风险评分 (`security_risk_assessments`)
- 基于滚动基线 + z-score 的统计异常检测 (`security_incidents`)
- 仅限管理员访问的监控 API (`/api/security/*`)
- 模拟跨用户访问尝试和暴力破解行为的集成测试
注意：本项目中的“AI”指的是可解释的本地安全分析（规则 + 统计异常检测），而非外部 LLM 调用或付费 AI 服务。
## 关键特性
- 用户注册和登录，采用基于 JWT 的无状态认证
- 具有严格用户所有权检查的密钥 CRUD API
- 专用的明文访问揭示端点
- 使用 AES-256-GCM 加密静态存储的密钥（IV + 密文存储）
- 登录速率限制以降低暴力破解攻击风险
- 针对认证和密钥相关事件的审计日志
- 集中式 API 错误处理，提供一致的错误响应
- 容器化的本地数据库设置
## 安全亮点
- 认证：由自定义安全过滤器验证的 JWT 令牌
- 授权：在数据层强制执行的基于所有者的访问控制 (`findByIdAndOwnerEmail`)
- IDOR/BOLA 防护：阻止跨用户揭示尝试（当前实现中预期返回 `404`）
- 密钥管理：数据库中不持久化明文密钥值
- 配置规范：敏感值从环境变量加载，而非硬编码
- 代理/IP 规范：仅在显式启用时信任转发头
- 仓库规范：忽略 `.env`，提供 `.env.example` 作为模板
- CI 保护：通过 Gitleaks 进行 GitHub Actions 密钥扫描
## 技术栈
- Java 21
- Spring Boot 4
- Spring Security
- Spring Data JPA / Hibernate
- PostgreSQL
- H2 (测试配置)
- JUnit 5 集成测试
- Maven
- Docker / Docker Compose
## API 概览
认证：
- `POST /auth/register`
- `POST /auth/login`
密钥：
- `GET /api/secrets`
- `POST /api/secrets`
- `GET /api/secrets/{id}`
- `GET /api/secrets/{id}/reveal`
- `PUT /api/secrets/{id}`
- `DELETE /api/secrets/{id}`
注意：`GET /api/secrets` 仅返回元数据。明文仅由 `GET /api/secrets/{id}/reveal` 针对所有者用户返回。
安全监控（仅限管理员）：
- `GET /api/security/overview`
- `GET /api/security/incidents?page=&size=`
- `GET /api/security/anomalies?page=&size=`
- `GET /api/security/risk/top?window=24h&limit=10`
访问要求：所有 `/api/security/*` 端点都需要 `ROLE_ADMIN` 权限。
## 快速演示（复制/粘贴）
启动应用和数据库，然后运行此最小流程：
```
# 1) 注册
curl -X POST http://localhost:8080/auth/register \
-H "Content-Type: application/json" \
-d '{"email":"demo.user@test.com","password":"Password123!"}'
# 2) 登录 (从响应 JSON 中复制 token)
curl -X POST http://localhost:8080/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"demo.user@test.com","password":"Password123!"}'
# 3) 创建 secret (替换 )
curl -X POST http://localhost:8080/api/secrets \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{"title":"demo","data":"my first secret"}'
# 4) 仅列出 metadata
curl -X GET http://localhost:8080/api/secrets \
-H "Authorization: Bearer "
# 5) 显示 plaintext (替换 )
curl -X GET http://localhost:8080/api/secrets//reveal \
-H "Authorization: Bearer "
```
提示：本仓库中的 `requests.http` 包含适用于 IDE HTTP 客户端的相同流程。
## API 文档
可以为本地/开发用途显式启用交互式 API 文档：
- `http://localhost:8080/swagger-ui.html`
原始 OpenAPI 规范：
- `http://localhost:8080/v3/api-docs`
默认情况下（`PUBLIC_DOCS_ENABLED=false`），Swagger/OpenAPI 端点被禁用且不会公开暴露。
## 架构
```
flowchart LR
Client[Client / Swagger / Tests] -->|HTTP| Sec[Spring Security Filter Chain]
Sec -->|JWT validated| Ctrl[Controllers]
Ctrl --> Svc[Service Layer]
Svc --> Enc[EncryptionService
AES-256-GCM] Svc --> Repo[Vault Repositories] Svc --> EventSvc[SecurityEventService] EventSvc --> EventRepo[(security_events)] MonitorCtrl[Admin Monitoring API] --> MonitorSvc[SecurityMonitoringService] MonitorSvc --> RiskSvc[RiskScoringService] MonitorSvc --> AnomalySvc[AnomalyDetectionService] RiskSvc --> RiskRepo[(security_risk_assessments)] AnomalySvc --> IncidentRepo[(security_incidents)] RiskSvc --> EventRepo AnomalySvc --> EventRepo Repo --> DB[(PostgreSQL / H2 test profile)] ``` ## 风险评分规则（可解释） | 规则 | 分数 | 理由 | |------|--------|-----------| | `AUTH_LOGIN_FAIL` | 每次 +25 | 重复的登录失败表明存在凭证攻击 | | `AUTH_RATE_LIMIT_TRIGGERED` | 每次 +60 | 暴力破解行为的强烈信号 | | `AUTH_FORBIDDEN` 或 `SUSPICIOUS_ENUMERATION` | 每次 +80 | 高风险未授权访问模式 | | 高频揭示活动 (`SECRET_REVEALED` > 5/窗口) | +15 | 异常高的密钥访问量 | 分数按主体（`USER` 和 `IP`）在可配置窗口（默认：`24h`）内计算，并包含原因代码。 ## 示例响应 `GET /api/security/overview` ``` { "loginFailsLast24h": 8, "rateLimitsLast24h": 1, "forbiddenLast24h": 1, "revealsLast24h": 3, "topRiskySubjects": [ { "subjectType": "IP", "subjectValue": "203.0.113.77", "score": 260, "topReasons": ["LOGIN_FAIL_x8", "RATE_LIMIT_x1"] } ], "openIncidents": [ { "incidentId": 12, "category": "RULE", "severity": "HIGH", "subjectType": "USER", "subjectValue": "sec-b+123@test.com", "reasons": ["CROSS_USER_SECRET_ACCESS_ATTEMPT"] } ] } ``` `GET /api/security/incidents?page=0&size=2` ``` { "content": [ { "incidentId": 12, "category": "ANOMALY", "severity": "MED", "subjectType": "IP", "subjectValue": "203.0.113.77", "reasons": ["ANOMALY_FAILED_LOGINS_PER_HOUR", "Z_SCORE_10.00"] } ] } ``` ## 本地运行 1. 根据 `.env.example` 创建本地 `.env` 文件。 2. 启动 PostgreSQL： ``` docker-compose up -d ``` 3. 启动应用： ``` ./mvnw spring-boot:run ``` 在 Windows PowerShell 上： ``` .\mvnw.cmd spring-boot:run ``` ## 环境变量 示例值（见 `.env.example`）： ``` JWT_SECRET=your-strong-secret AES_KEY=base64-32-byte-key DB_PASSWORD=change-me TRUST_FORWARD_HEADERS=false PUBLIC_DOCS_ENABLED=false ``` 注意： - 仅当运行在受信任的反向代理（清理 `X-Forwarded-For` / `X-Real-IP`）之后时，才设置 `TRUST_FORWARD_HEADERS=true`。 - `PUBLIC_DOCS_ENABLED=true` 启用 Swagger/OpenAPI 端点（仅建议用于本地/开发环境）。 ## 安全设计说明 - 密码存储：用户密码使用 BCrypt 进行哈希处理（`BCryptPasswordEncoder`）。 - JWT 声明：`sub` = 用户邮箱，自定义 `role` 声明。 - JWT 过期：可通过 `security.jwt.expiration-minutes` 配置（默认 `60`）。 - 刷新令牌：目前未实现（仅访问令牌）。 - 密钥轮换：JWT/AES 密钥轮换尚未自动化（计划中的未来工作）。 ## 简要威胁模型 - 数据库泄露：通过对密钥负载进行 AES-256-GCM 静态加密来缓解。 - IDOR/BOLA：通过限定所有者范围的仓库访问和跨用户检查来缓解。 - 暴力登录尝试：通过登录速率限制和安全事件监控来缓解。 - 令牌被盗/重放窗口：通过 JWT 过期时间来缩短；尚无刷新令牌流程。 - 内部人员/滥用可见性：通过审计和安全事件跟踪来改善。 ## 测试 运行所有测试： ``` ./mvnw clean test ``` Windows PowerShell： ``` .\mvnw.cmd clean test ``` 包含的安全集成测试： - `SecretAuthorizationITTest` - 用户 A 可以揭示自己的密钥 (`200`) - 用户 B 无法揭示用户 A 的密钥 (`403` 或 `404`，当前为 `404`) - `SecurityMonitoringITTest` - 跨用户揭示尝试会增加风险并创建事件 - 暴力破解模拟触发速率限制和监控信号 - 正常行为不会为该用户创建高严重性异常 ## CI GitHub Actions 在每次推送到 `main` 和每个 Pull Request 时运行 CI。 - 构建和测试管道：`./mvnw -B clean test` (Java 21) - 安全管道：Gitleaks 密钥扫描 ## 本项目的价值 本仓库展示了我能够： - 设计超越基础 CRUD 的安全后端 API - 实现并验证授权边界（包括 IDOR/BOLA 防护） - 应用静态加密和基于环境的密钥管理 - 构建可解释的安全分析（事件管道、风险评分、异常检测） - 为现实攻击场景（跨用户访问、暴力破解）编写集成测试 - 实践贴近生产的工程实践（Docker 化设置、Swagger/OpenAPI、CI + 密钥扫描） ## 作者 Yassin El Founti 信息技术学士学生 后端与应用安全爱好者
AES-256-GCM] Svc --> Repo[Vault Repositories] Svc --> EventSvc[SecurityEventService] EventSvc --> EventRepo[(security_events)] MonitorCtrl[Admin Monitoring API] --> MonitorSvc[SecurityMonitoringService] MonitorSvc --> RiskSvc[RiskScoringService] MonitorSvc --> AnomalySvc[AnomalyDetectionService] RiskSvc --> RiskRepo[(security_risk_assessments)] AnomalySvc --> IncidentRepo[(security_incidents)] RiskSvc --> EventRepo AnomalySvc --> EventRepo Repo --> DB[(PostgreSQL / H2 test profile)] ``` ## 风险评分规则（可解释） | 规则 | 分数 | 理由 | |------|--------|-----------| | `AUTH_LOGIN_FAIL` | 每次 +25 | 重复的登录失败表明存在凭证攻击 | | `AUTH_RATE_LIMIT_TRIGGERED` | 每次 +60 | 暴力破解行为的强烈信号 | | `AUTH_FORBIDDEN` 或 `SUSPICIOUS_ENUMERATION` | 每次 +80 | 高风险未授权访问模式 | | 高频揭示活动 (`SECRET_REVEALED` > 5/窗口) | +15 | 异常高的密钥访问量 | 分数按主体（`USER` 和 `IP`）在可配置窗口（默认：`24h`）内计算，并包含原因代码。 ## 示例响应 `GET /api/security/overview` ``` { "loginFailsLast24h": 8, "rateLimitsLast24h": 1, "forbiddenLast24h": 1, "revealsLast24h": 3, "topRiskySubjects": [ { "subjectType": "IP", "subjectValue": "203.0.113.77", "score": 260, "topReasons": ["LOGIN_FAIL_x8", "RATE_LIMIT_x1"] } ], "openIncidents": [ { "incidentId": 12, "category": "RULE", "severity": "HIGH", "subjectType": "USER", "subjectValue": "sec-b+123@test.com", "reasons": ["CROSS_USER_SECRET_ACCESS_ATTEMPT"] } ] } ``` `GET /api/security/incidents?page=0&size=2` ``` { "content": [ { "incidentId": 12, "category": "ANOMALY", "severity": "MED", "subjectType": "IP", "subjectValue": "203.0.113.77", "reasons": ["ANOMALY_FAILED_LOGINS_PER_HOUR", "Z_SCORE_10.00"] } ] } ``` ## 本地运行 1. 根据 `.env.example` 创建本地 `.env` 文件。 2. 启动 PostgreSQL： ``` docker-compose up -d ``` 3. 启动应用： ``` ./mvnw spring-boot:run ``` 在 Windows PowerShell 上： ``` .\mvnw.cmd spring-boot:run ``` ## 环境变量 示例值（见 `.env.example`）： ``` JWT_SECRET=your-strong-secret AES_KEY=base64-32-byte-key DB_PASSWORD=change-me TRUST_FORWARD_HEADERS=false PUBLIC_DOCS_ENABLED=false ``` 注意： - 仅当运行在受信任的反向代理（清理 `X-Forwarded-For` / `X-Real-IP`）之后时，才设置 `TRUST_FORWARD_HEADERS=true`。 - `PUBLIC_DOCS_ENABLED=true` 启用 Swagger/OpenAPI 端点（仅建议用于本地/开发环境）。 ## 安全设计说明 - 密码存储：用户密码使用 BCrypt 进行哈希处理（`BCryptPasswordEncoder`）。 - JWT 声明：`sub` = 用户邮箱，自定义 `role` 声明。 - JWT 过期：可通过 `security.jwt.expiration-minutes` 配置（默认 `60`）。 - 刷新令牌：目前未实现（仅访问令牌）。 - 密钥轮换：JWT/AES 密钥轮换尚未自动化（计划中的未来工作）。 ## 简要威胁模型 - 数据库泄露：通过对密钥负载进行 AES-256-GCM 静态加密来缓解。 - IDOR/BOLA：通过限定所有者范围的仓库访问和跨用户检查来缓解。 - 暴力登录尝试：通过登录速率限制和安全事件监控来缓解。 - 令牌被盗/重放窗口：通过 JWT 过期时间来缩短；尚无刷新令牌流程。 - 内部人员/滥用可见性：通过审计和安全事件跟踪来改善。 ## 测试 运行所有测试： ``` ./mvnw clean test ``` Windows PowerShell： ``` .\mvnw.cmd clean test ``` 包含的安全集成测试： - `SecretAuthorizationITTest` - 用户 A 可以揭示自己的密钥 (`200`) - 用户 B 无法揭示用户 A 的密钥 (`403` 或 `404`，当前为 `404`) - `SecurityMonitoringITTest` - 跨用户揭示尝试会增加风险并创建事件 - 暴力破解模拟触发速率限制和监控信号 - 正常行为不会为该用户创建高严重性异常 ## CI GitHub Actions 在每次推送到 `main` 和每个 Pull Request 时运行 CI。 - 构建和测试管道：`./mvnw -B clean test` (Java 21) - 安全管道：Gitleaks 密钥扫描 ## 本项目的价值 本仓库展示了我能够： - 设计超越基础 CRUD 的安全后端 API - 实现并验证授权边界（包括 IDOR/BOLA 防护） - 应用静态加密和基于环境的密钥管理 - 构建可解释的安全分析（事件管道、风险评分、异常检测） - 为现实攻击场景（跨用户访问、暴力破解）编写集成测试 - 实践贴近生产的工程实践（Docker 化设置、Swagger/OpenAPI、CI + 密钥扫描） ## 作者 Yassin El Founti 信息技术学士学生 后端与应用安全爱好者
标签：AES-256-GCM, AI 安全分析, API 安全, DevSecOps, DNS 反向解析, DNS解析, Docker, JWT 认证, PostgreSQL, RESTful API, Spring Boot, Streamlit, Z-score, 上游代理, 个人作品集, 加密存储, 后端开发, 域名枚举, 安全合规, 安全防御评估, 开源项目, 异常检测, 提示词优化, 机密存储, 测试用例, 管理员监控, 组合测试, 统计学, 网络代理, 访问控制, 请求拦截