Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update documentation and examples #35

Merged
merged 4 commits into from
Apr 23, 2024
Merged

Update documentation and examples #35

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
faff66b
update documentation
Apr 23, 2024
c4f0e5e
added 'display_vulnerability_findings' input arg
Apr 23, 2024
17ba0df
fix invalid YAML
Apr 23, 2024
7a69cb7
fix aws-actions url
Apr 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 97 additions & 0 deletions .github/workflows/example_display_findings.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
name: Display Findings Example

# Run once per day and on git push
on:
schedule:
- cron: '0 0 * * *'
push:
branches: #
- '*'

jobs:
daily_job:
runs-on: ubuntu-latest
environment:
name: plugin-development # change this to match your GitHub Secrets environment

steps:

# modify this block based on how you authenticate to AWS
- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v4
with:
aws-region: ${{ secrets.AWS_REGION }}
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}


# modify this block to scan your intended artifact
- name: Scan container
id: inspector
uses: aws-actions/vulnerability-scan-github-action-for-amazon-inspector@main
with:
# change artifact_type to either 'repository', 'container', 'binary', or 'archive'.
# this example scans a container image
artifact_type: 'container'

# change artifact_path to the file path or container image you would like to scan.
# 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: 'ubuntu:14.04'

# If enabled, this setting will display Inspector's vulnerability scan findings
# as a GitHub actions job summary. See here for an example:
# https://github.com/aws-actions/vulnerability-scan-github-action-for-amazon-inspector/actions/runs/8800085041
display_vulnerability_findings: true

# Set vulnerability thresholds; if the number of vulns is
# equal to or greater than any of the specified thresholds, 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.
# See 'action.yml' for additional input/output options.


# The following steps illustrate how to
# display scan results in the GitHub Actions job terminal.
# These examples simply print the output files to the console.
- 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 }}


206 changes: 159 additions & 47 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,112 +1,220 @@
## Amazon Inspector for GitHub Actions
# Vulnerability Scan GitHub Action for Amazon Inspector

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

Using this action, you can automatically scan supported artifacts with Amazon Inspector from your GitHub Actions workflows.
This GitHub Action allows you to scan supported artifacts for software vulnerabilities using Amazon Inspector from your GitHub Actions workflows.

An active AWS account is required to use this action.


## Overview

Amazon Inspector for GitHub Actions can be used to detect software vulnerabilities in the following artifacts within your GitHub Actions workflows:
This action works by first generating a CycloneDX software bill of materials (SBOM) for the provided artifact.

The SBOM is then sent to Amazon Inspector; Inspector scans the provided SBOM for known vulnerabilities, and returns its results to the calling action.

1. Package dependencies
This action can scan the following artifact types for software vulnerabilities:

1. Repository files and directories
2. Container images
3. Compiled Go and Rust binaries
4. Archives *(.zip, .tar, .tar.gz)*

This action is powered by the [Amazon Inspector SBOM Generator (inspector-sbomgen)](https://docs.aws.amazon.com/inspector/latest/user/sbom-generator.html).
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).


## Prerequisites

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).

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).

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.
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.

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).

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).

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".
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).

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).


## Usage

The following examples demonstrate how to use this action:
### Quick Start

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

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

```bash
# from your repository's root directory
touch .github/workflows/invoke_inspector_scan.yml
```

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

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

### 1. Scan Package Dependencies
```yaml
TODO: paste me / link me
```

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

```yaml
- name: Invoke Amazon Inspector Scan
uses: aws/amazon-inspector-github-actions-plugin@v1
with:
artifact_type: 'repository'
artifact_path: './' # change this if you would like to scan a specific sub-directory, otherwise the entire repo will be scanned.
```
GitHub should automatically run your new workflow; review its results and make any needed changes to the input and output arguments.


### Configuring Vulnerability Scan Outputs

This action provides detailed Inspector scan findings in JSON, CSV, and markdown, plus, a CycloneDX software bill of materials in JSON.

- [*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).
By default, this action will only display the number of vulnerabilities detected in the GitHub Actions job terminal; detailed findings are not shown.

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

