sjashwant21/vuln-platform
GitHub: sjashwant21/vuln-platform
基于 FastAPI 与 React 构建的多租户 AI 漏洞评估平台，结合异步扫描与大模型分析实现自动化的漏洞优先级排序和报告生成。
Stars: 0 | Forks: 0
# VulnAssess 平台
基于 AI 的漏洞评估平台 —— 一个生产就绪、支持多租户的 Web 应用，结合了 FastAPI 后端、React + Vite 前端、后台 worker (Celery + Redis) 以及 PostgreSQL 持久化。它提供自动化的漏洞分析、报告生成以及 AI 辅助的智能层（集成 Groq/OpenAI）。
[](https://github.com/sjashwant21/vuln-platform/actions)
[](LICENSE)
概要：FastAPI 后端 (异步)，React + Vite 前端，Celery worker，Redis，Postgres。API 挂载于 `/v1`，文档位于 `/docs`，健康检查位于 `/health`。
目录
- 功能
- 快速开始 (Docker)
- 本地开发
- 环境变量
- 数据库与迁移
- 测试、代码检查与格式化
- 部署说明
- 安全
- 贡献
- 代码导航
- 许可证与联系
## 功能
- 异步 FastAPI 后端，具备结构化 JSON 日志 (structlog) 和健壮的异常处理
- React (Vite + TypeScript) 前端，预配置了 Tailwind
- 使用 Celery + Redis 进行后台处理，用于长时间运行的分析和报告生成
- PostgreSQL 持久化 (asyncpg) 及 Alembic 迁移
- 报告生成：DOCX、HTML 和图表
- 通过可配置的 provider (Groq 为主，OpenAI 为备) 进行 AI 辅助分析
- 身份验证：JWT，可选 MFA 以及速率限制
## 快速开始 — 开发 (Docker，推荐)
1. 复制环境模板并生成密钥：
```
cp .env.example .env
# 生成 secrets（打印值，复制到 .env）
make gen-secrets
```
2. 启动技术栈：
```
make up
# 或
docker-compose up -d --remove-orphans
```
3. 运行迁移 (API 在启动时会尝试进行幂等的自动迁移；您也可以手动运行)：
```
make migrate
# 或
docker-compose run --rm migrate
```
4. 访问各项服务：
- 前端：http://localhost (nginx 反向代理)
- API 文档：http://localhost/docs
- 健康检查：http://localhost/health
停止技术栈：
```
make down
# 或
docker-compose down
```
注意事项
- 在本地使用 compose 运行时，项目要求通过 `.env` 提供密钥。
- 如果在本地未使用 nginx，前端开发服务器将在 `npm run dev` (前端) 显示的端口上运行。
## 分步使用指南
**第 1 步：访问 API 文档 (Swagger UI)**
1. 在 Docker 技术栈运行 (`make up` 或 `docker compose up -d`) 的情况下，打开浏览器并访问：`http://localhost/docs` (如果在本地运行，则为 `http://localhost:8000/docs`)。
2. 这是一个交互式仪表盘，您可以在其中测试所有的 endpoint，而无需编写任何前端代码。
**第 2 步：创建组织和用户 (注册)**
1. 在 Swagger UI 中，向下滚动到 **Auth** 部分并点击 `POST /v1/auth/register`。
2. 点击 **“Try it out”** 按钮。
3. 输入测试 JSON 数据：
{
"email": "admin@mycompany.com",
"password": "Password123!",
"full_name": "John Doe",
"organization_name": "My Security Corp",
"organization_slug": "my-sec-corp"
}
4. 点击 **Execute**。您应该会收到一个 `201 Created` 响应，其中包含您新的 `access_token`。
**第 3 步：身份验证 (登录)**
1. 滚动到 Swagger UI 页面的最顶部，点击绿色的 **“Authorize”** 按钮 (带有挂锁图标)。
2. 将您刚刚收到的 `access_token` 粘贴到输入框中，然后点击 **Authorize**。
3. 现在，您发出的每一个 API 请求都将自动包含您的身份验证 token！
**第 4 步：测试 AI 漏洞功能 (核心流程)**
1. **添加资产**：前往 Assets endpoint (例如 `POST /v1/assets`)，点击 "Try it out"，然后添加您想要扫描的目标 URL 或 IP 地址。
2. **触发扫描**：调用该资产的扫描 endpoint。因为我们使用的是 Celery + Redis，这将被作为后台任务加入队列。
3. **查看 AI 分析**：扫描完成后，您可以使用 `GET /v1/scans/{scan_id}/report` endpoint。这将返回发现的漏洞，并由 AI 引擎进行优先级排序和总结！
## 本地开发 (不使用 Docker)
后端 (推荐 Python 3.11+)：
```
cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
# 从 .env.example 设置 env vars（DATABASE_URL、REDIS_URL 等）
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```
前端：
```
cd frontend
npm install
npm run dev
# 构建 production assets
npm run build
# 提供 preview build 服务
npm run preview
```
若要在 nginx 后面托管前端构建版本 (正如 docker-compose 所做的那样)，请将 `dist/` 复制到 nginx/static 中，或进行适当的挂载，然后重新加载 nginx。
## 环境变量
有关完整的模板，请参阅 `.env.example`。重要变量包括：
- APP_ENV / APP_NAME / LOG_LEVEL
- SECRET_KEY, JWT_SECRET_KEY, JWT_* 设置
- DATABASE_URL (例如 postgresql+asyncpg://user:pass@host:5432/dbname)
- REDIS_URL, CELERY_BROKER_URL, CELERY_RESULT_BACKEND
- GROQ_API_KEY 和 GROQ_MODEL (AI provider)
- NVD_API_KEY (可选，用于 NVD 查询)
请勿提交真实的密钥。
## 数据库与迁移
- Alembic 配置和迁移位于 `backend/alembic/` 和 `backend/alembic.ini` 下。
- Docker-compose 提供了一个运行 `alembic upgrade head` 的 `migrate` 服务。
- 本地运行 (从 `backend/` 开始)：
```
alembic -c alembic.ini upgrade head
```
如果您喜欢使用 Makefile 辅助命令：
```
make migrate-local
```
## 测试、代码检查与格式化
运行后端测试和覆盖率：
```
make test
# 或
cd backend && pytest tests/ -v --cov=app --cov-report=term-missing --cov-report=html
```
单元/集成测试示例：
- 单元测试：`make test-unit`
- 集成测试：`make test-integration`
代码检查/格式化和类型检查：
```
make lint # ruff
make fmt # ruff format
make check # ruff + mypy
```
## 部署说明
- 前端包含 `frontend/vercel.json`，方便您将静态站点部署到 Vercel。
- 后端包含用于 Railway 部署的 `railway.toml`；它同时也支持通过 Dockerfile 进行容器化部署。
- 在生产环境中，请使用密钥管理器 (Vault/Secret Manager)，启用 TLS 终止，并在 orchestrator (如 Kubernetes、ECS、Cloud Run 等) 中运行服务。
## 后台 worker
- Celery worker 镜像由 `backend/Dockerfile.worker` 构建。
- 确保配置了 `CELERY_BROKER_URL` 和 `CELERY_RESULT_BACKEND`，并且 Redis 接受所配置的密码。
## 可观测性与日志记录
- 通过 structlog 实现结构化 JSON 日志。请在 `.env` 中配置 `LOG_LEVEL`。
- docker-compose 包含针对 postgres、redis、api 和 nginx 的健康检查。
## 安全注意事项
- 配置强大的 `JWT_SECRET_KEY` 并将密钥排除在 VCS 之外。
- 当应用处于生产模式时，将应用安全标头和 HSTS。
- 确保为公共部署配置了速率限制和租户配额。
- 在生产环境中，必须在应用前端启用 TLS (本仓库中的 nginx 要求将证书挂载到 `nginx/ssl`)。
## 代码导航
- `backend/app/main.py` — 应用工厂 (生命周期、middleware、路由)
- `backend/pyproject.toml` & `backend/requirements.txt` — 依赖项
- `backend/alembic/` — 数据库迁移
- `frontend/src/` — 前端源码
- `docker-compose.yml` 和 `Makefile` — 开发编排与辅助命令
## 许可证与联系
本项目基于 MIT 许可证授权 - 有关详细信息，请参阅 [LICENSE.md](LICENSE.md) 文件。
联系方式：Shaan Jashwant (<109244010+sjashwant21@users.noreply.github.com>)
标签：AES-256, AV绕过, FastAPI, React, Syscalls, 人工智能辅助, 搜索引擎查询, 测试用例, 漏洞评估, 网络空间测绘, 请求拦截, 逆向工具