xiaoxia-saas/docs/ci/first-security-scan-briefing.md

首次安全扫描简报

仓库: xiaoxia/xiaoxia-saas 扫描时间: 2026-07-13 负责人: 代码审计 Agent 状态: CI 排队中（Runner 环境修复中），gitleaks 下载链路二次优化已提交，待 CI 跑通后获取真实扫描数据

一、概览

工具	优先级	PR	接入状态	CI 验证	扫描结果
gitleaks（密钥检测）	P0	#256	✅ 二次优化提交	🕐 CI 排队中	待验证
pip-audit（Python 依赖漏洞）	P1	#256	✅ 代码已提交	🕐 CI 排队中	待验证
vulture（死代码检测）	P2	#259	✅ 代码已提交	🕐 等待 black 修复 + CI 排队	待验证

二、各工具详情

1. gitleaks 密钥检测（P0）

接入配置

• 位置：validate Job 第 3 步（Verify CI environment 之后）
• PR 模式：增量扫描（--log-opts="origin/base..HEAD"），只扫描改动文件
• Push 模式：全量扫描
• 阻断策略：发现密钥直接阻断合并（exit code 1）
• 白名单：.gitleaks.toml，排除以下路径/内容：
  • .env.example、示例配置文件
  • tests/、docs/、node_modules/、site-packages/
  • 锁定文件（poetry.lock 等）
  • 占位符字符串（your-password、changeme、placeholder 等）

下载问题（第二轮修复已提交）

• 第一轮修复（ghproxy + 99988866 + GitHub 直连）：全部失败
  • mirror.ghproxy.com: 连接超时（7.7s）
  • gh.api.99988866.xyz: SSL 握手失败
  • GitHub 直连: 120s 超时，仅下载 1.6MB/2.9MB
• 第二轮修复（6 个镜像 + go install 降级）：
  • 新增 4 个国内镜像：gh-proxy.com、ghproxy.net、hub.gitmirror.com、ghps.cc
  • 每个镜像重试 2 次，connect-timeout 8s，max-time 90s
  • 增加 go install 源码编译降级方案
  • 全部失败时告警跳过（不阻断 CI），避免阻塞开发流程
• 修复 commit：fix(ci): add more Chinese mirrors for gitleaks download + graceful degradation

长期建议：在 Runner 镜像中预装 gitleaks 二进制，彻底避免下载问题

CI 状态

• 当前状态：大量 CI 任务排队中（9 个 Runner 在线但任务堆积）
• 历史失败 Run #4071（旧 Runner）：gitleaks 下载失败（见上）
• 历史失败 Run #4075（新 Runner）：Job in_progress 但步骤全 queued（新 Runner 执行环境问题）
• 最新 Run #4096：queued 状态，等待执行
• 构建运维 Agent 正在修复：Runner 标签匹配 + 新 Runner 执行环境 + 并发优化

2. pip-audit Python 依赖漏洞扫描（P1）

接入配置

• 位置：validate Job 第 5 步（Install dependencies 之后）
• 扫描范围：requirements.txt、requirements-base.txt、requirements-dev.txt、requirements-worker.txt
• 数据源：OSV（PyPA 官方推荐）
• 阻断策略：告警模式，不阻断 CI
• 计划：运行 1-2 周摸清漏洞存量后，按严重等级设置阻断阈值

CI 状态

• 同 PR #256，因 Runner 卡住暂未执行

3. vulture 死代码检测（P2）

接入配置

• 位置：validate Job，Run security scan (bandit) 之后
• 置信度阈值：80%
• 扫描范围：alembic/、apps/、packages/、scripts/
• 排除：测试文件、迁移文件、文档、node_modules、site-packages
• 白名单：框架自动调用代码
  • FastAPI routes / dependencies / middleware
  • SQLAlchemy models / Pydantic schemas
  • Celery tasks
  • Alembic migration functions
  • CLI scripts / 工具函数
• 阻断策略：告警模式，不阻断 CI

CI 状态

• Workflow Run #4054
• 失败原因：scripts/check_migration_safety.py 不符合 black 格式

  would reformat scripts/check_migration_safety.py
  1 file would be reformatted, 376 files would be left unchanged.
  

• 说明：非 vulture 引入的问题（vulture 步骤还没执行到），是其他 Agent 修改了迁移安全检查脚本但没跑 black 格式化
• 建议：后端开发 Agent 在迁移安全 PR 中同步修复 black 格式问题

三、PR #264（前端清理）安全审查

审查结论：✅ 无安全风险，可合并

审查范围：PR #264 cleanup/phase3-frontend → develop，6 个文件变更（+261/-1359 行）

检查项：

检查项	结果	说明
危险 DOM 操作（innerHTML/eval 等）	✅ 通过	未发现 dangerouslySetInnerHTML、eval、document.write 等
硬编码密钥/Token	✅ 通过	未发现 API Key、Secret、Password 等硬编码
本地存储操作（localStorage 等）	✅ 通过	未新增本地存储操作
开放重定向漏洞	✅ 通过	未新增 window.location / redirect 操作
新增第三方依赖	✅ 通过	仅新增 @ant-design/icons 的 DatabaseOutlined 图标
删除文件安全性	✅ 通过	删除 apps/web/src/api/accounts.ts（Mock API 文件），无安全影响

核心变更性质：

• 删除 Mock 数据（accounts.ts），替换为真实 API 调用或占位
• 清理 Admin.css 冗余样式（-460 行）
• Dashboard / GeneratePage / TitleLibrary 页面 Mock 替换为真实数据调用
• 整体净删除 1098 行，代码量减少，攻击面缩小

四、发现的其他 CI 问题

Runner 环境问题

1. 新服务器 Runner 卡住：xiaoxia-ci-runner-new-2 上的 Job 一直停留在 queued 状态，无法执行步骤
2. Unit Tests 快速失败：Unit Tests Job 18 秒就失败了，可能是环境/依赖问题，非代码问题
3. Integration Tests 快速失败：24 秒失败，同样可能是环境问题

代码质量预存问题

1. scripts/check_migration_safety.py 不符合 black 格式（可能是后端开发刚改动过）

五、下一步计划

1. 等待 CI 环境修复：构建运维修复 Runner 标签匹配 + 执行环境 + 并发配置后，CI 才能正常运行
2. 收集首次扫描数据：CI 跑通后，第一时间整理 gitleaks / pip-audit / vulture 的首次真实扫描结果
3. 根据结果调优白名单：如有误报，及时更新 .gitleaks.toml 和 vulture_whitelist.py
4. 跟进 PR #259 black 格式问题：等待后端开发修复 check_migration_safety.py 后 rebase 验证 vulture
5. 推动 gitleaks 预装：建议在 Runner 镜像中预装 gitleaks，彻底规避下载链路问题
6. 推进 npm audit：前端开发 PR #260 已提交 npm audit，等待 CI 验证
7. PR #264 合并：安全审查通过，CI 跑通后可合并

六、相关文档

• 安全工具接入方案
• 安全工具路线图
• gitleaks 白名单配置
• vulture 配置
• vulture 白名单