added 'display_vulnerability_findings' input arg

aws-actions · Apr 23, 2024 · c4f0e5e · c4f0e5e
1 parent faff66b
commit c4f0e5e
Show file tree

Hide file tree

Showing 5 changed files with 118 additions and 83 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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,