From 1bd03f632b562309899fa600ff4ba27948defc01 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rog=C3=A9rio=20Peixoto?= <rogerio.peixoto@checkmarx.com>
Date: Thu, 18 Mar 2021 15:30:17 +0000
Subject: [PATCH] updating documentation

---
 README.md | 101 +++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 97 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 020096a..02056c4 100644
--- a/README.md
+++ b/README.md
@@ -36,9 +36,9 @@ It is as simple as running a CLI tool, making it easy to integrate into any proj
 | queries            |                                         | path to directory with queries (default "./assets/queries")      | String  | No       | ./assets/queries downloaded with the binaries |
 | verbose            | true                                    | verbose scan                                                     | Boolean | No       | false                                         |
 
-## Example usage
-****
-```
+## Simple Example usage
+
+```yaml
     # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
     # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
@@ -49,12 +49,105 @@ It is as simple as running a CLI tool, making it easy to integrate into any proj
         with:
           path: 'terraform'
           output_path: 'results.json'
-	# Display the results in json format
+	  # Display the results in json format
      - name: display kics results
         run: |
           cat results.json
 ```
 
+## Example Using Docker Runner and SARIF report
+
+checkmarx/kics-action@docker-runner branch runs an alpine based linux container (`checkmarx/kics:nightly-alpine`) that doesn't require downloading kics binaries and queries in the `entrypoint.sh`
+
+```yaml
+name: scan with KICS docker-runner
+
+on:
+  pull_request:
+    branches: [master]
+
+jobs:
+  kics-job:
+    runs-on: ubuntu-latest
+    name: kics-action
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v2
+      - name: Mkdir results-dir
+        # make sure results dir is created
+        run: mkdir -p results-dir
+      - name: Run KICS Scan with SARIF result
+        uses: checkmarx/kics-action@docker-runner
+        with:
+          path: 'terraform'
+          # when provided with a directory on output_path
+          # it will generate the specified reports file named 'results.{extension}'
+          # in this example it will generate:
+          # - results-dir/results.json
+          # - results-dir/results.json
+          output_path: results-dir
+          platform_type: terraform
+          output_formats: 'json,sarif'
+          exclude_paths: "terraform/gcp/big_data.tf,terraform/azure"
+          # seek query id in it's metadata.json
+          exclude_queries: 0437633b-daa6-4bbc-8526-c0d2443b946e
+      - name: Show results
+        run: |
+          cat results-dir/results.sarif
+          cat results-dir/results.json
+      - name: Upload SARIF file
+        uses: github/codeql-action/upload-sarif@v1
+        with:
+          sarif_file: results-dir/results.sarif
+```
+## Example using docker-runner and config file
+
+```yaml
+name: scan with KICS using config file
+
+on:
+  pull_request:
+    branches: [master]
+
+jobs:
+  kics-job:
+    runs-on: ubuntu-latest
+    name: kics-action
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v2
+      - name: Mkdir results-dir
+        # make sure results dir is created
+        run: mkdir -p results-dir
+      - name: Create config file
+        run: |
+          cat <<EOF >>kics.config
+          {
+            "exclude-categories": "Encryption",
+            "exclude-paths": "terraform/gcp/big_data.tf,terraform/gcp/gcs.tf",
+            "log-file": true,
+            "minimal-ui": false,
+            "no-color": false,
+            "no-progress": true,
+            "output-path": "./results-dir",
+            "path": "terraform,ansible",
+            "payload-path": "file path to store source internal representation in JSON format",
+            "preview-lines": 5,
+            "report-formats": "json,sarif",
+            "type": "terraform",
+            "verbose": true
+          }
+          EOF
+      - name: Run KICS Scan using config
+        uses: checkmarx/kics-action@docker-runner
+        with:
+          path: 'terraform'
+          config_path: ./kics.config
+      - name: Upload SARIF file
+        uses: github/codeql-action/upload-sarif@v1
+        with:
+          sarif_file: results-dir/results.sarif
+```
 
 ## How To Contribute