npm-audit

套件鎖定

預設情況下，npm 需要 package-lock 或 shrinkwrap 才能執行 audit。您可以使用 --no-package-lock 繞過套件鎖定，但請注意每次執行結果都可能不同，因為 npm 會每次重新建置相依性樹狀結構。

稽核簽章

若要確保您從公開 npm 註冊表或支援簽署的任何註冊表下載的套件的完整性，您可以使用 npm CLI 驗證已下載套件的註冊表簽署。

可以使用下列 audit 指令驗證註冊表簽署

$ npm audit signatures

audit signatures 指令也會驗證已下載套件的來源證明。由於來源證明是一項新功能，安全性功能可能會隨著時間推移而新增到 (或在) 證明格式中變更。若要確保您始終能夠驗證證明簽署，請檢查您執行的是最新版本的 npm CLI。請注意，這通常表示 npm 更新的版本超過隨附 Node.js 的版本。

如果遵循下列慣例，npm CLI 支援任何註冊表提供的註冊表簽署和簽署金鑰

1. 簽署在套件的 packument 中提供，在 dist 物件中的每個已發布版本中

"dist":{
  "..omitted..": "..omitted..",
  "signatures": [{
    "keyid": "SHA256:{{SHA256_PUBLIC_KEY}}",
    "sig": "a312b9c3cb4a1b693e8ebac5ee1ca9cc01f2661c14391917dcb111517f72370809..."
  }]
}

請參閱這個 範例，了解來自公開 npm 註冊表的已簽署套件。

sig 是使用下列範本產生的： ${package.name}@${package.version}:${package.dist.integrity}，而 keyid 必須與下列其中一個公開簽署金鑰相符。

2. 公開簽署金鑰在 registry-host.tld/-/npm/v1/keys 以下列格式提供

{
  "keys": [{
    "expires": null,
    "keyid": "SHA256:{{SHA256_PUBLIC_KEY}}",
    "keytype": "ecdsa-sha2-nistp256",
    "scheme": "ecdsa-sha2-nistp256",
    "key": "{{B64_PUBLIC_KEY}}"
  }]
}

金鑰回應

• expires：null 或簡化的延伸 ISO 8601 格式： YYYY-MM-DDTHH:mm:ss.sssZ
• keydid：公開金鑰的 sha256 指紋
• keytype：目前 npm CLI 僅支援 ecdsa-sha2-nistp256
• scheme：目前 npm CLI 僅支援 ecdsa-sha2-nistp256
• 金鑰：base64 編碼的公開金鑰

參閱這個 公用 npm 註冊表的範例金鑰回應。

稽核端點

npm 可能使用兩個稽核端點來擷取漏洞資訊：大量建議端點和 快速稽核端點。

大量建議端點

從第 7 版開始，npm 使用更快的 大量建議端點來最佳化計算稽核結果的速度。

npm 會產生一個 JSON 酬載，其中包含樹狀結構中每個套件的名稱和版本清單，並將其 POST 到預設設定的註冊表，路徑為 /-/npm/v1/security/advisories/bulk。

樹狀結構中任何在 package.json 檔案中沒有 版本欄位的套件都將被忽略。如果指定任何 --omit 選項（透過 --omit 設定，或其中一個速寫，例如 --production、--only=dev 等），則會適當地從已提交的酬載中省略套件。

如果註冊表以錯誤或無效的回應回應，則 npm 會嘗試從 快速稽核端點載入建議資料。

預期的結果將包含一組建議物件，針對符合建議範圍的每個依賴項。每個建議物件包含 名稱、網址、識別碼、嚴重性、易受攻擊的版本 和 標題。

然後，npm 使用這些建議物件來計算樹狀結構中依賴項的漏洞和元漏洞。

快速稽核端點

如果 大量建議端點傳回錯誤或無效資料，npm 會嘗試從 快速稽核端點載入建議資料，在大多數情況下，這會慢很多。

在 package-lock.json 中找到的完整套件樹狀結構會與下列額外元資料一起提交

• npm_version
• node_version
• platform
• arch
• node_env

樹狀結構中的所有套件都會提交到快速稽核端點。在產生報告時，會略過已省略的依賴項類型。

清除

基於謹慎原則，npm 5 和 6 版本會在提交的報告中「清除」任何包含 / 字元的套件名稱，以避免洩漏潛在私人套件或 git URL 的名稱。

