KICS Docker镜像技术文档

1. 镜像概述

1.1 主要用途

KICS（Keeping Infrastructure as Code Secure）是一款用于保障基础设施即代码（IaC）安全的工具，通过扫描IaC文件（如Terraform、Kubernetes、Dockerfile等），识别其中的安全漏洞、合规违规、配置错误等问题，帮助用户在部署前发现并修复基础设施配置风险。

2. 核心功能与特性

• 多平台支持：扫描多种IaC平台，包括Terraform、Kubernetes、Dockerfile、CloudFormation、Ansible等。
• 全面漏洞检测：覆盖安全漏洞、合规性问题、最佳实践违背等多种风险类型。
• 自动修复：支持基于扫描结果自动修复部分配置问题（remediate命令）。
• 多格式报告：生成JSON、HTML、JUnit、SARIF等多种格式报告，便于集成到CI/CD或安全审计流程。
• 灵活配置：支持排除/包含特定类别、查询ID、路径，自定义查询规则路径等。
• 秘密扫描：可检测配置文件中的敏感信息（如密钥、令牌），支持自定义秘密规则。
• UBI基础镜像：提供基于Red Hat UBI8的镜像，支持非root用户运行，增强容器安全性。

3. 使用场景与适用范围

• 开发阶段本地验证：开发人员在编写IaC文件后，本地快速扫描验证配置安全性。
• CI/CD流程集成：作为流水线环节，在代码提交或部署前自动扫描，阻止不安全配置进入生产环境。
• 安全审计：安全团队对现有基础设施配置进行合规性检查，确保符合企业安全策略。
• 多环境适配：支持自定义用户/组ID，适配不同主机环境的文件权限需求。

4. 使用方法

4.1 拉取镜像

通过Docker Hub拉取最新版KICS镜像：

docker pull checkmarx/kics:latest

4.2 基本扫描操作

4.2.1 扫描目录

将主机目录挂载到容器内，使用scan命令扫描指定路径，结果输出到挂载目录：

docker run -t -v {主机待扫描目录路径}:/path checkmarx/kics:latest scan -p /path -o "/path/"

说明：

• -v {主机目录}:/path：将主机目录挂载到容器内/path路径。
• -p /path：指定容器内待扫描的路径（即挂载的目录）。
• -o "/path/"：指定结果输出目录（需在挂载目录内，否则主机无法访问）。
• 扫描结果将在主机挂载目录下生成results.json文件。

4.2.2 扫描单个文件

类似目录扫描，指定容器内单个文件路径：

docker run -t -v {主机文件所在目录}:/path checkmarx/kics:latest scan -p /path/{文件名}.{扩展名} -o "/path/"

示例：扫描主机/home/user/iac目录下的main.tf文件：

docker run -t -v /home/user/iac:/path checkmarx/kics:latest scan -p /path/main.tf -o "/path/"

4.3 UBI基础镜像特殊配置

基于Red Hat UBI8的镜像（checkmarx/kics:ubi8）默认以kics用户（UID=1000，GID=1000）运行。挂载主机文件时，若主机文件权限与容器默认UID/GID不匹配，需通过以下方式调整：

4.3.1 临时覆盖用户/组ID

使用-u参数指定当前主机用户的UID/GID，确保容器有权访问挂载文件：

docker run -it -u $UID:$GID -v $PWD:/path checkmarx/kics:ubi8 scan -p /path/assets/queries/dockerfile -o /path -v

说明：$UID和$GID为当前主机用户的ID，通过id命令可查看。

4.3.2 重新构建镜像自定义用户

通过构建参数自定义用户/组ID，重新构建UBI8镜像：

docker build -f docker/Dockerfile.ubi8 \
  --build-arg UID=999 \
  --build-arg GID=999 \
  --build-arg KUSER=myuser \
  --build-arg KGROUP=mygroup \
  -t my-kics:ubi8 .

5. CLI命令与选项详解

5.1 可用命令

kics [command]

Available Commands:
  generate-id    为查询生成UUID
  help           查看命令帮助
  list-platforms 列出支持的平台
  remediate      自动修复项目配置
  scan           执行扫描分析
  version        显示当前版本

5.2 remediate子命令

自动修复项目配置，基于扫描结果中的修复建议。

Usage:
  kics remediate [flags]

Flags:
  -h, --help                  显示帮助信息
      --include-ids strings   指定需修复的相似度ID（默认修复所有），示例："f6b7acac2d541d8c15c88d2be51b0e6abd576750b71c580f2e3a9346f7ed0e67,6af5fc5d7c0ad0077348a090f7c09949369d24d5608bbdbd14376a15de62afd1"
      --results string        指向包含修复建议的JSON结果文件路径

5.3 scan子命令

执行IaC扫描分析，核心功能命令。

Usage:
  kics scan [flags]

