Dependency Audit

依赖审计

Evaluating New Dependencies

评估新依赖

Before adding any dependency, run through this evaluation checklist. Every "no" answer is a risk that must be explicitly accepted.

在添加任何依赖前，请完成以下评估清单。每一个“否”的回答都代表一项必须被明确接受的风险。

Evaluation Checklist

评估清单

Maintenance: Last commit within 6 months? Issues responded to? More than one maintainer?
Adoption: More than 1,000 weekly downloads (npm) or equivalent? Used by known projects?
Bundle size: Checked via bundlephobia.com or equivalent? Is tree-shaking supported?
License: Compatible with your project license? (See license matrix below)
Security: No open CVEs? Has a security policy? Publishes signed releases?
API surface: Does it do one thing well, or is it a kitchen-sink package?
Alternatives: Have you checked if the standard library or an existing dep covers this?
Transitive deps: How many transitive dependencies does it pull in?

维护情况：最近6个月内有提交记录？问题得到响应？维护者数量超过1人？
采用度：每周下载量超过1000次（npm或其他包管理器等效数据）？被知名项目使用？
包体积：通过bundlephobia.com或同类工具检查过？支持tree-shaking？
许可证：与项目许可证兼容？（见下方许可证矩阵）
安全性：无公开CVE漏洞？有安全政策？发布签名版本？
API范围：是否专注于单一功能，还是大而全的包？
替代方案：是否检查过标准库或现有依赖是否已覆盖该功能？
传递依赖：会引入多少个传递依赖？

Quick Evaluation Commands

快速评估命令

bash

undefined

bash

undefined

npm — check package info

npm — 查看包信息

npm info <package> --json | jq '{name, version, license, homepage, maintainers}'

Check download stats

查看下载统计

npm info <package> --json | jq '.downloads'

Bundle size (requires bundlephobia API or website)

包体积检查（需使用bundlephobia API或官网）

Visit: https://bundlephobia.com/package/<package>

访问：https://bundlephobia.com/package/<package>

Check for known vulnerabilities before installing

安装前检查已知漏洞

npm audit --dry-run --package-lock-only

Python — check package metadata

Python — 查看包元数据

pip show <package> pip index versions <package>

Rust — check crate info

Rust — 查看crate信息

cargo info <crate>

undefined

cargo info <crate>

undefined

Decision Framework

决策框架

Factor	Accept	Investigate	Reject
Weekly downloads	> 50,000	1,000 - 50,000	< 1,000
Last commit	< 3 months	3 - 12 months	> 12 months
Open issues	< 50 with triage	50 - 200	> 200 untriaged
Maintainers	>= 2	1 active	0 active
Transitive deps	< 5	5 - 20	> 20
Bundle size (JS)	< 10 KB gzipped	10 - 50 KB	> 50 KB (for a single feature)
License	MIT, Apache-2.0, BSD	ISC, MPL-2.0	GPL, AGPL, SSPL, unlicensed

因素	可接受	需调查	拒绝
每周下载量	> 50,000	1,000 - 50,000	< 1,000
最后一次提交	< 3个月	3 - 12个月	> 12个月
未处理问题	< 50个且已分类	50 - 200个	> 200个未分类
维护者数量	>= 2	1名活跃维护者	0名活跃维护者
传递依赖数量	< 5	5 - 20	> 20
JS包体积（压缩后）	< 10 KB	10 - 50 KB	> 50 KB（单一功能包）
许可证	MIT, Apache-2.0, BSD	ISC, MPL-2.0	GPL, AGPL, SSPL, 无许可证

Security Vulnerability Scanning

安全漏洞扫描

npm / Yarn

bash

undefined

bash

undefined

Run audit against known vulnerability databases

针对已知漏洞数据库运行审计

npm audit

Fix automatically where possible

自动修复可修复的漏洞

npm audit fix

Fix with major version bumps (review changes carefully)

修复时允许主版本升级（需仔细审查变更）

npm audit fix --force

Generate machine-readable report

生成机器可读的报告

npm audit --json > audit-report.json

Yarn equivalent

Yarn 等效命令

yarn audit yarn audit --json

undefined

yarn audit yarn audit --json

undefined

pip (Python)

pip（Python）

bash

undefined

bash

undefined

Install safety or pip-audit

安装 safety 或 pip-audit

pip install pip-audit

Run audit

运行审计

pip-audit

Output in JSON

以JSON格式输出

pip-audit --format json --output audit-report.json

Check a requirements file without installing

无需安装即可检查requirements文件

pip-audit -r requirements.txt

undefined

pip-audit -r requirements.txt

undefined

Cargo (Rust)