然而，在實際情況中，這導致審核經常無法正確偵測元漏洞，因為樹狀結構會因缺少相依性而顯示為無效，並阻止偵測使用 git 相依性或私人模組的套件樹狀結構中的漏洞。

此清除功能已從 npm 7 版本中移除。

計算元漏洞和補救措施

npm 使用 @npmcli/metavuln-calculator 模組將一組安全性建議轉換為一組「漏洞」物件。一個「元漏洞」是一個相依性，它會因為相依於一個漏洞套件的漏洞版本而變得有漏洞。

例如，如果套件 foo 在範圍 >=1.0.2 <2.0.0 中有漏洞，而套件 bar 相依於 foo@^1.1.0，那麼 bar 的那個版本只能透過安裝 foo 的漏洞版本來安裝。在這種情況下，bar 是「元漏洞」。

一旦計算出特定套件的元漏洞，它們就會快取在 ~/.npm 資料夾中，並且僅在建議範圍變更或套件的新版本發佈時重新評估（在這種情況下，也會檢查新版本是否有元漏洞狀態）。

如果元漏洞鏈一直延伸到根專案，而且無法在不變更其相依性範圍的情況下更新，那麼 npm audit fix 將需要 --force 選項來套用修復。如果修復不需要變更相依性範圍，那麼所有有漏洞的套件都將更新到沒有針對其發佈建議或元漏洞的版本。

結束代碼

如果沒有發現漏洞，npm audit 命令將退出並傳回 0 退出碼。如果沒有發現漏洞或修復能夠成功修復所有漏洞，npm audit fix 命令將退出並傳回 0 退出碼。

如果發現漏洞，退出碼將取決於 audit-level 設定。

範例

掃描專案中的漏洞，並自動安裝任何相容的更新至有漏洞的相依性

$ npm audit fix

執行 audit fix 而不用修改 node_modules，但仍更新 pkglock

$ npm audit fix --package-lock-only

略過更新 devDependencies

$ npm audit fix --only=prod

讓 audit fix 安裝頂層相依項的 SemVer 主要更新，而不仅仅是 SemVer 相容的更新

$ npm audit fix --force

執行乾運行以了解 audit fix 會執行哪些動作，並同時以 JSON 格式輸出安裝資訊

$ npm audit fix --dry-run --json

掃描專案以尋找漏洞，並只顯示詳細資料，而不修復任何問題

$ npm audit

以 JSON 格式取得詳細的稽核報告

$ npm audit --json

只有在結果包含中度或更高層級的漏洞時，稽核才會失敗

$ npm audit --audit-level=moderate

設定

稽核層級

• 預設值：null
• 類型：null、"info"、"low"、"moderate"、"high"、"critical" 或 "none"

讓 npm audit 以非零退出碼結束的漏洞最低層級。

乾運行

• 預設值：false
• 類型：布林值

表示您不希望 npm 進行任何變更，而且它應該只報告它會執行的動作。這可以傳遞給任何會修改您本機安裝的指令，例如 install、update、dedupe、uninstall，以及 pack 和 publish。

注意：其他與網路相關的指令不會遵守這項設定，例如 dist-tags、owner 等。

強制

• 預設值：false
• 類型：布林值

移除針對不幸的副作用、常見錯誤、不必要的效能降低和惡意輸入的各種防護措施。

• 允許在全域安裝中覆寫非 npm 檔案。
• 允許 npm version 指令在不乾淨的 git 儲存庫中運作。
• 允許使用 npm cache clean 刪除快取資料夾。
• 允許安裝具有需要不同版本的 npm 的 engines 宣告的套件。
• 允許安裝具有 engines 宣告，需要不同版本的 node 的套件，即使已啟用 --engine-strict。
• 允許 npm audit fix 安裝超出您所述依賴範圍的模組（包括 SemVer-major 變更）。
• 允許取消發布已發布套件的所有版本。
• 允許在根專案中安裝衝突的 peerDependencies。
• 在 npm init 期間隱含設定 --yes。
• 允許在 npm pkg 中覆寫現有值
• 允許取消發布整個套件（不只單一版本）。

如果您不清楚自己想做什麼，強烈建議您不要使用此選項！

json

• 預設值：false
• 類型：布林值

是否要輸出 JSON 資料，而不是一般輸出。

