Merge pull request #112 from snyk/fix/iac-test-readme

fix: refined iac test action readme [CFG-1631]
snyk · Nov 29, 2022 · 1cc9026 · 1cc9026
2 parents a8dd587 + fa1c578
commit 1cc9026
Show file tree

Hide file tree

Showing 2 changed files with 81 additions and 48 deletions.
diff --git a/iac/README.md b/iac/README.md
@@ -12,26 +12,32 @@ jobs:
   security:
     runs-on: ubuntu-latest
     steps:
+      - uses: actions/checkout@v2
       - name: Run Snyk to check Kubernetes manifest file for issues
         uses: snyk/actions/iac@master
         env:
           SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
-        with:
-          file: your/kubernetes-manifest.yaml
 ```
 
+In order to use the Snyk Infrastructure as Code Test Action, you will need to have a Snyk API token. 
+More details in [Getting Your Snyk Token](https://github.com/snyk/actions#getting-your-snyk-token), or you can [sign up for free](https://snyk.io/login).  
+
+
 The Snyk Infrastructure as Code Action has properties which are passed to the underlying image. These are
-passed to the action using `with`.
+passed to the action using `with`:
 
-| Property | Default | Description                                                      |
-|----------|---------|------------------------------------------------------------------|
-| args     |         | Override the default arguments to the Snyk image                 |
-| command  | test    | Specify which command to run, currently only `test` is supported |
-| file     |         | The file to check for issues.                                    |
-| json     | false   | In addition to the stdout, save the results as snyk.json         |
-| sarif    | true    | In addition to the stdout, save the results as snyk.sarif        |
+| Property  | Default | Description                                                        |
+|-----------|----------|-------------------------------------------------------------------|
+| `args`    |          | Override the default arguments to the Snyk image.                 |
+| `command` | `"test"` | Specify which command to run, currently only `test` is supported. |
+| `file`    |          | The paths in which to scan files with issues.                     |
+| `json`    | `false`  | In addition to the stdout, save the results as snyk.json          |
+| `sarif`   | `true`   | In addition to the stdout, save the results as snyk.sarif         |
 
-For example, you can choose to only report on high severity vulnerabilities.
+## Examples
+### Specifying paths
+You can specify the paths to the configuration files and directories to target during the test.  
+When no path is specified, the whole repository is scanned by default:
 
 ```yaml
 name: Example workflow for Snyk Infrastructure as Code
@@ -40,6 +46,26 @@ jobs:
   security:
     runs-on: ubuntu-latest
     steps:
+      - uses: actions/checkout@v2
+      - name: Run Snyk to check Kubernetes manifest file for issues
+        uses: snyk/actions/iac@master
+        env:
+          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
+        with:
+          file: your/kubernetes-manifest.yaml your/terraform/directory
+```
+
+### Specifying severity threshold
+You can also choose to only report on high severity vulnerabilities:
+
+```yaml
+name: Example workflow for Snyk Infrastructure as Code
+on: push
+jobs:
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
       - name: Run Snyk to check Kubernetes manifest file for issues
         uses: snyk/actions/iac@master
         env:
@@ -48,61 +74,69 @@ jobs:
           file: your/kubernetes-manifest.yaml
           args: --severity-threshold=high
 ```
-
-The Infrastructure as Code Action also supports integrating with GitHub Code Scanning and can show issues in the GitHub Security tab. When run, a `snyk.sarif` file will be generated which can be uploaded to GitHub Code Scanning.
+### Sharing test results
+You can [share your test results](https://docs.snyk.io/products/snyk-infrastructure-as-code/share-cli-results-with-the-snyk-web-ui) to the Snyk platform:
 
 ```yaml
-name: Snyk Infrastructure as Code
+name: Example workflow for Snyk Infrastructure as Code
 on: push
 jobs:
-  snyk:
+  security:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
-      - name: Run Snyk to check configuration files for security issues
-        # Snyk can be used to break the build when it detects security issues.
-        # In this case we want to upload the issues to GitHub Code Scanning
-        continue-on-error: true
+      - name: Run Snyk to check Kubernetes manifest file for issues
         uses: snyk/actions/iac@master
         env:
-          # In order to use the Snyk Action you will need to have a Snyk API token.
-          # More details in https://github.com/snyk/actions#getting-your-snyk-token
-          # or you can signup for free at https://snyk.io/login
           SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
         with:
-          # Add the path to the configuration file that you would like to test.
-          # For example `deployment.yaml` for a Kubernetes deployment manifest
-          # or `main.tf` for a Terraform configuration file
-          file: your-file-to-test.yaml
-      - name: Upload result to GitHub Code Scanning
-        uses: github/codeql-action/upload-sarif@v2
+          args: --report
+```
+### Specifying scan mode for Terraform Plan
+You can also choose the [scan mode](https://docs.snyk.io/products/snyk-infrastructure-as-code/snyk-cli-for-infrastructure-as-code/test-your-terraform-files-with-the-cli-tool#terraform-plan), when scanning Terraform Plan files:
+
+```yaml
+name: Example workflow for Snyk Infrastructure as Code
+on: push
+jobs:
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Run Snyk to check Kubernetes manifest file for issues
+        uses: snyk/actions/iac@master
+        env:
+          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
         with:
-          sarif_file: snyk.sarif
+          args: --scan=resource-changes
 ```
 
-### Specifying Multiple Files
+### Integrating with GitHub Code Scanning
 
-If you want to run IaC tests against multiple files, the [Build Matrix](https://docs.github.com/en/actions/using-jobs/using-a-build-matrix-for-your-jobs) feature can be used.
+The Infrastructure as Code Action also supports integrating with GitHub Code Scanning and can show issues in the GitHub Security tab. When run, a `snyk.sarif` file will be generated which can be uploaded to GitHub Code Scanning:
 
 ```yaml
-name: Example workflow for Snyk Infrastructure as Code with multiple files
+name: Snyk Infrastructure as Code
 on: push
 jobs:
-  security:
+  snyk:
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        files:
-          - main.tf
-          - outputs.tf
-          - variables.tf
     steps:
-      - name: Run Snyk to check Kubernetes manifest file for issues
+      - uses: actions/checkout@v2
+      - name: Run Snyk to check configuration files for security issues
+        # Snyk can be used to break the build when it detects security issues.
+        # In this case we want to upload the issues to GitHub Code Scanning
+        continue-on-error: true
         uses: snyk/actions/iac@master
         env:
           SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
+      - name: Upload result to GitHub Code Scanning
+        uses: github/codeql-action/upload-sarif@v2
         with:
-          file: ${{ matrix.files }}
+          sarif_file: snyk.sarif
 ```
 
-The Actions example above refers to a `files` list that must contain at least _one_ supported file.
+## Related Documentation
+For more information on how to use the `snyk iac test` command, see the following: 
+- [Snyk CLI for Infastructure as Code](https://docs.snyk.io/products/snyk-infrastructure-as-code/snyk-cli-for-infrastructure-as-code)
+- [Snyk Infrastructure as Code Test Command](https://docs.snyk.io/snyk-cli/commands/iac-test)
diff --git a/iac/example.yml b/iac/example.yml
@@ -22,12 +22,11 @@ jobs:
           # More details in https://github.com/snyk/actions#getting-your-snyk-token
           # or you can signup for free at https://snyk.io/login
           SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
-        with:
-          # Scan the whole repository
-          file: . 
-          # Alternatively, add the path to the configuration file that you would like to test.
-          # For example `deployment.yaml` for a Kubernetes deployment manifest
-          # or `main.tf` for a Terraform configuration file
+        # Scans the whole repository by default.
+        # Alternatively, add the path to the configuration file that you would like to test.
+        # For example `deployment.yaml` for a Kubernetes deployment manifest
+        # or `main.tf` for a Terraform configuration file
+        # with:
           # file: your-file-to-test.yaml
       - name: Upload result to GitHub Code Scanning
         uses: github/codeql-action/upload-sarif@v2