Infrastructure as Code (IaC) security scanning using Checkov with 750+ built-in policies for Terraform, CloudFormation, Kubernetes, Dockerfile, and ARM templates.
Checkov is a static code analysis tool that scans Infrastructure as Code (IaC) files for security misconfigurations and compliance violations before deployment. With 750+ built-in policies, Checkov helps prevent cloud security issues by detecting problems in Terraform, CloudFormation, Kubernetes, Dockerfiles, Helm charts, and ARM templates.
Checkov performs graph-based scanning to understand resource relationships and detect complex misconfigurations that span multiple resources, making it more powerful than simple pattern matching.
# Via pip
pip install checkov
# Via Homebrew (macOS)
brew install checkov
# Via Docker
docker pull bridgecrew/checkov
# Scan all Terraform files in directory
checkov -d ./terraform
# Scan specific file
checkov -f ./terraform/main.tf
# Scan with specific framework
checkov -d ./infrastructure --framework terraform
# Scan Kubernetes YAML files
checkov -d ./k8s --framework kubernetes
# Scan Helm chart
checkov -d ./helm-chart --framework helm
# Scan CloudFormation template
checkov -f ./cloudformation/template.yaml --framework cloudformation
Identify IaC files and frameworks to scan:
# Supported frameworks
checkov --list-frameworks
# Output:
# terraform, cloudformation, kubernetes, dockerfile, helm,
# serverless, arm, secrets, ansible, github_actions, gitlab_ci
Scope Considerations:
Execute Checkov with appropriate output format:
# CLI output (human-readable)
checkov -d ./terraform
# JSON output (for automation)
checkov -d ./terraform -o json
# Multiple output formats
checkov -d ./terraform -o cli -o json -o sarif
# Save output to file
checkov -d ./terraform -o json --output-file-path ./reports
What Checkov Detects:
Focus on critical issues first:
# Show only high severity issues
checkov -d ./terraform --check CKV_AWS_*
# Skip specific checks (false positives)
checkov -d ./terraform --skip-check CKV_AWS_8,CKV_AWS_21
# Check against specific compliance framework
checkov -d ./terraform --compact --framework terraform \
--check CIS_AWS,CIS_AZURE
# Run only checks with specific severity
checkov -d ./terraform --check HIGH,CRITICAL
Severity Levels:
Use inline suppression for legitimate exceptions:
# Terraform example
resource "aws_s3_bucket" "example" {
# checkov:skip=CKV_AWS_18:This bucket is intentionally public for static website
bucket = "my-public-website"
acl = "public-read"
}
# Kubernetes example
apiVersion: v1
kind: Pod
metadata:
name: privileged-pod
annotations:
checkov.io/skip: CKV_K8S_16=Legacy application requires privileged mode
spec:
containers:
- name: app
securityContext:
privileged: true
See references/suppression_guide.md for comprehensive suppression strategies.
Define organization-specific policies:
# custom_checks/require_s3_versioning.py
from checkov.terraform.checks.resource.base_resource_check import BaseResourceCheck
from checkov.common.models.enums import CheckResult, CheckCategories
class S3BucketVersioning(BaseResourceCheck):
def __init__(self):
name = "Ensure S3 bucket has versioning enabled"
id = "CKV_AWS_CUSTOM_001"
supported_resources = ['aws_s3_bucket']
categories = [CheckCategories.BACKUP_AND_RECOVERY]
super().__init__(name=name, id=id, categories=categories,
supported_resources=supported_resources)
def scan_resource_conf(self, conf):
if 'versioning' in conf:
if conf['versioning'][0].get('enabled') == [True]:
return CheckResult.PASSED
return CheckResult.FAILED
check = S3BucketVersioning()
Run with custom policies:
checkov -d ./terraform --external-checks-dir ./custom_checks
See references/custom_policies.md for advanced policy development.
Create reports for audit and compliance:
# Generate comprehensive report
checkov -d ./terraform \
-o cli -o json -o junitxml \
--output-file-path ./compliance-reports \
--repo-id my-infrastructure \
--branch main
# CycloneDX SBOM for IaC
checkov -d ./terraform -o cyclonedx
# SARIF for GitHub Security
checkov -d ./terraform -o sarif --output-file-path ./sarif-report.json
Report Types:
Map findings to compliance frameworks using references/compliance_mapping.md.
Add Checkov scanning to pull request checks:
# .github/workflows/checkov.yml
name: Checkov IaC Security Scan
on: [push, pull_request]
jobs:
checkov-scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Run Checkov
uses: bridgecrewio/checkov-action@master
with:
directory: infrastructure/
framework: terraform
output_format: sarif
output_file_path: checkov-results.sarif
soft_fail: false
- name: Upload SARIF Report
if: always()
uses: github/codeql-action/upload-sarif@v2
with:
sarif_file: checkov-results.sarif
Prevent committing insecure IaC:
# .pre-commit-config.yaml
repos:
- repo: https://github.com/bridgecrewio/checkov
rev: 2.5.0
hooks:
- id: checkov
args: [--soft-fail]
files: \.(tf|yaml|yml|json)$
Install pre-commit hooks:
pip install pre-commit
pre-commit install
# .gitlab-ci.yml
checkov_scan:
image: bridgecrew/checkov:latest
stage: security
script:
- checkov -d ./terraform -o json -o junitxml
--output-file-path $CI_PROJECT_DIR/checkov-report
artifacts:
reports:
junit: checkov-report/results_junitxml.xml
paths:
- checkov-report/
when: always
// Jenkinsfile
pipeline {
agent any
stages {
stage('Checkov Scan') {
steps {
sh 'pip install checkov'
sh '''
checkov -d ./terraform \
-o cli -o junitxml \
--output-file-path ./reports
'''
}
}
}
post {
always {
junit 'reports/results_junitxml.xml'
}
}
}
See assets/ directory for complete CI/CD templates.
Scan Terraform with Variable Files:
# Scan with tfvars
checkov -d ./terraform --var-file ./terraform.tfvars
# Download and scan external modules
checkov -d ./terraform --download-external-modules true
# Skip Terraform plan files
checkov -d ./terraform --skip-path terraform.tfstate
Common Terraform Checks:
Scan Kubernetes Manifests:
# Scan all YAML manifests
checkov -d ./k8s --framework kubernetes
# Scan Helm chart
checkov -d ./helm-chart --framework helm
# Scan kustomize output
kustomize build ./overlay/prod | checkov -f - --framework kubernetes
Common Kubernetes Checks:
Scan CloudFormation Templates:
# Scan CloudFormation template
checkov -f ./cloudformation/stack.yaml --framework cloudformation
# Scan AWS SAM template
checkov -f ./sam-template.yaml --framework serverless
Scan Dockerfiles for Security Issues:
# Scan Dockerfile
checkov -f ./Dockerfile --framework dockerfile
# Common issues detected:
# - Running as root user
# - Using :latest tag
# - Missing HEALTHCHECK
# - Exposing sensitive ports
Establish baseline for existing infrastructure:
# Create baseline (first scan)
checkov -d ./terraform --create-baseline
# This creates .checkov.baseline file with current findings
Compare subsequent scans against baseline:
# Compare against baseline - only fail on NEW issues
checkov -d ./terraform --baseline .checkov.baseline
# This allows existing issues while preventing new ones
Use Cases:
Detect hardcoded secrets in IaC:
# Enable secrets scanning
checkov -d ./terraform --framework secrets
# Common secrets detected:
# - AWS access keys
# - API tokens
# - Private keys
# - Database passwords
# - Generic secrets (high entropy strings)
--hard-fail-on for severity levels that should block deploymentscripts/)checkov_scan.py - Comprehensive scanning script with multiple frameworks and output formatscheckov_terraform_scan.sh - Terraform-specific scanning with variable file supportcheckov_k8s_scan.sh - Kubernetes manifest scanning with cluster comparisoncheckov_baseline_create.sh - Baseline creation and drift detection workflowcheckov_compliance_report.py - Generate compliance reports (CIS, PCI-DSS, HIPAA, SOC2)ci_integration.sh - CI/CD integration examples for multiple platformsreferences/)compliance_mapping.md - Mapping of Checkov checks to CIS, PCI-DSS, HIPAA, SOC2, NISTcustom_policies.md - Guide for writing custom Python and YAML policiessuppression_guide.md - Best practices for suppressing false positivesterraform_checks.md - Comprehensive list of Terraform checks with remediationkubernetes_checks.md - Kubernetes security checks and pod security standardscloudformation_checks.md - CloudFormation security checks with examplesassets/)checkov_config.yaml - Checkov configuration file templategithub_actions.yml - Complete GitHub Actions workflowgitlab_ci.yml - Complete GitLab CI pipelinejenkins_pipeline.groovy - Jenkins pipeline templatepre_commit_config.yaml - Pre-commit hook configurationcustom_policy_template.py - Template for custom Python policiespolicy_metadata.yaml - Policy metadata for organization-specific policiesGradually increase security posture:
# Phase 1: Scan without failing (awareness)
checkov -d ./terraform --soft-fail
# Phase 2: Fail only on CRITICAL issues
checkov -d ./terraform --hard-fail-on CRITICAL
# Phase 3: Fail on CRITICAL and HIGH
checkov -d ./terraform --hard-fail-on CRITICAL,HIGH
# Phase 4: Full enforcement with baseline
checkov -d ./terraform --baseline .checkov.baseline
Scan complete infrastructure stack:
# Use bundled script for comprehensive scanning
python3 scripts/checkov_scan.py \
--infrastructure-dir ./infrastructure \
--frameworks terraform,kubernetes,dockerfile \
--output-dir ./security-reports \
--compliance CIS,PCI-DSS
Maintain centralized policy repository:
policies/
├── custom_checks/
│ ├── aws/
│ │ ├── require_encryption.py
│ │ └── require_tags.py
│ ├── kubernetes/
│ │ └── require_psp.py
├── .checkov.yaml # Global config
└── suppression_list.txt # Approved suppressions
Focus on specific compliance requirements:
# CIS AWS Foundations Benchmark
checkov -d ./terraform --check CIS_AWS
# PCI-DSS compliance
checkov -d ./terraform --framework terraform \
--check CKV_AWS_19,CKV_AWS_21,CKV_AWS_61 \
-o json --output-file-path ./pci-dss-report
# HIPAA compliance
checkov -d ./terraform --framework terraform \
--compact --check CKV_AWS_17,CKV_AWS_19,CKV_AWS_61,CKV_AWS_93
Solution: Use progressive adoption with baselines:
# Create baseline with current state
checkov -d ./terraform --create-baseline
# Only fail on new issues
checkov -d ./terraform --baseline .checkov.baseline --soft-fail-on LOW,MEDIUM
Solution: Use inline suppressions with justification:
# Provide clear business justification
resource "aws_security_group" "allow_office" {
# checkov:skip=CKV_AWS_23:Office IP range needs SSH access for developers
ingress {
from_port = 22
to_port = 22
protocol = "tcp"
cidr_blocks = ["203.0.113.0/24"] # Office IP range
}
}
Solution: Optimize scan scope:
# Skip unnecessary paths
checkov -d ./terraform \
--skip-path .terraform/ \
--skip-path modules/vendor/ \
--skip-framework secrets
# Use compact output
checkov -d ./terraform --compact --quiet
Solution: Verify policy structure and loading:
# Check policy syntax
python3 custom_checks/my_policy.py
# Ensure proper directory structure
checkov -d ./terraform \
--external-checks-dir ./custom_checks \
--list
# Debug with verbose output
checkov -d ./terraform --external-checks-dir ./custom_checks -v
Solution: Configure module access:
# Set up Terraform credentials
export TF_TOKEN_app_terraform_io="your-token"
# Download external modules
checkov -d ./terraform --download-external-modules true
# Or scan after terraform init
cd ./terraform && terraform init
checkov -d .