• 在 npm pkg set 中，它可以在儲存到 package.json 之前，使用 JSON.parse() 來分析設定值。

並非所有 npm 指令都支援。

僅套件鎖定

• 預設值：false
• 類型：布林值

如果設定為 true，目前的作業只會使用 package-lock.json，忽略 node_modules。

對於 update，這表示只會更新 package-lock.json，而不是檢查 node_modules 並下載依賴項。

對於 list，這表示輸出將根據 package-lock.json 所描述的樹狀結構，而不是 node_modules 的內容。

套件鎖定

• 預設值：true
• 類型：布林值

如果設定為 false，則在安裝時忽略 package-lock.json 檔案。如果 save 為 true，這也會阻止寫入 package-lock.json。

省略

• 預設值：如果 NODE_ENV 環境變數設定為 'production'，則為 'dev'，否則為空。
• 類型：「dev」、「optional」或「peer」（可以設定多次）

從磁碟上的安裝樹狀結構中省略的依賴項類型。

請注意，這些依賴項仍會解析並新增到 package-lock.json 或 npm-shrinkwrap.json 檔案中。它們只是不會實際安裝在磁碟上。

如果套件類型同時出現在 --include 和 --omit 清單中，則會包含該類型。

如果產生的遺漏清單包含 'dev'，則會將 NODE_ENV 環境變數設定為 'production'，以適用於所有生命週期指令碼。

包含

• 預設值
• 類型：「prod」、「dev」、「optional」 或 「peer」（可設定多次）

允許定義要安裝的相依性類型的選項。

這是 --omit=<type> 的反向操作。

在 --include 中指定的相依性類型將不會被遺漏，無論在命令列中指定遺漏/包含的順序為何。

前景腳本

• 預設值：false，除非使用 npm pack 或 npm publish，預設值為 true
• 類型：布林值

在前景處理中執行已安裝套件的所有建置指令碼（即 preinstall、install 和 postinstall）指令碼，並與主要 npm 處理共用標準輸入、輸出和錯誤。

請注意，這通常會使安裝執行得更慢，而且會產生更多雜訊，但對於除錯很有用。

忽略腳本

• 預設值：false
• 類型：布林值

如果為 true，npm 就不會執行 package.json 檔案中指定的指令碼。

請注意，明確用於執行特定指令碼的指令，例如 npm start、npm stop、npm restart、npm test 和 npm run-script，如果設定了 ignore-scripts，仍會執行其預期的指令碼，但不會執行任何前置或後置指令碼。

工作區

• 預設值
• 類型：字串（可設定多次）

啟用在當前專案設定的工作空間的內容中執行指令，同時透過僅執行此設定選項所定義的工作空間進行篩選。

workspace 設定的有效值為

• 工作空間名稱
• 工作空間目錄的路徑
• 指向父工作區目錄的路徑（將導致選取該資料夾中的所有工作區）

當設定為 npm init 指令時，這可能會設定為尚不存在的工作區資料夾，以建立資料夾並將其設定為專案中的全新工作區。

此值不會匯出至子程式的環境。

工作區

• 預設值：null
• 類型：null 或布林值

設定為 true 以在所有已設定工作區的內容中執行指令。

明確將此設定為 false 會導致 install 等指令完全忽略工作區。未明確設定時

• 對 node_modules 樹狀結構進行操作的指令（安裝、更新等）會將工作區連結至 node_modules 資料夾。- 對其他事項進行操作的指令（測試、執行、發布等）會在根專案中進行操作，除非在 workspace 設定中指定一個或多個工作區。

此值不會匯出至子程式的環境。

包含工作區根目錄

• 預設值：false
• 類型：布林值

當指令啟用工作區時，包含工作區根目錄。

當為 false 時，透過 workspace 設定指定個別工作區，或透過 workspaces 旗標指定所有工作區，將導致 npm 僅對指定的工作區進行操作，而不對根專案進行操作。

此值不會匯出至子程式的環境。

安裝連結

• 預設值：false
• 類型：布林值

設定時，file: 協定相依項會打包並安裝為一般相依項，而不是建立符號連結。此選項對工作區無影響。

另請參閱

• npm install
• 設定

在 GitHub 上編輯此頁面

5 貢獻者

最後由 emmanuel-ferdman 編輯於 2024 年 4 月 4 日