Checkov

Checkov is an open-source static analysis tool for infrastructure as code, built by the startup Bridgecrew and now developed under Palo Alto Networks, where it also serves as the open-source engine behind Prisma Cloud's IaC scanning. Its whole reason for existing is that "does this Terraform module, this CloudFormation stack, this Kubernetes manifest, or this Dockerfile look safe to apply" used to mean maintaining a different scanner, a different policy format, and a different suppression syntax for each language separately. Checkov answers all four from one Python engine, one shared policy library, and one command — because it doesn't scan text, it parses each source language into a resolved graph of resources first, which is also what lets it write a single check once and evaluate it against the same underlying resource however it was declared. By the end of this page you should know how that graph gets built, what a built-in policy ID actually checks, how to write your own check in Python or in YAML with no Python at all, and — the part teams get wrong most often — the real difference between suppressing a finding as an accepted risk and actually fixing it.

What Checkov is, and the problem it solves

☺ Like you're 10: It started as a Terraform scanner for one small startup's own use, and grew into the policy engine a much bigger security company now ships as its own product.

Checkov was created by Bridgecrew, a cloud-security startup, and released as free, open-source software under the Apache-2.0 license. Palo Alto Networks acquired Bridgecrew in 2021 and folded its technology into Prisma Cloud as the "Code Security" module — but Checkov itself stayed open source, is still hosted at github.com/bridgecrewio/checkov, and is still actively released with no Prisma Cloud account required to run it. That split matters operationally: everything on this page — the graph engine, the built-in policy library, custom checks, suppression — works completely offline with the open-source binary. Connecting a Prisma Cloud account layers on a hosted dashboard, additional proprietary policies (identified by a BC_* ID prefix instead of Checkov's own CKV_*), and org-wide policy management — a paid tier on top of a genuinely complete free tool, not a crippled trial of one.

The problem Checkov was built to solve is coverage plus consistency at once. A platform team's infrastructure is rarely written in one language: Terraform provisions the cloud resources, a Kubernetes manifest or Helm chart describes what runs on top of them, a Dockerfile builds the image those workloads run, and a CloudFormation stack might sit alongside all of it because one team standardized differently than another. Scanning each language with a different specialist tool means four different policy libraries that can drift out of sync with each other — a rule enforced for Terraform-provisioned S3 buckets but never written for the equivalent CloudFormation resource, simply because nobody built that second tool's version of the same check. Checkov's answer is one engine and one policy library that already understands all of those languages, so a policy written once has a real chance of applying everywhere the same underlying resource can appear.

Architecture: parsing IaC into a graph, not scanning it as text

☺ Like you're 10: Checkov doesn't just read each file on its own — it first draws the whole map of how every resource, variable, and module connects to every other one, then checks the finished map.

The detail that separates Checkov from a simple regex-over-text scanner is that it builds a resource graph before running a single check. For each supported framework, a dedicated parser reads the source — HCL2 for Terraform, YAML/JSON for CloudFormation and Kubernetes, a Dockerfile-specific parser for images, and similar parsers for Helm, Kustomize, Serverless Framework, ARM, and Bicep — and produces a graph (built on the NetworkX library under the hood) where each resource is a node, and edges connect a resource to the variables, modules, and other resources it actually depends on. Terraform variables get resolved through that graph: a var.bucket_name reference, a value passed down into a module, a count or for_each expansion — Checkov walks the graph to substitute the real value before a check ever runs, rather than a check having to parse raw interpolation syntax itself. Checks then run against fully resolved resource configurations, and — because the graph also captures relationships between resources — some checks can inspect a connection rather than a single resource in isolation: whether an EC2 instance is reachable through a security group that itself allows unrestricted ingress, for example, which no per-file, per-resource scan can see on its own.

Two more architectural details are worth knowing precisely. First, resolving a Terraform module fully sometimes requires the module's own source — Checkov can fetch remote modules from a registry or a git URL to complete the graph (controlled with --download-external-modules), which means graph accuracy for anything pulled from a remote module quietly depends on that fetch succeeding; in an air-gapped environment, disable it and pre-vendor the modules instead. Second, not everything in a graph can be resolved to a concrete value — a value that only exists once cloud infrastructure is actually provisioned (an AWS-generated ARN, an unresolved data source lookup) is represented internally as an "unknown," and checks that need a concrete value to evaluate are written to handle that case explicitly rather than guessing.

The policy library: one scanner across Terraform, CloudFormation, Kubernetes, and Dockerfiles

☺ Like you're 10: Every rule has an ID and a plain-English name, and the same rulebook covers your cloud resources, your cluster manifests, and the image your app runs in.

Checkov ships with well over a thousand built-in checks, each carrying a stable ID with a prefix that names its framework family — CKV_AWS_*, CKV_AZURE_*, and CKV_GCP_* for cloud-provider resources (evaluated against both Terraform and CloudFormation, per provider), CKV_K8S_* for Kubernetes manifests and Helm-rendered output, and CKV_DOCKER_* for Dockerfile instructions — plus additional families for Serverless Framework, ARM/Bicep, OpenAPI, and several CI-config formats. A handful of checks that show up constantly in practice, exactly the kind you should recognize on sight in a scan's output:

Treat those IDs as illustrative rather than a fixed table to memorize — new checks ship every release, and IDs are never reused once assigned, so the exact catalogue for your installed version is always one command away: checkov --list prints every check Checkov knows, with its ID, name, and framework. Checks also map to published compliance frameworks — --compliance-framework cis_aws and similar flags filter a run down to just the checks that correspond to a specific CIS Benchmark section, which is the mechanism compliance as code at scale covers from the compliance-reporting side rather than the scanning side.

# auto-detect every framework Checkov finds under this directory in one pass
$ checkov -d infra/

# scan just the frameworks that are actually present, explicitly
$ checkov -d infra/ --framework terraform,cloudformation,kubernetes,dockerfile

# see exactly what a specific check ID means before you decide to suppress or fix it
$ checkov --list | grep CKV_AWS_20

Custom policies: a check written in Python, or the same idea in YAML with no Python at all

☺ Like you're 10: If none of the built-in rules cover something your team specifically cares about, you can write your own rule two ways — as real code, or by filling in a template that needs no code.

Every organization eventually has a rule the built-in library doesn't ship, because it's specific to that organization: every S3 bucket must carry a managed-by tag naming the team that owns it, every Deployment must reference an image from the internal registry, no security group may reference a specific legacy CIDR block that's known to be a shared, poorly governed subnet. Checkov supports two ways to write that rule, and the choice mostly comes down to who's writing it.

A Python check, for anything a YAML condition can't express

A custom Python check subclasses BaseResourceCheck, declares which resource types it applies to, and implements scan_resource_conf to return a pass or fail result against that resource's parsed configuration:

# custom_checks/EnsureBucketManagedByTag.py
from checkov.common.models.enums import CheckCategories, CheckResult
from checkov.terraform.checks.resource.base_resource_check import BaseResourceCheck

class EnsureBucketManagedByTag(BaseResourceCheck):
    def __init__(self):
        super().__init__(
            name="Ensure S3 buckets carry a managed-by tag",
            id="CKV_ACME_1",                         # pick an unused, org-namespaced prefix
            categories=[CheckCategories.GENERAL_SECURITY],
            supported_resources=["aws_s3_bucket"],
        )

    def scan_resource_conf(self, conf):
        tags = conf.get("tags")
        # the HCL2 parser wraps a single block's attributes in a one-item list —
        # conf.get("tags") returns [{"managed-by": ["platform-team"]}], not a bare dict
        if tags and isinstance(tags, list):
            tags = tags[0]
        if tags and tags.get("managed-by") == ["platform-team"]:
            return CheckResult.PASSED
        return CheckResult.FAILED

check = EnsureBucketManagedByTag()   # Checkov discovers checks by the module-level instance

# point Checkov at a directory of custom checks alongside the built-in library
$ checkov -d infra/ --external-checks-dir ./custom_checks

A YAML custom policy, for a team that would rather not write Python

For conditions that boil down to "does this attribute equal/exist/match this value," Checkov's YAML policy format expresses the same idea declaratively, no Python required — and because it's built on the same graph, a YAML policy can express a connection check, not just a single resource's attributes:

# custom_checks/bucket-tag-policy.yaml
metadata:
  id: "CKV2_ACME_1"
  name: "Ensure S3 buckets carry a managed-by tag"
  category: "GENERAL_SECURITY"
scope:
  provider: "aws"
definition:
  cond_type: "attribute"
  resource_types:
    - "aws_s3_bucket"
  attribute: "tags.managed-by"
  operator: "equals"
  value: "platform-team"

The cond_type: attribute shape checks one resource's own configuration; cond_type: connection instead walks the graph's edges to check a relationship between two resource types — the shape that lets a custom policy flag "an EC2 instance whose security group allows ingress from anywhere," which no single-resource check, built-in or custom, can express. Checkov's YAML operator vocabulary and condition types have grown across releases, so treat the shape above as the pattern rather than a guaranteed copy-paste — check the current schema in Checkov's own documentation before authoring one for real, the same way you'd check checkov --list before assuming a built-in ID still means what an older blog post says it means.

Suppression: an accepted-risk finding versus an actual fix

☺ Like you're 10: Turning off a smoke alarm because you're cooking bacon is fine for five minutes — leaving it off forever because you got used to the beeping is a different decision entirely, and Checkov makes you write down which one you meant.

Not every finding should block a merge. A bucket that intentionally has public read access because it serves a static website, a security group rule that's genuinely restricted further by a second rule Checkov's per-resource check can't see, a legacy resource mid-migration that will be deleted next sprint — these are real cases where the right move is to acknowledge the finding and move on, not to force a change that makes the infrastructure worse to satisfy a scanner. Checkov gives you three ways to do that, and they're not interchangeable.

Inline suppression: scoped to one resource, with a reason on record

# infra/static_site.tf
resource "aws_s3_bucket" "site" {
  bucket = "acme-marketing-site"
}

resource "aws_s3_bucket_public_access_block" "site" {
  bucket = aws_s3_bucket.site.id
  # checkov:skip=CKV_AWS_20:Public READ is intentional — this bucket serves a static
  # website behind CloudFront; see runbook RB-114 for the origin-access-identity setup
  block_public_acls = false
}

A #checkov:skip=<check id>:<reason> comment placed on or directly above the resource block suppresses exactly that check, for exactly that resource, and nothing else. The reason after the colon isn't enforced by the tool — Checkov will happily accept a skip with no explanation at all — but treating it as mandatory in code review is the entire difference between an accepted risk and a silently disabled gate. A skip comment with a real reason is reviewable in the same pull request as the change that needed it; a bare skip comment is a scanner that's been switched off with no trace of why, which is functionally worse than not scanning that resource at all, because it looks green in every report from then on.

--skip-check: broader, and worth treating as a policy exception, not a convenience flag

# skip a check across an entire run — every resource, every file
$ checkov -d infra/ --skip-check CKV_AWS_130

# the inverse: run only a named allowlist of checks, ignoring everything else in the library
$ checkov -d infra/ --check CKV_AWS_20,CKV_AWS_21,CKV_AWS_24

--skip-check disables a rule everywhere it would otherwise fire, for the whole run, with no per-resource reason attached at all — appropriate for a genuinely inapplicable check (a rule scoped to a cloud provider or service the pipeline never touches), and a poor substitute for the inline comment when the real intent is "this one resource, for this one reason."

A baseline file: freezing today's findings so new ones are the only ones that block

# capture every current finding as accepted, without fixing or suppressing any of it individually
$ checkov -d infra/ --create-baseline
# writes .checkov.baseline — a fingerprinted snapshot of today's findings

# subsequent runs only fail on findings NOT already in the baseline
$ checkov -d infra/ --baseline .checkov.baseline

A baseline exists for exactly one situation: adopting Checkov against infrastructure that's been running unscanned for years, where failing the build on every pre-existing finding on day one would block all work indefinitely rather than improving anything. It's meant to be a debt inventory a team pays down over time, not a permanent amnesty — nothing about --baseline distinguishes "we're actively fixing these" from "we generated this once and forgot it existed."

Day-to-day commands

☺ Like you're 10: One command scans everything by default, one flag decides whether a finding actually stops the build, and a handful of output formats feed whatever's reading the results next.

# the default: scan a directory, auto-detect every framework present, human-readable CLI output
$ checkov -d infra/

# scan a single file, or force a specific framework instead of auto-detection
$ checkov -f main.tf --framework terraform

# scan an already-rendered Terraform plan, not just source — catches values only known at plan time
$ terraform show -json tfplan.binary > tfplan.json
$ checkov -f tfplan.json --framework terraform_plan

# machine-readable output for CI annotations, a dashboard, or DefectDojo import
$ checkov -d infra/ -o json --output-file-path results.json
$ checkov -d infra/ -o sarif --output-file-path results.sarif   # GitHub code scanning
$ checkov -d infra/ -o junitxml --output-file-path results.xml  # most CI test-result viewers

# quieter output for a pipeline log, showing only failures
$ checkov -d infra/ --compact --quiet

# report only, never fail the build — the flag that flips Checkov's DEFAULT-FAIL behavior
$ checkov -d infra/ --soft-fail

# list every built-in check this installed version knows about
$ checkov --list

Checkov also ships as a Docker image (bridgecrew/checkov) for a pipeline that would rather not manage a Python environment, a pre-commit hook for a local, pre-push gate, and an official GitHub Action — all wrapping the exact same CLI and exit-code behavior described above, so nothing about the commands changes based on which wrapper is running them.

Gotchas and failure modes

☺ Like you're 10: Most surprises trace back to the graph needing something it couldn't reach, or a custom check assuming the parsed config looks simpler than it actually does.

• The HCL2 parser wraps single blocks in a list. The custom-check gotcha every new author hits at least once: conf.get("tags") on a resource with one tags block returns [{"managed-by": [...]}], not a bare dict — a list containing one dict, whose own values are themselves lists. A custom check that assumes a plain dict fails silently (returns FAILED for a resource that's actually fine) rather than raising a clear error. Unwrap defensively, as in the Python example above, or test a new custom check against a resource you know should pass before trusting it against one you expect to fail.
• Remote module resolution needs network access, and a failed fetch degrades quietly. If --download-external-modules can't reach a module's source, Checkov doesn't necessarily hard-fail the whole run — the graph for that module can end up less complete than intended, which shows up as findings you expected but didn't get, not as an obvious error. In air-gapped or heavily firewalled CI, vendor modules locally and disable remote resolution explicitly rather than assuming a failed fetch will be loud about it.
• "Unknown" values aren't the same as "safe." A value only known once real infrastructure exists — a generated ARN, an unresolved data source — can't be evaluated against most checks, and Checkov's built-in checks are written to handle that gracefully rather than crash. A custom check that isn't written the same way can throw on an unknown value instead of skipping it cleanly, which is worth testing for explicitly if you're authoring your own.
• Check IDs are never reused, but new ones ship every release. An allowlist built from --check or an org-wide --skip-check list written against last year's Checkov version doesn't automatically account for checks added since — it just silently never runs them, because nothing in an ID-based allowlist references anything not yet on it. Revisit any hand-maintained check list periodically against a fresh checkov --list, the same review discipline the suppression warning above already argues for.
• A CloudFormation-shared check ID doesn't guarantee identical coverage. Checks that declare support for both a Terraform resource type and its CloudFormation equivalent are checking the same underlying risk, but parser maturity and edge-case handling aren't always perfectly symmetric between the two — don't assume a clean CloudFormation scan proves the exact same depth of coverage a clean Terraform scan would, particularly on a less common resource type.

Where Checkov sits against tfsec, Trivy, Terrascan, and Snyk IaC

☺ Like you're 10: Every alternative is trading Checkov's breadth and graph-based depth for something else — a smaller, faster single-purpose binary, or a bundle deal with a tool that already does three other jobs.

The real question, as with most tool comparisons on this page's shelf, is rarely "which one is objectively better" — it's which trade-off matches the pipeline stage you're building.

A pipeline that's already committed to Checkov as its IaC gate rarely needs a second tool in the same category — the built-in library and graph-based checks cover more ground out of the box than most teams write custom policies for in their first year. Where a second, narrower tool earns its place is usually a specific format Checkov doesn't reach as deeply, or a team that's already standardized on Rego for Kubernetes admission control and wants one policy language rather than two. See vulnerability management & triage for how Checkov's findings get deduplicated alongside every other scanner's output once a pipeline is running more than one at a time, and platform engineering for security guardrails for why a platform team usually runs Checkov centrally against every plan rather than trusting each application team to opt in on their own.