Cargo（Rust）

bash

undefined

bash

undefined

Install cargo-audit

安装 cargo-audit

cargo install cargo-audit

Run audit

运行审计

cargo audit

Fix where possible

修复可修复的漏洞

cargo audit fix

Generate JSON report

生成JSON报告

cargo audit --json

undefined

cargo audit --json

undefined

Go

bash

undefined

bash

undefined

Built-in vulnerability scanning (Go 1.18+)

内置漏洞扫描（Go 1.18+）

govulncheck ./...

undefined

govulncheck ./...

undefined

CI Integration

CI集成

Run audits on every pull request. Fail the build on critical or high severity findings.

yaml

undefined

在每个拉取请求中运行审计。若发现严重或高危漏洞，终止构建。

yaml

undefined

GitHub Actions example

GitHub Actions 示例

name: Security audit run: | npm audit --audit-level=high if [ $? -ne 0 ]; then echo "::error::Security vulnerabilities found" exit 1 fi

---

name: Security audit run: | npm audit --audit-level=high if [ $? -ne 0 ]; then echo "::error::Security vulnerabilities found" exit 1 fi

---

Automated Dependency Updates

自动依赖更新

Dependabot Configuration

Dependabot 配置

yaml

undefined

yaml

undefined

.github/dependabot.yml

version: 2 updates:

package-ecosystem: "npm" directory: "/" schedule: interval: "weekly" day: "monday" time: "09:00" timezone: "America/New_York" open-pull-requests-limit: 10 reviewers:
- "team-platform" labels:
- "dependencies"
- "automated"
Group minor and patch updates to reduce PR noise

groups: production-deps: patterns: - "*" update-types: - "minor" - "patch" dev-deps: dependency-type: "development" update-types: - "minor" - "patch"

Ignore major version bumps for specific packages

ignore:
- dependency-name: "aws-sdk" update-types: ["version-update:semver-major"]
package-ecosystem: "github-actions" directory: "/" schedule: interval: "weekly"
package-ecosystem: "docker" directory: "/" schedule: interval: "weekly"

undefined

version: 2 updates:

package-ecosystem: "npm" directory: "/" schedule: interval: "weekly" day: "monday" time: "09:00" timezone: "America/New_York" open-pull-requests-limit: 10 reviewers:
- "team-platform" labels:
- "dependencies"
- "automated"
分组次要和补丁版本更新以减少PR数量

groups: production-deps: patterns: - "*" update-types: - "minor" - "patch" dev-deps: dependency-type: "development" update-types: - "minor" - "patch"

忽略特定包的主版本升级

ignore:
- dependency-name: "aws-sdk" update-types: ["version-update:semver-major"]
package-ecosystem: "github-actions" directory: "/" schedule: interval: "weekly"
package-ecosystem: "docker" directory: "/" schedule: interval: "weekly"

undefined

Renovate Configuration

Renovate 配置

json

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": [
    "config:recommended",
    ":semanticCommits",
    "group:monorepos",
    "group:recommended"
  ],
  "schedule": ["before 9am on monday"],
  "prConcurrentLimit": 10,
  "labels": ["dependencies", "automated"],
  "packageRules": [
    {
      "matchUpdateTypes": ["minor", "patch"],
      "matchCurrentVersion": "!/^0/",
      "automerge": true,
      "automergeType": "pr",
      "platformAutomerge": true
    },
    {
      "matchUpdateTypes": ["major"],
      "labels": ["dependencies", "breaking-change"],
      "automerge": false
    },
    {
      "matchPackagePatterns": ["eslint", "prettier", "@types/*"],
      "groupName": "linting and types",
      "automerge": true
    },
    {
      "matchDepTypes": ["devDependencies"],
      "matchUpdateTypes": ["minor", "patch"],
      "automerge": true
    }
  ],
  "vulnerabilityAlerts": {
    "enabled": true,
    "labels": ["security"],
    "prPriority": 10
  }
}

json

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": [
    "config:recommended",
    ":semanticCommits",
    "group:monorepos",
    "group:recommended"
  ],
  "schedule": ["before 9am on monday"],
  "prConcurrentLimit": 10,
  "labels": ["dependencies", "automated"],
  "packageRules": [
    {
      "matchUpdateTypes": ["minor", "patch"],
      "matchCurrentVersion": "!/^0/",
      "automerge": true,
      "automergeType": "pr",
      "platformAutomerge": true
    },
    {
      "matchUpdateTypes": ["major"],
      "labels": ["dependencies", "breaking-change"],
      "automerge": false
    },
    {
      "matchPackagePatterns": ["eslint", "prettier", "@types/*"],
      "groupName": "linting and types",
      "automerge": true
    },
    {
      "matchDepTypes": ["devDependencies"],
      "matchUpdateTypes": ["minor", "patch"],
      "automerge": true
    }
  ],
  "vulnerabilityAlerts": {
    "enabled": true,
    "labels": ["security"],
    "prPriority": 10
  }
}

