本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 使用 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市场上查看该Jenkins插件的最新版本，[网址为 https://plugins.jenkins.io/amazon-inspector-image-scanner/](https://plugins.jenkins.io/amazon-inspector-image-scanner/)。以下步骤介绍了如何设置 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 Scan** 插件，然后安装该插件。
## （可选）第 3 步。将 docker 凭证添加到 Jenkins
**注意**
仅当 docker 映像位于私有存储库中时，才添加 docker 凭证。否则，请跳过此步骤。
以下过程描述如何从 Jenkins 控制面板将 docker 凭证添加到 Jenkins 中。
1. 在 Jenkins 控制面板中，依次选择**管理 Jenkins**、**凭证**、**系统**。
1. 选择**全局凭证**，然后选择**添加凭证**。
1. 在**种类**中，选择**用户名和密码**。
1. 对于**范围**，选择**全局(Jenkins、节点、项目、所有子项目等)。**
1. 输入您的详细信息，然后选择**确定**。
## （可选）第 4 步。添加 AWS 凭证
**注意**
仅当您想要基于 IAM 用户进行身份验证时，才添加 AWS 证书。否则，请跳过此步骤。
以下过程介绍如何从Jenkins仪表板添加 AWS 凭据。
1. 在 Jenkins 控制面板中，依次选择**管理 Jenkins**、**凭证**、**系统**。
1. 选择**全局凭证**，然后选择**添加凭证**。
1. 对于**种类**，请选择 **AWS 凭证**。
1. 输入您的详细信息，包括您的**访问密钥 ID** 和**秘密访问密钥**，然后选择**确定**。
## 步骤 5。在 Jenkins 脚本中添加 CSS 支持
以下过程介绍如何在 Jenkins 脚本中添加 CSS 支持。
1. 重启 Jenkins。
1. 在控制面板中，选择**管理 Jenkins**、**节点**、**内置节点**，然后选择**脚本控制台**。
1. 在文本框中，添加行 `System.setProperty("hudson.model.DirectoryBrowserSupport.CSP", "")`，然后选择**运行**。
## 步骤 6. 将 Amazon Inspector Scan 添加到您的构建中
您可以通过在项目中添加构建步骤或使用 Jenkins 声明式管道，将 Amazon Inspector 扫描添加到您的构建中。
### 通过在项目中添加构建步骤将 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 生成器](https://docs.aws.amazon.com/inspector/latest/user/sbom-generator.html)中[安装 Amazon Inspector SBOM 生成器（Sbomgen）](https://docs.aws.amazon.com/inspector/latest/user/sbom-generator.html#install-sbomgen)。
1. 完成以下操作以完成 Amazon Inspector 扫描构建步骤的配置：
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:: role/)。*AccountNumber* *RoleName*
1. （可选）对于 **AWS 证书**，请根据 IAM 用户指定要进行身份验证的 AWS 证书。
1. （可选）对于 **AWS 配置文件名称**，请提供要使用配置文件名称进行身份验证的配置文件的名称。
1. （可选）选择**启用漏洞阈值**。使用此选项，您可以确定如果扫描的漏洞超过某个值，您的构建是否会失败。如果所有值均等于 `0`，则无论扫描了多少漏洞，构建都会成功。对于 EPSS 分数，该值可以介于 0 到 1 之间。如果扫描的漏洞超过某个值，则构建将失败，并且所有 CVEs EPSS 分数高于该值的漏洞都会显示在控制台中。
1. 选择**保存**。
### 使用 Jenkins 声明式管道将 Amazon Inspector Scan 添加到构建中。
您可以使用 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_cn/inspector/latest/user/images/report.png)
**注意**
您可以使用较旧的脚本，因为该插件支持旧参数名称。但是，您会在控制台中遇到警告，建议将这些参数更新为较新的参数。例如，如果您使用 `isThresholdEnabled`，将遇到一条警告，建议您将该参数更新为 `isSeverityThresholdEnabled`。
## 问题排查
以下是您在使用适用于 Jenkins 的 Amazon Inspector Scan 插件时可能遇到的常见错误。
### 无法加载凭证或 sts 异常错误
**错误：**
`InstanceProfileCredentialsProvider(): Failed to load credentials or sts exception.`
**解决办法**
`aws_secret_access_key`为你的 AWS 账户获取`aws_access_key_id`和使用。在 `~/.aws/credentials` 中设置 `aws_access_key_id` 和 `aws_secret_access_key`。
### 无法从 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 生成器](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 作业。