关于安全审计

About security audits

安全审计是对安全漏洞的包依赖的评估。安全审计使你能够发现并修复依赖中可能导致数据丢失、服务中断、未经授权访问敏感信息或其他问题的已知漏洞,从而帮助你保护包的用户。

A security audit is an assessment of package dependencies for security vulnerabilities. Security audits help you protect your package's users by enabling you to find and fix known vulnerabilities in dependencies that could cause data loss, service outages, unauthorized access to sensitive information, or other issues.

使用 npm audit 运行安全审计

Running a security audit with npm audit

注意:npm audit 命令在 npm@6 中可用。要升级,请运行 npm install npm@latest -g

Note: The npm audit command is available in npm@6. To upgrade, run npm install npm@latest -g.

npm audit 命令 将你的包中配置的依赖的描述提交到你的默认注册表,并要求报告已知漏洞。npm audit 检查直接 dependencies、devDependencies、bundledDependencies 和 optionalDependencies,但不检查 peerDependencies。

The npm audit command submits a description of the dependencies configured in your package to your default registry and asks for a report of known vulnerabilities. npm audit checks direct dependencies, devDependencies, bundledDependencies, and optionalDependencies, but does not check peerDependencies.

当你使用 npm install 安装包时,npm audit 会自动运行。你还可以在你的 本地安装的包 上手动运行 npm audit 以对包进行安全审计,并生成依赖漏洞报告,如果可用,建议补丁。

npm audit automatically runs when you install a package with npm install. You can also run npm audit manually on your locally installed packages to conduct a security audit of the package and produce a report of dependency vulnerabilities and, if available, suggested patches.

  1. 在命令行上,输入 cd path/to/your-package-name 并按 Enter 键导航到包目录。

    On the command line, navigate to your package directory by typing cd path/to/your-package-name and pressing Enter.

  2. 确保你的包中包含 package.jsonpackage-lock.json 文件。

    Ensure your package contains package.json and package-lock.json files.

  3. 输入 npm audit 并按 Enter 键。

    Type npm audit and press Enter.

  4. 查看审计报告并运行推荐的命令或在需要时进一步调查。

    Review the audit report and run recommended commands or investigate further if needed.

解决 EAUDITNOPJSONEAUDITNOLOCK 错误

Resolving EAUDITNOPJSON and EAUDITNOLOCK errors

npm audit 要求包有 package.jsonpackage-lock.json 文件。

npm audit requires packages to have package.json and package-lock.json files.

  • 如果出现 EAUDITNOPJSON 错误,请按照“创建 package.json 文件”中的步骤创建 package.json 文件。

    If you get an EAUDITNOPJSON error, create a package.json file by following the steps in "Creating a package.json file".

  • 如果遇到 EAUDITNOLOCK 错误,请确保你的包有 package.json 文件,然后通过运行 npm i --package-lock-only 创建包锁定文件。

    If you get an EAUDITNOLOCK error, make sure your package has a package.json file, then create the package lock file by running npm i --package-lock-only.

审查和处理安全审计报告

Reviewing and acting on the security audit report

运行 npm audit 将生成一份安全漏洞报告,其中包含受影响的包名称、漏洞严重性和描述、路径和其他信息,以及(如果可用)应用补丁来解决漏洞的命令。审计报告中各字段的详细信息,请参见“关于审计报告

Running npm audit will produce a report of security vulnerabilities with the affected package name, vulnerability severity and description, path, and other information, and, if available, commands to apply patches to resolve vulnerabilities. For more information on the fields in the audit report, see "About audit reports"

发现建议更新的安全漏洞

Security vulnerabilities found with suggested updates

如果发现安全漏洞并且有可用更新,你可以:

If security vulnerabilities are found and updates are available, you can either:

  • 运行 npm audit fix 子命令以自动为易受攻击的依赖安装兼容更新。

    Run the npm audit fix subcommand to automatically install compatible updates to vulnerable dependencies.

  • 单独运行推荐的命令以安装易受攻击的依赖的更新。(某些更新可能是破坏性的更改;欲了解更多信息,请参阅“SEMVER 警告”。)

    Run the recommended commands individually to install updates to vulnerable dependencies. (Some updates may be semver-breaking changes; for more information, see "SEMVER warnings".)

Screenshot of command-line audit results with suggested fixes

SEMVER 警告

SEMVER warnings

如果建议的操作是潜在的重大更改(语义版本重大更改),则后面会出现 SEMVER WARNING,显示“SEMVER 警告:建议采取的行动是一项潜在的重大改变”。如果存在漏洞的包更改了其 API,你可能需要对包的代码进行额外的更改。

If the recommended action is a potential breaking change (semantic version major change), it will be followed by a SEMVER WARNING that says "SEMVER WARNING: Recommended action is a potentially breaking change". If the package with the vulnerability has changed its API, you may need to make additional changes to your package's code.

发现需要人工审核的安全漏洞

Security vulnerabilities found requiring manual review

如果发现安全漏洞,但没有可用的补丁,审核报告将提供有关漏洞的信息,以便你进一步调查。

If security vulnerabilities are found, but no patches are available, the audit report will provide information about the vulnerability so you can investigate further.

Screenshot of command-line audit results requiring a manual review

要解决该漏洞,你可以

To address the vulnerability, you can

检查缓解因素

Check for mitigating factors