Update Strategy

更新策略

Update Type	Strategy	Review Required
Patch	Auto-merge if tests pass	No
Minor	Auto-merge for stable deps (>= 1.0.0)	Spot-check
Major	Manual review, check migration guide	Yes
Security	Prioritize, merge within 24-48 hours	Yes

更新类型	策略	是否需要审核
补丁版本	测试通过则自动合并	否
次要版本	稳定依赖（>=1.0.0）自动合并	抽查
主版本	手动审核，查看迁移指南	是
安全更新	优先处理，24-48小时内合并	是

Lock File Hygiene

锁文件规范

Rules

规则

Always commit lock files (

package-lock.json

,

yarn.lock

,

Pipfile.lock

,

Cargo.lock

,

go.sum

)

Never manually edit lock files — use the package manager commands
Review lock file diffs in PRs — large unexplained changes may indicate supply chain issues
Use exact versions in lock files — never delete and regenerate without reason
One lock file per project — do not mix npm and yarn in the same project

始终提交锁文件（

package-lock.json

,

yarn.lock

,

Pipfile.lock

,

Cargo.lock

,

go.sum

）

切勿手动编辑锁文件 — 使用包管理器命令进行修改
审查PR中的锁文件差异 — 无解释的大量变更可能表明供应链问题
锁文件使用精确版本 — 除非有合理理由，否则不要删除并重新生成
每个项目仅使用一种锁文件 — 不要在同一项目中混合使用npm和yarn

Resolving Lock File Conflicts

解决锁文件冲突

bash

undefined

bash

undefined

npm — regenerate from package.json

npm — 从package.json重新生成

rm package-lock.json npm install

Yarn — regenerate

Yarn — 重新生成

rm yarn.lock yarn install

After resolving, verify nothing unexpected changed

解决冲突后，验证无意外变更

git diff package-lock.json | head -100

undefined

git diff package-lock.json | head -100

undefined

Integrity Verification

完整性验证

bash

undefined

bash

undefined

npm — verify installed packages match lock file

npm — 验证已安装包与锁文件匹配

npm ci # Clean install from lock file (CI environments)

npm ci # 从锁文件执行干净安装（CI环境适用）

Yarn — same concept

Yarn — 类似功能

yarn install --frozen-lockfile

pip — verify hashes

pip — 验证哈希

pip install --require-hashes -r requirements.txt

---

pip install --require-hashes -r requirements.txt

---

License Compatibility Matrix

许可证兼容性矩阵

Common License Compatibility

常见许可证兼容性

Dependency License	MIT Project	Apache-2.0 Project	GPL-3.0 Project	Proprietary Project
MIT	OK	OK	OK	OK
Apache-2.0	OK	OK	OK (GPL-3+ only)	OK
BSD-2/3-Clause	OK	OK	OK	OK
ISC	OK	OK	OK	OK
MPL-2.0	OK	OK	OK	OK (file-level)
LGPL-2.1/3.0	OK	OK	OK	OK (dynamic linking)
GPL-2.0	NO	NO	OK (same version)	NO
GPL-3.0	NO	NO	OK	NO
AGPL-3.0	NO	NO	NO (unless AGPL)	NO
SSPL	NO	NO	NO	NO
Unlicensed	NO	NO	NO	NO

依赖许可证	MIT项目	Apache-2.0项目	GPL-3.0项目	专有项目
MIT	兼容	兼容	兼容	兼容
Apache-2.0	兼容	兼容	兼容（仅GPL-3+）	兼容
BSD-2/3-Clause	兼容	兼容	兼容	兼容
ISC	兼容	兼容	兼容	兼容
MPL-2.0	兼容	兼容	兼容	兼容（文件级）
LGPL-2.1/3.0	兼容	兼容	兼容	兼容（动态链接）
GPL-2.0	不兼容	不兼容	兼容（同版本）	不兼容
GPL-3.0	不兼容	不兼容	兼容	不兼容
AGPL-3.0	不兼容	不兼容	不兼容（除非使用AGPL）	不兼容
SSPL	不兼容	不兼容	不兼容	不兼容
无许可证	不兼容	不兼容	不兼容	不兼容

License Scanning

许可证扫描

bash

undefined

bash

undefined

npm — check all dependency licenses

npm — 检查所有依赖的许可证

