From c715a2b0a797347d4723d315264fad4f37488dcc Mon Sep 17 00:00:00 2001 From: Michael Long <31821088+bluesentinelsec@users.noreply.github.com> Date: Tue, 23 Apr 2024 16:37:47 -0400 Subject: [PATCH] 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 --- .../workflows/example_display_findings.yml | 97 +++++++++ README.md | 206 ++++++++++++++---- action.yml | 6 + entrypoint/entrypoint/cli.py | 2 + entrypoint/entrypoint/orchestrator.py | 6 +- 5 files changed, 268 insertions(+), 49 deletions(-) create mode 100644 .github/workflows/example_display_findings.yml diff --git a/.github/workflows/example_display_findings.yml b/.github/workflows/example_display_findings.yml new file mode 100644 index 0000000..bdc3282 --- /dev/null +++ b/.github/workflows/example_display_findings.yml @@ -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 }} + + diff --git a/README.md b/README.md index df691f5..03b543a 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,27 @@ -## 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 @@ -22,91 +29,192 @@ This action is powered by the [Amazon Inspector SBOM Generator (inspector-sbomge 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 | |---|---|---| @@ -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. diff --git a/action.yml b/action.yml index 1a6c3dc..bc350ba 100644 --- a/action.yml +++ b/action.yml @@ -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 @@ -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 }} diff --git a/entrypoint/entrypoint/cli.py b/entrypoint/entrypoint/cli.py index fc50dfa..abc835f 100644 --- a/entrypoint/entrypoint/cli.py +++ b/entrypoint/entrypoint/cli.py @@ -42,6 +42,8 @@ def init(sys_argv=None) -> argparse.Namespace: help="Specifies one or more files and/or directories that should NOT be inventoried.") parser.add_argument("--timeout", type=str, default="600", help="The amount of time in seconds that inspector-sbomgne will run. When this timeout is exceeded, sbomgen will gracefully conclude and present any findings discovered up to that point.") + parser.add_argument("--display-vuln-findings", action='store_true', + help="If toggled, this program will present Inspector findings in the GitHub Actions job summary page") args = "" if sys_argv: diff --git a/entrypoint/entrypoint/orchestrator.py b/entrypoint/entrypoint/orchestrator.py index 5e164d3..931ad7e 100644 --- a/entrypoint/entrypoint/orchestrator.py +++ b/entrypoint/entrypoint/orchestrator.py @@ -333,8 +333,10 @@ def execute(args) -> int: mediums=mediums, lows=lows, others=others) - logging.info("posting markdown to job summary") - converter.post_github_step_summary(markdown) + + if args.display_vuln_findings: + logging.info("posting markdown to job summary") + converter.post_github_step_summary(markdown) is_exceeded = exceeds_threshold(criticals, args.critical, highs, args.high,