diff --git a/README.md b/README.md index d19e6be..e2be3af 100644 --- 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 -Terraform   Kubernetes   Docker   CloudFormation   Ansible +Terraform    +Kubernetes    +Docker    +
+CloudFormation    +Ansible    +OpenAPI    +
+
+Helm    ### Please find more info in the official website: kics.io @@ -23,8 +32,12 @@ It is as simple as running a CLI tool, making it easy to integrate into any proj | Variable | Example Value   | Description   | 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. + +> 📝   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 <>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 diff --git a/action.yml b/action.yml index e974b00..78b0200 100644 --- 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 }} diff --git a/entrypoint.sh b/entrypoint.sh index 1b1f83f..ed49151 100644 --- 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 \ No newline at end of file diff --git a/images/logo-helm.png b/images/logo-helm.png new file mode 100755 index 0000000..a02aa01 Binary files /dev/null and b/images/logo-helm.png differ diff --git a/images/logo-openapi.png b/images/logo-openapi.png new file mode 100755 index 0000000..7d0ca40 Binary files /dev/null and b/images/logo-openapi.png differ