diff --git a/README.md b/README.md index 03b543a..b0d9482 100644 --- a/README.md +++ b/README.md @@ -1,42 +1,54 @@ # 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. +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 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 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. +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 +1. Files and directories in your GitHub repository 2. Container images -3. Compiled Go and Rust binaries +3. Compiled Go and Rust binaries (*stripped and obfuscated binaries are not supported*) 4. Archives *(.zip, .tar, .tar.gz)* -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). - +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). +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). +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 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. +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). +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. **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). +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 @@ -44,31 +56,120 @@ To learn more about this action's supported artifacts, please see our documentat Perform the following steps to quickly add this action to your GitHub Actions pipeline: -1. Create a new workflow file in your repository: - - ```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. +1. Copy and paste the following YAML block into your workflow file. - You will need to modify this workflow definition to suit your environment: + **Read through this workflow definition and make changes to suit your environment**: ```yaml - TODO: paste me / link me + 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 }} ``` -3. Save your workflow file then git commit / git push the workflow to GitHub. +2. Save your workflow file then git commit / git push the workflow to GitHub. -GitHub should automatically run your new workflow; review its results and make any needed changes to the input and output arguments. +GitHub should automatically run your new workflow; review its results and make any needed changes to the input and +output arguments. +For additional examples, see [this repository's workflow definitions](.github/workflows/). ### 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. +This action provides detailed Inspector scan findings in JSON, CSV, and markdown, plus, a CycloneDX software bill of +materials in JSON. -By default, this action will only display the number of vulnerabilities detected in the GitHub Actions job terminal; detailed findings are not shown. +By default, this action will only display the number of vulnerabilities detected in the GitHub Actions job terminal; +detailed vulnerability findings are not shown. This is done so **you** can control how and where your vulnerability findings are presented and stored. @@ -79,10 +180,11 @@ Exercise caution to ensure you do not accidentally post vulnerability informatio ```yaml - name: Scan container id: inspector - uses: aws/vulnerability-scan-github-action-for-amazon-inspector@main + uses: aws/vulnerability-scan-github-action-for-amazon-inspector@v1 with: artifact_type: 'container' artifact_path: 'ubuntu:14.04' + display_vulnerability_findings: "enabled" # Display Inspector results in the GitHub Actions terminal - name: Display CycloneDX SBOM (JSON) @@ -94,6 +196,9 @@ Exercise caution to ensure you do not accidentally post vulnerability informatio - 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 }} + # Upload Inspector outputs as a .zip that can be downloaded # from the GitHub actions job summary page. @@ -111,7 +216,8 @@ Exercise caution to ensure you do not accidentally post vulnerability informatio This action allows the user to set vulnerability thresholds. -Vulnerability thresholds can be used to support custom logic, such as failing the workflow if any vulnerabilities are found. +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 set up vulnerability thresholds and fail the job when the threshold is exceeded: @@ -122,16 +228,16 @@ The example below shows how to set up vulnerability thresholds and fail the job with: artifact_type: 'repository' artifact_path: './' + display_vulnerability_findings: "enabled" - # set vulnerability thresholds; if the number of vulnerabilities - # equals or exceeds any of the specified thresholds, this action + # 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 are ignored - # by this action when determining whether the threshold was - # or was not exceeded. + # are found; lows and other type vulnerabilities will not set + # the 'vulnerability_threshold_exceeded' flag. critical_threshold: 1 high_threshold: 1 medium_threshold: 1 @@ -145,14 +251,15 @@ The example below shows how to set up vulnerability thresholds and fail the job ### 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 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. -We provide an example of this workflow below: +We provide an example of this workflow below; you must modify this workflow to suit your environment: ```yaml name: Build & Scan Container Image -on: [push] +on: [ push ] jobs: build: @@ -188,9 +295,8 @@ jobs: - 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 }} + aws-region: "us-east-1" + role-to-assume: "arn:aws:iam:::role/" - name: Scan built image with Inspector uses: aws/amazon-inspector-github-actions-plugin@v1 @@ -211,43 +317,57 @@ jobs: # add any additional steps for deploying your image ``` - ## Action Inputs and Outputs The following input and output options are provided by this action; see [action.yml](./action.yml) for more detail. -| Option | Required | Description | -|---|---|---| -| artifact_type | **Yes** | The artifact you would like to scan with Amazon Inspector. Valid choices are "repository", "container", "binary", or "archive". | -| artifact_path | **Yes** | The path to the artifact you would like to scan with Amazon Inspector. If scanning a container image, you must provide a value that follows the docker pull convention: "NAME[:TAG\|@DIGEST]", for example, "alpine:latest", or a path to an image exported as tarball using "docker save". | -| output_sbom_path | No | The destination file path for the generated SBOM. | -| output_inspector_scan_path | No | The destination file path for Inspector's vulnerability scan (JSON format). | -| output_inspector_scan_path_csv | No | The destination file path for Inspector's vulnerability scan (CSV format). | -| sbomgen_version | No | The inspector-sbomgen version you wish to use for SBOM generation. See [here for more info](https://docs.aws.amazon.com/inspector/latest/user/sbom-generator.html). | -| critical_threshold | No | Specifies the number of critical vulnerabilities to trigger job failure. | -| high_threshold | No | Specifies the number of high vulnerabilities to trigger job failure. | -| medium_threshold | No | Specifies the number of medium vulnerabilities to trigger job failure. | -| low_threshold | No | Specifies the number of low vulnerabilities to trigger job failure. | -| other_threshold | No | Specifies the number of 'other' vulnerabilities to trigger job failure, such as 'info', 'none', or 'unknown'. | -| scanners | No | Specifies the file scanners that you would like inspector-sbomgen to execute. By default, inspector-sbomgen will try to run all file scanners that are applicable to the target artifact. If this argument is set, inspector-sbomgen will only execute the specified file scanners. Provide your input as a single string. Separate each file scanner with a comma. To view a list of available file scanners, execute `inspector-sbomgen list-scanners`. [See here for more info](https://docs.aws.amazon.com/inspector/latest/user/sbom-generator.html). | -| skip_scanners | No | Specifies a list of file scanners that should NOT be executed; this argument cannot be combined with 'scanners'. If this argument is set, inspector-sbomgen will execute all file scanners except those you specified. Provide your input as a single string. Separate each file scanner with a comma. To view a list of available file scanners, execute `inspector-sbomgen list-scanners`. See [here for more info](https://docs.aws.amazon.com/inspector/latest/user/sbom-generator.html). | -| skip_files | No | Specifies one or more files and/or directories that should NOT be inventoried. Separate each file with a comma and enclose the entire string in double quotes. | -| timeout | No | Specifies a timeout in seconds. If this timeout is exceeded, the action will gracefully conclude and present any findings discovered up to that point. | - -## Action Outputs - -The following outputs are set by this action: - -| **Option** | **Description** | +### Input Options + +| **Name** | **Description** | **Required** | **Default** | +|---|---|---|---| +| artifact_type | The artifact you would like to scan with Amazon Inspector. Valid choices are "repository", "container", "binary", or "archive". | True | repository | +| artifact_path | The file path to the artifact you would like to scan with Amazon Inspector. File paths are relative to the root project directory. If scanning a container image, you must provide a value that follows the docker pull convention: "NAME[:TAG\|@DIGEST]", for example, "alpine:latest", or a path to an image exported as tarball using "docker save". | True | ./ | +| display_vulnerability_findings | If set to "enabled", 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 | True | disabled | +| output_sbom_path | The destination file path for the generated SBOM. | False | ./sbom_${{ github.run_id }}.json | +| output_inspector_scan_path | The destination file path for Inspector's vulnerability scan (JSON format). | False | inspector_scan_${{ github.run_id }}.json | +| output_inspector_scan_path_csv | The destination file path for Inspector's vulnerability scan (CSV format). | False | inspector_scan_${{ github.run_id }}.csv | +| output_inspector_scan_path_markdown | The destination file path for Inspector's vulnerability scan (markdown format). | False | inspector_scan_${{ github.run_id }}.md | +| sbomgen_version | The inspector-sbomgen version you wish to use for SBOM generation. See here for more info: https://docs.aws.amazon.com/inspector/latest/user/sbom-generator.html | False | latest | +| critical_threshold | Specifies the number of critical vulnerabilities needed to set the 'vulnerability_threshold_exceeded' flag. | False | 0 | +| high_threshold | Specifies the number of high vulnerabilities needed to set the 'vulnerability_threshold_exceeded' flag. | False | 0 | +| medium_threshold | Specifies the number of medium vulnerabilities needed to set the 'vulnerability_threshold_exceeded' flag. | False | 0 | +| low_threshold | Specifies the number of low vulnerabilities needed to set the 'vulnerability_threshold_exceeded' flag. | False | 0 | +| other_threshold | Specifies the number of other vulnerabilities needed to set the 'vulnerability_threshold_exceeded' flag. | False | 0 | +| scanners | Specifies the file scanners that you would like inspector-sbomgen to execute. By default, inspector-sbomgen will try to run all file scanners that are applicable to the target artifact. If this argument is set, inspector-sbomgen will only execute the specified file scanners. Provide your input as a single string. Separate each file scanner with a comma. For example: scanners: dpkg,python-requirements,javascript-nodejsTo view a list of available file scanners, execute 'inspector-sbomgen list-scanners'. See here for more info: https://docs.aws.amazon.com/inspector/latest/user/sbom-generator.html | False | '' | +| skip_scanners | Specifies a list of file scanners that should NOT be executed; this argument cannot be combined with 'scanners'. If this argument is set, inspector-sbomgen will execute all file scanners except those you specified. Provide your input as a single string. Separate each file scanner with a comma. For example: skip_scanners: 'binaries,alpine-apk,dpkg,php'To view a list of available file scanners, execute 'inspector-sbomgen list-scanners'. See here for more info: https://docs.aws.amazon.com/inspector/latest/user/sbom-generator.html | False | '' | +| skip_files | Specifies one or more files and/or directories that should NOT be inventoried. Separate each file with a comma and enclose the entire string in double quotes, for example: skip_files: "./media,/tmp/foo/,/bar/my_program" | False | '' | +| timeout | Specifies a timeout in seconds. If this timeout is exceeded, the action will gracefully conclude and present any findings discovered up to that point. Default value is 600 seconds or 10 minutes. | False | 600 | + +### Output Options + +| **Name** | **Description** | |---|---| -| artifact_sbom | The filepath to the generated SBOM. | -| inspector_scan_results | The filepath to the Inspector vulnerability scan in JSON format. | -| 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. | +| artifact_sbom | The file path to the artifact's software bill of materials. | +| inspector_scan_results | The file path to the Inspector vulnerability scan findings in JSON format. | +| inspector_scan_results_csv | The file path to the Inspector vulnerability scan findings in CSV format. | +| inspector_scan_results_markdown | The file path to the Inspector vulnerability scan findings in markdown format. | +| vulnerability_threshold_exceeded | This variable is set to 1 if any vulnerability threshold was exceeded, otherwise it is 0. This variable can be used to trigger custom logic, such as failing the job if vulnerabilities were detected. | ## Get Help -TODO: add me +For general questions about this action, please post your question to the project's discussion page: + +- https://github.com/aws-actions/vulnerability-scan-github-action-for-amazon-inspector/discussions + +You may also consider exploring these resources for additional help with AWS products and services: + +- https://repost.aws/knowledge-center/get-aws-help + +## Bugs + +If you encountered a bug, please open a GitHub issue: + +- https://github.com/aws-actions/vulnerability-scan-github-action-for-amazon-inspector/issues/new/choose ## Security diff --git a/action.yml b/action.yml index eebbbd6..d498236 100644 --- a/action.yml +++ b/action.yml @@ -8,7 +8,7 @@ inputs: default: 'repository' artifact_path: - description: 'The path to the artifact you would like to scan with Amazon Inspector. If scanning a container image, you must provide a value that follows the docker pull convention: "NAME[:TAG|@DIGEST]", for example, "alpine:latest", or a path to an image exported as tarball using "docker save".' + description: 'The file path to the artifact you would like to scan with Amazon Inspector. File paths are relative to the root project directory. If scanning a container image, you must provide a value that follows the docker pull convention: "NAME[:TAG|@DIGEST]", for example, "alpine:latest", or a path to an image exported as tarball using "docker save".' required: True default: './' @@ -33,39 +33,37 @@ inputs: default: 'inspector_scan_${{ github.run_id }}.csv' output_inspector_scan_path_markdown: - description: "The destination file path for Inspector's vulnerability scan (CSV format)." + description: "The destination file path for Inspector's vulnerability scan (markdown format)." required: False default: 'inspector_scan_${{ github.run_id }}.md' - sbomgen_version: description: "The inspector-sbomgen version you wish to use for SBOM generation. See here for more info: https://docs.aws.amazon.com/inspector/latest/user/sbom-generator.html" required: False default: "latest" - critical_threshold: - description: "Specifies the number of critical vulnerabilities to trigger job failure." + description: "Specifies the number of critical vulnerabilities needed to set the 'vulnerability_threshold_exceeded' flag." required: False default: 0 high_threshold: - description: "Specifies the number of high vulnerabilities to trigger job failure." + description: "Specifies the number of high vulnerabilities needed to set the 'vulnerability_threshold_exceeded' flag." required: False default: 0 medium_threshold: - description: "Specifies the number of medium vulnerabilities to trigger job failure." + description: "Specifies the number of medium vulnerabilities needed to set the 'vulnerability_threshold_exceeded' flag." required: False default: 0 low_threshold: - description: "Specifies the number of low vulnerabilities to trigger job failure." + description: "Specifies the number of low vulnerabilities needed to set the 'vulnerability_threshold_exceeded' flag." required: False default: 0 other_threshold: - description: "Specifies the number of 'other' vulnerabilities to trigger job failure, such as 'info', 'none', or 'unknown'." + description: "Specifies the number of other vulnerabilities needed to set the 'vulnerability_threshold_exceeded' flag." required: False default: 0 @@ -97,19 +95,19 @@ inputs: outputs: artifact_sbom: - description: "The filepath to the artifact SBOM." + description: "The filepath to the artifact's software bill of materials." inspector_scan_results: - description: "The filepath to the Inspector vulnerability scan in JSON format." + description: "The file path to the Inspector vulnerability scan findings in JSON format." inspector_scan_results_csv: - description: "The filepath to the Inspector vulnerability scan in CSV format." + description: "The file path to the Inspector vulnerability scan findings in CSV format." inspector_scan_results_markdown: - description: "The filepath to the Inspector vulnerability scan in markdown format." + description: "The file path to the Inspector vulnerability scan findings in markdown format." vulnerability_threshold_exceeded: - description: "This variable is set to 1 if any vulnerability threshold was exceeded, otherwise it is 0." + description: "This variable is set to 1 if any vulnerability threshold was exceeded, otherwise it is 0. This variable can be used to trigger custom logic, such as failing the job if vulnerabilities were detected." runs: using: 'docker'