aws-actions/vulnerability-scan-github-action-for-amazon-inspector
GitHub: aws-actions/vulnerability-scan-github-action-for-amazon-inspector
一个将 Amazon Inspector 漏洞扫描能力集成到 GitHub Actions 工作流中的官方 Action，支持对多种制品生成 SBOM 并自动检测已知漏洞。
Stars: 58 | Forks: 16
# Amazon Inspector 漏洞扫描 GitHub Action
此 GitHub Action 允许您在 GitHub Actions 工作流中使用 Amazon Inspector 扫描受支持的制品的软件漏洞。
使用此操作需要有效的 AWS 账户。
## 概述
此操作首先会为提供的制品生成 CycloneDX 软件物料清单 (SBOM)。然后，该 SBOM 将被发送至 Amazon Inspector 以扫描已知漏洞。
此操作可以扫描以下制品类型是否存在漏洞：
1. GitHub 仓库中的文件和目录
2. 容器镜像
3. 已编译的 Go 和 Rust 二进制文件 (*不支持已剥离和混淆的二进制文件*)
4. 归档文件 *(.zip, .tar, .tar.gz)*
有关更多信息，请参阅 Amazon Inspector 支持的[制品](https://docs.aws.amazon.com/inspector/latest/user/sbom-generator.html)和[容器操作系统](https://docs.aws.amazon.com/inspector/latest/user/supported.html#supported-os-ecr)。
要了解有关 Amazon Inspector 的更多信息，以及 Inspector 的免费试用和定价模型，请访问以下链接：
1. https://aws.amazon.com/inspector/
2. https://aws.amazon.com/inspector/pricing/?nc=sn&loc=3
## 前置条件
1. **必需：** 您必须拥有有效的 AWS 账户才能使用此操作。有关创建 AWS 账户的指导可在[此处](https://docs.aws.amazon.com/inspector/latest/user/configure-cicd-account.html)找到。
2. **必需：** 您必须拥有对 **InspectorScan:ScanSbom** API 的读取权限。[请在此处查看配置说明](https://docs.aws.amazon.com/inspector/latest/user/configure-cicd-account.html#cicd-iam-role)。
3. **必需：** 您必须配置 AWS 身份验证以用于 GitHub Action 工作流。为此，我们建议使用 [configure-aws-credentials](https://github.com/marketplace/actions/configure-aws-credentials-action-for-github-actions)。
4. **必需：** 如果您还没有 GitHub Actions 工作流，请创建一个。相关指导可在[此处](https://docs.github.com/en/actions/quickstart)找到。
5. **必需：** 配置 Dependabot 以保持此操作处于最新状态，以便您收到最新的错误修复和安全更新。相关指导可在[此处](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot#enabling-dependabot-version-updates-for-actions)找到。
6. *可选：* 如果需要，请配置容器镜像库身份验证。为此提供了 GitHub Action，包括 [Docker Login](https://github.com/marketplace/actions/docker-login)。
## 用法
### 快速开始
执行以下步骤以快速将此操作添加到您的 GitHub Actions 流水线中：
1. 将以下 YAML 块复制并粘贴到您的工作流文件中。
**请通读此工作流定义并进行更改以适应您的环境**：
name: Scan artifact with Amazon Inspector
on: [push]
jobs:
daily_job:
runs-on: ubuntu-latest
# change this to match your GitHub Secrets environment
environment:
name: your_github_secrets_environment
steps:
# modify this block based on how you authenticate to AWS
# make sure you have permission to access the Inspector ScanSbom API
# https://docs.aws.amazon.com/inspector/latest/user/configure-cicd-account.html#cicd-iam-role
- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v4
with:
aws-region: "us-east-1"
role-to-assume: "arn:aws:iam:::role/"
# Check out your repository if needed
- name: Checkout this repository
uses: actions/checkout@v4
# modify this block to scan your intended artifact
- name: Inspector Scan
id: inspector
uses: aws-actions/vulnerability-scan-github-action-for-amazon-inspector@v1
with:
# change artifact_type to either 'repository', 'container', 'binary', or 'archive'.
artifact_type: 'repository'
# change artifact_path to the file path or container image you would like to scan.
# File paths should be relative to your root project directory.
# For containers, this action accepts 'docker pull'-style references to containers,
# such as 'alpine:latest' or a file path to an image exported as TAR using docker save.
artifact_path: './'
# If enabled, this setting will display Inspector's vulnerability scan findings
# as a GitHub actions step summary. See here for an example step summary:
# https://github.com/aws-actions/vulnerability-scan-github-action-for-amazon-inspector/actions/runs/8800085041
display_vulnerability_findings: "enabled"
# Set vulnerability thresholds; if the number of vulnerabilities is
# equal to or greater than any of the specified thresholds, this
# action will set the 'vulnerability_threshold_exceeded'
# output flag to 1.
critical_threshold: 1
high_threshold: 1
medium_threshold: 1
low_threshold: 1
other_threshold: 1
# Additional input arguments are available to control scan behavior.
# See 'action.yml' for additional input/output options.
# The following steps illustrate how to
# display scan results in the GitHub Actions job terminal.
- name: Display CycloneDX SBOM (JSON)
run: cat ${{ steps.inspector.outputs.artifact_sbom }}
- name: Display Inspector vulnerability scan results (JSON)
run: cat ${{ steps.inspector.outputs.inspector_scan_results }}
- name: Display Inspector vulnerability scan results (CSV)
run: cat ${{ steps.inspector.outputs.inspector_scan_results_csv }}
- name: Display Inspector vulnerability scan results (Markdown)
run: cat ${{ steps.inspector.outputs.inspector_scan_results_markdown }}
# The following steps illustrate how to
# upload scan results as a GitHub actions job artifact
- name: Upload Scan Results
uses: actions/upload-artifact@v4
with:
name: Inspector Vulnerability Scan Artifacts
path: |
${{ steps.inspector.outputs.inspector_scan_results }}
${{ steps.inspector.outputs.inspector_scan_results_csv }}
${{ steps.inspector.outputs.artifact_sbom }}
${{ steps.inspector.outputs.inspector_scan_results_markdown }}
# This step illustrates how to add custom logic if
# the vulnerability threshold is exceeded. This example
# simply prints the 'vulnerability_threshold_exceeded' value
# to the GitHub actions job terminal.
# Replace 'echo' with 'exit' if you want to fail the job.
- name: On vulnerability threshold exceeded
run: echo ${{ steps.inspector.outputs.vulnerability_threshold_exceeded }}
2. 保存您的工作流文件，然后通过 git commit / git push 将工作流推送到 GitHub。
GitHub 应该会自动运行您的新工作流；查看其结果并对输入和输出参数进行任何必要的更改。
有关更多示例，请参阅[此仓库的工作流定义](.github/workflows/)。
### 配置漏洞扫描输出
默认情况下，此操作仅在 GitHub Actions 作业终端中显示检测到的漏洞数量。详细的发现是可选的，并且可以配置为 JSON、CSV 或 Markdown 格式。此外，制品清单以 CycloneDX JSON 文件的形式提供。
以下示例展示了如何在各种位置和格式中启用操作输出。
**请务必小心，确保您不会意外地将漏洞信息展示给不受信任的查看者。**
```
- name: Scan container
id: inspector
uses: aws/vulnerability-scan-github-action-for-amazon-inspector@v1
with:
artifact_type: 'container'
artifact_path: 'ubuntu:14.04'
display_vulnerability_findings: "enabled"
# 在 GitHub Actions 终端中显示 Inspector 结果
- name: Display CycloneDX SBOM (JSON)
run: cat ${{ steps.inspector.outputs.artifact_sbom }}
- name: Display Inspector vulnerability scan results (JSON)
run: cat ${{ steps.inspector.outputs.inspector_scan_results }}
- name: Display Inspector vulnerability scan results (CSV)
run: cat ${{ steps.inspector.outputs.inspector_scan_results_csv }}
- name: Display Inspector vulnerability scan results (markdown)
run: cat ${{ steps.inspector.outputs.inspector_scan_results_markdown }}
# 将 Inspector 输出上传为可下载的 .zip 文件
# 从 GitHub actions job summary 页面。
- name: Upload Scan Results
id: inspector
uses: actions/upload-artifact@v4
with:
path: |
${{ steps.inspector.outputs.inspector_scan_results }}
${{ steps.inspector.outputs.inspector_scan_results_csv }}
${{ steps.inspector.outputs.artifact_sbom }}
```
### 配置漏洞阈值
此操作允许用户设置漏洞阈值。
以下示例展示了如何设置漏洞阈值并在超过阈值时使作业失败：
```
- name: Invoke Amazon Inspector Scan
id: inspector
uses: aws/vulnerability-scan-github-action-for-amazon-inspector@v1
with:
artifact_type: 'repository'
artifact_path: './'
display_vulnerability_findings: "enabled"
# If the number of vulnerabilities equals or exceeds
# any of the specified vulnerability thresholds, this action
# sets a flag, 'vulnerability_threshold_exceeded' to 1, else 0.
# To ignore thresholds for a given severity, set its value to 0.
# This example sets 'vulnerability_threshold_exceeded' flag if
# one or more criticals, highs, or medium severity vulnerabilities
# are found; lows and other type vulnerabilities will not set
# the 'vulnerability_threshold_exceeded' flag.
critical_threshold: 1
high_threshold: 1
medium_threshold: 1
low_threshold: 0
other_threshold: 0
# 如果设置了 vuln threshold flag，则使用 'exit 1' 使 job 失败
- name: On vulnerability threshold exceeded
run: exit ${{ steps.inspector.outputs.vulnerability_threshold_exceeded }}
```
### 忽略特定发现
您可以抑制特定发现，从而将它们从报告中排除，并且不计入漏洞阈值。
有两种方法可以定义要忽略的发现，这两种方法也可以结合使用：
**1. `ignore_findings` 输入参数** — 在工作流中直接提供以逗号分隔的发现 ID 列表 (CVE, GHSA 等)：
```
- name: Inspector Scan
id: inspector
uses: aws-actions/vulnerability-scan-github-action-for-amazon-inspector@v1
with:
artifact_type: 'repository'
artifact_path: './'
critical_threshold: 1
ignore_findings: "CVE-2021-12345,CVE-2022-67890,GHSA-mqqf-5wvp-8fh8"
```
**2. `.inspector-ignore` 文件** — 在您的仓库根目录（工作流的工作目录——即您存放 `.gitignore` 的位置）放置一个名为 `.inspector-ignore` 的纯文本文件。无论扫描哪种制品类型，都会读取该文件。每行一个发现 ID；以 `#` 开头的行和行内的 `#` 注释将被忽略：
```
# .inspector-ignore
CVE-2021-12345 # accepted risk: no fix available, mitigated by network controls
CVE-2022-67890
GHSA-abcd-1234-efgh
```
在上述任一位置列出的发现都将从所有输出报告 (JSON、CSV、Markdown) 中移除，并且在评估漏洞阈值时不予计数。
### 构建并扫描容器镜像
此操作支持一种常见的用例，即构建容器镜像、扫描构建的镜像是否存在漏洞，并可选地在镜像部署到容器镜像库或其他地方之前使工作流失败。
我们在下面提供了此工作流的示例。您必须修改此工作流以适应您的环境：
```
name: Build & Scan Container Image
on: [ push ]
jobs:
build:
name: Build docker image
runs-on: ubuntu-latest
environment:
# change this to match your GitHub secrets environment
name: plugin-development
steps:
# checkout the repository containing our Dockerfile
- name: Checkout this repository
uses: actions/checkout@v4
# Setup prerequisites for docker/build-push-action
- name: Set up docker build prereqs (QEMU)
uses: docker/setup-qemu-action@v3
- name: Set up docker build prereqs (Buildx)
uses: docker/setup-buildx-action@v3
# build the image you wish to scan
- name: Build Docker image
uses: docker/build-push-action@v5
with:
context: .
file: ./Dockerfile
push: false
tags: app:latest
load: true
# setup your AWS credentials
- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v4
with:
aws-region: "us-east-1"
role-to-assume: "arn:aws:iam:::role/"
- name: Scan built image with Inspector
uses: aws-actions/vulnerability-scan-github-action-for-amazon-inspector@v1
id: inspector
with:
artifact_type: 'container'
artifact_path: 'app:latest' # make sure this matches the image you built
critical_threshold: 1
high_threshold: 1
medium_threshold: 1
low_threshold: 1
other_threshold: 1
# set additional arguments as needed
- name: Fail job if vulnerability threshold is exceeded
run: exit ${{ steps.inspector.outputs.vulnerability_threshold_exceeded }}
# add any additional steps for deploying your image
```
## 操作输入与输出
此操作提供以下输入和输出选项。有关更多详细信息，请参阅 [action.yml](./action.yml)。
### 输入选项
| **名称** | **描述** | **必需** | **默认值** |
|---|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---|---|
| artifact_type | 您希望使用 Amazon Inspector 扫描的制品。有效选项为 "repository"、"container"、"binary" 或 "archive"。 | 是 | repository |
| artifact_path | 您希望使用 Amazon Inspector 扫描的制品的文件路径。文件路径是相对于根项目目录的。如果扫描容器镜像，您必须提供遵循 docker pull 约定的值。例如，"alpine:latest"，或者是使用 "docker save" 导出为 tarball 格式镜像的路径。 | 是 | ./ |
| display_vulnerability_findings | 如果设置为 "enabled"，该操作将在操作摘要页面上显示详细的漏洞发现；有关示例，请参见此处：https://github.com/aws-actions/vulnerability-scan-github-action-for-amazon-inspector/actions/runs/8742638284/attempts/1#summary-23991378549 | 是 | disabled |
| output_sbom_path | 生成的 SBOM 的目标文件路径。 | 否 | ./sbom_${{ github.run_id }}.json |
| output_inspector_scan_path | Inspector 漏洞扫描的目标文件路径 (JSON 格式)。 | 否 | inspector_scan_${{ github.run_id }}.json |
| output_inspector_scan_path_csv | Inspector 漏洞扫描的目标文件路径 (CSV 格式)。 | 否 | inspector_scan_${{ github.run_id }}.csv |
| output_inspector_scan_path_markdown | Inspector 漏洞扫描的目标文件路径 (markdown 格式)。 | 否 | inspector_scan_${{ github.run_id }}.md |
| sbomgen_version | 您希望用于生成 SBOM 的 inspector-sbomgen 版本。有关更多信息，请参见此处：https://docs.aws.amazon.com/inspector/latest/user/sbom-generator.html | 否 | latest |
| critical_threshold | 指定设置 'vulnerability_threshold_exceeded' 标志所需的严重漏洞数量。 | 否 | 0 |
| high_threshold | 指定设置 'vulnerability_threshold_exceeded' 标志所需的高危漏洞数量。 | 否 | 0 |
| medium_threshold | 指定设置 'vulnerability_threshold_exceeded' 标志所需的中危漏洞数量。 | 否 | 0 |
| low_threshold | 指定设置 'vulnerability_threshold_exceeded' 标志所需的低危漏洞数量。 | 否 | 0 |
| other_threshold | 指定设置 'vulnerability_threshold_exceeded' 标志所需的其他漏洞数量。 | 否 | 0 |
| scanners | 指定您希望 inspector-sbomgen 执行的文件扫描器。默认情况下，inspector-sbomgen 会尝试运行所有适用于目标制品的文件扫描器。如果设置了此参数，inspector-sbomgen 将仅执行指定的文件扫描器。以单个字符串形式提供您的输入。每个文件扫描器之间用逗号分隔。例如：scanners: dpkg,python-requirements,javascript-npm-packagelock 要查看可用文件扫描器的列表，请执行 'inspector-sbomgen list-scanners'。有关更多信息，请参见此处：https://docs.aws.amazon.com/inspector/latest/user/sbom-generator.html | 否 | '' |
| skip_scanners | 指定一个不应执行的文件扫描器列表；此参数不能与 'scanners' 结合使用。如果设置了此参数，inspector-sbomgen 将执行除您指定的扫描器之外的所有文件扫描器。以单个字符串形式提供您的输入。每个文件扫描器之间用逗号分隔。例如：skip_scanners: 'binaries,alpine-apk,dpkg,php' 要查看可用文件扫描器的列表，请执行 'inspector-sbomgen list-scanners'。有关更多信息，请参见此处：https://docs.aws.amazon.com/inspector/latest/user/sbom-generator.html | 否 | '' |
| skip_files | 指定一个或多个不应被清点的文件和/或目录。每个文件之间用逗号分隔并将整个字符串用双引号括起来，例如：skip_files: "./media,/tmp/foo/,/bar/my_program" | 否 | '' |
| timeout | 指定超时时间（以秒为单位）。如果超过此超时时间，该操作将平滑结束并显示截至该时间点发现的任何结果。默认值为 600 秒或 10 分钟。 | 否 | 600 |
| ignore_findings | 要抑制的以逗号分隔的发现 ID 列表。被忽略的发现将从所有输出报告中排除，并且不计入漏洞阈值。您也可以在仓库根目录（工作流的工作目录；每行一个 ID，`#` 用于注释）放置一个纯文本的 `.inspector-ignore` 文件。请参见[忽略特定发现](#ignoring-specific-findings)。示例：`CVE-2021-12345,CVE-2022-67890,GHSA-mqqf-5wvp-8fh8` | 否 | '' |
| license_collection | 如果设置为 `true`，inspector-sbomgen 会在生成 SBOM 时收集 SPDX 许可证元数据，并且该操作会呈现一份许可证清单报告（CSV 和 markdown 格式），同时将其发布到步骤摘要中。许可证收集支持选定的生态系统；对于不受支持的生态系统，报告为空。 | 否 | false |
### 输出选项
| **名称** | **描述** |
|---|---|
| artifact_sbom | 制品软件物料清单的文件路径。 |
| inspector_scan_results | JSON 格式的 Inspector 漏洞扫描发现结果的文件路径。 |
| inspector_scan_results_csv | CSV 格式的 Inspector 漏洞扫描发现结果的文件路径。 |
| inspector_scan_results_markdown | Markdown 格式的 Inspector 漏洞扫描发现结果的文件路径。 |
| inspector_license_results_csv | CSV 格式的已收集许可证清单的文件路径。仅在启用 `license_collection` 时生成。 |
| inspector_license_results_markdown | Markdown 格式的已收集许可证清单的文件路径。仅在启用 `license_collection` 时生成。 |
| vulnerability_threshold_exceeded | 如果超出了任何漏洞阈值，此变量将设置为 1，否则为 0。此变量可用于触发自定义逻辑，例如在检测到漏洞时使作业失败。 |
## 获取帮助
有关此操作的一般问题，请将您的问题发布到项目的讨论页面：
- https://github.com/aws-actions/vulnerability-scan-github-action-for-amazon-inspector/discussions
您也可以考虑浏览这些资源，以获取有关 AWS 产品和服务的额外帮助：
- https://repost.aws/knowledge-center/get-aws-help
## Bug
如果您遇到了 bug，请提交一个 GitHub issue：
- https://github.com/aws-actions/vulnerability-scan-github-action-for-amazon-inspector/issues/new/choose
## 安全
## 许可证
该项目基于 MIT 许可证授权。
该项目使用了 [Amazon Inspector SBOM Generator](https://docs.aws.amazon.com/inspector/latest/user/sbom-generator.html)，该生成器基于 [AWS Intellectual Property License](https://aws.amazon.com/legal/aws-ip-license-terms/) 授权。
版权所有 2025 Amazon.com, Inc. 或其附属公司。保留所有权利。
标签：AI应用开发, Google Gemini, 漏洞利用检测, 聊天机器人