Added integration tests and updated documentation (#9)

Added integration tests and also updated documentation.

---------

Co-authored-by: Adish Agarwal <[email protected]>

Author: adishagarwal

.github/workflows/test.yml

@@ -54,4 +54,139 @@ jobs:
       - name: 'npm test'
         run: 'npm run test'
 
-## TODO : Add functionality specific test
+  integration:
+    permissions:
+      contents: 'read'
+      id-token: 'write'
+    runs-on: 'ubuntu-latest'
+
+    env:
+      ORGANIZATION_ID: '777838403257'
+    
+    steps:
+      - uses: 'actions/checkout@v4'
+
+      - uses: 'actions/setup-node@v4'
+        with:
+          node-version: '20.x'
+
+      - name: 'npm build'
+        run: 'npm ci && npm run build'
+
+      - uses: 'google-github-actions/auth@v2'
+        with:
+          workload_identity_provider: 'projects/111685897256/locations/global/workloadIdentityPools/github/providers/my-repo' 
+          service_account: '[email protected]'
+
+      - id: 'violations-found'
+        name: 'Violations found in plan file'
+        uses: './'
+        with:
+          organization_id: '${{ env.ORGANIZATION_ID }}'
+          # plan file has 1 CRITICAL, 2 LOW severity vulnerabilites
+          scan_file_ref: 'test/resources/with-violations-tf_plan.json'
+          iac_type: 'terraform'
+          iac_version: '1.0.0'
+          failure_criteria: 'CRITICAL:2, Operator:OR'
+          ignore_violations: 'false'
+          fail_silently: 'false'
+          scan_timeout: '1m'
+      - name: 'Check scan result and compare sarif report generated.'
+        run: |
+          report_expected="test/resources/sarif.json"
+          report_generated="${{ steps.violations-found.outputs.iac_scan_result_sarif_path }}"
+          if cmp -s "$report_expected" "$report_generated"; then
+            exit 1
+          fi
+          if [ "${{ steps.violations-found.outputs.iac_scan_result }}" != "passed" ]; then
+            exit 1
+          fi
+
+      - id: 'no-violations-found'
+        name: 'No violations found in plan file'
+        uses: './'
+        with:
+          organization_id: '${{ env.ORGANIZATION_ID }}'
+          scan_file_ref: 'test/resources/no-violations-tf_plan.json'
+          iac_type: 'terraform'
+          iac_version: '1.0.0'
+          failure_criteria: 'CRITICAL:2, Operator:OR'
+      - name: 'Check scan result and report not generated.'
+        run: |
+          if [ "${{ steps.no-violations-found.outputs.iac_scan_result_sarif_path }}" != "" ]; then
+            exit 1
+          fi
+          if [ "${{ steps.no-violations-found.outputs.iac_scan_result }}" != "passed" ]; then
+            exit 1
+          fi
+    
+      - id: 'failure-criteria-satisfied'
+        name: 'Failure criteria satisfied'
+        uses: './'
+        with:
+          organization_id: '${{ env.ORGANIZATION_ID }}'
+          # plan file has 1 CRITICAL, 2 LOW severity vulnerabilites
+          scan_file_ref: 'test/resources/with-violations-tf_plan.json'
+          iac_type: 'terraform'
+          iac_version: '1.0.0'
+          failure_criteria: 'CRITICAL:1, Operator:OR'
+        continue-on-error: true
+      - name: 'Check scan result and action build status'
+        run: |
+          if [ "${{ steps.failure-criteria-satisfied.outputs.iac_scan_result }}" != "failed" ]; then
+            exit 1
+          fi
+          if [ "${{ steps.failure-criteria-satisfied.outcome }}" != "failure"]; then
+           exit 1
+          fi
+
+      - id: 'failure-criteria-satisfied-ignore-violations-true'
+        name: 'Failure criteria satisfied, ignore violations true'
+        uses: './'
+        with:
+          organization_id: '${{ env.ORGANIZATION_ID }}'
+          # plan file has 1 CRITICAL, 2 LOW severity vulnerabilites
+          scan_file_ref: 'test/resources/with-violations-tf_plan.json'
+          iac_type: 'terraform'
+          iac_version: '1.0.0'
+          ignore_violations: 'true'
+          failure_criteria: 'CRITICAL:1, Operator:OR'
+      - name: 'Check scan result'
+        run: |
+          if [ "${{ steps.failure-criteria-satisfied-ignore-violations-true.outputs.iac_scan_result }}" != "failed" ]; then
+            exit 1
+          fi
+      
+      - id: 'action-internal-error'
+        name: 'Action internal error'
+        uses: './'
+        with:
+          # Invalid org id, will cause an internal error in action
+          organization_id: 'invalid-id'
+          scan_file_ref: 'test/resources/with-violations-tf_plan.json'
+          iac_type: 'terraform'
+          iac_version: '1.0.0'
+        continue-on-error: true
+      - name: 'Check scan result and build status'
+        run: |
+          if [ "${{ steps.action-internal-error.outputs.iac_scan_result }}" != "error" ]; then
+            exit 1
+          fi
+          if [ "${{ steps.action-internal-error.outcome }}" != "failure" ]; then
+            exit 1
+          fi
+
+      - id: 'action-internal-error-fail-silently-true'
+        name: 'Action internal error, fail silently true'
+        uses: './'
+        with:
+          organization_id: 'invalid-id'
+          scan_file_ref: 'test/resources/with-violations-tf_plan.json'
+          iac_type: 'terraform'
+          iac_version: '1.0.0'
+          fail_silently: 'true'
+      - name: Check scan result 
+        run: |
+          if [ "${{ steps.action-internal-error-fail-silently-true.outputs.iac_scan_result }}" != "error" ]; then
+            exit 1
+          fi

README.md

@@ -2,20 +2,30 @@
 
 ## Description
 
-This Github Action scans Infrastructure as Code (IaC) files for security risks. When a scan finds violations, this action will write the report in SARIF format to the workspace.
-Currently only terraform plan files are supported for scanning.
+This Github action identifies insecure configurations in Infrastructure as Code (IaC) files for Google Cloud resources. 
+This action requires Terraform plan files in JSON format for scanning.
+
+Use this action to detect and remediate issues in IaC files for Google Cloud before you deploy the resources.
+
+This action lets you:
+- Scan IaC template files (such as Terraform plan files).
+- Display issues with their severity as a SARIF Report in the GitHub Workspace after a scan completes.
+- Define severity-based failure criteria for passing or failing the build.
+
+> [!NOTE] 
+> This is a Security Command Center Premium tier offering for subscription customers only. You must activate the Security Command Center Premium tier in the Google Cloud organization to use this feature.
 
 ## Prerequisites
 
--   This action requires a service account which have **Security Posture
-    Shift-Left Validator or Security Posture Admin** Role on the Google Cloud
-    organization to which IaC resources belong's. See
-    [Authorization](#authorization) for more information.
+-   This action requires a Google Cloud service account which has the 
+    **Security Posture Shift-Left Validator** role or the **Security 
+    Posture Admin** role on the Google Cloud organization that includes 
+    the IaC resources. For more information, see [Authorization](#authorization).
 
 -   This action runs using Node 20. If you are using self-hosted GitHub Actions
     runners, you must use a [runner
     version](https://github.com/actions/virtual-environments) that supports this
-    version or newer.
+    version or later.
 
 ## Usage
 
@@ -54,34 +64,38 @@ jobs:
 
 ## Inputs
 
--   `organization_id`: (Required) ID of the Google Cloud organization which owns
-    resources under modification.
+-   `organization_id`: (Required) The Google Cloud organization ID for the 
+    organization which includes the resources that you want to modify.
 
--   `scan_file_ref`: (Required) Absolute file path including file name where the
-    IaC file is stored in the workspace. Examples: 'tf_plan.json',
-    'artifacts/tf_plan.json'.
+-   `scan_file_ref`: (Required) The absolute file path, including the file name, 
+    for the IaC file in the workspace. For example: './tf_plan.json', or 
+    './artifacts/tf_plan.json'.
 
--   `iac_type`: (Required) IaC template type. Currently only Terraform is
+-   `iac_type`: (Required) The IaC template type. Currently only Terraform is
     supported.
 
--   `iac_version`: (Required) IaC template version. Examples: '1.6.6', '1.6.5'.
+-   `iac_version`: (Required) The IaC template version. For example: '1.6.6', 
+    or '1.6.5'.
 
--   `scan_timeout`: (Optional) Max time upto which action should run, should be
-    between '1m' and '10m'. Default: 1m.
+-   `scan_timeout`: (Optional) The maximum time before the action stops. 
+    The time must be between '1m' and '10m'. The default is `1m`.
 
--   `ignore_violations`: (Optional) If set to true, violations found in IaC file
-    will be ignored to determine build status. Although violations will not be
-    ignored to generate SARIF report and determining iac_scan_result. Default:
-    false.
+-   `ignore_violations`: (Optional) Whether violations found in IaC file 
+    should be ignored when determining the build status. This input doesn’t 
+    apply to  violations that are related to generating SARIF reports and 
+    determining the `iac_scan_result`. The default is `false`.
 
--   `failure_criteria`: (Optional) Failure criteria evaluates workflow build
-    status. It contains threshold for count of critical, high, medium, and low
-    severity issues and `AND/OR` based aggregator to evaluate the criteria. The
-    threshold for each severity is evaluated against count of issues with
-    similar severity in IaC scan result and then severity level evaluations are
-    aggregated using `AND\OR` to arrive at failure_criteria value.
+-   `failure_criteria`: (Optional) The failure criteria that determines the 
+    workflow build status. You can set a threshold for the number of critical, 
+    high, medium, and low severity issues and use an aggregator  (either `and` 
+    or `or`) to evaluate the criteria. To determine whether a build has failed, 
+    the threshold for each severity is evaluated against the count of issues 
+    with that severity in the IaC scan results and then severity level evaluations 
+    are aggregated using `AND` or `OR` to arrive at `failure_criteria` value.
 
-    If `failure_criteria` evaluates to true, workflow is marked as `FAILED` otherwise workflow is marked as `SUCCESS`. Default: "Critical:1, High:1, Medium:1, Low:1, Operator:or".
+    If the `failure_criteria` evaluates to `true`, the workflow is marked as 
+    `FAILED`. Otherwise, the workflow is marked as `SUCCESS`. The default is 
+    "Critical:1, High:1, Medium:1, Low:1, Operator:or".
 
 -   `fail_silently`: (Optional) If set to true, workflow will not fail in case
     of any internal error including invalid credentials and plugin dependency
@@ -90,22 +104,22 @@ jobs:
 
 ## Outputs
 
--   `iac_scan_result`: Security Scan Result. One of:
+-   `iac_scan_result`: The result of the security scan. One of:
 
-    1.  `passed` - no violations found or the `failure_criteria` was not
+    1.  `passed` - No violations were found or the `failure_criteria` was not
         satisfied.
-    2.  `failed` - `failure_criteria` was satisfied.
-    3.  `error` - Action ran into execution error, generally due to
-        misconfiguration or invalid credentials.
+    2.  `failed` - The `failure_criteria` was satisfied.
+    3.  `error` - The action ran into an execution error, generally 
+        due to a misconfiguration or invalid credentials.
 
--   `iac_scan_result_sarif_path`: Path for the SARIF Report file. This is only
-    available when violations are found in the scan file.
+-   `iac_scan_result_sarif_path`: The path for the SARIF report file. This 
+    file is only available when violations are found in the scan file.
 
 ## Authorization
 
 Use [google-github-actions/auth](https://github.com/google-github-actions/auth)
 to authenticate the action. You can use [Workload Identity Federation][wif] or
-traditional [Service Account Key JSON][sa] authentication.
+traditional [Service Account Key JSON][sa] for authentication.
 
 ```yaml
 jobs:

action.yml

@@ -20,61 +20,65 @@ description: |-
 inputs:
   organization_id:
     description: |-
-      Google Cloud OrganizationId which owns resources under modification.
+      The Google Cloud organization ID for the organization which includes 
+      the resources that you want to modify.
     required: true
   scan_file_ref:
     description: |-
-      Absolute file path including file name where the IaC file is stored in the workspace.
-      Ex: 'tf_plan.json', 'artifacts/tf_plan.json'.
+      The absolute file path, including the file name, for the IaC file in the 
+      workspace. For example: './tf_plan.json', or './artifacts/tf_plan.json'.
     required: true
   iac_type:
     description: |-
-      IaC template type. Currently only terraform is supported.
+      The IaC template type. Currently only Terraform is supported.
     required: true
   iac_version:
     description: |-
-      IaC template version. Examples: '1.6.6', '1.6.5'.
+      The IaC template version. For example: '1.6.6', or '1.6.5'.
     required: true
   scan_timeout:
     description: |-
-      Max time upto which action should run, should be between '1m' and '10m'.
+      The maximum time before the action stops. The time must be between '1m' and '10m'. 
     default: '1m'
     required: false
   ignore_violations:
     description: |-
-      If set to true, violations found in IaC file will be ignored to determine build status.
-      Although violations will not be ignored to generate SARIF report and determining
-      iac_scan_result.
+      Whether violations found in IaC file should be ignored when determining 
+      the build status. This input doesn’t apply to  violations that are 
+      related to generating SARIF reports and determining the `iac_scan_result`. 
     default: false
     required: false
   failure_criteria:
     description: |-
-      Failure criteria evaluates workflow build status. It contains threshold for count of
-      critical, high, medium, and low severity issues and AND/OR based aggregator to evaluate
-      the criteria. The threshold for each severity is evaluated against count of issues with
-      similar severity in IaC scan result and then severity level evaluations are aggregated using
-      AND\OR to arrive at failure_criteria value.
-      If failure_criteria evaluates to true, workflow is marked as FAILED otherwise workflow is marked as SUCCESS.
-    default: 'Critical:1, High:1, Medium:1, Low:1, Operator:or'
+      The failure criteria that determines the workflow build status. You can set 
+      a threshold for the number of critical, high, medium, and low severity 
+      issues and use an aggregator  (either `and` or `or`) to evaluate the criteria. 
+      To determine whether a build has failed, the threshold for each severity is 
+      evaluated against the count of issues with that severity in the IaC scan 
+      results and then severity level evaluations are aggregated using `AND` or `OR` 
+      to arrive at `failure_criteria` value.
+      If the `failure_criteria` evaluates to `true`, the workflow is marked as `FAILED`. 
+      Otherwise, the workflow is marked as `SUCCESS`.
+    default: 'Critical:1, High:1, Medium:1, Low:1, Operator:OR'
     required: false
   fail_silently:
     description: |-
-      If set to true, workflow will not fail in case of any internal error including invalid credentials
-      and plugin dependency failure.
-      Note: Action will always fail in case of any input validation failure.
+      If set to true, workflow will not fail in case of any internal error including 
+      invalid credentials and plugin dependency failure. 
+      Note: Action will always fail in case of any input validationfailure.
     default: false
     required: false
 
 outputs:
   iac_scan_result:
     description: |-
-      Security Scan Result. One of:
-      `passed` - no violations found or failure_criteria was not satisfied.
-      `failed` - failure_criteria was satisfied.
-      `error` - Action ran into execution error, generally due to misconfiguration or invalid credentials.
+      The result of the security scan. One of:
+      `passed` - No violations were found or the `failure_criteria` was not satisfied.
+      `failed` - The `failure_criteria` was satisfied.
+      `error` - The action ran into an execution error, generally due to a misconfiguration or invalid credentials.
   iac_scan_result_sarif_path:
     description: |-
-      Path for the SARIF Report file. This is only available when violations are found in the scan file.
+      The path for the SARIF report file. This file is only available when violations are found in the scan file.
 
 runs:
   using: 'node20'