checkov v3.3.12
인프라를 코드로 관리하는 정적 분석 도구로, Terraform, Kubernetes, CloudFormation, 컨테이너 이미지에서 클라우드 구성 오류, 취약점, 시크릿을 빌드 시점에 탐지합니다.
Checkov는 인프라스트럭처 애즈 코드(IaC)를 위한 정적 코드 분석 도구이자, 이미지 및 오픈 소스 패키지를 위한 소프트웨어 구성 분석(SCA) 도구입니다.
Terraform, Terraform plan, Cloudformation, AWS SAM, Kubernetes, Helm charts, Kustomize, Dockerfile, Serverless, Bicep, OpenAPI, ARM Templates 또는 OpenTofu를 사용하여 프로비저닝된 클라우드 인프라를 스캔하고, 그래프 기반 스캔을 통해 보안 및 규정 준수 설정 오류를 탐지합니다.
또한 오픈 소스 패키지와 이미지의 CVE(Common Vulnerabilities and Exposures)를 스캔하는 소프트웨어 구성 분석(SCA) 스캔을 수행합니다.
Checkov는 개발 수명 주기 전반에 걸쳐 클라우드 보안을 코드화하고 간소화하는 개발자 우선 플랫폼인 Prisma Cloud Application Security를 지원합니다. Prisma Cloud는 클라우드 리소스 및 인프라스트럭처 애즈 코드 파일의 설정 오류를 식별, 수정 및 방지합니다.
목차
기능
- 1000개 이상의 내장 정책으로 AWS, Azure 및 Google Cloud에 대한 보안 및 규정 준수 모범 사례를 다룹니다.
- Terraform, Terraform Plan, Terraform JSON, CloudFormation, AWS SAM, Kubernetes, Helm, Kustomize, Dockerfile, Serverless framework, Ansible, Bicep, ARM 및 OpenTofu 템플릿 파일을 스캔합니다.
- Argo Workflows, Azure Pipelines, BitBucket Pipelines, Circle CI Pipelines, GitHub Actions 및 GitLab CI 워크플로 파일을 스캔합니다.
- 메모리 내 그래프 기반 스캔을 기반으로 하는 컨텍스트 인식 정책을 지원합니다.
- 속성 정책에는 Python 형식을, 속성 및 복합 정책에는 YAML 형식을 지원합니다.
- EC2 Userdata, Lambda 환경 변수 및 Terraform 공급자에서 AWS 자격 증명을 탐지합니다.
- 정규 표현식, 키워드 및 엔트로피 기반 탐지를 사용하여 비밀 정보를 식별합니다.
- Terraform을 통해 관리되는 IaaS, PaaS 또는 SaaS의 생성, 관리 및 업데이트를 규제하기 위해 Terraform Provider 설정을 평가합니다.
- 정책은 변수의 선택적 기본값까지 평가를 지원합니다.
- 인라인 억제를 통해 승인된 위험 또는 오탐지로 인한 반복적인 스캔 실패를 줄일 수 있습니다. 또한 CLI를 사용한 전역 건너뛰기도 지원합니다.
- 현재 CLI, CycloneDX, JSON, JUnit XML, CSV, SARIF, github markdown 형식으로 출력을 제공하며 수정 가이드로 연결됩니다.
스크린샷
CLI에서의 스캔 결과
Jenkins에서의 예약된 스캔 결과
시작하기
요구 사항
- Python >= 3.9, <=3.12
- Terraform >= 0.12
설치
pip를 설치하려면 공식 문서를 참조하세요.```sh pip3 install checkov
일부 환경(예: Debian 12)에서는 Checkov를 가상 환경에 설치해야 할 수도 있습니다.```sh
# Create and activate a virtual environment
python3 -m venv /path/to/venv/checkov
cd /path/to/venv/checkov
source ./bin/activate
# Install Checkov with pip
pip install checkov
# Optional: Create a symlink for easy access
sudo ln -s /path/to/venv/checkov/bin/checkov /usr/local/bin/checkov
또는 Homebrew (macOS 또는 Linux)```sh brew install checkov
### Bash 자동 완성 활성화```sh
source <(register-python-argcomplete checkov)
업그레이드
만약 pip3로 checkov를 설치했다면```sh pip3 install -U checkov
또는 Homebrew로```sh
brew upgrade checkov
입력 폴더 또는 파일 구성```sh
checkov --directory /user/path/to/iac/code
또는 특정 파일 또는 파일들```sh
checkov --file /user/tf/example.tf
또는```sh checkov -f /user/cloudformation/example1.yml -f /user/cloudformation/example2.yml
또는 JSON 형식의 terraform plan 파일```sh
terraform init
terraform plan -out tf.plan
terraform show -json tf.plan > tf.json
checkov -f tf.json
참고: terraform show 출력 파일인 tf.json은 한 줄로 구성됩니다.
그러므로 Checkov는 모든 발견 사항을 0번 줄로 보고합니다.```sh check: CKV_AWS_21: "Ensure all data stored in the S3 bucket have versioning enabled" FAILED for resource: aws_s3_bucket.customer File: /tf/tf.json:0-0 Guide: https://docs.prismacloud.io/en/enterprise-edition/policy-reference/aws-policies/s3-policies/s3-16-enable-versioning
`jq`가 설치되어 있다면 다음 명령어로 json 파일을 여러 줄로 변환할 수 있습니다:```sh
terraform show -json tf.plan | jq '.' > tf.json
스캔 결과가 훨씬 사용자 친화적일 것입니다.```sh checkov -f tf.json Check: CKV_AWS_21: "Ensure all data stored in the S3 bucket have versioning enabled" FAILED for resource: aws_s3_bucket.customer File: /tf/tf1.json:224-268 Guide: https://docs.prismacloud.io/en/enterprise-edition/policy-reference/aws-policies/s3-policies/s3-16-enable-versioning
225 | "values": {
226 | "acceleration_status": "",
227 | "acl": "private",
228 | "arn": "arn:aws:s3:::mybucket",
또는 `--repo-root-for-plan-enrichment` 플래그를 사용하여 플랜 파일을 생성하는 데 사용된 hcl 파일의 리포지토리 루트를 지정하면, 적절한 파일 경로, 줄 번호, 리소스의 코드 블록으로 출력을 보강할 수 있습니다. 추가적인 이점으로 검사 억제가 적절히 처리됩니다.```sh
checkov -f tf.json --repo-root-for-plan-enrichment /user/path/to/iac/code
스캔 결과 샘플 (CLI)```sh
Passed Checks: 1, Failed Checks: 1, Suppressed Checks: 0 Check: "Ensure all data stored in the S3 bucket is securely encrypted at rest" /main.tf: Passed for resource: aws_s3_bucket.template_bucket Check: "Ensure all data stored in the S3 bucket is securely encrypted at rest" /../regionStack/main.tf: Failed for resource: aws_s3_bucket.sls_deployment_bucket_name
Checkov를 사용하려면 [시작하기](https://github.com/bridgecrewio/checkov/blob/main/docs/1.Welcome/Quick%20Start.md) 페이지를 읽어보세요.
### Docker 사용하기```sh
docker pull bridgecrew/checkov
docker run --tty --rm --volume /user/tf:/tf --workdir /tf bridgecrew/checkov --directory /tf
참고: Python 3.6(Ubuntu 18.04의 기본 버전)을 사용하는 경우 checkov가 작동하지 않으며 ModuleNotFoundError: No module named 'dataclasses' 오류 메시지와 함께 실패합니다. 이 경우 대신 docker 버전을 사용할 수 있습니다.
참고로 docker run --tty 출력을 파일로 리디렉션하는 경우(예: Checkov JUnit 출력을 파일로 저장하려는 경우) 추가 제어 문자가 출력될 수 있습니다. 이로 인해 파일 구문 분석이 손상될 수 있습니다. 이 문제가 발생하면 --tty 플래그를 제거하십시오.
--workdir /tf 플래그는 선택 사항으로 작업 디렉터리를 마운트된 볼륨으로 변경합니다. SARIF 출력 -o sarif를 사용하는 경우 results.sarif 파일이 마운트된 볼륨(위 예에서는 /user/tf)으로 출력됩니다. 해당 플래그를 포함하지 않으면 작업 디렉터리는 "/"가 됩니다.
검사 실행 또는 건너뛰기
명령줄 플래그를 사용하여 이름이 지정된 검사만 실행(허용 목록)하거나 나열된 검사를 제외한 모든 검사를 실행(거부 목록)하도록 지정할 수 있습니다. API 키를 통해 플랫폼 통합을 사용하는 경우 건너뛰기 및/또는 포함할 심각도 임계값을 지정할 수도 있습니다. 또한 json 파일은 주석을 포함할 수 없으므로 정규식 패턴을 전달하여 json 파일 비밀 검사를 건너뛸 수 있습니다.
이러한 플래그가 함께 작동하는 방식에 대한 자세한 내용은 문서를 참조하세요.
예제
지정된 두 검사만 실행하도록 허용:```sh checkov --directory . --check CKV_AWS_20,CKV_AWS_57
지정된 검사를 제외한 모든 검사 실행:```sh
checkov -d . --skip-check CKV_AWS_20
지정된 패턴을 제외한 모든 검사를 실행합니다:```sh checkov -d . --skip-check CKV_AWS*
MEDIUM 심각도 이상의 모든 검사를 실행합니다 (API 키 필요):```sh
checkov -d . --check MEDIUM --bc-api-key ...
MEDIUM 심각도 이상의 모든 검사를 실행하고, CKV_123 검사도 실행합니다 (이 검사는 LOW 심각도로 가정):```sh checkov -d . --check MEDIUM,CKV_123 --bc-api-key ...
Skip all checks that are MEDIUM severity or lower:```sh
checkov -d . --skip-check MEDIUM --bc-api-key ...
MEDIUM 심각도 이하의 모든 검사를 건너뛰고, 검사 CKV_789도 건너뜁니다 (이는 high 심각도 검사라고 가정합니다):```sh checkov -d . --skip-check MEDIUM,CKV_789 --bc-api-key ...
중간 심각도 이상인 모든 검사를 실행하지만, 검사 CKV_123은 건너뜁니다 (이 검사는 중간 이상 심각도라고 가정합니다):```sh
checkov -d . --check MEDIUM --skip-check CKV_123 --bc-api-key ...
CKV_789 검사를 실행하되, 중간 심각도인 경우 건너뜁니다(--check 논리는 항상 --skip-check보다 먼저 적용됨).```sh checkov -d . --skip-check MEDIUM --check CKV_789 --bc-api-key ...
Kubernetes 워크로드의 경우 allow/deny 네임스페이스를 사용할 수도 있습니다. 예를 들어 kube-system 네임스페이스에 대한 결과는 보고하지 마십시오:```sh
checkov -d . --skip-check kube-system
컨테이너 이미지 스캔을 실행합니다. 먼저 이미지를 풀(pull)하거나 빌드(build)한 다음 해시, ID 또는 name:tag로 참조하십시오:```sh checkov --framework sca_image --docker-image sha256:1234example --dockerfile-path /Users/path/to/Dockerfile --repo-id ... --bc-api-key ...
checkov --docker-image :tag --dockerfile-path /User/path/to/Dockerfile --repo-id ... --bc-api-key ...
--image 플래그를 사용하여 컨테이너 이미지를 스캔할 수도 있습니다. --docker-image 대신 단축어로 사용됩니다:```sh
checkov --image <image-name>:tag --dockerfile-path /User/path/to/Dockerfile --repo-id ... --bc-api-key ...
리포지토리의 패키지에 대한 SCA 스캔 실행:```sh checkov -d . --framework sca_package --bc-api-key ... --repo-id <repo_id(arbitrary)>
버퍼링을 제거하고 디버그 수준 로그를 추가하는 환경 변수로 디렉터리 스캔을 실행하세요:```sh
PYTHONUNBUFFERED=1 LOG_LEVEL=DEBUG checkov -d .
또는 여러 실행을 위해 환경 변수를 활성화하십시오```sh export PYTHONUNBUFFERED=1 LOG_LEVEL=DEBUG checkov -d .
MyDirectory의 모든 파일에 대해 시크릿 스캐닝을 실행합니다. 접미사가 DontScan인 json 파일에 대해서는 CKV_SECRET_6 검사를 건너뜁니다.```sh
checkov -d /MyDirectory --framework secrets --repo-id ... --bc-api-key ... --skip-check CKV_SECRET_6:.*DontScan.json$
MyDirectory에 있는 모든 파일에 대해 비밀 검사를 실행합니다. 경로에 "skip_test"가 포함된 json 파일의 CKV_SECRET_6 검사를 건너뜁니다.```sh checkov -d /MyDirectory --framework secrets --repo-id ... --bc-api-key ... --skip-check CKV_SECRET_6:.*skip_test.*json$
스캔 결과에서 값을 마스킹하려면 mask 항목이 포함된 설정 파일을 제공하면 됩니다(--config-file 플래그 사용). 마스킹은 리소스 및 값(또는 쉼표로 구분된 여러 값)에 적용할 수 있습니다. 예시:```sh
mask:
- aws_instance:user_data
- azurerm_key_vault_secret:admin_password,user_passwords
위 예시에서 다음 값들이 마스킹됩니다:
- aws_instance 리소스의 user_data
- azurerm_key_vault_secret의 admin_password &user_passwords
검사 억제/무시
모든 정적 분석 도구와 마찬가지로 이 도구도 분석 범위에 한계가 있습니다. 예를 들어, 리소스가 수동으로 관리되거나 이후 구성 관리 도구를 사용하는 경우, 간단한 코드 주석을 통해 억제를 삽입할 수 있습니다.
억제 주석 형식
특정 Terraform 정의 블록 또는 CloudFormation 리소스에 대한 검사를 건너뛰려면, 해당 범위 내에서 다음 주석 패턴을 적용하세요:
checkov:skip=<check_id>:<suppression_comment>
<check_id>는 [사용 가능한 검사 스캐너](docs/5.Policy Index/all.md) 중 하나입니다.<suppression_comment>는 출력에 포함될 선택적 억제 이유입니다.
예시
다음 주석은 foo-bucket으로 식별된 리소스에 대한 CKV_AWS_20 검사를 건너뜁니다. 이 검사는 AWS S3 버킷이 비공개인지 확인합니다.
예시에서 버킷은 공개 읽기 액세스로 구성되어 있습니다. 억제 주석을 추가하면 검사가 실패하는 대신 적절한 검사를 건너뛰게 됩니다.```hcl-terraform
resource "aws_s3_bucket" "foo-bucket" {
region = var.region
#checkov:skip=CKV_AWS_20:The bucket is a public static content host
bucket = local.bucket_name
force_destroy = true
acl = "public-read"
}
출력에는 이제 ``SKIPPED`` 검사 결과 항목이 포함됩니다:```bash
...
...
Check: "S3 Bucket has an ACL defined which allows public access."
SKIPPED for resource: aws_s3_bucket.foo-bucket
Suppress comment: The bucket is a public static content host
File: /example_skip_acl.tf:1-25
...
여러 검사를 건너뛰려면 각 검사를 새 줄에 추가하십시오.``` #checkov:skip=CKV2_AWS_6 #checkov:skip=CKV_AWS_20:The bucket is a public static content host
Kubernetes 매니페스트에서 검사를 억제하기 위해, 다음 형식의 어노테이션이 사용됩니다:
`checkov.io/skip#: <check_id>=<suppression_comment>`
예를 들어:```bash
apiVersion: v1
kind: Pod
metadata:
name: mypod
annotations:
checkov.io/skip1: CKV_K8S_20=I don't care about Privilege Escalation :-O
checkov.io/skip2: CKV_K8S_14
checkov.io/skip3: CKV_K8S_11=I have not set CPU limits as I want BestEffort QoS
spec:
containers:
...
Logging
자세한 로깅을 stdout으로 출력하려면 환경 변수 LOG_LEVEL을 DEBUG로 설정하세요.
기본값은 LOG_LEVEL=WARNING입니다.
Skipping directories
파일이나 디렉터리를 건너뛰려면 --skip-path 인수를 사용하세요. 이 인수는 여러 번 지정할 수 있습니다. 이 인수는 현재 작업 디렉터리를 기준으로 하는 경로에 대한 정규 표현식을 받습니다. 전체 디렉터리 및/또는 특정 파일을 건너뛰는 데 사용할 수 있습니다.
기본적으로 node_modules, .terraform, .serverless라는 이름의 모든 디렉터리와 .으로 시작하는 모든 파일 및 디렉터리가 건너뛰어집니다. .으로 시작하는 디렉터리를 건너뛰지 않으려면 환경 변수 CKV_IGNORE_HIDDEN_DIRECTORIES를 재정의하여 export CKV_IGNORE_HIDDEN_DIRECTORIES=false로 설정하세요.
환경 변수 CKV_IGNORED_DIRECTORIES를 설정하여 건너뛸 기본 디렉터리 집합을 재정의할 수 있습니다. 이 목록을 유지하면서 추가하려면 이러한 값을 포함해야 합니다. 예를 들어, CKV_IGNORED_DIRECTORIES=mynewdir은 해당 디렉터리만 건너뛰고 위에서 언급한 다른 디렉터리는 건너뛰지 않습니다. 이 변수는 레거시 기능입니다. --skip-file 플래그 사용을 권장합니다.
Console Output
콘솔 출력은 기본적으로 색상이 적용됩니다. 단색 출력으로 전환하려면 환경 변수 ANSI_COLORS_DISABLED를 설정하세요.
VS Code Extension
VS Code 내에서 Checkov를 사용하려면 Prisma Cloud 확장 프로그램을 사용해 보세요.
Configuration using a config file
Checkov는 YAML 구성 파일을 사용하여 구성할 수 있습니다. 기본적으로 checkov는 다음 위치에서 우선순위 순서대로 .checkov.yaml 또는 .checkov.yml 파일을 찾습니다:
- checkov가 실행되는 디렉터리. (
--directory) - checkov가 호출된 현재 작업 디렉터리.
- 사용자의 홈 디렉터리.
주의: checkov 구성 파일은 검증된 ID로 구성된 신뢰할 수 있는 소스에서 로드되는 것이 모범 사례입니다. 이를 통해 스캔된 파일, 검사 ID 및 로드된 사용자 지정 검사가 원하는 대로 작동합니다.
사용자는 명령줄을 통해 구성 파일의 경로를 전달할 수도 있습니다. 이 경우 다른 구성 파일은 무시됩니다. 예:```sh checkov --config-file path/to/config.yaml
사용자는 `--create-config` 명령을 사용하여 설정 파일을 생성할 수도 있습니다. 이 명령은 현재 명령줄 인수를 받아 지정된 경로에 기록합니다. 예를 들어:```sh
checkov --compact --directory test-dir --docker-image sample-image --dockerfile-path Dockerfile --download-external-modules True --external-checks-dir sample-dir --quiet --repo-id prisma-cloud/sample-repo --skip-check CKV_DOCKER_3,CKV_DOCKER_2 --skip-framework dockerfile secrets --soft-fail --branch develop --check CKV_DOCKER_1 --create-config /Users/sample/config.yml
다음과 같은 config.yaml 파일을 생성합니다:```yaml
branch: develop
check:
- CKV_DOCKER_1 compact: true directory:
- test-dir docker-image: sample-image dockerfile-path: Dockerfile download-external-modules: true evaluate-variables: true external-checks-dir:
- sample-dir external-modules-download-path: .external_modules framework:
- all output: cli quiet: true repo-id: prisma-cloud/sample-repo skip-check:
- CKV_DOCKER_3
- CKV_DOCKER_2 skip-framework:
- dockerfile
- secrets soft-fail: true
사용자는 또한 `--show-config` 플래그를 사용하여 모든 인수와 설정 및 그 출처(즉 명령줄, 설정 파일, 환경 변수 또는 기본값)를 볼 수 있습니다. 예를 들어:```sh
checkov --show-config
표시됩니다:```sh Command Line Args: --show-config Environment Variables: BC_API_KEY: your-api-key Config File (/Users/sample/.checkov.yml): soft-fail: False branch: master skip-check: ['CKV_DOCKER_3', 'CKV_DOCKER_2'] Defaults: --output: cli --framework: ['all'] --download-external-modules:False --external-modules-download-path:.external_modules --evaluate-variables:True
## 기여
기여를 환영합니다!
[기여 가이드라인](https://github.com/bridgecrewio/checkov/blob/main/CONTRIBUTING.md)을 먼저 검토해 주세요. 그런 다음 [good first issue](https://github.com/bridgecrewio/checkov/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)를 살펴보세요.
다음 링크를 통해 Gitpod에서 브라우저로 원클릭 개발을 바로 시작할 수도 있습니다:
[](https://gitpod.io/#https://github.com/bridgecrewio/checkov)
새로운 검사 항목을 기여하고 싶으신가요? [여기](https://github.com/bridgecrewio/checkov/blob/main/docs/6.Contribution/Contribution%20Overview.md)에서 새로운 검사(정책) 작성 방법을 알아보세요.
## 면책 조항
`checkov`는 식별 가능한 고객 정보를 저장, 게시 또는 공유하지 않습니다.
식별 가능한 고객 정보가 Prisma Cloud의 공개적으로 접근 가능한 가이드를 조회하는 데 사용되지 않습니다.
`checkov`는 Prisma Cloud의 API를 사용하여 결과에 수정 가이드 링크를 추가합니다.
이 API 호출을 건너뛰려면 `--skip-download` 플래그를 사용하세요.
## 지원
[Prisma Cloud](https://www.prismacloud.io/?utm_source=github&utm_medium=organic_oss&utm_campaign=checkov)는 Checkov를 구축하고 유지 관리하여 정책을 코드로 간단하고 접근 가능하게 만듭니다.
빠른 튜토리얼과 예제는 [문서](https://www.checkov.io/1.Welcome/Quick%20Start.html)에서 시작하세요.
## Python 버전 지원
공식 Python 지원 주기를 따르며, 지원되는 Python 버전에 대해 자동화된 테스트를 사용합니다.
즉, 현재 Python 3.9~3.13을 포함하여 지원합니다.
참고: Python 3.8은 2024년 10월에 EOL(지원 종료)에 도달했으며, Python 3.9는 2025년 10월에 EOL에 도달할 예정입니다.
EOL이 아닌 Python 버전에서 문제가 발생하면 이슈를 열어 주세요.