readme + table of contents
This commit is contained in:
Rogério Peixoto
188
README.md
188
README.md
@ -1,10 +1,29 @@
|
||||
# KICS Github Action  <img src="images/github.png" alt="Github" width="40" height="40">
|
||||
# KICS Github Action
|
||||
|
||||
[](https://www.gnu.org/licenses)
|
||||
[](https://github.com/checkmarx/kics-github-action/releases)
|
||||
[](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.
|
||||
|
||||
@ -28,10 +47,12 @@ 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>
|
||||
|
||||
And official documentation page <a href="https://docs.kics.io">docs.kics.io</a>
|
||||
|
||||
## Inputs
|
||||
|
||||
| Variable | Example Value | Description | Type | Required | Default |
|
||||
| ------------------ | --------------------------------------- | ---------------------------------------------------------------- | ------- | -------- | --------------------------------------------- |
|
||||
| ------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------- | --------------------------------------------- |
|
||||
| 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 |
|
||||
| ignore_on_exit | results | defines which non-zero exit codes should be ignored (all, results, errors, none) | String | No | none |
|
||||
@ -54,7 +75,7 @@ It is as simple as running a CLI tool, making it easy to integrate into any proj
|
||||
| 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_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 |
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
### 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
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
### 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 | 3 |
|
||||
|  | MEDIUM | 2 |
|
||||
|  | LOW | 0 |
|
||||
|  | INFO | 0 |
|
||||
|  | TRACE | 0 |
|
||||
|  | TOTAL | 5 |
|
||||
|
||||
</td><td>
|
||||
|
||||
| | Metric | Values |
|
||||
| -------------------------------------------------------------------------------------------------------------------- | ------------------------- | ------ |
|
||||
|  | Files scanned | 2 |
|
||||
|  | Files parsed | 2 |
|
||||
|  | Files failed to scan | 0 |
|
||||
|  | Total queries | 821 |
|
||||
|  | Queries failed to execute | 0 |
|
||||
|  | 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
|
||||
|
||||
@ -234,65 +319,6 @@ jobs:
|
||||
with:
|
||||
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 | 3 |
|
||||
|  |MEDIUM | 2 |
|
||||
|  |LOW | 0 |
|
||||
|  |INFO | 0 |
|
||||
|  |TRACE | 0 |
|
||||
|  | TOTAL | 5 |
|
||||
|
||||
</td><td>
|
||||
|
||||
| | Metric | Values |
|
||||
| --- | --- | --- |
|
||||
|  | Files scanned | 2 |
|
||||
|  | Files parsed | 2 |
|
||||
|  | Files failed to scan | 0 |
|
||||
|  | Total queries | 821 |
|
||||
|  | Queries failed to execute | 0 |
|
||||
|  | Execution time | 13s |
|
||||
|
||||
</td></tr> </table>
|
||||
|
||||
## 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!
|
||||
|
||||
BIN
images/annotations-preview.png
Normal file
BIN
images/annotations-preview.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 134 KiB |
Reference in New Issue
Block a user