Flags:
  -m, --bom                           在结果中包含物料清单（BoM）
      --cloud-provider strings        指定云提供商（alicloud, aws, azure, gcp, nifcloud, tencentcloud），可指定多个
      --config string                 配置文件路径
      --disable-full-descriptions     禁用完整描述请求，使用默认漏洞描述
      --disable-secrets               禁用秘密扫描
      --enable-openapi-refs           解析OpenAPI文件中的引用（默认false）
      --exclude-categories strings    排除指定类别（名称），不可与包含查询的标志同时使用，可多次指定或逗号分隔，示例：'Access control,Best practices'
      --exclude-gitignore             禁用排除.gitignore中指定的路径
  -e, --exclude-paths strings         排除扫描路径，支持通配符，可多次指定或逗号分隔，示例：'./shouldNotScan/*,somefile.txt'
      --exclude-queries strings       排除指定查询ID，不可与包含查询的标志同时使用，可多次指定或逗号分隔，示例：'e69890e6-fce5-461d-98ad-cb98318dfc96'
  -x, --exclude-results strings       排除指定相似度ID的结果，可多次指定或逗号分隔
      --exclude-severities strings    排除指定严重级别结果（info, low, medium, high），可多次指定或逗号分隔
      --experimental-queries          包含实验性查询（未彻底审核的查询）（默认false）
      --fail-on strings               指定导致非0退出码的结果类型（high, medium, low, info），默认全部（default [high,medium,low,info]）
  -h, --help                          显示帮助信息
      --ignore-on-exit string         忽略非0退出码的类型（all, results, errors, none），示例：'results'仅忽略结果导致的非0码（default "none"）
  -i, --include-queries strings       包含指定查询ID，不可与排除查询的标志同时使用，可多次指定或逗号分隔
      --input-data string             查询输入数据文件路径
  -b, --libraries-path string         库目录路径（default "./assets/libraries"）
      --max-file-size int             最大扫描文件大小（MB）（default 5）
      --minimal-ui                    简化CLI输出
      --no-progress                   隐藏进度条
      --output-name string            报告名称（default "results"）
  -o, --output-path string            报告输出目录路径
      --parallel int                  每个平台的并行工作线程数，0为自动检测（default 1）
  -p, --path strings                  待扫描路径或目录，示例："./somepath,somefile.txt"
      --payload-lines                 在payload中添加行信息
  -d, --payload-path string           内部表示JSON文件存储路径
      --preview-lines int             CLI结果中显示的行数（1-30）（default 3）
  -q, --queries-path strings          查询目录路径（default [./assets/queries]）
      --report-formats strings        报告格式（all, asff, codeclimate, csv, cyclonedx, glsast, html, json, junit, pdf, sarif, sonarqube）（default [json]）
  -r, --secrets-regexes-path string   秘密扫描规则配置文件路径
      --terraform-vars-path string    Terraform变量文件路径
      --timeout int                   查询执行超时时间（秒）（default 60）
  -t, --type strings                  指定扫描平台类型（大小写不敏感），如：Terraform,Kubernetes
      --exclude-type strings          排除扫描平台类型（大小写不敏感），不可与-t同时使用

5.4 全局选项

所有命令均支持的全局标志：

Global Flags:
      --ci                  仅输出日志消息到CLI（与silent互斥）
  -f, --log-format string   日志格式（pretty,json）（default "pretty"）
      --log-level string    日志级别（TRACE,DEBUG,INFO,WARN,ERROR,FATAL）（default "INFO"）
      --log-path string     日志文件生成路径（info.log）
      --no-color            禁用CLI彩色输出
      --profiling string    启用性能分析，在日志中打印资源消耗 metrics（CPU, MEM）
  -s, --silent              静默stdout输出（与verbose、ci互斥）
  -v, --verbose             同时输出日志到stdout（与silent互斥）

6. 示例配置

6.1 生成多格式报告

扫描并输出JSON、HTML、JUnit格式报告：

docker run -t -v $PWD:/path checkmarx/kics:latest scan \
  -p /path \
  -o /path/reports \
  --report-formats json,html,junit \
  --output-name iac-scan-results

结果：在$PWD/reports目录下生成iac-scan-results.json、iac-scan-results.html、iac-scan-results.junit.xml。

6.2 排除低危结果并忽略扫描结果导致的非0退出码

docker run -t -v $PWD:/path checkmarx/kics:latest scan \
  -p /path \
  -o /path \
  --exclude-severities low \
  --ignore-on-exit results

6.3 UBI8镜像指定用户ID扫描

docker run -it -u 1001:1001 -v $PWD:/path checkmarx/kics:ubi8 scan \
  -p /path/terraform \
  -o /path/output \
  --log-level DEBUG \
  -v

官方文档：[]
代码仓库：[]