feat(docs): adding support to kics v1.3.0

2021-05-10 18:13:38 +01:00
parent 9d4208bd68
commit 24d46b812e
5 changed files with 209 additions and 18 deletions
--- a/README.md
+++ b/README.md
@ -14,7 +14,16 @@ It is as simple as running a CLI tool, making it easy to integrate into any proj

 #### Supported Platforms

-<img alt="Terraform" src="images/logo-terraform.png" width="150">&nbsp;&nbsp;&nbsp;<img alt="Kubernetes" src="images/logo-k8s.png" width="150">&nbsp;&nbsp;&nbsp;<img alt="Docker" src="images/logo-docker.png" width="150">&nbsp;&nbsp;&nbsp;<img alt="CloudFormation" src="images/logo-cf.png" width="150">&nbsp;&nbsp;&nbsp;<img alt="Ansible" src="images/logo-ansible.png" width="150">
+<img alt="Terraform" src="images/logo-terraform.png" width="150">&nbsp;&nbsp;&nbsp;
+<img alt="Kubernetes" src="images/logo-k8s.png" width="150">&nbsp;&nbsp;&nbsp;
+<img alt="Docker" src="images/logo-docker.png" width="150">&nbsp;&nbsp;&nbsp;
+<br>
+<img alt="CloudFormation" src="images/logo-cf.png" width="150">&nbsp;&nbsp;&nbsp;
+<img alt="Ansible" src="images/logo-ansible.png" width="150">&nbsp;&nbsp;&nbsp;
+<img alt="OpenAPI" src="images/logo-openapi.png" width="150">&nbsp;&nbsp;&nbsp;
+<br>
+<br>
+<img alt="Helm" src="images/logo-helm.png" width="150">&nbsp;&nbsp;&nbsp;


 ### Please find more info in the official website: <a href="https://kics.io">kics.io</a>
@ -23,8 +32,12 @@ It is as simple as running a CLI tool, making it easy to integrate into any proj

 | Variable           | Example Value &nbsp;                    | Description &nbsp;                                               | Type    | Required | Default                                       |
 | ------------------ | --------------------------------------- | ---------------------------------------------------------------- | ------- | -------- | --------------------------------------------- |
