npm audit

npm audit 的運作原理

npm audit 會將專案相依套件的描述傳送到您的預設登錄庫，查詢已知漏洞。它需要 package-lock.json 或 shrinkwrap 檔案，因為它要藉此得知您使用的版本。詳情請參閱 npm 文件。

npm audit                       # report everything
npm audit --omit=dev            # skip dev dependencies
npm audit --audit-level=high    # fail only on high or critical
npm audit --json                # machine-readable output

如何解讀報告

• 嚴重程度來自資安公告。它說明的是這個缺陷一般而言有多嚴重，而不是對您而言有多嚴重。
• 相依路徑顯示是什麼引入了這個套件。大多數發現屬於遞移相依套件，修正通常要從上一層的套件著手。
• 開發用或正式環境用。測試工具中的缺陷不會交付給使用者，但它仍會在您的建置中執行，因此不要完全忽略。

如果清單很長，請先從已遭利用與會交付出去的項目著手。請參閱如何排定漏洞的優先順序。

npm audit fix，以及何時不該強制執行

指令	作用	風險
npm audit fix	在您的版本範圍內套用相容的更新	低。由於它會執行完整安裝，仍請執行測試
npm audit fix --force	也允許範圍外的變更，包括主要版本	高。它可能讓您的應用程式無法運作，npm 也表示，若不清楚自己要什麼，就不要使用它

如果沒有可用的修正，您可以升級上層套件，或使用 overrides 欄位（位於 package.json）強制採用已修補的遞移相依版本。請務必測試，因為上層套件並非針對該版本建置。

在 CI 中執行 npm audit

預設情況下，npm audit 只要發現任何問題就會以非零代碼結束，導致每個低嚴重程度的公告都會讓作業失敗。團隊通常會設定門檻。請注意，--audit-level 只會改變失敗門檻，並不會篩選報告內容。

- run: npm ci
- run: npm audit --omit=dev --audit-level=high

這類檢查也可能在程式碼毫無變更的情況下讓建置失敗，因為前一晚發布了新的公告。啟用之前，請先決定由誰負責處理這類失敗。詳情請參閱該在哪裡執行 SCA 掃描。

npm audit 會遺漏什麼

• npm 以外的一切。您的基礎映像檔、作業系統套件、Python 工具與 GitHub Actions 都不在 package-lock.json 中。
• 安裝期間擷取的程式碼。安裝腳本可以下載任何 lockfile 都不會記錄的檔案。請參閱鎖定檔（lockfile）不會記錄什麼。
• 新出現的惡意套件。它比對的是已發布的公告，因此尚無公告的套件會被判定為沒有問題。
• 已經交付的內容。它只針對眼前的專案回報。去年版本的新公告，只有在有人針對該版本重新執行時才會出現。
• 您是否真的受影響。它不知道您的程式碼是否使用了有漏洞的函式。可達性分析能處理這個問題。

npm audit signatures 是另一個指令，用於驗證您所安裝套件的登錄庫簽章與來源證明（provenance）。它檢查的是套件的來源，而不是套件是否安全。

npm audit 與 CRACI

請繼續在 pull request 上執行 npm audit。它免費，而且能及早抓出已知問題。CRACI 涵蓋它看不到的部分：作為您的 GitHub Actions 執行器，CRACI 會記錄每個作業實際從 npm 及其他所有來源擷取的每個套件，包括從 CI 快取還原的套件，以及安裝 hook 擷取的檔案。接著，隨著新漏洞公布，CRACI 會持續檢查已交付內容的 SBOM。請參閱最佳 SCA 工具或建置時 SBOM 產生。

npm audit：常見問題

npm audit 有什麼作用？

它會將您相依套件的描述傳送到 npm 登錄庫，與已知的資安公告比對，並回報任何有漏洞的套件，包括其嚴重程度，以及它們是如何進入您的專案的。

npm audit fix 安全嗎？

一般的 npm audit fix 通常是安全的，因為它不會超出您的版本範圍，但事後仍請執行測試。npm audit fix --force 可能安裝新的主要版本，導致您的應用程式無法運作。

為什麼 npm audit 會顯示這麼多漏洞？

大多數來自遞移相依套件與開發工具。使用 --omit=dev 聚焦於會交付出去的內容，並依遭利用狀況與暴露程度排定優先順序，而不是看數量。

如何在 npm audit 中忽略某個漏洞？

npm audit 沒有內建的忽略清單。團隊會使用 overrides 欄位變更版本、以 --audit-level 設定門檻，或使用能記錄已接受發現的包裝工具。

npm audit 需要 lockfile 嗎？

需要。預設情況下，它需要 package-lock.json 或 shrinkwrap 檔案。您可以用 --no-package-lock 略過這項要求，但每次執行的結果可能會不同。

npm audit 能偵測惡意軟體嗎？

只有在該套件的公告已發布之後才能。新的惡意套件沒有公告，因此在它出現的當天不會被回報。