From c4f0e5e77743992e9bbaa12493b7f07346c8121d Mon Sep 17 00:00:00 2001 From: Michael Long Date: Tue, 23 Apr 2024 16:25:26 -0400 Subject: [PATCH] added 'display_vulnerability_findings' input arg --- .../workflows/example_display_findings.yml | 13 +- README.md | 174 ++++++++++-------- action.yml | 6 + entrypoint/entrypoint/cli.py | 2 + entrypoint/entrypoint/orchestrator.py | 6 +- 5 files changed, 118 insertions(+), 83 deletions(-) diff --git a/.github/workflows/example_display_findings.yml b/.github/workflows/example_display_findings.yml index 7dc36fe..1279e46 100644 --- a/.github/workflows/example_display_findings.yml +++ b/.github/workflows/example_display_findings.yml @@ -31,7 +31,7 @@ jobs: uses: aws/vulnerability-scan-github-action-for-amazon-inspector@main with: # change artifact_type to either 'repository', 'container', 'binary', or 'archive'. - # this example scans a legacy container image + # this example scans a container image artifact_type: 'container' # change artifact_path to the file path or container image you would like to scan. @@ -40,16 +40,13 @@ jobs: 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 a representative example: + # 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_findings: true + display_vulnerability_findings: true # Set vulnerability thresholds; if the number of vulns is - # equal to or greater than the specified threshold, set - # the 'vulnerability_threshold_exceeded' output to 1. - # This can be used to perform custom logic when - # vulnerability thresholds are exceeded, such as failing - # a job to prevent deploying a container with vulnerabilities. + # 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 diff --git a/README.md b/README.md index f2aea8a..03b543a 100644 --- a/README.md +++ b/README.md @@ -2,16 +2,20 @@ Amazon Inspector is a vulnerability management service that scans AWS workloads and [CycloneDX SBOMs](https://cyclonedx.org/) for known software vulnerabilities. -This GitHub Action allows you to scan supported artifacts for software vulnerabilities using Amazon Inspector. +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 -This action can detect software vulnerabilities in the following artifact types within your GitHub Actions workflows: +This action works by first generating a CycloneDX software bill of materials (SBOM) for the provided artifact. -1. Package dependencies +The SBOM is then sent to Amazon Inspector; Inspector scans the provided SBOM for known vulnerabilities, and returns its results to the calling action. + +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)* @@ -42,18 +46,18 @@ Perform the following steps to quickly add this action to your GitHub Actions pi 1. Create a new workflow file in your repository: -```bash -# from your repository's root directory -touch .github/workflows/invoke_inspector_scan.yml -``` + ```bash + # from your repository's root directory + touch .github/workflows/invoke_inspector_scan.yml + ``` 2. Copy and paste the following YAML block into your workflow file. -You will need to modify this workflow definition to suit your environment: + You will need to modify this workflow definition to suit your environment: -```yaml -TODO: paste me / link me -``` + ```yaml + TODO: paste me / link me + ``` 3. Save your workflow file then git commit / git push the workflow to GitHub. @@ -68,7 +72,9 @@ By default, this action will only display the number of vulnerabilities detected This is done so **you** can control how and where your vulnerability findings are presented and stored. -The example below shows how to present this action's outputs in various locations and formats: +The example below shows how to present this action's outputs in various locations and formats. + +Exercise caution to ensure you do not accidentally post vulnerability information to untrusted viewers. ```yaml - name: Scan container @@ -80,13 +86,13 @@ The example below shows how to present this action's outputs in various location # Display Inspector results in the GitHub Actions terminal - name: Display CycloneDX SBOM (JSON) -run: cat ${{ steps.inspector.outputs.artifact_sbom }} + run: cat ${{ steps.inspector.outputs.artifact_sbom }} - name: Display Inspector vulnerability scan results (JSON) -run: cat ${{ steps.inspector.outputs.inspector_scan_results }} + run: cat ${{ steps.inspector.outputs.inspector_scan_results }} - name: Display Inspector vulnerability scan results (CSV) -run: cat ${{ steps.inspector.outputs.inspector_scan_results_csv }} + run: cat ${{ steps.inspector.outputs.inspector_scan_results_csv }} # Upload Inspector outputs as a .zip that can be downloaded @@ -95,7 +101,6 @@ run: cat ${{ steps.inspector.outputs.inspector_scan_results_csv }} id: inspector 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 }} @@ -106,9 +111,9 @@ run: cat ${{ steps.inspector.outputs.inspector_scan_results_csv }} This action allows the user to set vulnerability thresholds. -If the number of vulnerabilities found is greater than or equal to the provided vulnerability threshold, the `vulnerability_threshold_exceeded` output argument will be set to 1. If the vulnerability threshold is NOT exceeded, `vulnerability_threshold_exceeded` is set to 0. This can be used to setup custom logic when vulnerability thresholds are exceeded, such as failing the job to avoid publishing an artifact with known vulnerabilities. +Vulnerability thresholds can be used to support custom logic, such as failing the workflow if any vulnerabilities are found. -The example below shows how to setup vulnerability thresholds and fail the job when the threshold is exceeded: +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 @@ -118,75 +123,94 @@ The example below shows how to setup vulnerability thresholds and fail the job w artifact_type: 'repository' artifact_path: './' - # set vulnerability thresholds + # 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: 1 - other_threshold: 1 + low_threshold: 0 + other_threshold: 0 -# Fail the job with 'exit 1' if vuln threshold is exceeded +# 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 }} ``` -### 1. Scan Package Dependencies +### Build and Scan Container Images -This example will scan your repository contents for vulnerable software packages, based on contents from files known to contain package information, such as Python's requirements.txt file. +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. -```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. -``` - -- [*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). - - -### 2. Scan Container Image - -This example will scan a container image for vulnerable software packages. +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: 'container' - artifact_path: 'alpine:latest' # change this to the image you would like to scan +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 ``` -This action can scan containers exported as tarballs, locally built images, and images from remote registries. - -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). - - -### 3. Scan Compiled Go or Rust Binary - -This example will scan a compiled Go or Rust binary's package dependencies for vulnerabiliies. - -```yaml -- name: Invoke Amazon Inspector Scan - uses: aws/amazon-inspector-github-actions-plugin@v1 - with: - artifact_type: 'binary' - artifact_path: './path/to/binary' # change this to your binary's filepath -``` - -### 4. Scan Archive - -This example will scan an archive for vulnerable software packages. The supported archive formats are **.zip**, **.tar**, and **.tar.gz**. - -```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 -``` ## Action Inputs and Outputs @@ -221,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,