### 2. Scan Container Image
The example below shows how to present this action's outputs in various locations and formats.
This example will scan a container image for vulnerable software packages.
Exercise caution to ensure you do not accidentally post vulnerability information to untrusted viewers.
```yaml
- name: Invoke Amazon Inspector Scan
uses: aws/amazon-inspector-github-actions-plugin@v1
- name: Scan container
id: inspector
uses: aws/vulnerability-scan-github-action-for-amazon-inspector@main
with:
artifact_type: 'container'
artifact_path: 'alpine:latest' # change this to the image you would like to scan
```
artifact_path: 'ubuntu:14.04'
# Display Inspector results in the GitHub Actions 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 }}
This action can scan containers exported as tarballs, locally built images, and images from remote registries.
- name: Display Inspector vulnerability scan results (CSV)
run: cat ${{ steps.inspector.outputs.inspector_scan_results_csv }}
For locally built images, this action only supports images built with Docker engine.
- [*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).
# Upload Inspector outputs as a .zip that can be downloaded
# from the GitHub actions job summary page.
- 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 }}
```
### Configuring Vulnerability Thresholds
This action allows the user to set vulnerability thresholds.
### 3. Scan Compiled Go or Rust Binary
Vulnerability thresholds can be used to support custom logic, such as failing the workflow if any vulnerabilities are found.
This example will scan a compiled Go or Rust binary's package dependencies for vulnerabiliies.
The example below shows how to set up vulnerability thresholds and fail the job when the threshold is exceeded:
```yaml
- name: Invoke Amazon Inspector Scan
uses: aws/amazon-inspector-github-actions-plugin@v1
id: inspector
uses: aws/vulnerability-scan-github-action-for-amazon-inspector@v1
with:
artifact_type: 'binary'
artifact_path: './path/to/binary' # change this to your binary's filepath
artifact_type: 'repository'
artifact_path: './'
# set vulnerability thresholds; if the number of vulnerabilities
# equals or exceeds any of the specified 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 are ignored
# by this action when determining whether the threshold was
# or was not exceeded.
critical_threshold: 1
high_threshold: 1
medium_threshold: 1
low_threshold: 0
other_threshold: 0
# Fail the job with 'exit 1' if vuln threshold flag is set
- name: On vulnerability threshold exceeded
run: exit ${{ steps.inspector.outputs.vulnerability_threshold_exceeded }}
```
### 4. Scan Archive
### Build and Scan Container Images
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.
This example will scan an archive for vulnerable software packages. The supported archive formats are **.zip**, **.tar**, and **.tar.gz**.
We provide an example of this workflow below:
```yaml
- name: Invoke Amazon Inspector Scan
uses: aws/amazon-inspector-github-actions-plugin@v1
with:
artifact_type: 'archive'
artifact_path: './path/to/archive' # change this to your archive's filepath
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: ${{ secrets.AWS_REGION }}
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
- name: Scan built image with Inspector
uses: aws/amazon-inspector-github-actions-plugin@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 Inputs
The following input options can be added to this action to control its behavior.
## Action Inputs and Outputs
See [action.yml](./action.yml) for more detail.
The following input and output options are provided by this action; see [action.yml](./action.yml) for more detail.
| Option | Required | Description |
|---|---|---|
Expand Down Expand Up @@ -137,6 +245,10 @@ The following outputs are set by this action:
| inspector_scan_results_csv | The filepath to the Inspector vulnerability scan in CSV format. |
| vulnerability_threshold_exceeded | This variable is set to 1 if any vulnerability threshold was exceeded, otherwise it is 0. |
## Get Help
TODO: add me
## Security
See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
Expand Down
6 changes: 6 additions & 0 deletions action.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,11 @@ inputs:
required: True
default: './'

display_vulnerability_findings:
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'
required: True
default: False

output_sbom_path:
description: "The destination file path for the generated SBOM."
required: False
Expand Down Expand Up @@ -104,6 +109,7 @@ runs:
args:
- --artifact-type=${{ inputs.artifact_type }}
- --artifact-path=${{ inputs.artifact_path }}
- --display-vuln-findings=${{ inputs.display_vulnerability_findings }}
- --out-sbom=${{ inputs.output_sbom_path}}
- --out-scan=${{ inputs.output_inspector_scan_path }}
- --out-scan-csv=${{ inputs.output_inspector_scan_path_csv }}
Expand Down
Loading
Loading