npx license-checker --summary npx license-checker --failOn "GPL-2.0;GPL-3.0;AGPL-3.0" npx license-checker --production --csv > licenses.csv

Python

pip install pip-licenses pip-licenses --format=table pip-licenses --fail-on="GPL-3.0;AGPL-3.0"

Rust

cargo install cargo-license cargo license

undefined

cargo install cargo-license cargo license

undefined

License Policy

许可证政策

Maintain an approved license allow-list in CI
Flag any new dependency with an unapproved license as a blocking issue
When in doubt, consult legal before merging

在CI中维护已批准的许可证白名单
将任何使用未批准许可证的新依赖标记为阻塞问题
“无许可证”意味着“保留所有权利” — 切勿使用无许可证代码
如有疑问，合并前咨询法务人员

Vendoring vs Package Management

依赖 vendoring vs 包管理

When to Vendor

何时使用Vendoring

The dependency is abandoned but you need it
You need to patch a critical bug upstream has not fixed
You are building for an air-gapped environment
The dependency is very small (< 100 lines) and unlikely to change

依赖已被弃用但你仍需使用
你需要修复上游未解决的关键bug
你正在为离线环境构建项目
依赖非常小（少于100行代码）且不太可能变更

When NOT to Vendor

何时不使用Vendoring

The dependency is actively maintained
Security patches are regularly published
The dependency has its own complex dependency tree
You would be taking on maintenance burden you cannot sustain

依赖仍在积极维护
定期发布安全补丁
依赖自身有复杂的依赖树
你无法承担维护该依赖的负担

Vendoring Procedure

Vendoring 流程

Copy the source into a
```
vendor/
```
or
```
third_party/
```
directory
Record the original source, version, and license in a
```
VENDORED.md
```
file
Apply your patches as separate, clearly commented commits
Set a calendar reminder to check for upstream updates quarterly

将源代码复制到
```
vendor/
```
或
```
third_party/
```
目录
在
```
VENDORED.md
```
文件中记录原始来源、版本和许可证
将你的补丁作为单独的、注释清晰的提交
设置日历提醒，每季度检查上游更新

Monorepo Dependency Management

单体仓库（Monorepo）依赖管理

Hoisting Strategy

提升策略

bash

undefined

bash

undefined

npm workspaces — hoist shared deps to root

npm workspaces — 将共享依赖提升到根目录

npm install <package> -w packages/shared

Yarn workspaces — nohoist for packages that need isolation

Yarn workspaces — 为需要隔离的包设置nohoist

package.json

{ "workspaces": { "packages": ["packages/*"], "nohoist": ["/react-native", "/react-native/**"] } }

undefined

{ "workspaces": { "packages": ["packages/*"], "nohoist": ["/react-native", "/react-native/**"] } }

undefined

Monorepo Rules

单体仓库规则

Shared dependencies go in the root
```
package.json
```
Package-specific dependencies go in that package's
```
package.json
```
Version consistency — all packages should use the same version of shared deps
Use a tool like
```
syncpack
```
or
```
manypkg
```
to enforce version consistency

bash

undefined

共享依赖 放在根目录的
```
package.json
```
中
包专属依赖 放在对应包的
```
package.json
```
中
版本一致性 — 所有包应使用相同版本的共享依赖
使用工具 如
```
syncpack
```
或
```
manypkg
```
来强制版本一致性

bash

undefined

Check for version mismatches across packages

检查跨包的版本不匹配

npx syncpack list-mismatches

Fix version mismatches

修复版本不匹配

npx syncpack fix-mismatches

---

npx syncpack fix-mismatches

---

Vulnerability Response Procedure

漏洞响应流程

Severity Classification

严重程度分类

Severity	CVSS Score	Response Time	Example
Critical	9.0-10.0	4 hours	Remote code execution, auth bypass
High	7.0-8.9	24 hours	SQL injection, privilege escalation
Medium	4.0-6.9	1 week	XSS in admin panel, info disclosure
Low	0.1-3.9	Next sprint	Minor info leak, DoS requiring auth

严重程度	CVSS分数	响应时间	示例
关键	9.0-10.0	4小时	远程代码执行、身份验证绕过
高	7.0-8.9	24小时	SQL注入、权限提升
中	4.0-6.9	1周	管理面板XSS、信息泄露
低	0.1-3.9	下一个迭代	轻微信息泄露、需身份验证的拒绝服务

Response Steps

响应步骤

Assess: Determine if your usage of the dependency triggers the vulnerability
Mitigate: Apply a workaround if a patch is not immediately available
Patch: Update to a fixed version as soon as one is available
Verify: Confirm the vulnerability is resolved with scanning tools
Document: Record the vulnerability, your response, and timeline in an incident log

