From 543a99bf4a2792bbc4dcdee7a24fe7e201717d9c Mon Sep 17 00:00:00 2001 From: Your Name Date: Wed, 27 May 2026 12:31:33 +0800 Subject: [PATCH] docs: add dependency audit risk register --- README.md | 2 ++ SECURITY.md | 3 ++ docs/dependency-risk-register.md | 57 ++++++++++++++++++++++++++++++++ docs/operations.md | 10 ++++++ docs/release-readiness.md | 3 ++ package.json | 2 ++ 6 files changed, 77 insertions(+) create mode 100644 docs/dependency-risk-register.md diff --git a/README.md b/README.md index e4c6e5bb3..ff7e6eeec 100644 --- a/README.md +++ b/README.md @@ -80,6 +80,7 @@ pnpm test:helpers pnpm check:artifacts pnpm check:quality pnpm clean:artifacts +pnpm audit:security pnpm exec tsc --noEmit --pretty false pnpm test pnpm db:migrate @@ -119,6 +120,7 @@ tests/ Playwright e2e and route-level tests - [运维与质量门禁](docs/operations.md) - [系统架构说明](docs/architecture.md) - [发布就绪检查清单](docs/release-readiness.md) +- [依赖风险登记](docs/dependency-risk-register.md) - [安全策略](SECURITY.md) - [贡献指南](CONTRIBUTING.md) - [行为准则](CODE_OF_CONDUCT.md) diff --git a/SECURITY.md b/SECURITY.md index 095a553a8..1ad278a0b 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -43,6 +43,7 @@ Before merging security-sensitive changes, run: ```bash pnpm check:quality +pnpm audit:security ``` For route-level release smoke tests, also run: @@ -54,6 +55,8 @@ SMOKE_BASE_URL=http://127.0.0.1:3001 pnpm smoke:routes If a file starts logging prompts, URLs, provider responses, upload details, OAuth data, or user content, add it to `scripts/check-log-hygiene.mjs` and ensure `pnpm check:logs` passes. +Dependency audit risk is tracked in `docs/dependency-risk-register.md`. Critical/high advisories in runtime dependencies should be remediated or explicitly accepted before production release. + ## Deployment Security Notes - Configure `AUTH_SECRET` and production `AUTH_URL`. diff --git a/docs/dependency-risk-register.md b/docs/dependency-risk-register.md new file mode 100644 index 000000000..18bfaffe9 --- /dev/null +++ b/docs/dependency-risk-register.md @@ -0,0 +1,57 @@ +# yedir-ai Dependency Risk Register + +Last local audit snapshot: 2026-05-27. + +This register tracks dependency security debt that cannot safely be fixed as an incidental change. It exists so commercial delivery and open-source review do not rely on hidden tribal knowledge. + +## Audit Command + +Use the official npm registry for audit checks: + +```bash +pnpm audit:security +pnpm audit:security:json +pnpm --silent audit:security:json > audit-security.json +``` + +The explicit registry is intentional. Some mirrors do not implement the npm audit endpoint, which makes audit fail for infrastructure reasons rather than project reasons. +Use `pnpm --silent audit:security:json` when another script needs machine-readable JSON without pnpm's script header. + +## Current Snapshot + +`pnpm audit --registry=https://registry.npmjs.org --audit-level high --json` currently reports: + +- Critical: 2 advisories. +- High: about 30 advisories. +- Moderate/low advisories also exist but are lower priority for the first remediation pass. + +## Priority Remediation Buckets + +- `next`: multiple high advisories affecting the currently resolved Next.js version. Upgrade Next.js in a dedicated framework update branch and run the full quality gate, route smoke tests, and focused homepage/settings/canvas checks. +- `fast-xml-parser`: critical/high advisories through AWS SDK XML parsing. Prefer upgrading AWS SDK packages or adding a targeted override only after confirming the lockfile resolves to patched `fast-xml-parser`. +- `protobufjs`: critical/high advisories through `@xenova/transformers -> onnxruntime-web -> onnx-proto`. Treat as high priority because code generation and parser dependencies are sensitive. +- `drizzle-orm`: high advisory affecting SQL identifier escaping. Upgrade in a dedicated data-access branch and run route/helper tests plus migration checks. +- `xlsx`: high advisories with no patched version reported by npm audit. Plan a replacement or isolation strategy rather than pretending a patch exists. +- `@vercel/blob` / `undici`: high advisories through the Blob client dependency chain. Upgrade storage dependencies and verify upload/download flows. +- `ultracite` transitive dev tooling chain: advisories in Vite/Rollup/Picomatch/tRPC via lint/test tooling. Keep pinned execution, then upgrade tooling in a separate CI-focused branch. + +## Release Policy + +- Do not add `pnpm audit:security` to `pnpm check:quality` until the critical/high baseline is remediated or a documented exception policy exists. +- New direct dependencies should be checked with `pnpm audit:security` before merging. +- Critical advisories in runtime dependencies should block production release unless they are proven unreachable and documented here. +- High advisories should have either a remediation PR or an explicit risk acceptance note before commercial deployment. + +## Verification After Remediation + +After each dependency remediation batch: + +```bash +pnpm install --frozen-lockfile +pnpm check:quality +pnpm audit:security +AUTH_TRUST_HOST=true PORT=3001 pnpm dev +SMOKE_BASE_URL=http://127.0.0.1:3001 pnpm smoke:routes +``` + +Record the remaining critical/high count in this file until the audit baseline reaches zero or only accepted exceptions remain. diff --git a/docs/operations.md b/docs/operations.md index 7747c3b53..8595cf4af 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -18,6 +18,7 @@ pnpm exec tsc --noEmit --pretty false git diff --check pnpm check:artifacts pnpm clean:artifacts +pnpm audit:security ``` 等价的一键质量门禁： @@ -40,6 +41,15 @@ Playwright workflow 独立运行，避免 e2e 依赖、浏览器安装和 secret Dependabot 每周检查 npm/pnpm 依赖和 GitHub Actions。依赖 PR 仍需按 PR 模板运行 `pnpm check:quality` 和路由烟测，不应自动合并。 +## 依赖安全审计 + +```bash +pnpm audit:security +pnpm audit:security:json +``` + +`pnpm audit:security` 显式使用官方 npm registry，避免镜像源缺少 audit endpoint 导致误失败。当前依赖安全债务记录在 [dependency-risk-register.md](dependency-risk-register.md)。在 critical/high baseline 清零或形成正式例外策略前，不把 audit 纳入 `pnpm check:quality`。 + ## 日志治理 新增或修改已治理文件时不要使用裸 `console.*`。使用： diff --git a/docs/release-readiness.md b/docs/release-readiness.md index 2c2866787..be24be50d 100644 --- a/docs/release-readiness.md +++ b/docs/release-readiness.md @@ -7,6 +7,7 @@ ```bash pnpm install --frozen-lockfile pnpm check:quality +pnpm audit:security AUTH_TRUST_HOST=true PORT=3001 pnpm dev SMOKE_BASE_URL=http://127.0.0.1:3001 pnpm smoke:routes ``` @@ -14,6 +15,7 @@ SMOKE_BASE_URL=http://127.0.0.1:3001 pnpm smoke:routes 预期： - `pnpm check:quality` 通过 lint、日志脱敏门禁、公开交付面品牌治理、CI hygiene、环境变量示例卫生、secret hygiene、package metadata、测试门禁卫生、轻量 helper 回归测试、类型检查、diff hygiene 和 tracked 污染物检查。 +- `pnpm audit:security` 输出已审计；若仍有 critical/high，必须在 [dependency-risk-register.md](dependency-risk-register.md) 中记录 remediation 或风险接受状态。 - `pnpm smoke:routes` 验证 `/` 返回 200。 - `/classic` 和 `/chat/test-id` 重定向到 `/`。 - `/settings` 未登录重定向到 `/login?callbackUrl=%2Fsettings`。 @@ -38,6 +40,7 @@ SMOKE_BASE_URL=http://127.0.0.1:3001 pnpm smoke:routes ## 已知后续专项 - 远端 GitHub Actions 实跑结果需要在 push/PR 后确认。 +- 当前依赖 audit baseline 仍需分批 remediation；详见 [dependency-risk-register.md](dependency-risk-register.md)。 - Enhance、Angle Edit、Prompt Optimizer 等历史接口仍可继续分批纳入日志门禁。 - Canvas/Agent 少数大型历史模块仍可继续领域化拆分，但不阻塞当前交付基线。 - License 以仓库根目录 `LICENSE` 为准；如商业分发策略变化，应单独进行法律审查。 diff --git a/package.json b/package.json index 0133eee3e..2970788ce 100644 --- a/package.json +++ b/package.json @@ -26,6 +26,8 @@ "check:tests": "node scripts/check-test-hygiene.mjs", "test:helpers": "PLAYWRIGHT=True pnpm exec playwright test --config=playwright.helpers.config.ts", "check:quality": "pnpm lint && pnpm check:logs && pnpm check:brand && pnpm check:ci && pnpm check:env && pnpm check:secrets && pnpm check:metadata && pnpm check:tests && pnpm test:helpers && pnpm exec tsc --noEmit --pretty false && git diff --check && pnpm check:artifacts", + "audit:security": "pnpm audit --registry=https://registry.npmjs.org --audit-level high", + "audit:security:json": "pnpm audit --registry=https://registry.npmjs.org --audit-level high --json", "clean:artifacts": "node scripts/clean-local-artifacts.mjs", "smoke:routes": "node scripts/smoke-routes.mjs", "format": "pnpm exec ultracite fix",