Checkmarx/kics-github-action
GitHub: Checkmarx/kics-github-action
将 KICS 基础设施即代码安全扫描器封装为 GitHub Action，实现 CI/CD 中的自动化安全检查与合规审计。
Stars: 4 | Forks: 0
# KICS GitHub Action
[](https://www.gnu.org/licenses)
[](https://github.com/checkmarx/kics-github-action/releases)
[](https://github.com/checkmarx/kics-github-action/issues)
- [KICS GitHub Action](#kics-github-action)
- [将 KICS 集成到你的 GitHub workflows 中](#integrate-kics-into-your-github-workflows)
- [支持的平台](#supported-platforms)
- [请在官方网站查找更多信息：kics.io](#please-find-more-info-in-the-official-website-kicsio)
- [输入参数](#inputs)
- [简单用法示例](#simple-usage-example)
- [工作流失败](#workflow-failures)
- [不在发现结果时失败](#dont-fail-on-results)
- [按严重程度失败的用法示例](#fail-by-severity-usage-example)
- [启用 Pull Request 评论](#enabling-pull-request-comment)
- [PR 评论示例](#pr-comment-example)
- [注解](#annotations)
- [KICS 性能分析](#profiling-kics)
- [上传 SARIF 报告](#uploading-sarif-report)
- [使用配置文件](#using-configuration-file)
- [如何贡献](#how-to-contribute)
- [许可证](#license)
## 将 KICS 集成到你的 GitHub workflows 中
**KICS** (发音为 'kick-s') 或 **Kicscan** 是一个开源的 Infrastructure as Code (IaC) 静态代码分析解决方案。
**K**eeping **I**nfrastructure as **C**ode **S**ecure (简称 **KICS**) 是任何云原生项目的必备工具。使用 KICS，可以在开发周期的早期发现安全漏洞、合规性问题和基础设施配置错误，此时修复这些问题既直接又成本低廉。
它就像运行一个 CLI 工具一样简单，因此很容易集成到任何项目的 CI 中。
#### 支持的平台
官方文档页面 docs.kics.io。
在创建工作流时，请确保使用 最新的 KICS Github Action 版本。
## 输入参数
| Variable | Example Value | Description | Type | Required | Default |
|-------------------------------------------|--------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|---------| -------- |--------------------------------------------------------|
| enable_comments | true | 启用 pull request 报告评论 | Boolean | No | false |
| enable_jobs_summary | true | 启用作为作业摘要的报告 | Boolean | No | false |
| enable_annotations | true | 启用注解报告 | Boolean | No | true |
| comments_with_queries | true | 在 pull request 报告评论中添加查询（当 enable_comments = true 时可用） | Boolean | No | false |
| excluded_column_for_comments_with_queries | description_id,similarity_id,search_line,search_value | 排除带有查询的评论的列，接受逗号分隔的列表 | String | No | description_id,similarity_id,search_line,search_value |
| path | terraform/main.tf,Dockerfile | 要扫描的文件或目录路径，逗号分隔列表 | String | Yes | N/A |
| ignore_on_exit | results | 定义应忽略哪些非零退出代码 (all, results, errors, none) | String | No | none |
| fail_on | high,medium | 逗号分隔的严重级别列表，返回退出代码 !=0 | String | No | high,medium,low,info |
| timeout | 75 | 查询在取消前必须执行的秒数 | String | No | 60 |
| profiling | CPU | 开启分析器，在执行期间在日志中打印资源消耗情况 (CPU, MEM) | String | No | N/A |
| config_path | ./kics.config | 配置文件路径 | String | No | N/A |
| platform_type | terraform,ansible | 要扫描的平台类型列表，不区分大小写 | String | No | All platforms |
| exclude_paths | ./shouldNotScan/*,somefile.txt | 从扫描中排除路径，支持 glob，逗号分隔列表 | String | No | N/A |
| exclude_queries | a227ec01-f97a-4084-91a4-47b350c1db54 | 通过提供查询 ID 排除查询，逗号分隔列表 | String | No | N/A |
| exclude_categories | 'Observability,Networking and Firewall' | 通过提供名称排除类别，逗号分隔列表 | String | No | N/A |
| exclude_results | 'd4a1fa80-d9d8-450f-87c2-e1f6669c41f8' | 通过提供结果的相似度 ID 排除结果 | String | No | N/A |
| exclude_severities | 'info,low' | 通过提供结果的严重程度排除结果 | String | No | N/A |
| exclude_gitignore (仅在 KICS 版本 1.6 及以上可用) | | 禁用排除 .gitignore 文件中指定的路径 | Boolean | No | false |
| include_queries | a227ec01-f97a-4084-91a4-47b350c1db54 | 仅将指定的查询列表包含在扫描中，不能与查询排除标志一起使用 | String | No | N/A |
| output_formats | 'json,sarif' | 导出结果报告的格式 | String | No | json |
| output_path | myResults/ | 存储 JSON 格式结果的文件路径 | String | No | "./" |
| payload_path | /tmp/mypayload.json | 存储 JSON 格式源内部表示的文件路径 | String | No | N/A |
| queries | | 查询目录路径（默认 "./assets/queries"） | String | No | ./assets/queries downloaded with the binaries |
| verbose | true | 详细扫描 | Boolean | No | false |
| type | Ansible,Dockerfile | 以逗号分隔的平台类型列表（不区分大小写）进行扫描 (Ansible, AzureResourceManager, CloudFormation, Dockerfile, Kubernetes, OpenAPI, Terraform) | String | No | all types |
| bom | true | 在 results.json 输出中包含物料清单 | Boolean | No | false |
| disable_full_descriptions | false | 禁用请求完整描述并使用默认漏洞描述 | Boolean | false |
| disable_secrets | false | 禁用密钥检测 | Boolean | false |
| secrets_regexes_path | ./mydir/secrets-config.json | 自定义密钥正则表达式规则配置文件的路径 | String | No | N/A |
| libraries_path | ./myLibsDir | Rego 库目录路径 | String | No | N/A |
| cloud_provider | aws,azure | 要扫描的云提供商列表 | String | No | N/A |
## 简单用法示例
```
# 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@v3
# Scan Iac with kics
- name: run kics Scan
uses: checkmarx/kics-github-action@v2.1.20
with:
# scanning two directories: ./terraform/ ./cfn-templates/ plus a single file
path: 'terraform,cfn-templates,my-other-sub-folder/Dockerfile'
output_path: myResults/
# Display the results in json format
- name: display kics results
run: |
cat myResults/results.json
```
## 工作流失败
默认情况下，只要发现任何结果，KICS 就会导致工作流失败。
### 不在发现结果时失败
如果你希望 KICS 忽略结果并返回退出状态码 0，除非发生 KICS 引擎错误：
```
steps:
- uses: actions/checkout@v3
- name: run kics Scan
uses: checkmarx/kics-github-action@v2.1.20
with:
path: 'terraform'
ignore_on_exit: results
output_path: myResults/
- name: display kics results
run: |
cat myResults/results.json
```
### 按严重程度失败的用法示例
如果你希望管道仅在发现 HIGH 和 MEDIUM 严重性结果以及 KICS 引擎执行错误时失败：
```
steps:
- uses: actions/checkout@v3
- name: run kics Scan
uses: checkmarx/kics-github-action@v2.1.20
with:
path: 'terraform,my-other-sub-folder/Dockerfile'
fail_on: high,medium
output_path: myResults/
- name: display kics results
run: |
cat myResults/results.json
```
## 启用 Pull Request 评论
`GITHUB_TOKEN` 使此 github action 能够访问 github API 并在 pull request 中发表评论：
```
name: Test KICS action PR comment
on:
pull_request:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: run kics Scan
uses: checkmarx/kics-github-action@v2.1.20
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 评论示例
**KICS 版本： 2.1.5**
## 注解
扫描后，[kics-github-action](https://github.com/Checkmarx/kics-github-action) 会将结果作为注解添加到 pull request 中：
## KICS 性能分析
你一次只能启用一个分析器，CPU 或 MEM。
```
steps:
- uses: actions/checkout@v3
- name: run kics Scan
uses: checkmarx/kics-github-action@v2.1.20
with:
path: 'terraform'
profiling: MEM
output_path: myResults/
- name: display kics results
run: |
cat myResults/results.json
```
## 上传 SARIF 报告
```
name: scan with KICS and upload SARIF
on:
pull_request:
branches: [master]
jobs:
kics-job:
runs-on: ubuntu-latest
name: kics-action
steps:
- name: Checkout repo
uses: actions/checkout@v3
- 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-github-action@v2.1.20
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
ignore_on_exit: results
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@v3
with:
sarif_file: results-dir/results.sarif
```
## 使用配置文件
查看 [配置文件](https://github.com/Checkmarx/kics/blob/master/docs/configuration-file.md) 参考以获取更多选项。
```
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@v3
- 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-github-action@v2.1.20
with:
path: 'terraform'
config_path: ./kics.config
- name: Upload SARIF file
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: results-dir/results.sarif
```
# 许可证
KICS Github Action
本程序是自由软件：你可以根据自由软件基金会发布的 GNU 通用公共许可证的条款重新分发和/或修改它，许可证版本为 3，或（根据你的选择）任何后续版本。
分发本程序是希望它有用，但不提供任何保证；甚至没有适销性或特定用途适用性的默示保证。有关更多详细信息，请参阅 GNU 通用公共许可证。
你应该随本程序一起收到 GNU 通用公共许可证的副本。如果没有，请参阅 https://www.gnu.org/licenses/。
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**KICS 版本： 2.1.5**
| | | Category | Results | | --------------------------------------------------------------------------------------------------------------- | -------- | ------- | |  | HIGH | 3 | |  | MEDIUM | 2 | |  | LOW | 0 | |  | INFO | 0 | |  | TRACE | 0 | |  | TOTAL | 5 | | | | Metric | Values | | -------------------------------------------------------------------------------------------------------------------- | ------------------------- | ------ | |  | Files scanned | 2 | |  | Files parsed | 2 | |  | Files failed to scan | 0 | |  | Total queries | 821 | |  | Queries failed to execute | 0 | |  | Execution time | 13s | |
## KICS 性能分析
你一次只能启用一个分析器，CPU 或 MEM。
```
steps:
- uses: actions/checkout@v3
- name: run kics Scan
uses: checkmarx/kics-github-action@v2.1.20
with:
path: 'terraform'
profiling: MEM
output_path: myResults/
- name: display kics results
run: |
cat myResults/results.json
```
## 上传 SARIF 报告
```
name: scan with KICS and upload SARIF
on:
pull_request:
branches: [master]
jobs:
kics-job:
runs-on: ubuntu-latest
name: kics-action
steps:
- name: Checkout repo
uses: actions/checkout@v3
- 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-github-action@v2.1.20
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
ignore_on_exit: results
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@v3
with:
sarif_file: results-dir/results.sarif
```
## 使用配置文件
查看 [配置文件](https://github.com/Checkmarx/kics/blob/master/docs/configuration-file.md) 参考以获取更多选项。
```
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@v3
- 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 <标签：Checkmarx, CI/CD 集成, DevSecOps, Docker 安全, GitHub Actions, Homebrew安装, IaC 安全, Java RMI, KICS, Kubernetes 安全, SARIF, Terraform 扫描, 上游代理, 图计算, 安全工程, 开源安全工具, 日志审计, 模型鲁棒性, 自动笔记, 自定义脚本, 请求拦截, 逆向工程平台, 配置错误检测, 错误基检测, 静态代码分析