xiner/NextEdu
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
2c8e229e0059ee42c75e10629823a88b4c90280a
NextEdu/docs/security/scanning.md
SpecialX 6585e10c6f feat(P2): 实现质量保障类5项功能(无障碍/视觉回归/通知渠道/漏洞扫描/灾备) 
## 新增功能

### 1. 屏幕阅读器兼容性增强（a11y）
- 无障碍工具库：src/shared/lib/a11y.ts
- aria-live Hook：src/shared/hooks/use-aria-live.ts
- a11y 组件：skip-link/visually-hidden/focus-trap/aria-status
- 增强 UI：table.tsx 系统性 ARIA role，dialog.tsx aria-modal
- 审计文档：docs/accessibility/a11y-audit.md（WCAG 2.1 AA 清单）

### 2. 视觉回归测试
- 测试套件：tests/visual/（homepage + 3 个 dashboard）
- 3 视口（desktop/tablet/mobile）× 2 主题（light/dark）
- 动态元素遮罩，避免误报
- playwright.config.ts 新增 visual-chromium 项目
- 文档：docs/testing/visual-regression.md

### 3. 短信/微信推送渠道集成
- 新模块：src/modules/notifications/
- 4 个渠道：SMS（阿里云/腾讯云）、WeChat（公众号）、Email（SMTP）、In-App
- 分发器按用户偏好并行多渠道发送
- 外部 SDK 动态 import，Mock 模式开发可用
- 文档：docs/notifications/channels.md

### 4. 漏洞扫描 CI 集成
- CI security-scan job：npm audit + Snyk + Trivy FS + OWASP ZAP
- 独立工作流 security.yml：每周一深度扫描 + 容器镜像扫描
- 配置：suppressions.json + .trivyignore
- 本地脚本：security-scan.sh/ps1
- 文档：docs/security/scanning.md（SLA 分级）

### 5. 灾备方案
- 脚本：backup-verify/backup-offsite-sync/dr-drill/failover/health-check
- CI 增强：备份后校验+异地同步，每周灾备演练
- 独立工作流 dr-drill.yml：每周一凌晨 4 点自动演练
- 文档：docs/dr/dr-plan.md（RTO 4h/RPO 24h）+ dr-runbook.md（6 故障场景）

## 验证
- npx tsc --noEmit：0 错误
- npm run lint：0 错误 0 警告
2026-06-17 20:18:29 +08:00

153 lines
6.2 KiB
Markdown
Raw Blame History

# 安全扫描指南
本项目集成了多层安全扫描,覆盖依赖审计、深度依赖分析、静态分析、容器镜像扫描与动态应用安全测试(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 脚本
```bash
# 仅依赖审计
npm run security:audit
# 完整本地扫描(npm audit + Trivy fs)
npm run security:scan
```
### 4.2 直接运行脚本
**Linux/macOS:**
```bash
chmod +x scripts/security-scan.sh
./scripts/security-scan.sh
```
**Windows PowerShell:**
```powershell
.\scripts\security-scan.ps1
```
### 4.3 退出码
| 退出码 | 含义 |
|--------|------|
| `0` | 无高危(critical/high)漏洞 |
| `1` | 存在高危漏洞,需尽快处理 |
### 4.4 前置依赖
- **Node.js + npm** — 必需
- **Trivy** — 可选(未安装则跳过文件系统扫描),[安装指南](https://aquasecurity.github.io/trivy/latest/getting-started/installation/)
- **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) |
Reference in New Issue View Git Blame Copy Permalink