评估：确定你对该依赖的使用是否会触发漏洞
缓解：如果补丁尚未发布，应用临时解决方案
修复：一旦有修复版本，立即更新
验证：使用扫描工具确认漏洞已解决
记录：在事件日志中记录漏洞、你的响应及时间线

Assessment Template

评估模板

markdown

undefined

markdown

undefined

Vulnerability Assessment: CVE-YYYY-XXXXX

漏洞评估：CVE-YYYY-XXXXX

Package: example-lib Installed Version: 2.3.1 Fixed Version: 2.3.2 Severity: High (CVSS 8.1)

包：example-lib 已安装版本：2.3.1 修复版本：2.3.2 严重程度：高（CVSS 8.1）

Are We Affected?

我们是否受影响？

[ ] We use the affected function/feature [ ] The vulnerable code path is reachable in our application [ ] External input reaches the vulnerable code

[ ] 我们使用了受影响的功能/函数 [ ] 应用中可到达漏洞代码路径 [ ] 外部输入可到达漏洞代码

Mitigation

缓解措施

Describe workaround if patch is not yet available

描述补丁发布前的临时解决方案

Action

行动项

Dependency Hygiene Checklist (Periodic Review)

依赖规范清单（定期审查）

Run this checklist quarterly or when onboarding a new team member.

Run
```
npm audit
```
/
```
pip-audit
```
/
```
cargo audit
```
— zero critical or high findings
Remove unused dependencies (
```
npx depcheck
```
,
```
pip-extra-reqs
```
)
Verify all lock files are committed and up to date
Check for deprecated packages (
```
npm outdated
```
)
Review license compliance report — no unapproved licenses
Confirm Dependabot or Renovate is running and PRs are being merged
Review vendored dependencies for upstream updates
Verify CI fails on audit findings above your threshold
Document any accepted risks with justification and expiration date

每季度或新团队成员入职时运行此清单。

运行
```
npm audit
```
/
```
pip-audit
```
/
```
cargo audit
```
— 无关键或高危漏洞
移除未使用的依赖（
```
npx depcheck
```
,
```
pip-extra-reqs
```
）
验证所有锁文件已提交且为最新版本
检查已弃用的包（
```
npm outdated
```
）
审查许可证合规报告 — 无不批准的许可证
确认Dependabot或Renovate正在运行且PR已被合并
审查vendored依赖的上游更新
验证CI在发现超过阈值的审计结果时会终止构建
记录所有已接受的风险，包括理由和到期日期

dependency-audit

Original

Translation

Dependency Audit

依赖审计

Evaluating New Dependencies

评估新依赖

Evaluation Checklist

评估清单

Quick Evaluation Commands

快速评估命令

npm — check package info

npm — 查看包信息

Check download stats

查看下载统计

Bundle size (requires bundlephobia API or website)

包体积检查（需使用bundlephobia API或官网）

Visit: https://bundlephobia.com/package/<package>

访问：https://bundlephobia.com/package/<package>

Check for known vulnerabilities before installing

安装前检查已知漏洞

Python — check package metadata

Python — 查看包元数据

Rust — check crate info

Rust — 查看crate信息

Decision Framework

决策框架

Security Vulnerability Scanning

安全漏洞扫描

npm / Yarn

npm / Yarn

Run audit against known vulnerability databases

针对已知漏洞数据库运行审计

Fix automatically where possible

自动修复可修复的漏洞

Fix with major version bumps (review changes carefully)

修复时允许主版本升级（需仔细审查变更）

Generate machine-readable report

生成机器可读的报告

Yarn equivalent

Yarn 等效命令

pip (Python)

pip（Python）

Install safety or pip-audit

安装 safety 或 pip-audit

Run audit

运行审计

Output in JSON

以JSON格式输出

Check a requirements file without installing

无需安装即可检查requirements文件

Cargo (Rust)

Cargo（Rust）

Install cargo-audit

安装 cargo-audit

Run audit

运行审计

Fix where possible

修复可修复的漏洞

Generate JSON report

生成JSON报告

Go

Go

Built-in vulnerability scanning (Go 1.18+)

内置漏洞扫描（Go 1.18+）

CI Integration

CI集成

GitHub Actions example

GitHub Actions 示例

Automated Dependency Updates

自动依赖更新

Dependabot Configuration

Dependabot 配置

.github/dependabot.yml

.github/dependabot.yml

Group minor and patch updates to reduce PR noise

Ignore major version bumps for specific packages

分组次要和补丁版本更新以减少PR数量

忽略特定包的主版本升级

Renovate Configuration