本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 Amazon Inspector Jenkins 外掛程式
Jenkins 外掛程式利用 [Amazon Inspector SBOM 產生器](https://docs.aws.amazon.com/inspector/latest/user/sbom-generator.html#sbomgen-supported)二進位和 Amazon Inspector Scan API 在建置結束時產生詳細報告，因此您可以在部署之前調查和修復風險。使用 Amazon Inspector Jenkins外掛程式，您可以將 Amazon Inspector 漏洞掃描新增至Jenkins管道。Amazon Inspector 漏洞掃描可以設定為根據偵測到的漏洞數量和嚴重性來傳遞或失敗管道執行。您可以在 Jenkins https：//[https://plugins.jenkins.io/amazon-inspector-image-scanner/](https://plugins.jenkins.io/amazon-inspector-image-scanner/) 市集中檢視最新版本的Jenkins外掛程式。下列步驟說明如何設定 Amazon Inspector Jenkins 外掛程式。
**重要**
在完成下列步驟之前，您必須將 Jenkins 升級至 2.387.3 版或更新版本，外掛程式才能執行。
## 步驟 1. 設定 AWS 帳戶
AWS 帳戶 使用允許存取 Amazon Inspector Scan API 的 IAM 角色來設定 。如需說明，請參閱[設定 AWS 帳戶以使用 Amazon Inspector CI/CD 整合](configure-cicd-account.md)。
## 步驟 2. 安裝 Amazon Inspector Jenkins 外掛程式
下列程序說明如何從Jenkins儀表板安裝 Amazon Inspector Jenkins 外掛程式。
1. 從 Jenkins 儀表板中，選擇**管理 Jenkins**，然後選擇**管理外掛程式**。
1. 選擇**可用**。
1. 從**可用**索引標籤中，搜尋 **Amazon Inspector Scans**，然後安裝外掛程式。
## (選用) 步驟 3. 將 docker 登入資料新增至 Jenkins
**注意**
只有在 Docker 映像位於私有儲存庫中時，才新增 Docker 登入資料。否則，請跳過這個步驟。
下列程序說明如何Jenkins從Jenkins儀表板將 docker 登入資料新增至 。
1. 從 Jenkins 儀表板中，選擇**管理 Jenkins**、**登入**資料，然後選擇**系統**。
1. 選擇**全域登入**資料，然後選擇**新增登入資料**。
1. 針對 **Kind**，選取**使用者名稱與密碼**。
1. 針對**範圍**，選取**全域 (Jenkins、節點、項目、所有子項目等）**。
1. 輸入您的詳細資訊，然後選擇**確定**。
## （選用） 步驟 4。新增 AWS 登入資料
**注意**
只有在您想要根據 IAM 使用者進行身分驗證時，才新增 AWS 登入資料。否則，請跳過這個步驟。
下列程序說明如何從Jenkins儀表板新增 AWS 登入資料。
1. 從 Jenkins 儀表板中，選擇**管理 Jenkins**、**登入**資料，然後選擇**系統**。
1. 選擇**全域登入資料**，然後選擇**新增登入資料**。
1. 針對 **Kind**，選取 **AWS 登入**資料。
1. 輸入您的詳細資訊，包括您的**存取金鑰 ID** 和**私密存取金鑰**，然後選擇**確定**。
## 步驟 5. 在Jenkins指令碼中新增 CSS 支援
下列程序說明如何在Jenkins指令碼中新增 CSS 支援。
1. 重新啟動 Jenkins。
1. 從儀表板中，選擇**管理 Jenkins**、**節點**、**內建節點**，然後選擇**指令碼主控台**。
1. 在文字方塊中，新增行 `System.setProperty("hudson.model.DirectoryBrowserSupport.CSP", "")`，然後選擇**執行**。
## 步驟 6. 將 Amazon Inspector Scan 新增至您的建置
您可以在專案中新增建置步驟或使用宣告管道，將 Amazon Inspector Scan Jenkins 新增至您的建置。
### 在專案中新增建置步驟，將 Amazon Inspector Scan 掃描到您的建置
1. 在組態頁面上，向下捲動至**建置步驟**，然後選擇**新增建置步驟**。然後選取 **Amazon Inspector Scan**。
1. 選擇兩種 inspector-sbomgen 安裝方法：**自動**或**手動**。自動選項允許外掛程式下載最新版本。它還確保您始終擁有最新的功能、安全性更新和錯誤修正。
1. （選項 1) 選擇**自動**下載最新版本的 inspector-sbomgen。此選項會自動偵測目前正在使用的作業系統和 CPU 架構。
1. （選項 2) 如果您想要設定用於掃描的 Amazon Inspector SBOM 產生器二進位檔，請選擇**手動**。如果您選擇此方法，請務必提供先前下載的 inspector-sbomgen 版本的完整路徑。
如需詳細資訊，請參閱在 [Amazon Inspector SBOM 產生器中安裝 Amazon Inspector SBOM 產生器 (Sbomgen)](https://docs.aws.amazon.com/inspector/latest/user/sbom-generator.html#install-sbomgen)。 [Amazon Inspector ](https://docs.aws.amazon.com/inspector/latest/user/sbom-generator.html)
1. 完成以下操作以完成設定 Amazon Inspector Scan 建置步驟：
1. 輸入您的**映像 ID**。映像可以是本機、遠端或封存。影像名稱應遵循Docker命名慣例。如果分析匯出的影像，請提供預期 tar 檔案的路徑。請參閱下列範例影像 ID 路徑：
1. 對於本機或遠端容器： `NAME[:TAG|@DIGEST]`
1. 對於 tar 檔案： `/path/to/image.tar`
1. 選取要**AWS 區域**傳送掃描請求的 。
1. （選用） 針對**報告成品名稱**，輸入建置程序期間產生的成品自訂名稱。這有助於唯一識別和管理它們。
1. （選用） 對於**略過檔案**，指定您要從掃描中排除的一或多個目錄。對於因為大小而不需要掃描的目錄，請考慮此選項。
1. （選用） 針對 **Docker 登入**資料，選取您的Docker使用者名稱。只有當您的容器映像位於私有儲存庫時，才執行此操作。
1. （選用） 您可以提供下列支援的 AWS 身分驗證方法：
1. （選用） 對於 **IAM 角色**，請提供角色 ARN (arn：aws：iam：：*AccountNumber*：role/*RoleName*)。
1. （選用） 對於 **AWS 登入**資料，請指定要根據 IAM 使用者進行驗證的 AWS 登入資料。
1. （選用） 對於**AWS 設定檔名稱**，請提供要使用設定檔名稱進行驗證的設定檔名稱。
1. （選用） 選取**啟用漏洞閾值**。使用此選項，您可以判斷如果掃描的漏洞超過值，建置是否失敗。如果所有值都等於 `0`，則無論掃描多少個漏洞，組建都會成功。對於 EPSS 分數，值可以是 0 到 1。如果掃描的漏洞超過值，組建會失敗，且 EPSS 分數高於該值的所有 CVEs會顯示在主控台中。
1. 選擇**儲存**。
### 使用宣告管道將 Amazon Inspector Scan Jenkins 新增至您的建置
您可以使用 Jenkins 宣告管道自動或手動將 Amazon Inspector Scan 新增至您的建置。
**自動下載 SBOMGen 宣告管道**
+ 若要將 Amazon Inspector Scan 新增至組建，請使用下列範例語法。將 *IMAGE\$1PATH* 取代為映像的路徑 （例如 *alpine：latest*)、將 *IAM\$1ROLE* 取代為您在步驟 1 中設定的 IAM 角色的 ARN，以及將 *ID* 取代為登入Docker資料 ID。您可以選擇性地啟用漏洞閾值，並為每個嚴重性指定值。
```
pipeline {
agent any
stages {
stage('amazon-inspector-image-scanner') {
steps {
script {
step([
$class: 'com.amazon.inspector.jenkins.amazoninspectorbuildstep.AmazonInspectorBuilder',
archivePath: 'IMAGE_PATH', // Path to your container image or tar file
awsRegion: 'REGION', // AWS region for scan requests
iamRole: 'IAM ROLE', // IAM role ARN for authentication
credentialId: 'Id', // Docker credentials (empty if public repo)
awsCredentialId: 'AWS ID', // AWS credential ID for authentication
awsProfileName: 'Profile Name', // AWS profile name to use
sbomgenSkipFiles: '*.log,node_modules,/tmp/*', // Files/directories to exclude from scanning
// Vulnerability threshold settings (updated parameter names)
isSeverityThresholdEnabled: false, // Enable/disable build failure on vulnerability count
countCritical: 0, // Max critical vulnerabilities before build fails
countHigh: 0, // Max high vulnerabilities before build fails
countMedium: 5, // Max medium vulnerabilities before build fails
countLow: 10, // Max low vulnerabilities before build fails
// EPSS (Exploit Prediction Scoring System) settings
isEpssThresholdEnabled: false, // Enable/disable EPSS-based failure threshold
epssThreshold: 0.7, // EPSS score threshold (0.0 to 1.0)
// NEW FEATURE: CVE Suppression - ignore specific false positives
isSuppressedCveEnabled: false, // Enable CVE suppression feature
suppressedCveList: '', // Comma-separated list of CVEs to ignore in thresholds
// NEW FEATURE: Auto-Fail CVEs - always fail on critical security issues
isAutoFailCveEnabled: false, // Enable auto-fail CVE feature
autoFailCveList: '' // Comma-separated list of CVEs that always fail build
])
}
}
}
}
```
**手動下載 SBOMGen 宣告管道**
+ 若要將 Amazon Inspector Scan 新增至組建，請使用下列範例語法。將 *SBOMGEN\$1PATH* 取代為您在步驟 3 中安裝的 Amazon Inspector SBOM 產生器路徑、將 *IMAGE\$1PATH* 取代為您映像的路徑 （例如 *alpine：latest*)、將 *IAM\$1ROLE* 取代為您在步驟 1 中設定之 IAM 角色的 ARN，並將 *ID* 取代為您使用私有儲存庫的Docker憑證 ID。您可以選擇性地啟用漏洞閾值，並為每個嚴重性指定值。
**注意**
將 Sbomgen放置在 Jenkins 目錄中，並提供外掛程式中 Jenkins 目錄的路徑 （例如 */opt/folder/arm64/inspector-sbomgen*)。
```
pipeline {
agent any
stages {
stage('amazon-inspector-image-scanner') {
steps {
script {
step([
$class: 'com.amazon.inspector.jenkins.amazoninspectorbuildstep.AmazonInspectorBuilder',
archivePath: 'IMAGE_PATH', // Path to your container image or tar file
awsRegion: 'REGION', // AWS region for scan requests
iamRole: 'IAM ROLE', // IAM role ARN for authentication
credentialId: 'Id', // Docker credentials (empty if public repo)
awsCredentialId: 'AWS ID', // AWS credential ID for authentication
awsProfileName: 'Profile Name', // AWS profile name to use
sbomgenSkipFiles: '*.log,node_modules,/tmp/*', // Files/directories to exclude from scanning
// Vulnerability threshold settings (updated parameter names)
isSeverityThresholdEnabled: false, // Enable/disable build failure on vulnerability count
countCritical: 0, // Max critical vulnerabilities before build fails
countHigh: 0, // Max high vulnerabilities before build fails
countMedium: 5, // Max medium vulnerabilities before build fails
countLow: 10, // Max low vulnerabilities before build fails
// EPSS (Exploit Prediction Scoring System) settings
isEpssThresholdEnabled: false, // Enable/disable EPSS-based failure threshold
epssThreshold: 0.7, // EPSS score threshold (0.0 to 1.0)
// NEW FEATURE: CVE Suppression - ignore specific false positives
isSuppressedCveEnabled: false, // Enable CVE suppression feature
suppressedCveList: '', // Comma-separated list of CVEs to ignore in thresholds
// NEW FEATURE: Auto-Fail CVEs - always fail on critical security issues
isAutoFailCveEnabled: false, // Enable auto-fail CVE feature
autoFailCveList: '' // Comma-separated list of CVEs that always fail build
])
}
}
}
}
```
外掛程式包含管理安全漏洞的功能。
**隱藏的 CVE 清單**
掃描偶爾可以偵測非實際威脅的漏洞。若要防止這些誤報停止您的建置，您可以將它們新增至*隱藏*的清單。
```
isSuppressedCveEnabled: true,
suppressedCveList: 'CVE-2023-1234,CVE-2023-5678'
```
這會在檢查組建是否應失敗時忽略特定 CVEs。只有在處理禁止清單時，才應該將誤報新增至禁止清單。將這些漏洞新增至隱藏清單後，CVEs 仍會出現在您的安全報告中，但不會導致建置失敗。
**自動失敗 CVE 清單**
對於重大安全漏洞，您可以建立永遠導致建置失敗的清單。
```
isAutoFailCveEnabled: true,
autoFailCveList: 'CVE-2024-9999'
```
無論您啟用了哪些設定，這一律會導致您的建置失敗。您應該僅為不應部署的高優先順序安全問題建立此清單。清單會覆寫所有其他閾值設定，以提供最大的安全性。
## 步驟 7. 檢視您的 Amazon Inspector 漏洞報告
1. 完成專案的新建置。
1. 建置完成後，從結果中選取輸出格式。如果選取 HTML，您可以選擇下載 JSON SBOM 或 CSV 版本的報告。以下顯示 HTML 報告的範例：
![\[Amazon Inspector 漏洞報告的範例。\]](http://docs.aws.amazon.com/zh_tw/inspector/latest/user/images/report.png)
**注意**
您可以使用較舊的指令碼，因為外掛程式支援舊的參數名稱。不過，您會在主控台中遇到警告，建議您將這些參數更新為較新的參數。例如，如果您使用 `isThresholdEnabled`，您會遇到警告，告知您將 參數更新為 `isSeverityThresholdEnabled`。
## 疑難排解
以下是使用適用於 的 Amazon Inspector Scan 外掛程式時可能遇到的常見錯誤Jenkins。
### 無法載入登入資料或 sts 例外狀況錯誤
**錯誤：**
`InstanceProfileCredentialsProvider(): Failed to load credentials or sts exception.`
**還原**
`aws_secret_access_key` 為 AWS 您的帳戶取得 `aws_access_key_id`和 。在 `aws_secret_access_key`中設定 `aws_access_key_id`和 `~/.aws/credentials`。
### 無法從 tarball、本機或遠端來源載入映像
**錯誤：**
`2024/10/16 02:25:17 [ImageDownloadFailed]: failed to load image from tarball, local, or remote sources.`
**注意**
如果 Jenkins 外掛程式無法讀取容器映像、Docker引擎中找不到容器映像，而且遠端容器登錄檔中找不到容器映像，則可能會發生此錯誤。
**解決方法：**
驗證下列項目；
+ Jenkins 外掛程式使用者具有您要掃描之映像的讀取許可。
+ 您想要掃描的映像存在於Docker引擎中。
+ 您的遠端映像 URL 正確。
+ 系統會對您進行遠端登錄檔的身分驗證 （如適用）。
### Inspector-sbomgen 路徑錯誤
**錯誤：**
`Exception:com.amazon.inspector.jenkins.amazoninspectorbuildstep.exception.SbomgenNotFoundException: There was an issue running inspector-sbomgen, is /opt/inspector/inspector-sbomgen the correct path?`
**解決方法：**
完成下列程序以解決問題。
1. 將正確的作業系統架構 Inspector-sbomgen 放入Jenkins目錄 如需詳細資訊，請參閱 [Amazon Inspector SBOM Generator](https://docs.aws.amazon.com/inspector/latest/user/sbom-generator.html)。
1. 使用下列命令將可執行檔許可授予二進位檔：`chmod +x inspector-sbomgen`。
1. 在外掛程式中提供正確的Jenkins機器路徑，例如 `/opt/folder/arm64/inspector-sbomgen`。
1. 儲存組態並執行Jenkins任務。