HPCE/kics-github-action
0
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

readme + table of contents

Browse Source
This commit is contained in:
Rogério Peixoto
2021-10-18 18:07:08 +01:00
parent 00ad4364d4
commit b83a01cd04
2 changed files with 131 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

236
README.md
View File

@ -1,10 +1,29 @@
# KICS Github Action ![kics](images/icon-32x32.png) <img src="images/github.png" alt="Github" width="40" height="40"> # KICS Github Action
[![License: GPL-3.0](https://img.shields.io/badge/License-GPL3.0-yellow.svg)](https://www.gnu.org/licenses) [![License: GPL-3.0](https://img.shields.io/badge/License-GPL3.0-yellow.svg)](https://www.gnu.org/licenses)
[![Latest Release](https://img.shields.io/github/v/release/checkmarx/kics-github-action)](https://github.com/checkmarx/kics-github-action/releases) [![Latest Release](https://img.shields.io/github/v/release/checkmarx/kics-github-action)](https://github.com/checkmarx/kics-github-action/releases)
[![Open Issues](https://img.shields.io/github/issues-raw/checkmarx/kics-github-action)](https://github.com/checkmarx/kics-github-action/issues) [![Open Issues](https://img.shields.io/github/issues-raw/checkmarx/kics-github-action)](https://github.com/checkmarx/kics-github-action/issues)
## Integrate KICS into your GitHub workflows, using KICS Github Action to make your IaC more secure - [KICS Github Action](#kics-github-action)
- [Integrate KICS into your GitHub workflows](#integrate-kics-into-your-github-workflows)
- [Supported Platforms](#supported-platforms)
- [Please find more info in the official website: <a href="https://kics.io">kics.io</a>](#please-find-more-info-in-the-official-website-kicsio)
- [Inputs](#inputs)
- [Simple usage example](#simple-usage-example)
- [Workflow failures](#workflow-failures)
- [Don't fail on results](#dont-fail-on-results)
- [Fail by severity usage example](#fail-by-severity-usage-example)
- [Enabling Pull Request Comment](#enabling-pull-request-comment)
- [PR Comment Example](#pr-comment-example)
- [Annotations](#annotations)
- [Profiling KICS](#profiling-kics)
- [Uploading SARIF report](#uploading-sarif-report)
- [Using configuration file](#using-configuration-file)
- [How To Contribute](#how-to-contribute)
- [License](#license)
## Integrate KICS into your GitHub workflows
**KICS** (pronounced as 'kick-s') or **Kicscan** is an open source solution for static code analysis of Infrastructure as Code. **KICS** (pronounced as 'kick-s') or **Kicscan** is an open source solution for static code analysis of Infrastructure as Code.
@ -28,34 +47,36 @@ It is as simple as running a CLI tool, making it easy to integrate into any proj
### Please find more info in the official website: <a href="https://kics.io">kics.io</a> ### Please find more info in the official website: <a href="https://kics.io">kics.io</a>
And official documentation page <a href="https://docs.kics.io">docs.kics.io</a>
## Inputs ## Inputs
| Variable | Example Value &nbsp; | Description &nbsp; | Type | Required | Default | | Variable | Example Value &nbsp; | Description &nbsp; | Type | Required | Default |
| ------------------ | --------------------------------------- | ---------------------------------------------------------------- | ------- | -------- | --------------------------------------------- | | ------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------- | --------------------------------------------- |
| enable_comment | true | Enable pull request report comments | Boolean | No | false | | enable_comment | true | Enable pull request report comments | Boolean | No | false |
| path | terraform/main.tf,Dockerfile | paths to a file or directories to scan, comma separated list | String | Yes | 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 | | 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 | | 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 | | 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 | | 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 | | 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 | | 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_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 | | exclude_queries | a227ec01-f97a-4084-91a4-47b350c1db54 | exclude queries by providing the query ID, comma separated list | String | No | N/A |
| exclude_categories | 'Observability,Networking and Firewall' | exclude categories by providing its name, comma separated list | String | No | N/A | | exclude_categories | 'Observability,Networking and Firewall' | exclude categories by providing its name, comma separated list | String | No | N/A |
| exclude_results | 'd4a1fa80-d9d8-450f-87c2-e1f6669c41f8' | exclude results by providing the similarity ID of a result | String | No | N/A | | exclude_results | 'd4a1fa80-d9d8-450f-87c2-e1f6669c41f8' | exclude results by providing the similarity ID of a result | String | No | N/A |
| include_queries | a227ec01-f97a-4084-91a4-47b350c1db54 | include only specified list of queries to the scan, cannot be provided with query exclusion flags | String | No | N/A | | include_queries | a227ec01-f97a-4084-91a4-47b350c1db54 | include only specified list of queries to the scan, cannot be provided with query exclusion flags | String | No | N/A |
| output_formats | 'json,sarif' | formats in which the results report will be exported | String | No | json | | 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 | | output_path | results.json | file path to store result 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 | | 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 | | queries | | path to directory with queries (default "./assets/queries") | String | No | ./assets/queries downloaded with the binaries |
| verbose | true | verbose scan | Boolean | No | false | | verbose | true | verbose scan | Boolean | No | false |
| type | Ansible,Dockerfile | case insensitive comma-separated list of platform types to scan (Ansible, AzureResourceManager, CloudFormation, Dockerfile, Kubernetes, OpenAPI, Terraform) | String | No | all types | | type | Ansible,Dockerfile | case insensitive comma-separated list of platform types to scan (Ansible, AzureResourceManager, CloudFormation, Dockerfile, Kubernetes, OpenAPI, Terraform) | String | No | all types |
| bom | true | include bill of materials (BoM) in results.json output | Boolean | No | false | | bom | true | include bill of materials (BoM) in results.json output | Boolean | No | false |
| disable_full_descriptions | false | disable request for full descriptions and use default vulnerability descriptions | Boolean | false | | disable_full_descriptions | false | disable request for full descriptions and use default vulnerability descriptions | Boolean | false |
| disable_secrets | false | disable secrets detection | Boolean | false | | disable_secrets | false | disable secrets detection | Boolean | false |
| secrets_regexes_path| ./mydir/secrets-config.json | path to custom secrets regex rules configuration file | String | No | N/A | | secrets_regexes_path | ./mydir/secrets-config.json | path to custom secrets regex rules configuration file | String | No | N/A |
| libraries_path | ./myLibsDir | path to directory with Rego libraries | String | No | N/A | | libraries_path | ./myLibsDir | path to directory with Rego libraries | String | No | N/A |
## Simple usage example ## Simple usage example
@ -82,24 +103,6 @@ It is as simple as running a CLI tool, making it easy to integrate into any proj
By default KICS will fail your workflow on any results found. 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.3
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 ### 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: If you want KICS to ignore the results and return exit status code 0 unless a KICS engine error happens:
@ -118,6 +121,88 @@ If you want KICS to ignore the results and return exit status code 0 unless a KI
cat results.json cat results.json
``` ```
### 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.3
with:
path: 'terraform,my-other-sub-folder/Dockerfile'
fail_on: high,medium
output_path: 'results.json'
- name: display kics results
run: |
cat results.json
```
## Enabling Pull Request Comment
`GITHUB_TOKEN` enables this github action to access github API and post comments in a pull request:
```yaml
name: Test KICS action PR comment
on:
pull_request:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: run kics Scan
uses: checkmarx/kics-action@v1.3
with:
path: test/samples/positive1.tf,test/samples/positive2.tf
token: ${{ secrets.GITHUB_TOKEN }}
output_path: myResults/
ignore_on_exit: results
enable_comments: true
```
### PR Comment Example
<img alt="KICS Logo" src="https://user-images.githubusercontent.com/75368139/136991766-a4e5bc8b-63db-48f7-9384-740e9f15c9f6.png" width="150">
**KICS version: 1.4.5**
<table>
<tr></tr>
<tr><td>
| | Category | Results |
| --------------------------------------------------------------------------------------------------------------- | -------- | ------- |
| ![HIGH](https://user-images.githubusercontent.com/23239410/92157087-97285600-ee32-11ea-988f-0aca12c4c126.png) | HIGH | 3 |
| ![MEDIUM](https://user-images.githubusercontent.com/23239410/92157093-98598300-ee32-11ea-83d7-af52251a011b.png) | MEDIUM | 2 |
| ![LOW](https://user-images.githubusercontent.com/23239410/92157091-98598300-ee32-11ea-8498-19bd7d62019b.png) | LOW | 0 |
| ![INFO](https://user-images.githubusercontent.com/23239410/92157090-97c0ec80-ee32-11ea-9b2e-aa6b32b03d54.png) | INFO | 0 |
| ![TRACE](https://user-images.githubusercontent.com/23239410/92157090-97c0ec80-ee32-11ea-9b2e-aa6b32b03d54.png) | TRACE | 0 |
| ![TOTAL](https://user-images.githubusercontent.com/23239410/92157090-97c0ec80-ee32-11ea-9b2e-aa6b32b03d54.png) | TOTAL | 5 |
</td><td>
| | Metric | Values |
| -------------------------------------------------------------------------------------------------------------------- | ------------------------- | ------ |
| ![placeholder](https://user-images.githubusercontent.com/23239410/92157090-97c0ec80-ee32-11ea-9b2e-aa6b32b03d54.png) | Files scanned | 2 |
| ![placeholder](https://user-images.githubusercontent.com/23239410/92157090-97c0ec80-ee32-11ea-9b2e-aa6b32b03d54.png) | Files parsed | 2 |
| ![placeholder](https://user-images.githubusercontent.com/23239410/92157090-97c0ec80-ee32-11ea-9b2e-aa6b32b03d54.png) | Files failed to scan | 0 |
| ![placeholder](https://user-images.githubusercontent.com/23239410/92157090-97c0ec80-ee32-11ea-9b2e-aa6b32b03d54.png) | Total queries | 821 |
| ![placeholder](https://user-images.githubusercontent.com/23239410/92157090-97c0ec80-ee32-11ea-9b2e-aa6b32b03d54.png) | Queries failed to execute | 0 |
| ![placeholder](https://user-images.githubusercontent.com/23239410/92157090-97c0ec80-ee32-11ea-9b2e-aa6b32b03d54.png) | Execution time | 13s |
</td></tr> </table>
## Annotations
After scanning, [kics-github-action](https://github.com/Checkmarx/kics-github-action) will add the results as annotations in a pull request:
<img alt="annotations-preview" src="images/annotations-preview.png" width=800>
## Profiling KICS ## Profiling KICS
@ -234,65 +319,6 @@ jobs:
with: with:
sarif_file: results-dir/results.sarif sarif_file: results-dir/results.sarif
``` ```
## Enabling Pull Request Comment
`GITHUB_TOKEN` enables this github action to access github API and post comments in a pull request:
```yaml
name: Test KICS action PR comment
on:
pull_request:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: run kics Scan
uses: checkmarx/kics-action@v1.3
with:
path: test/samples/positive1.tf,test/samples/positive2.tf
token: ${{ secrets.GITHUB_TOKEN }}
output_path: myResults/
ignore_on_exit: results
enable_comments: true
```
### Example Pull Request Comment
<img alt="KICS Logo" src="https://user-images.githubusercontent.com/75368139/136991766-a4e5bc8b-63db-48f7-9384-740e9f15c9f6.png" width="150">
**KICS version: 1.4.5**
<table>
<tr></tr>
<tr><td>
| | Category | Results |
| --- |--- | --- |
| ![HIGH](https://user-images.githubusercontent.com/23239410/92157087-97285600-ee32-11ea-988f-0aca12c4c126.png) |HIGH | 3 |
| ![MEDIUM](https://user-images.githubusercontent.com/23239410/92157093-98598300-ee32-11ea-83d7-af52251a011b.png) |MEDIUM | 2 |
| ![LOW](https://user-images.githubusercontent.com/23239410/92157091-98598300-ee32-11ea-8498-19bd7d62019b.png) |LOW | 0 |
| ![INFO](https://user-images.githubusercontent.com/23239410/92157090-97c0ec80-ee32-11ea-9b2e-aa6b32b03d54.png) |INFO | 0 |
| ![TRACE](https://user-images.githubusercontent.com/23239410/92157090-97c0ec80-ee32-11ea-9b2e-aa6b32b03d54.png) |TRACE | 0 |
| ![TOTAL](https://user-images.githubusercontent.com/23239410/92157090-97c0ec80-ee32-11ea-9b2e-aa6b32b03d54.png) | TOTAL | 5 |
</td><td>
| | Metric | Values |
| --- | --- | --- |
| ![placeholder](https://user-images.githubusercontent.com/23239410/92157090-97c0ec80-ee32-11ea-9b2e-aa6b32b03d54.png) | Files scanned | 2 |
| ![placeholder](https://user-images.githubusercontent.com/23239410/92157090-97c0ec80-ee32-11ea-9b2e-aa6b32b03d54.png) | Files parsed | 2 |
| ![placeholder](https://user-images.githubusercontent.com/23239410/92157090-97c0ec80-ee32-11ea-9b2e-aa6b32b03d54.png) | Files failed to scan | 0 |
| ![placeholder](https://user-images.githubusercontent.com/23239410/92157090-97c0ec80-ee32-11ea-9b2e-aa6b32b03d54.png) | Total queries | 821 |
| ![placeholder](https://user-images.githubusercontent.com/23239410/92157090-97c0ec80-ee32-11ea-9b2e-aa6b32b03d54.png) | Queries failed to execute | 0 |
| ![placeholder](https://user-images.githubusercontent.com/23239410/92157090-97c0ec80-ee32-11ea-9b2e-aa6b32b03d54.png) | Execution time | 13s |
</td></tr> </table>
## How To Contribute ## How To Contribute
We welcome [issues](https://github.com/checkmarx/kics-github-action/issues) to and [pull requests](https://github.com/checkmarx/kics-github-action/pulls) against this repository! We welcome [issues](https://github.com/checkmarx/kics-github-action/issues) to and [pull requests](https://github.com/checkmarx/kics-github-action/pulls) against this repository!

BIN
images/annotations-preview.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 134 KiB