Checkov

Learn how the starter kit uses Checkov to enforce security and compliance on CloudFormation templates.

What is Checkov?

Checkov is an open-source static analysis tool from Bridgecrew/Palo Alto Networks. It scans infrastructure-as-code files—including CloudFormation—for misconfigurations that could lead to security, compliance, or operational issues.

How the starter kit uses Checkov

  • Local validation: ./scripts/validate-templates.sh ensures Checkov is installed and then runs it with the repository's .checkov.yml configuration.
  • CI enforcement: The deploy workflow calls bridgecrewio/checkov-action@v12 before any Rain deployment. Failing checks block the pipeline so unsafe changes never reach AWS.
  • Custom policy control: The .checkov.yml file lets you enable/disable frameworks, skip findings, or add inline suppressions.

Running Checkov manually

The starter kit validation script includes Checkov:

./scripts/validate-templates.sh

Or run Checkov directly on templates:

# Scan all templates
checkov -d templates/ --framework cloudformation

# Scan with configuration file
checkov -d templates/ -c .checkov.yml

# Scan a single template
checkov -f templates/oidc-provider.yml --framework cloudformation

Common security issues detected

Checkov scans for hundreds of security and compliance checks, including:

  • S3 security: Unencrypted buckets, public access, missing versioning
  • IAM policies: Overly permissive policies, wildcard actions, missing MFA
  • Network security: Open security groups, unencrypted traffic, missing VPC flow logs
  • Encryption: Missing encryption at rest and in transit
  • Logging: Missing CloudTrail, CloudWatch logs, or access logging
  • Compliance: PCI-DSS, HIPAA, CIS AWS Foundations, SOC2, and more

Example output:

Check: CKV_AWS_18: "Ensure S3 bucket has server-side encryption enabled"
  FAILED for resource: AWS::S3::Bucket.DataBucket
  File: /templates/storage.yml:10-15
  Guide: https://docs.bridgecrew.io/docs/s3_14-data-encrypted-at-rest

Suppressing false positives

When Checkov flags a legitimate design choice, suppress the check with an inline comment:

Resources:
  LogBucket:
    # checkov:skip=CKV_AWS_18:Encryption not required for access logs
    Type: AWS::S3::Bucket
    Properties:
      BucketName: app-access-logs

Always include a justification explaining why the check doesn't apply.

CloudFormation-specific configuration

The starter kit includes a .checkov.yml file. For details on the default configuration and how to customize it, see the Checkov configuration section.

Configuration file format

branch: main
directory:
  - templates
download-external-modules: false
evaluate-variables: true
external-modules-download-path: .external_modules
framework:
  - cloudformation
secrets-scan-file-type: []
skip-check:
  - CKV_AWS_7    # Example checks to skip
  - CKV_AWS_18
  - CKV_AWS_21

Configuration options explained

framework

Specifies CloudFormation as the IaC framework:

framework:
  - cloudformation

evaluate-variables

Set to true to evaluate CloudFormation parameters and conditions:

evaluate-variables: true

This helps Checkov understand conditional logic in your templates.

skip-check

List check IDs to skip:

skip-check:
  - CKV_AWS_18  # S3 encryption - using bucket policies
  - CKV_AWS_21  # S3 versioning - not required for logs

Find check IDs in Checkov output or the Checkov documentation.

directory

Specify directories to scan:

directory:
  - templates
  - stacks

Tuning results

Output formats

Control output format for different use cases:

# Compact output for CI
checkov -d templates/ --framework cloudformation --compact

# JSON output for parsing
checkov -d templates/ --framework cloudformation --output json

# JUnit XML for test reporting
checkov -d templates/ --framework cloudformation --output junitxml > results.xml

Severity filtering

Focus on high-severity issues:

checkov -d templates/ --framework cloudformation --check CRITICAL,HIGH

Integration with CI/CD

The GitHub Actions workflow includes Checkov as part of the validation stage:

- name: Validate templates
  run: ./scripts/validate-templates.sh

This runs all validation tools including Checkov, ensuring security checks pass before deployment. Failed checks block the pipeline, preventing unsafe infrastructure from reaching production.

For complete details on how Checkov integrates into the automated workflow, see the CI/CD Workflow documentation.

Best practices

  • Run locally first: Use ./scripts/validate-templates.sh before committing to catch issues early
  • Review all failures: Don't blindly suppress checks—understand what they protect against
  • Document suppressions: Always add clear justifications when skipping checks
  • Update regularly: Keep Checkov up to date to get new security checks
  • Combine with cfn-lint: Use both tools together—Checkov focuses on security while cfn-lint focuses on correctness

Next steps

Pair Checkov with cfn-lint for comprehensive validation coverage, and review the Scripts reference to see all available validation commands.

← Raincfn-lint →