查看 "更多信息" 字段中的安全公告,了解可能允许你在有限情况下继续使用包含漏洞的包的缓解因素。例如,该漏洞可能仅在代码用于特定操作系统或调用特定函数时存在。

Review the security advisory in the "More info" field for mitigating factors that may allow you to continue using the package with the vulnerability in limited cases. For example, the vulnerability may only exist when the code is used on specific operating systems, or when a specific function is called.

如果存在修复则更新依赖包

Update dependent packages if a fix exists

如果存在修复程序,但依赖于具有漏洞的程序包的程序包尚未更新以包含固定版本,则你可能希望在依赖程序包存储库上打开拉取或合并请求以使用固定版本。

If a fix exists but packages that depend on the package with the vulnerability have not been updated to include the fixed version, you may want to open a pull or merge request on the dependent package repository to use the fixed version.

  1. 要查找必须更新的包,请检查 "路径" 字段以获取存在漏洞的包的位置,然后检查依赖于它的包。例如,如果漏洞的路径是 @package-name > dependent-package > package-with-vulnerability,则需要更新 dependent-package

    To find the package that must be updated, check the "Path" field for the location of the package with the vulnerability, then check for the package that depends on it. For example, if the path to the vulnerability is @package-name > dependent-package > package-with-vulnerability, you will need to update dependent-package.

  2. npm 公共注册表 上,找到依赖包并导航到其存储库。有关查找包的更多信息,请参阅“搜索并选择要下载的包”。

    On the npm public registry, find the dependent package and navigate to its repository. For more information on finding packages, see "Searching for and choosing packages to download".

  3. 在依赖包存储库中,打开拉取或合并请求以将易受攻击的包的版本更新为具有修复的版本。

    In the dependent package repository, open a pull or merge request to update the version of the vulnerable package to a version with a fix.

  4. 合并拉取或合并请求并且包已在 npm 公共注册表 中更新后,请使用 npm update 更新你的包副本。

    Once the pull or merge request is merged and the package has been updated in the npm public registry, update your copy of the package with npm update.

修复漏洞

Fix the vulnerability

如果修复不存在,你可能希望在包存储库的拉取或合并请求中向包维护者建议解决漏洞的更改。

If a fix does not exist, you may want to suggest changes that address the vulnerability to the package maintainer in a pull or merge request on the package repository.

  1. 检查 "路径" 字段以了解漏洞的位置。

    Check the "Path" field for the location of the vulnerability.

  2. npm 公共注册表 上,找到存在漏洞的包。有关查找包的更多信息,请参阅“搜索并选择要下载的包”。

    On the npm public registry, find the package with the vulnerability. For more information on finding packages, see "Searching for and choosing packages to download".

  3. 在包存储库中,打开拉取或合并请求以对包存储库进行修复。

    In the package repository, open a pull or merge request to make the fix on the package repository.

  4. 合并修复并在 npm 公共注册表中更新包后,使用修复更新依赖于包的包副本。

    Once the fix is merged and the package has been updated in the npm public registry, update your copy of the package that depends on the package with the fix.

在包或依赖包问题跟踪器中打开问题

Open an issue in the package or dependent package issue tracker

如果你不想自己修复漏洞或更新依赖包,请在包或依赖包问题跟踪器中打开问题。

If you do not want to fix the vulnerability or update the dependent package yourself, open an issue in the package or dependent package issue tracker.

  1. npm 公共注册表 上找到存在漏洞的包或者需要更新的依赖包。有关查找包的更多信息,请参阅“搜索并选择要下载的包”。

    On the npm public registry, find the package with the vulnerability or the dependent package that needs an update. For more information on finding packages, see "Searching for and choosing packages to download".

  2. 在包或依赖包问题跟踪器中,打开一个问题并包含来自审计报告的信息,包括来自 "更多信息" 字段的漏洞报告。

    In the package or dependent package issue tracker, open an issue and include information from the audit report, including the vulnerability report from the "More info" field.

未发现安全漏洞

No security vulnerabilities found

如果没有发现安全漏洞,这意味着在你的包依赖树中没有找到具有已知漏洞的包。由于咨询数据库可以随时更新,我们建议定期手动运行 npm audit,或者将 npm audit 添加到你的持续集成过程中。

If no security vulnerabilities are found, this means that packages with known vulnerabilities were not found in your package dependency tree. Since the advisory database can be updated at any time, we recommend regularly running npm audit manually, or adding npm audit to your continuous integration process.

Screenshot showing audit report with no vulnerabilities

在安装包时关闭 npm audit

Turning off npm audit on package installation

安装单个包

Installing a single package

要在安装单个包时关闭 npm audit,请使用 --no-audit 标志:

To turn off npm audit when installing a single package, use the --no-audit flag:

npm install example-package-name --no-audit

有关详细信息,请参阅 npm-install 命令

For more information, see the npm-install command.

安装所有包

Installing all packages

要在安装所有包时关闭 npm audit,请在你的用户和全局 npmrc 配置文件中将 audit 设置设置为 false

To turn off npm audit when installing all packages, set the audit setting to false in your user and global npmrc config files:

npm set audit false

有关详细信息,请参阅 npm-config 管理命令npm-config 审计设置

For more information, see the npm-config management command and the npm-config audit setting.

npm 中文网 - 粤ICP备13048890号