-| path               | terraform                               | path to file or directory to scan                                | String  | Yes      | N/A                                           |
-| config_path             | ./kics.config                           | path to configuration file                                       | String  | No       | N/A                                           |
+| path               | terraform/main.tf,Dockerfile            | paths to a file or directories to scan, comma separated list     | String  | Yes      | N/A                                           |
+| ignore_on_exit     | results                                 | defines which non-zero exit codes should be ignored (all, results, errors, none) | String  | No       | none                  |
+| fail_on            | high,medium                             | comma separated list of which severities returns exit code !=0   | String  | No       | high,medium,low,info                          |
+| timeout            | 75                                      | number of seconds the query has to execute before being canceled | String  | No       | 60                                            |
+| profiling          | CPU                                     | turns on profiler that prints resource consumption in the logs during the execution (CPU, MEM) | String  | No   | N/A |
+| config_path        | ./kics.config                           | path to configuration file                                       | String  | No       | N/A                                           |
 | platform_type      | terraform,ansible                       | case insensitive list of platform types to scan                  | String  | No       | All platforms                                 |
 | exclude_paths      | ./shouldNotScan/*,somefile.txt          | exclude paths from scan, supports glob, comma separated list     | String  | No       | N/A                                           |
 | exclude_queries    | a227ec01-f97a-4084-91a4-47b350c1db54    | exclude queries by providing the query ID, comma separated list  | String  | No       | N/A                                           |
@ -32,29 +45,187 @@ It is as simple as running a CLI tool, making it easy to integrate into any proj
 | exclude_results    | 'd4a1fa80-d9d8-450f-87c2-e1f6669c41f8'  | exclude results by providing the similarity ID of a result       | String  | No       | N/A                                           |
 | output_formats     | 'json,sarif'                            | formats in which the results report will be exported             | String  | No       | json                                          |
 | output_path        | results.json                            | file path to store result in json format                         | String  | No       | N/A                                           |
-| payload_path       |                                         | file path to store source internal representation in JSON format | String  | No       | N/A                                           |
+| payload_path       | /tmp/mypayload.json                     | file path to store source internal representation in JSON format | String  | No       | N/A                                           |
 | 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 usage example

-```
+```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
    - uses: actions/checkout@v2
    # Scan Iac with kics
-     - name: run kics Scan
-        uses: checkmarx/kics-action@v1.0
-        with:
-          path: 'terraform'
-          output_path: 'results.json'
-	# Display the results in json format
-     - name: display kics results
-        run: |
-          cat results.json
+    - name: run kics Scan
+      uses: checkmarx/kics-action@v1.2
+      with:
+        # scanning two directories: ./terraform/ ./cfn-templates/ plus a single file
+        path: 'terraform,cfn-templates,my-other-sub-folder/Dockerfile'
+        output_path: 'results.json'
+    # Display the results in json format
+    - name: display kics results
+      run: |
+        cat results.json
 ```

+## Workflow failures
+
+By default KICS will fail your workflow on any results found.
+
+### Fail by severity usage example
+
+If want your pipeline just to fail on HIGH and MEDIUM severity results and KICS engine execution errors:
+
+```yaml
+    steps:
+    - uses: actions/checkout@v2
+    - name: run kics Scan
+      uses: checkmarx/kics-action@v1.2
+      with:
+        path: 'terraform,my-other-sub-folder/Dockerfile'
+        fail_on: high,medium
+        output_path: 'results.json'
+    - name: display kics results
+      run: |
+        cat results.json
+```
+
+### Don't fail on results
+
+If you want KICS to ignore the results and return exit status code 0 unless a KICS engine error happens:
+
+```yaml
+    steps:
+    - uses: actions/checkout@v2
+    - name: run kics Scan
+      uses: checkmarx/kics-action@v1.2
+      with:
+        path: 'terraform'
+        ignore_on_exit: results
+        output_path: 'results.json'
+    - name: display kics results
+      run: |
+        cat results.json
+```
+
+
+## Profiling KICS
+
+You can only enable one profiler at a time, CPU or MEM.
+
+> 📝 &nbsp; Please note that execution time may be impacted by enabling performance profiler due to sampling
+
+```yaml
+    steps:
+    - uses: actions/checkout@v2
+    - name: run kics Scan
+      uses: checkmarx/kics-action@v1.2
+      with:
+        path: 'terraform'
+        profiling: MEM
+        output_path: 'results.json'
+    - 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.sarif
+          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 a config file
+
+Check [configuration file](https://github.com/Checkmarx/kics/blob/master/docs/configuration-file.md) reference for more options.
+
+```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
+        # creating a heredoc 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",
+            "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

--- a/action.yml
+++ b/action.yml
@ -3,8 +3,20 @@ name: 'KICS Github Action'
 description: 'Run KICS scan against IaC projects'
 inputs:
  path:
-    description: 'path to file or directory to scan'
+    description: 'paths to a file or directories to scan, accepts a comma separated list'
    required: true
+  ignore_on_exit:
+    description: 'defines which non-zero exit codes should be ignored (all, results, errors, none)'
+    required: false
+  fail_on:
+    description: 'comma separated list of which severities returns exit code !=0'
+    required: false
+  timeout:
+    description: 'number of seconds the query has to execute before being canceled'
+    required: false
+  profiling:
+    description: 'turns on profiler that prints resource consumption in the logs during the execution (CPU, MEM)'
+    required: false
  config_path:
    description: 'path to configuration file'
    required: false
@ -48,6 +60,10 @@ runs:
  image: 'Dockerfile'
  args:
    - ${{ inputs.path }}
+    - ${{ inputs.ignore_on_exit }}
+    - ${{ inputs.fail_on }}
+    - ${{ inputs.timeout }}
+    - ${{ inputs.profiling }}
    - ${{ inputs.config }}
    - ${{ inputs.platform_type }}
    - ${{ inputs.exclude_paths }}
--- a/entrypoint.sh
+++ b/entrypoint.sh
@ -18,6 +18,10 @@ fi
 [[ ! -z "$INPUT_EXCLUDE_CATEGORIES" ]] && EXCLUDE_CATEGORIES_PARAM="--exclude-categories $INPUT_EXCLUDE_CATEGORIES"
 [[ ! -z "$INPUT_OUTPUT_FORMATS" ]] && OUTPUT_FORMATS_PARAM="--report-formats $INPUT_OUTPUT_FORMATS"
 [[ ! -z "$INPUT_PLATFORM_TYPE" ]] && PLATFORM_TYPE_PARAM="--type $INPUT_PLATFORM_TYPE"
+[[ ! -z "$INPUT_IGNORE_ON_EXIT" ]] && IGNORE_ON_EXIT_PARAM="--ignore_on_exit $INPUT_IGNORE_ON_EXIT"
+[[ ! -z "$INPUT_FAIL_ON" ]] && FAIL_ON_PARAM="--fail_on $INPUT_FAIL_ON"
+[[ ! -z "$INPUT_TIMEOUT" ]] && TIMEOUT_PARAM="--timeout $INPUT_TIMEOUT"
+[[ ! -z "$INPUT_PROFILING" ]] && PROFILING_PARAM="--profiling $INPUT_PROFILING"

 [[ ! -z "$INPUT_VERBOSE" ]] && VERBOSE_PARAM="-v"

@ -30,5 +34,5 @@ fi

 cd $GITHUB_WORKSPACE
 echo "${DATETIME} - INF : about to scan directory $INPUT_PATH"
-echo "${DATETIME} - INF : kics command kics $INPUT_PARAM $OUTPUT_PATH_PARAM $OUTPUT_FORMATS_PARAM $PLATFORM_TYPE_PARAM $PAYLOAD_PATH_PARAM $CONFIG_PATH_PARAM $EXCLUDE_PATHS_PARAM $EXCLUDE_CATEGORIES_PARAM $EXCLUDE_RESULTS_PARAM $EXCLUDE_QUERIES_PARAM $QUERIES_PARAM $VERBOSE_PARAM"
-/app/bin/kics scan --no-progress $INPUT_PARAM $OUTPUT_PATH_PARAM $OUTPUT_FORMATS_PARAM $PLATFORM_TYPE_PARAM $PAYLOAD_PATH_PARAM $CONFIG_PATH_PARAM $EXCLUDE_PATHS_PARAM $EXCLUDE_CATEGORIES_PARAM $EXCLUDE_RESULTS_PARAM $EXCLUDE_QUERIES_PARAM $QUERIES_PARAM $VERBOSE_PARAM
+echo "${DATETIME} - INF : kics command kics $INPUT_PARAM $OUTPUT_PATH_PARAM $OUTPUT_FORMATS_PARAM $PLATFORM_TYPE_PARAM $PAYLOAD_PATH_PARAM $CONFIG_PATH_PARAM $EXCLUDE_PATHS_PARAM $EXCLUDE_CATEGORIES_PARAM $EXCLUDE_RESULTS_PARAM $EXCLUDE_QUERIES_PARAM $QUERIES_PARAM $VERBOSE_PARAM $IGNORE_ON_EXIT_PARAM $FAIL_ON_PARAM $TIMEOUT_PARAM $PROFILING_PARAM"
+kics scan --no-progress $INPUT_PARAM $OUTPUT_PATH_PARAM $OUTPUT_FORMATS_PARAM $PLATFORM_TYPE_PARAM $PAYLOAD_PATH_PARAM $CONFIG_PATH_PARAM $EXCLUDE_PATHS_PARAM $EXCLUDE_CATEGORIES_PARAM $EXCLUDE_RESULTS_PARAM $EXCLUDE_QUERIES_PARAM $QUERIES_PARAM $VERBOSE_PARAM $IGNORE_ON_EXIT_PARAM $FAIL_ON_PARAM $TIMEOUT_PARAM $PROFILING_PARAM
--- a/images/logo-helm.png
+++ b/images/logo-helm.png
--- a/images/logo-openapi.png
+++ b/images/logo-openapi.png