datntpro/VulnGuard

# 🛡️ VulnGuard — 本地 DevSecOps 安全扫描器 **VulnGuard** 是一款完全在本地运行的安全扫描工具，集成了 AI 分析功能 (Ollama)，全面支持 DevSecOps 流水线 —— 从代码扫描到生成中文安全报告。 ## 🚀 快速开始 ### 系统要求 | | 最低要求 | 推荐 | |---|---|---| | **Docker** | v24+ 及 Compose v2 | Docker Desktop | | **内存 (RAM)** | 8 GB | 16 GB (用于 AI 模型) | | **磁盘 (Disk)** | 10 GB | 20 GB | | **操作系统 (OS)** | macOS, Linux, Windows (WSL2) | macOS / Ubuntu | | **Ollama** | 安装在宿主机上 (无需 Docker) | | ### 安装 Ollama (在宿主机上运行，而不是在 Docker 中) ``` # macOS / Linux curl -fsSL https://ollama.com/install.sh | sh # 拉取 AI model（选择 1）： ollama pull llama3.2 # Recommended (4GB, cân bằng tốt) ollama pull deepseek-coder:6.7b # Tốt hơn cho code analysis (8GB RAM) ollama pull phi3:mini # Máy yếu <8GB RAM ``` ### 启动 VulnGuard ``` # 1. Clone / 解压 project cd VulnGuard # 2. 配置 cp .env.example .env # 打开 .env，修改 SCAN_WORKSPACE 指向包含 source code 的目录： # SCAN_WORKSPACE=/home/user/projects (Linux/macOS) # SCAN_WORKSPACE=C:/Users/user/projects (Windows WSL2) # 3. Build 并启动（首次约 5-15 分钟） docker compose build docker compose up -d # 4. 打开浏览器 open http://localhost:8080 ``` ### 扫描源代码 ``` # 步骤 1：将 source code 复制到 workspace cp -r /path/to/your/project ~/vulnguard-workspace/my-project # 步骤 2：在 Web UI 中： # → 创建 Project → Trigger Scan → 输入路径：/workspace/my-project ``` ## 🤖 AI 分析 (Ollama) Ollama 直接在宿主机上运行 —— **不会将数据发送到外部互联网**。 | 模型 | 内存 (RAM) | 质量 | 备注 | |---|---|---|---| | `llama3.2` | ~4 GB | ⭐⭐⭐⭐ | **默认** —— 速度与质量平衡 | | `deepseek-coder:6.7b` | ~8 GB | ⭐⭐⭐⭐⭐ | 最适合代码分析 | | `codellama:7b` | ~6 GB | ⭐⭐⭐ | 很好的替代方案 | | `phi3:mini` | ~3 GB | ⭐⭐ | 适用于低性能、低内存设备 | 更改模型：在 Web UI 中进入 **Settings → AI Model**，或者修改 `.env` 中的 `OLLAMA_MODEL`。 ## 🛠️ 集成扫描工具 | 工具 | 类型 | 语言 / 范围 | |---|---|---| | **Semgrep** | SAST | Python, JS/TS, Java, Go, C/C++, Ruby... | | **Bandit** | SAST | 深入扫描 Python | | **Trivy** | SCA + IaC + Container | 多生态系统 (npm, pip, Maven, Go...) | | **pip-audit** | SCA | Python 依赖 (PyPI Advisory DB + OSV) | | **Checkov** | IaC | Terraform, CloudFormation, K8s, Dockerfile, Ansible | | **Hadolint** | IaC | Dockerfile linter | | **Grype** | Container | 用于容器镜像的 Anchore CVE scanner | | **Gitleaks** | Secrets | 代码/git 中的 API keys, tokens, credentials | | **detect-secrets** | Secrets | 熵分析 + 关键词检测 | ## 📊 核心功能 ### 🔍 扫描引擎 - **并行**运行所有扫描器 (异步) —— 节省时间 - **实时进度**：查看每个工具的运行状态及实时结果 - 基于指纹 (fingerprint) 的自动去重 - 支持：SAST, SCA, IaC, Container, Secrets - 路径验证：如果路径不存在会明确报错 ### 🤖 AI 分析 - **误报检测**：提供误报概率百分比及具体原因 - **可利用性 (公开/私有)**：根据环境评估风险 - **中文解释**：开发者易于理解，无需阅读原始 CVE - **详细修复指南**：包含代码片段、文件名和行号 ### 📄 AI 报告 (HTML) - 扫描完成后生成完整的 HTML 报告 - **跨工具去重**：多个工具发现的同一漏洞 → 合并处理 - **按组件分组**：Package (SCA)、Rule (SAST)、Secret 类型、IaC 检查 - 汇总表：组件 · 错误数 · 严重程度 · 发现工具 · AI 判定 - 详情：文件路径 + 行号 + 代码片段 + 修复指南 - **下载 .html** (用于发送邮件 / 归档) 和 **打印 / 导出 PDF** 按钮 ### 🔐 漏洞管理 - 每个项目最多保存 **5 次扫描** (滚动更新) - 跟踪状态：`OPEN` → `ACCEPTED` / `FALSE_POSITIVE` / `FIXED` - **豁免系统**：接受风险需记录审批人姓名 + 原因 + 到期日 ### ✅ 审批流程 - **严重性阈值**：如果存在 ≥ 阈值的 OPEN 状态漏洞，则阻止审批 - **审批检查**：部署前的快速检查 - **扫描对比**：查看差异 —— 两次扫描中新出现的 / 已修复的 / 仍然存在的漏洞 ### ⚙️ 设置 - **扫描工具**：检查安装状态及版本，启用/禁用各个工具 - **AI 模型**：管理 Ollama 模型，切换活跃模型 - 导出：JSON, CSV, HTML 报告 ## 📁 项目结构 ``` VulnGuard/ ├── docker-compose.yml # Container orchestration ├── .env # Cấu hình (SCAN_WORKSPACE, OLLAMA_MODEL...) ├── .env.example # Cấu hình mẫu ├── api/ │ ├── Dockerfile # All-in-one: API + tất cả Scanner tools │ ├── requirements.txt # Python deps cho API │ ├── config.py # App settings (pydantic-settings) │ ├── database.py # SQLite connection │ ├── main.py # FastAPI app entry point │ ├── models.py # DB models: Project, Scan, Vulnerability, Waiver │ ├── schemas.py # Pydantic schemas │ └── routes/ │ ├── projects.py # CRUD projects │ ├── scans.py # Trigger scan, live progress, export │ ├── vulns.py # Vulnerability management, waivers │ ├── compare.py # Scan comparison, approve check │ ├── report.py # AI HTML report generator │ ├── settings.py # Scanner health check, enable/disable │ └── ollama.py # Ollama model management ├── scanner/ │ ├── orchestrator.py # Chạy song song, live callback, dedup │ ├── ai_analyzer.py # Ollama integration, tiếng Việt │ └── scanners/ │ ├── base.py # BaseScanner abstract class │ ├── sast.py # Semgrep (bundled rules + online), Bandit │ ├── sca.py # Trivy SCA, pip-audit │ ├── container.py # Trivy container, Grype │ ├── iac.py # Checkov, TrivyIaC, Hadolint │ ├── secrets.py # Gitleaks, detect-secrets │ └── rules/ │ └── python-security.yaml # Bundled Semgrep rules (offline) ├── web/ │ └── index.html # Single-page Web Dashboard └── storage/ # Persistent data (Docker volume) ├── db/ # SQLite database └── scanner_config.json # Scanner enable/disable config ``` ## 📡 API 端点 ``` # Projects GET /api/projects Danh sách projects POST /api/projects Tạo project DELETE /api/projects/{id} Xóa project # Scans POST /api/projects/{id}/scans Trigger scan mới GET /api/projects/{id}/scans Danh sách scans GET /api/projects/scans/{id} Chi tiết scan GET /api/projects/scans/{id}/progress Live progress (poll 2s) GET /api/projects/scans/{id}/vulns Danh sách vulnerabilities GET /api/projects/scans/{id}/export Export JSON hoặc CSV # AI Report GET /api/scans/{id}/report Xem báo cáo HTML GET /api/scans/{id}/report?download=true Tải xuống file .html # Vulnerability Management PATCH /api/vulns/{id}/status Đổi trạng thái vuln POST /api/vulns/{id}/waiver Tạo waiver (accept risk) DELETE /api/vulns/{id}/waiver Xóa waiver # Approve & Compare GET /api/projects/{id}/approve-check Kiểm tra approve GET /api/projects/{id}/compare So sánh 2 scans # Settings GET /api/settings/scanners Health check tất cả tools PUT /api/settings/scanners Lưu enable/disable config # Ollama GET /api/ollama/health Kiểm tra Ollama GET /api/ollama/models Danh sách models POST /api/ollama/pull Pull model mới PUT /api/ollama/active-model Đổi model active # Swagger UI: http://localhost:8080/docs ``` ## 🔄 典型工作流 ``` 1. Developer push code lên nhánh mới 2. Security Approver mở VulnGuard → Tạo Project (nếu chưa có) 3. Copy source code vào SCAN_WORKSPACE 4. Trigger Scan → chọn scan types → theo dõi live progress 5. Chờ AI Analysis hoàn tất (tự động sau scan) 6. Review vulnerabilities: ├── CRITICAL/HIGH → ưu tiên fix ├── Đánh dấu False Positive (AI hỗ trợ đánh giá) └── Accept Risk → tạo Waiver (ghi rõ lý do + người duyệt + ngày hết hạn) 7. Tạo Báo Cáo AI → gửi file .html cho dev team fix 8. Dev fix xong → Scan lại → Compare để xác nhận 9. Chạy Approve Check → phải ra "APPROVED" → Deploy ``` ## ⚙️ 配置 (.env) ``` # Port Web UI VULNGUARD_PORT=8080 # Host 机器上的 source code 目录（mount 到 container 内的 /workspace） SCAN_WORKSPACE=/Users/yourname/vulnguard-workspace # Docker socket（macOS Docker Desktop） DOCKER_SOCK=/Users/yourname/.docker/run/docker.sock # Docker socket（Linux） # DOCKER_SOCK=/var/run/docker.sock # Ollama OLLAMA_MODEL=llama3.2 # Model đang dùng (phải đã ollama pull) OLLAMA_TIMEOUT=120 # Timeout AI analysis (giây) # Scan limits MAX_SCANS_PER_PROJECT=5 # Rolling: tự xóa scan cũ nhất BLOCK_SEVERITY_THRESHOLD=HIGH # Block approve nếu còn OPEN >= mức này ``` ## 🔒 安全与隐私 - VulnGuard 和 Ollama **完全在本地运行** —— 不会向外部发送代码或结果 - 无需账户，无需任何 API key - SQLite 数据库存储在 `./storage/db/` —— 可按需自行备份 - Docker socket 挂载仅用于扫描容器镜像 ## 🐛 故障排除 **扫描路径不存在：** ``` Hãy đảm bảo SCAN_WORKSPACE trong .env trỏ đúng thư mục, rồi dùng path /workspace/ trong UI. ``` **AI 分析未运行 / 提示“未连接”：** ``` # 检查 Ollama 是否正在运行 ollama list curl http://localhost:11434/api/tags # 如果尚未运行 ollama serve ``` **更新后重新构建：** ``` docker compose down docker compose build --no-cache docker compose up -d ``` **查看日志：** ``` docker compose logs -f vulnguard ```

标签：AI应用开发, AI风险缓解, DevSecOps, 上游代理, 人工智能分析, 安全漏洞利用, 本地化部署, 请求拦截, 逆向工具