Skip to content

Commit c715a2b

Browse files
bluesentinelsecMichael Long
bluesentinelsec
and
Michael Long
authored
Update documentation and examples (#35)
* update documentation * added 'display_vulnerability_findings' input arg * fix invalid YAML * fix aws-actions url --------- Co-authored-by: Michael Long <mlongii@amazon.com>
1 parent fb6d0db commit c715a2b

File tree

5 files changed

+268
-49
lines changed

5 files changed

+268
-49
lines changed

‎.github/workflows/example_display_findings.yml‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
name: Display Findings Example
2+
3+
# Run once per day and on git push
4+
on:
5+
schedule:
6+
- cron: '0 0 * * *'
7+
push:
8+
branches: #
9+
- '*'
10+
11+
jobs:
12+
daily_job:
13+
runs-on: ubuntu-latest
14+
environment:
15+
name: plugin-development # change this to match your GitHub Secrets environment
16+
17+
steps:
18+
19+
# modify this block based on how you authenticate to AWS
20+
- name: Configure AWS credentials
21+
uses: aws-actions/configure-aws-credentials@v4
22+
with:
23+
aws-region: ${{ secrets.AWS_REGION }}
24+
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
25+
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
26+
27+
28+
# modify this block to scan your intended artifact
29+
- name: Scan container
30+
id: inspector
31+
uses: aws-actions/vulnerability-scan-github-action-for-amazon-inspector@main
32+
with:
33+
# change artifact_type to either 'repository', 'container', 'binary', or 'archive'.
34+
# this example scans a container image
35+
artifact_type: 'container'
36+
37+
# change artifact_path to the file path or container image you would like to scan.
38+
# For containers, this action accepts 'docker pull'-style references to containers,
39+
# such as 'alpine:latest' or a file path to an image exported as TAR using docker save.
40+
artifact_path: 'ubuntu:14.04'
41+
42+
# If enabled, this setting will display Inspector's vulnerability scan findings
43+
# as a GitHub actions job summary. See here for an example:
44+
# https://github.com/aws-actions/vulnerability-scan-github-action-for-amazon-inspector/actions/runs/8800085041
45+
display_vulnerability_findings: true
46+
47+
# Set vulnerability thresholds; if the number of vulns is
48+
# equal to or greater than any of the specified thresholds, set
49+
# the 'vulnerability_threshold_exceeded' output flag to 1.
50+
critical_threshold: 1
51+
high_threshold: 1
52+
medium_threshold: 1
53+
low_threshold: 1
54+
other_threshold: 1
55+
56+
# Additional input arguments are available.
57+
# See 'action.yml' for additional input/output options.
58+
59+
60+
# The following steps illustrate how to
61+
# display scan results in the GitHub Actions job terminal.
62+
# These examples simply print the output files to the console.
63+
- name: Display CycloneDX SBOM (JSON)
64+
run: cat ${{ steps.inspector.outputs.artifact_sbom }}
65+
66+
- name: Display Inspector vulnerability scan results (JSON)
67+
run: cat ${{ steps.inspector.outputs.inspector_scan_results }}
68+
69+
- name: Display Inspector vulnerability scan results (CSV)
70+
run: cat ${{ steps.inspector.outputs.inspector_scan_results_csv }}
71+
72+
# - name: Display Inspector vulnerability scan results (Markdown)
73+
# run: cat ${{ steps.inspector.outputs.inspector_scan_results_markdown }}
74+
75+
76+
# The following steps illustrate how to
77+
# upload scan results as a GitHub actions job artifact
78+
- name: Upload Scan Results
79+
uses: actions/upload-artifact@v4
80+
with:
81+
name: Inspector Vulnerability Scan Artifacts
82+
path: |
83+
${{ steps.inspector.outputs.inspector_scan_results }}
84+
${{ steps.inspector.outputs.inspector_scan_results_csv }}
85+
${{ steps.inspector.outputs.artifact_sbom }}
86+
# ${{ steps.inspector.outputs.inspector_scan_results_markdown }}
87+
88+
89+
# This step illustrates how to add custom logic if
90+
# the vulnerability threshold is exceeded. This example
91+
# simply prints the 'vulnerability_threshold_exceeded' value
92+
# to the GitHub actions job terminal.
93+
# Replace 'echo' with 'exit' if you want to fail the job.
94+
- name: On vulnerability threshold exceeded
95+
run: echo ${{ steps.inspector.outputs.vulnerability_threshold_exceeded }}
96+
97+

‎README.md‎

Lines changed: 159 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,112 +1,220 @@
1-
## Amazon Inspector for GitHub Actions
1+
# Vulnerability Scan GitHub Action for Amazon Inspector
22

33
Amazon Inspector is a vulnerability management service that scans AWS workloads and [CycloneDX SBOMs](https://cyclonedx.org/) for known software vulnerabilities.
44

5-
Using this action, you can automatically scan supported artifacts with Amazon Inspector from your GitHub Actions workflows.
5+
This GitHub Action allows you to scan supported artifacts for software vulnerabilities using Amazon Inspector from your GitHub Actions workflows.
6+
7+
An active AWS account is required to use this action.
68

79

810
## Overview
911

10-
Amazon Inspector for GitHub Actions can be used to detect software vulnerabilities in the following artifacts within your GitHub Actions workflows:
12+
This action works by first generating a CycloneDX software bill of materials (SBOM) for the provided artifact.
13+
14+
The SBOM is then sent to Amazon Inspector; Inspector scans the provided SBOM for known vulnerabilities, and returns its results to the calling action.
1115

12-
1. Package dependencies
16+
This action can scan the following artifact types for software vulnerabilities:
17+
18+
1. Repository files and directories
1319
2. Container images
1420
3. Compiled Go and Rust binaries
1521
4. Archives *(.zip, .tar, .tar.gz)*
1622

17-
This action is powered by the [Amazon Inspector SBOM Generator (inspector-sbomgen)](https://docs.aws.amazon.com/inspector/latest/user/sbom-generator.html).
23+
To learn more about this action's supported artifacts, please see our documentation here: [Amazon Inspector SBOM Generator (inspector-sbomgen)](https://docs.aws.amazon.com/inspector/latest/user/sbom-generator.html).
24+
1825

1926
## Prerequisites
2027

2128
1. **Required:** You must have an active AWS account to use this action. Guidance on creating an AWS account is provided [here](https://docs.aws.amazon.com/inspector/latest/user/configure-cicd-account.html).
2229

2330
2. **Required:** You must have read access to the **InspectorScan:ScanSbom** API. [See here for configuration instructions](https://docs.aws.amazon.com/inspector/latest/user/configure-cicd-account.html#cicd-iam-role).
2431

25-
3. **Required:** You must configure AWS authentication on GitHub. We recommend using [configure-aws-credentials](https://github.com/marketplace/actions/configure-aws-credentials-action-for-github-actions) for this purpose.
32+
3. **Required:** You must configure AWS authentication for use in GitHub action workflows. We recommend using [configure-aws-credentials](https://github.com/marketplace/actions/configure-aws-credentials-action-for-github-actions) for this purpose.
2633

2734
4. **Required:** Create a GitHub Actions workflow if you do not already have one. Guidance on doing so is available [here](https://docs.github.com/en/actions/quickstart).
2835

29-
5. *Optional:* Configure container registry authentication if needed. GitHub Actions are available for this purpose including [Docker Login](https://github.com/marketplace/actions/docker-login).
30-
31-
6. *Optional (strongly recommended):* Configure Dependabot to keep this action up to date. Guidance on doing so is available [here](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). Alternatively, consider creating automatic notifications for releases and security alerts by selecting the "watch" button and then "custom".
36+
5. **Required:** Configure Dependabot to keep this action up to date so you receive the latest bug fixes and security updates. Guidance on doing so is available [here](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).
3237

38+
6. *Optional:* Configure container registry authentication if needed. GitHub Actions are available for this purpose including [Docker Login](https://github.com/marketplace/actions/docker-login).
3339

3440

3541
## Usage
3642

37-
The following examples demonstrate how to use this action:
43+
### Quick Start
3844

39-
- Copy and paste the provided YAML excerpts into your GitHub Actions workflow file.
45+
Perform the following steps to quickly add this action to your GitHub Actions pipeline:
4046

41-
- Modify the input options as needed.
47+
1. Create a new workflow file in your repository:
4248

49+
```bash
50+
# from your repository's root directory
51+
touch .github/workflows/invoke_inspector_scan.yml
52+
```
4353

44-
- See [here for example workflows](./.github/workflows/).
54+
2. Copy and paste the following YAML block into your workflow file.
4555

56+
You will need to modify this workflow definition to suit your environment:
4657

47-
### 1. Scan Package Dependencies
58+
```yaml
59+
TODO: paste me / link me
60+
```
4861

49-
This example will scan your repository contents for vulnerable software packages, based on contents from files such as requirements.txt.
62+
3. Save your workflow file then git commit / git push the workflow to GitHub.
5063

51-
```yaml
52-
- name: Invoke Amazon Inspector Scan
53-
uses: aws/amazon-inspector-github-actions-plugin@v1
54-
with:
55-
artifact_type: 'repository'
56-
artifact_path: './' # change this if you would like to scan a specific sub-directory, otherwise the entire repo will be scanned.
57-
```
64+
GitHub should automatically run your new workflow; review its results and make any needed changes to the input and output arguments.
65+
66+
67+
### Configuring Vulnerability Scan Outputs
68+
69+
This action provides detailed Inspector scan findings in JSON, CSV, and markdown, plus, a CycloneDX software bill of materials in JSON.
5870

59-
- [*See here for more information on the types of package vulnerabilities this action can detect*](https://docs.aws.amazon.com/inspector/latest/user/sbom-generator.html).
71+
By default, this action will only display the number of vulnerabilities detected in the GitHub Actions job terminal; detailed findings are not shown.
6072

73+
This is done so **you** can control how and where your vulnerability findings are presented and stored.
6174

62-
### 2. Scan Container Image
75+
The example below shows how to present this action's outputs in various locations and formats.
6376
64-
This example will scan a container image for vulnerable software packages.
77+
Exercise caution to ensure you do not accidentally post vulnerability information to untrusted viewers.
6578
6679
```yaml
67-
- name: Invoke Amazon Inspector Scan
68-
uses: aws/amazon-inspector-github-actions-plugin@v1
80+
- name: Scan container
81+
id: inspector
82+
uses: aws/vulnerability-scan-github-action-for-amazon-inspector@main
6983
with:
7084
artifact_type: 'container'
71-
artifact_path: 'alpine:latest' # change this to the image you would like to scan
72-
```
85+
artifact_path: 'ubuntu:14.04'
86+
87+
# Display Inspector results in the GitHub Actions terminal
88+
- name: Display CycloneDX SBOM (JSON)
89+
run: cat ${{ steps.inspector.outputs.artifact_sbom }}
90+
91+
- name: Display Inspector vulnerability scan results (JSON)
92+
run: cat ${{ steps.inspector.outputs.inspector_scan_results }}
7393
74-
This action can scan containers exported as tarballs, locally built images, and images from remote registries.
94+
- name: Display Inspector vulnerability scan results (CSV)
95+
run: cat ${{ steps.inspector.outputs.inspector_scan_results_csv }}
7596
76-
For locally built images, this action only supports images built with Docker engine.
7797
78-
- [*See here for an example on building an image, scanning the image, and failing the build if vulnerabilities are detected*](./.github/workflows/container_local.yml).
98+
# Upload Inspector outputs as a .zip that can be downloaded
99+
# from the GitHub actions job summary page.
100+
- name: Upload Scan Results
101+
id: inspector
102+
uses: actions/upload-artifact@v4
103+
with:
104+
path: |
105+
${{ steps.inspector.outputs.inspector_scan_results }}
106+
${{ steps.inspector.outputs.inspector_scan_results_csv }}
107+
${{ steps.inspector.outputs.artifact_sbom }}
108+
```
109+
110+
### Configuring Vulnerability Thresholds
79111
112+
This action allows the user to set vulnerability thresholds.
80113
81-
### 3. Scan Compiled Go or Rust Binary
114+
Vulnerability thresholds can be used to support custom logic, such as failing the workflow if any vulnerabilities are found.
82115
83-
This example will scan a compiled Go or Rust binary's package dependencies for vulnerabiliies.
116+
The example below shows how to set up vulnerability thresholds and fail the job when the threshold is exceeded:
84117
85118
```yaml
86119
- name: Invoke Amazon Inspector Scan
87-
uses: aws/amazon-inspector-github-actions-plugin@v1
120+
id: inspector
121+
uses: aws/vulnerability-scan-github-action-for-amazon-inspector@v1
88122
with:
89-
artifact_type: 'binary'
90-
artifact_path: './path/to/binary' # change this to your binary's filepath
123+
artifact_type: 'repository'
124+
artifact_path: './'
125+
126+
# set vulnerability thresholds; if the number of vulnerabilities
127+
# equals or exceeds any of the specified thresholds, this action
128+
# sets a flag, 'vulnerability_threshold_exceeded' to 1, else 0.
129+
# To ignore thresholds for a given severity, set its value to 0.
130+
# This example sets 'vulnerability_threshold_exceeded' flag if
131+
# one or more criticals, highs, or medium severity vulnerabilities
132+
# are found; lows and other type vulnerabilities are ignored
133+
# by this action when determining whether the threshold was
134+
# or was not exceeded.
135+
critical_threshold: 1
136+
high_threshold: 1
137+
medium_threshold: 1
138+
low_threshold: 0
139+
other_threshold: 0
140+
141+
# Fail the job with 'exit 1' if vuln threshold flag is set
142+
- name: On vulnerability threshold exceeded
143+
run: exit ${{ steps.inspector.outputs.vulnerability_threshold_exceeded }}
91144
```
92145
93-
### 4. Scan Archive
146+
### Build and Scan Container Images
147+
148+
This action supports a common use case that entails building a container image, scanning the built image for vulnerabilities, and optionally, failing the workflow before the image is deployed to a container registry or elsewhere.
94149
95-
This example will scan an archive for vulnerable software packages. The supported archive formats are **.zip**, **.tar**, and **.tar.gz**.
150+
We provide an example of this workflow below:
96151
97152
```yaml
98-
- name: Invoke Amazon Inspector Scan
99-
uses: aws/amazon-inspector-github-actions-plugin@v1
100-
with:
101-
artifact_type: 'archive'
102-
artifact_path: './path/to/archive' # change this to your archive's filepath
153+
name: Build & Scan Container Image
154+
155+
on: [push]
156+
157+
jobs:
158+
build:
159+
name: Build docker image
160+
runs-on: ubuntu-latest
161+
environment:
162+
# change this to match your GitHub secrets environment
163+
name: plugin-development
164+
165+
steps:
166+
# checkout the repository containing our Dockerfile
167+
- name: Checkout this repository
168+
uses: actions/checkout@v4
169+
170+
# Setup prerequisites for docker/build-push-action
171+
- name: Set up docker build prereqs (QEMU)
172+
uses: docker/setup-qemu-action@v3
173+
174+
- name: Set up docker build prereqs (Buildx)
175+
uses: docker/setup-buildx-action@v3
176+
177+
# build the image you wish to scan
178+
- name: Build Docker image
179+
uses: docker/build-push-action@v5
180+
with:
181+
context: .
182+
file: ./Dockerfile
183+
push: false
184+
tags: app:latest
185+
load: true
186+
187+
# setup your AWS credentials
188+
- name: Configure AWS credentials
189+
uses: aws-actions/configure-aws-credentials@v4
190+
with:
191+
aws-region: ${{ secrets.AWS_REGION }}
192+
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
193+
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
194+
195+
- name: Scan built image with Inspector
196+
uses: aws/amazon-inspector-github-actions-plugin@v1
197+
id: inspector
198+
with:
199+
artifact_type: 'container'
200+
artifact_path: 'app:latest' # make sure this matches the image you built
201+
critical_threshold: 1
202+
high_threshold: 1
203+
medium_threshold: 1
204+
low_threshold: 1
205+
other_threshold: 1
206+
# set additional arguments as needed
207+
208+
- name: Fail job if vulnerability threshold is exceeded
209+
run: exit ${{ steps.inspector.outputs.vulnerability_threshold_exceeded }}
210+
211+
# add any additional steps for deploying your image
103212
```
104213
105-
## Action Inputs
106214
107-
The following input options can be added to this action to control its behavior.
215+
## Action Inputs and Outputs
108216
109-
See [action.yml](./action.yml) for more detail.
217+
The following input and output options are provided by this action; see [action.yml](./action.yml) for more detail.
110218
111219
| Option | Required | Description |
112220
|---|---|---|
@@ -137,6 +245,10 @@ The following outputs are set by this action:
137245
| inspector_scan_results_csv | The filepath to the Inspector vulnerability scan in CSV format. |
138246
| vulnerability_threshold_exceeded | This variable is set to 1 if any vulnerability threshold was exceeded, otherwise it is 0. |
139247
248+
## Get Help
249+
250+
TODO: add me
251+
140252
## Security
141253
142254
See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.

‎action.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,11 @@ inputs:
1212
required: True
1313
default: './'
1414

15+
display_vulnerability_findings:
16+
description: 'If true, the action will display detailed vulnerability findings in the action summary page; see here for an example: https://github.com/aws-actions/vulnerability-scan-github-action-for-amazon-inspector/actions/runs/8742638284/attempts/1#summary-23991378549'
17+
required: True
18+
default: False
19+
1520
output_sbom_path:
1621
description: "The destination file path for the generated SBOM."
1722
required: False
@@ -104,6 +109,7 @@ runs:
104109
args:
105110
- --artifact-type=${{ inputs.artifact_type }}
106111
- --artifact-path=${{ inputs.artifact_path }}
112+
- --display-vuln-findings=${{ inputs.display_vulnerability_findings }}
107113
- --out-sbom=${{ inputs.output_sbom_path}}
108114
- --out-scan=${{ inputs.output_inspector_scan_path }}
109115
- --out-scan-csv=${{ inputs.output_inspector_scan_path_csv }}

0 commit comments

Comments
 (0)