NextEdu/docs/security/scanning.md

安全扫描指南

本项目集成了多层安全扫描,覆盖依赖审计、深度依赖分析、静态分析、容器镜像扫描与动态应用安全测试(DAST)。

一、CI 中的安全扫描流程

1.1 主 CI 流水线(.gitea/workflows/ci.yml)

主流水线在 push/pull_request 到 main 时触发,包含三个 Job:

Job	触发条件	说明
build-deploy	push/PR to main	构建、测试、部署到 Docker
security-scan	push/PR to main(依赖 build-deploy)	完整安全扫描,失败不阻塞构建
scheduled-backup	schedule cron 0 2 * * *	每天凌晨 2 点数据库备份

security-scan Job 依次执行以下扫描,所有步骤均设置 continue-on-error: true,扫描失败不阻塞构建,但会生成报告并上传为 artifact(security-reports):

1. npm audit — 依赖漏洞审计(moderate 级别),生成 audit-report.json
2. Snyk 扫描 — 深度依赖分析(--severity-threshold=high),生成 snyk.sarif,需配置 SNYK_TOKEN secret
3. Trivy 文件系统扫描 — 扫描项目代码与依赖,生成 trivy-fs-report.json 与表格视图
4. OWASP ZAP 基线扫描 — 对部署后的应用执行 DAST,目标为 NEXTAUTH_URL secret 或 http://localhost:8015

1.2 独立安全工作流(.gitea/workflows/security.yml)

独立工作流执行深度安全扫描,触发方式:

• 定时:每周一凌晨 3 点(cron: "0 3 * * 1")
• 手动:workflow_dispatch,可指定 target_url(DAST 目标)与 skip_dast 选项

执行内容:

步骤	工具	类型	输出
依赖扫描	npm audit	依赖	audit-report.json
深度依赖 + 静态分析	Snyk(--severity-threshold=medium)	依赖 + 代码	snyk.sarif
文件系统扫描	Trivy fs	代码 + 依赖	trivy-fs-report.json
容器镜像扫描	Trivy image	容器	trivy-image-report.json
DAST	OWASP ZAP baseline	动态	控制台报告
汇总报告	shell + jq	汇总	security-summary.md

所有报告上传为 artifact security-reports-full。

二、各扫描工具的作用

工具	作用	覆盖范围
npm audit	Node.js 依赖漏洞审计,基于 npm advisory 数据库	直接与间接 npm 依赖
Snyk	深度依赖分析 + 代码静态分析,漏洞库更广,含许可证检查	npm 依赖 + 源码
Trivy(fs)	文件系统扫描,检测依赖锁文件、IaC 配置、密钥泄露	项目代码、配置、密钥
Trivy(image)	容器镜像扫描,检测镜像层漏洞与配置问题	构建出的 Docker 镜像
OWASP ZAP	动态应用安全测试(DAST),模拟攻击发现运行时漏洞	运行中的 Web 应用

三、如何处理扫描发现的漏洞

3.1 处理流程

1. 查看报告:从 CI artifact 下载 security-reports / security-reports-full
2. 分级评估:按漏洞等级确定处理优先级(见分级标准)
3. 修复或缓解:
   • 升级受影响依赖到修复版本
   • 若无法立即升级,评估是否可接受并记录抑制项
   • 对运行时漏洞,通过 WAF/配置/代码修复
4. 验证:本地运行 npm run security:scan 验证修复效果
5. 记录:更新抑制配置文件,记录处理决策

3.2 抑制配置文件

对于经评估确认可接受的漏洞,通过以下文件抑制:

• .gitea/suppressions.json — Snyk 漏洞抑制,每条需填写 id、package、severity、reason、expires(到期时间)、owner
• .trivyignore — Trivy 忽略的 CVE 列表,每行一个 CVE ID,带注释说明原因

抑制项到期后必须重新评估。suppressions.json 中 policy.reviewCadenceDays: 30 要求每 30 天复审一次。

3.3 必需的 Secrets

Secret	用途	必需性
SNYK_TOKEN	Snyk API 令牌	推荐(无则 Snyk 步骤跳过)
NEXTAUTH_URL	ZAP DAST 扫描目标 URL	可选(默认 localhost:8015)

四、本地扫描方法

4.1 npm 脚本

# 仅依赖审计
npm run security:audit

# 完整本地扫描(npm audit + Trivy fs)
npm run security:scan

4.2 直接运行脚本

Linux/macOS:

chmod +x scripts/security-scan.sh
./scripts/security-scan.sh

Windows PowerShell:

.\scripts\security-scan.ps1

4.3 退出码

退出码	含义
0	无高危(critical/high)漏洞
1	存在高危漏洞,需尽快处理

4.4 前置依赖

• Node.js + npm — 必需
• Trivy — 可选(未安装则跳过文件系统扫描),安装指南
• jq(仅 bash 脚本)— 可选(未安装则显示原始报告)

五、漏洞分级标准

等级	说明	示例
Critical	可被远程利用,导致 RCE、认证绕过、数据完全泄露	远程代码执行、SQL 注入
High	可导致权限提升、敏感数据泄露、服务中断	XSS、认证缺陷、SSRF
Medium	需特定条件触发,影响有限	信息泄露、CSRF
Low	影响极小,通常为信息收集类	版本号泄露、低危 ReDoS

六、修复 SLA(服务等级协议)

漏洞等级	修复时限	处理要求
Critical	24 小时	立即修复或下线受影响服务,发布紧急补丁
High	7 天	优先排期修复,升级依赖或应用补丁
Medium	30 天	纳入迭代计划修复
Low	90 天	评估后决定修复或抑制

超过 SLA 未处理的漏洞需升级至安全负责人,并在 suppressions.json 中记录延期原因。

七、相关文件清单

文件	用途
.gitea/workflows/ci.yml	主 CI 流水线(含 security-scan job)
.gitea/workflows/security.yml	独立深度安全扫描工作流
.gitea/suppressions.json	Snyk 漏洞抑制配置
.trivyignore	Trivy CVE 忽略列表
scripts/security-scan.sh	本地扫描脚本(Linux/macOS)
scripts/security-scan.ps1	本地扫描脚本(Windows)
scripts/audit.sh	依赖审计脚本(Linux/macOS)
scripts/audit.ps1	依赖审计脚本(Windows)