Related Pages

Related topics: Supported IaC, Pipeline, and SCA Frameworks, Configuration, Custom Policies, and Output Formats

Overview and Core Architecture

Purpose and Scope

Checkov is a static code analysis tool for Infrastructure as Code (IaC) that also functions as a software composition analysis (SCA) tool for images and open source packages. It scans cloud infrastructure provisioned through a wide range of IaC frameworks, providing built-in policies that cover security and compliance best practices for AWS, Azure, and Google Cloud. The project also validates AWS CDK synth outputs, ARM templates, Bicep, Serverless framework files, and Kubernetes manifests.

Source: README.md

The tool targets developers, DevOps engineers, and security teams who need a consistent, local-first way to evaluate IaC files before deployment. It is published to PyPI and packaged as a Docker image, with a CLI entry point that exposes more than 1000 built-in policies. Configuration can be supplied through command-line flags, environment variables, or a YAML config file; the merged configuration is visible via --show-config. Source: README.md

High-Level Architecture

Checkov is organized around three cooperating subsystems:

1. Framework parsers and runners — per-IaC-language modules that discover files, parse them into a normalized resource representation, and emit a record for each declared block.
2. Module loaders — a pluggable resolver chain that fetches external Terraform modules referenced via module blocks, supporting registries, generic Git remotes, and VCS-specific shortcuts.
3. Checks — pluggable policy classes (resource checks, graph checks, variable checks) that operate on the normalized resource records and produce a CheckResult of PASSED, FAILED, or UNKNOWN.

The CLI orchestrates these subsystems, applies user configuration, and produces output in formats such as CLI, JSON, SARIF, JUnit XML, and CycloneDX. Source: README.md

flowchart LR
    A[CLI / main] --> B[Framework Runners]
    B --> C[Module Loaders]
    C --> D[Resource Records]
    D --> E[Check Registry]
    E --> F[CheckResult]
    F --> G[Reporters]
    subgraph ModuleLoaders
        C1[RegistryLoader]
        C2[GenericGitLoader]
        C3[GithubLoader]
        C4[BitbucketAccessTokenLoader]
        C5[GithubAccessTokenLoader]
    end

Source: checkov/terraform/module_loading/loaders/registry_loader.py, checkov/terraform/module_loading/loaders/git_loader.py, checkov/terraform/module_loading/loaders/github_loader.py

Terraform Module Loading Subsystem

The module loading subsystem is built around a chain of ModuleLoader implementations. Each loader exposes discover, _is_matching_loader, and _load_module, and the runner selects the first loader that claims a given module_source string. Source: checkov/terraform/module_loading/loaders/git_loader.py

RegistryLoader

RegistryLoader resolves modules sourced from the Terraform Registry and private registries that speak the same protocol. It consults TF_HOST_NAME, TF_REGISTRY_TOKEN, and the deprecated TFC_TOKEN environment variables, normalizes the host part of module download URLs, and recognizes archive extensions such as .zip, .tar.gz, .tgz, .tar.bz2, .tar.xz, and .txz. A class-level modules_versions_cache keeps version lists in memory for the lifetime of the process. Source: checkov/terraform/module_loading/loaders/registry_loader.py

GenericGitLoader and friends

GenericGitLoader handles the git::<url> and git@<host>:<path> source forms. It splits the source on // to separate the protocol, the root module, and any inner module subdirectory, and extracts a ?ref=<version> query string that pins the checkout. GithubLoader rewrites short GitHub-style sources (e.g. github.com/org/repo) into a fetchable form, while GithubAccessTokenLoader and BitbucketAccessTokenLoader inject credentials from VCS_USERNAME/VCS_TOKEN, GITHUB_PAT, BITBUCKET_USERNAME/BITBUCKET_APP_PASSWORD, or BITBUCKET_TOKEN. Source: checkov/terraform/module_loading/loaders/git_loader.py, checkov/terraform/module_loading/loaders/github_loader.py, checkov/terraform/module_loading/loaders/github_access_token_loader.py, checkov/terraform/module_loading/loaders/bitbucket_access_token_loader.py

Version Constraints

versions_parser.py defines VERSION_REGEX and VersionConstraint, a small class that wraps a parsed version together with the operator (=, !=, >, >=, <, <=, ~>) and can answer whether an arbitrary version string satisfies the constraint. Helpers order_versions_in_descending_order and get_version_constraints are reused by RegistryLoader to pick the best matching version. Source: checkov/terraform/module_loading/loaders/versions_parser.py

Check Infrastructure

Each framework contributes its own set of checks. For Terraform, the dominant abstractions are:

• Resource checks that receive a normalized configuration dict and return a CheckResult.
• Graph checks that operate on the resource graph (relationships between resources).
• Variable checks that evaluate input variable definitions.

A reusable base class for IAM-related Terraform checks is BaseTerraformCloudsplainingIAMScanner, which uses the external cloudsplaining library to find privilege-escalation and resource-exposure violations in inline and managed policies. To amortize the cost of constructing a PolicyDocument, it maintains a class-level policy_document_cache keyed by the policy content. The base class also enriches evaluated_keys with the specific statement or action that triggered the violation. Source: checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py

A check that fails to evaluate a policy (for example, because the policy is templated and contains unresolved ARNs) returns CheckResult.UNKNOWN rather than PASSED or FAILED, which is the correct behavior for partial evaluation.

Configuration, Reporting, and Integration Tests

CLI flags, environment variables, and the .checkov.yml file form a layered configuration system. The merged result can be inspected with --show-config, which prints each option and the source (command line, environment, file, or default) that supplied it. Source: README.md

Output formats are pluggable and the tool integrates with SARIF, CycloneDX SBOM, JUnit XML, and Prisma Cloud's API for remediation-guide enrichment; the API call can be disabled with --skip-download. Source: README.md

The repository includes an integration test suite that synthesizes AWS CDK applications and verifies the resulting CloudFormation output against the relevant checks. Test fixtures exist in both Python and TypeScript, for example cdk_integration_tests/src/python/SNSTopicEncryption/fail.py and cdk_integration_tests/src/typescript/SNSTopicEncryption/fail.ts, which intentionally produce unencrypted SNS topics so that the corresponding check should fail. Source: cdk_integration_tests/src/python/SNSTopicEncryption/fail.py, cdk_integration_tests/src/typescript/SNSTopicEncryption/fail.ts

Operational Notes and Common Pitfalls

Several community-reported issues highlight recurring concerns with the architecture and packaging:

• Installation parity. CKV2 checks may not run when Checkov is installed via Homebrew, while the same version installed via pip does run them, leading to divergent CI results. Source: issue #6645
• Dependency CVEs. Older releases ship with vulnerable transitive dependencies (for example, urllib3, asteval, ply) that can affect the security posture of consumers and CI runners. Source: issue #7504
• API-dependent flags. Severity-based filters such as --hard-fail-on and --soft-fail-on rely on a Prisma Cloud API call to enrich severities; the call silently changes behavior when BC_API_KEY is missing. Source: issue #7379
• Parser gaps. Unsupported language constructs in Bicep (extension) and unresolved placeholders in Kubernetes manifests (${VAR}) cause the affected files to be silently skipped rather than surfaced as parse errors. Source: issue #7364, issue #7210

See Also

• Terraform module loading
• Check authoring guide
• Configuration and CLI flags
• Bicep / ARM scanning
• Kubernetes scanning

Related Pages

Related topics: Overview and Core Architecture, Configuration, Custom Policies, and Output Formats

Supported IaC, Pipeline, and SCA Frameworks

Checkov advertises itself as both a static code analysis tool for Infrastructure-as-Code (IaC) and a Software Composition Analysis (SCA) tool for images and open-source packages. The README.md enumerates the supported input formats and scan targets that define the project's scope.

Source: README.md:14-22

Infrastructure-as-Code (IaC) Frameworks

The README states that Checkov scans cloud infrastructure provisioned using Terraform, Terraform Plan, Terraform JSON, CloudFormation, AWS SAM, Kubernetes, Helm, Kustomize, Dockerfile, Serverless framework, Ansible, Bicep, ARM, and OpenTofu templates, as well as Argo Workflows. The repository also contains CDK integration tests that exercise AWS CDK Python and TypeScript projects (for example, Cloudtrail multi-region trails, SNS topic encryption, and Backup Vault encryption).

Source: README.md:14-22 Source: cdk_integration_tests/src/python/CloudtrailMultiRegion/pass.py:1-19 Source: cdk_integration_tests/src/python/SNSTopicEncryption/fail.py:1-21 Source: cdk_integration_tests/src/typescript/SNSTopicEncryption/fail.ts:1-18

Terraform and OpenTofu

The README indicates that the supported IaC scope begins with Terraform, Terraform Plan (.json produced by terraform show -json), and OpenTofu template files. The README.md documents the canonical workflow of producing a plan JSON via terraform plan -out tf.plan && terraform show -json tf.plan > tf.json and running checkov -f tf.json.

Source: README.md:30-58

The Terraform module loader subsystem demonstrates that Checkov supports multiple Terraform module source kinds, which is what makes the framework coverage practical for real-world repositories:

The RegistryLoader._get_archive_extension helper accepts the archive types defined in MODULE_ARCHIVE_EXTENSIONS = ["zip", "tar.bz2", "tar.gz", "tgz", "tar.xz", "txz"], matching the Terraform language specification for fetching archives over HTTP.

Source: checkov/terraform/module_loading/loaders/registry_loader.py:31-46

CloudFormation, SAM, and CDK

Checkov supports AWS CloudFormation and AWS SAM templates as listed in the README. The cdk_integration_tests/ directory demonstrates that the project is also tested against AWS CDK constructs in both Python and TypeScript, including aws_cloudtrail.Trail, aws_sns.Topic, and aws_backup.CfnBackupVault resources that are evaluated for encryption and multi-region settings.

Source: README.md:14-22 Source: cdk_integration_tests/src/python/CloudtrailMultiRegion/pass.py:1-19 Source: cdk_integration_tests/src/python/BackupVaultEncrypted/fail__1__.py:1-15

Kubernetes, Helm, Kustomize, and Argo Workflows

According to the README, Checkov scans Kubernetes manifests, Helm charts, Kustomize overlays, and Argo Workflows. The Helm and Kustomize frameworks are particularly relevant for templated Kubernetes deployments; community issue #7210 highlights a known limitation where manifests containing ${VAR} placeholders are silently skipped during scanning, indicating that not all templating styles are evaluated.

Source: README.md:14-22 Source: community_context — Kubernetes manifests with ${VAR} placeholders are silently skipped

Container, Serverless, and Configuration Management

The README lists Dockerfile, Serverless framework, and Ansible among the supported scan targets. These represent the container, function-as-a-service, and configuration management layers respectively, complementing the cloud-resource IaC coverage.

Source: README.md:14-22

Bicep and ARM

Checkov also supports Bicep and Azure ARM templates. Community feedback has surfaced parser gaps in these areas: issue #7364 reports that the Bicep parser does not recognize the extension keyword and throws a parse error, and issue #7394 notes that real-world Azure expectations around Bicep/ARM support differ from documented claims. These are documented limitations to be aware of when scanning Azure codebases.

Source: community_context — Bicep: Missing parser support for extension keyword Source: community_context — Bicep / ARM support expectations are misleading for real-world Azure usage

Pipeline and CI Integrations

Checkov is consumed as both a CLI tool and as a library that can be embedded in CI/CD pipelines. The README.md illustrates CLI invocations against a directory of files, individual files, and Terraform plan JSON outputs. The --show-config flag surfaces the resolved configuration from command line, config file, environment variable, and default sources, which is useful for debugging CI invocations.

Source: README.md:60-89

The Runner module loader subsystem reads authentication credentials from environment variables, including TF_HOST_NAME, TF_REGISTRY_TOKEN, TFC_TOKEN, VCS_BASE_URL, VCS_USERNAME, VCS_TOKEN, BITBUCKET_USERNAME, BITBUCKET_APP_PASSWORD, and BITBUCKET_TOKEN. These environment variables are what make CI integrations with private Terraform registries and source-control providers work without interactive prompts.

Source: checkov/terraform/module_loading/loaders/registry_loader.py:42-50 Source: checkov/terraform/module_loading/loaders/bitbucket_access_token_loader.py:1-19

Community evidence also points to installation-channel inconsistencies: issue #6645 reports that CKV2 checks fail to run when Checkov is installed via Homebrew but succeed under pip, which is a relevant caveat for teams standardizing CI environments.

Source: community_context — Discrepancy Between Homebrew vs pip Installations

Software Composition Analysis (SCA)

In addition to IaC scanning, the README describes Checkov as a Software Composition Analysis tool that scans open-source packages and container images for Common Vulnerabilities and Exposures (CVE). This capability overlaps with IaC scanning when Dockerfile and IaC manifests reference images or packages, and is a separate concern from the policy-based IaC checks.

Source: README.md:18-22

The SCA functionality depends on a BC_API_KEY (Prisma Cloud) for some flows; community issue #7379 requested explicit warnings when API-dependent parameters are used without the API key configured, which is relevant for CI pipelines that want predictable behavior from --hard-fail-on/--soft-fail-on severity filters.

Source: community_context — Add warnings when API-dependent parameters are used without API key

Terraform Module Source Loaders (Architecture)

The following diagram summarizes the loader dispatch pattern used to resolve Terraform module references of varying kinds. Each loader advertises a source URL prefix and rewrites the module_params.module_source to a canonical form before downloading content.

flowchart LR
    A[Module source string] --> B{Loader match?}
    B -- "registry.example.com/..." --> R[RegistryLoader]
    B -- "github.com/..." --> GH[GithubLoader]
    B -- "git@... or git::..." --> GG[GenericGitLoader]
    B -- "auth via VCS_TOKEN" --> AT[GithubAccessTokenLoader / BitbucketAccessTokenLoader]
    R --> D[Download archive or git clone]
    GH --> D
    GG --> D
    AT --> D
    D --> C[ModuleContent returned to Runner]

The GenericGitLoader._parse_module_source helper supports the three Terraform Git source forms: bare git::https://, SSH-style git@host:org/repo, and git::ssh://git@host/org/repo, including inner module paths and optional ?ref=<version> qualifiers.

Source: checkov/terraform/module_loading/loaders/git_loader.py:40-100

When loading from the Terraform Registry, the RegistryLoader constructs a /versions endpoint via urljoin and an ordered version list using versions_parser.order_versions_in_descending_order, then matches the requested ModuleParams.version against the registry's published versions. The VersionConstraint class supports the standard Terraform operators: =, !=, >, >=, <, <=, and ~>, with ~> constraining to the next major version (major + 1.0.0).

Source: checkov/terraform/module_loading/loaders/registry_loader.py:48-56 Source: checkov/terraform/module_loading/loaders/versions_parser.py:10-42

A shared utility, BaseTerraformCloudsplainingIAMScanner, demonstrates that some Terraform checks perform deeper IAM policy analysis using the cloudsplaining library and cache expensive PolicyDocument instances at the class level to avoid recomputation across resources.

Source: checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py:14-43

Common Pitfalls and Failure Modes

• Templated Kubernetes manifests with shell-style ${VAR} placeholders can be silently skipped, leaving gaps in coverage (issue #7210).
• Bicep extension keyword triggers a parser error; downstream projects must work around this (issue #7364).
• Azure expectations for Bicep/ARM scanning in real codebases can diverge from the README's framing (issue #7394).
• Homebrew vs pip parity: CKV2 checks may not run under Homebrew installations (issue #6645).
• Undetermined Terraform plan values (e.g., random_id-driven attributes) cause GCS logging checks to return UNDETERMINED rather than PASS/FAIL (issue #7473).

See Also

• README.md
• Terraform Plan Scanning
• Policy Index (all checks)
• Contribution Overview
• Migration v2 to v3

Related Pages

Related topics: Overview and Core Architecture, Supported IaC, Pipeline, and SCA Frameworks

Configuration, Custom Policies, and Output Formats

Checkov is a static code analysis tool for Infrastructure-as-Code (IaC) and a software composition analysis (SCA) tool for images and open source packages. It supports Terraform, Terraform Plan/JSON, CloudFormation, AWS SAM, Kubernetes, Helm, Kustomize, Dockerfile, Serverless framework, Ansible, Bicep, ARM, and OpenTofu template files (README.md). Configuration, custom policies, and output formats are the three orthogonal axes that determine how a scan behaves: *configuration* tells Checkov where to look and how to authenticate; *custom policies* encode the rules being applied; *output formats* decide how the resulting findings are reported.

Configuration Sources and Precedence

Checkov's runtime configuration is resolved through a layered model. As shown in README.md, the --show-config flag enumerates every active setting and its origin — command line, environment variable, config file, or built-in default. For example:

checkov --show-config

Will display:

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

Source: README.md. Within Checkov's own source code, environment-variable driven configuration is also visible in the module-loading subsystem. For Terraform registry modules, TF_HOST_NAME and TF_REGISTRY_TOKEN are read in RegistryLoader.discover, while TFC_TOKEN triggers a deprecation warning. Source: checkov/terraform/module_loading/loaders/registry_loader.py.

For Git-sourced modules, the generic loader reads VCS_BASE_URL, VCS_USERNAME, and VCS_TOKEN, with GITHUB_PAT used as a fallback credential. Source: checkov/terraform/module_loading/loaders/git_loader.py. Vendor-specific loaders extend this pattern: the Bitbucket loader expects BITBUCKET_USERNAME, BITBUCKET_APP_PASSWORD, or BITBUCKET_TOKEN, while the GitHub access-token loader injects a username:token pair into the rewritten source URL. Sources: checkov/terraform/module_loading/loaders/bitbucket_access_token_loader.py, checkov/terraform/module_loading/loaders/github_access_token_loader.py.

The version-constraint system that ultimately decides *which* artifact is fetched for a module reference is implemented in checkov/terraform/module_loading/loaders/versions_parser.py. A regex extracts (operator, version) pairs (e.g., ~>, >=, =) and VersionConstraint evaluates them against an externally supplied version string using matchers such as >= and ~>. Source: checkov/terraform/module_loading/loaders/versions_parser.py.

flowchart LR
    A[Command Line Args] --> M[Resolved Config]
    B[Environment Variables] --> M
    C[.checkov.yml] --> M
    D[Built-in Defaults] --> M
    M --> E[Module Loaders]
    M --> F[Runner / Output]
    E --> G[Policy Engine]
    F --> G
    G --> H[Reporters]

Custom Policies

Custom policies are implemented as Python classes that subclass a base check interface. The repository includes a reusable BaseTerraformCloudsplainingIAMScanner that wraps the cloudsplaining library to evaluate Terraform IAM policies. It maintains a class-level policy_document_cache keyed by cache_key to avoid re-parsing identical policies, and exposes two abstract hooks — convert_to_iam_policy and cloudsplaining_analysis — that concrete checks override. If parsing fails (typical for templated ARNs), the scanner returns CheckResult.UNKNOWN rather than FAILED, preventing false positives. Source: checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py.

The repository also contains a cdk_integration_tests directory that doubles as a corpus of working example policies. For instance, the Python fixture BackupVaultEncrypted/fail__1__.py constructs an aws_backup.CfnBackupVault without supplying a kms_key_arn, which the matching CKV_AWS_* policy is designed to flag. Source: cdk_integration_tests/src/python/BackupVaultEncrypted/fail__1__.py. The pass examples — CodeBuildProjectEncryption/pass.py (explicitly setting encryption_disabled=True is then matched against a policy that asserts encryption is enabled) and LaunchConfigurationEBSEncryption/pass.ts — illustrate how typed IaC constructs are translated into the JSON-like dicts consumed by BaseResourceCheck.scan_resource_conf. Sources: cdk_integration_tests/src/python/CodeBuildProjectEncryption/pass.py, cdk_integration_tests/src/typescript/LaunchConfigurationEBSEncryption/pass.ts. Together they document the expected *shape* of a passing vs. failing resource definition, which is the contract every custom policy enforces.

Output Formats

The default output is the CLI reporter, set by --output: cli in the defaults block. Source: README.md. A typical CLI line associates a check ID (e.g., CKV_AWS_21) with a human-readable title, the offending resource, and a Guide: hyperlink to the Prisma Cloud remediation page.

For machine consumption, Checkov can scan a Terraform plan rendered as JSON. The recommended workflow is:

terraform init
terraform plan -out tf.plan
terraform show -json tf.plan > tf.json
checkov -f tf.json

The README notes an important caveat: if the JSON is emitted on a single line, every finding is reported at file:0-0. Piping through jq '.' produces a multi-line file whose line numbers are then usable in CI annotations. Source: README.md.

Several community-reported issues highlight edge cases that operators should be aware of when configuring output. CKV2 checks do not run under the Homebrew distribution but do under pip, leading to divergent local vs. CI results — a configuration-channels concern rather than a true check failure. Source: issue #6645. Kubernetes manifests containing templated placeholders such as ${K8S_APP_NAME} are silently skipped, so reporters never see the corresponding FAILED lines. Source: issue #7210. Severity-based filters like --hard-fail-on and --soft-fail-on require a BC_API_KEY, and missing that key produces confusing failures rather than warnings. Source: issue #7379. Practitioners are advised to always run checkov --show-config before relying on severity filters and to prefer the pip distribution when running CKV2 checks.

Common Failure Modes and Mitigations

A handful of recurring failure modes are documented in the codebase and the issue tracker. Several GCP and AWS check IDs (e.g., CKV_GCP_62, CKV_GCP_63, CKV_AWS_86) mis-handle "undetermined" Terraform values — typically expressions referencing random_id or v2 CloudFront logging blocks — and emit FAILED for resources whose configuration is not yet resolvable. Sources: issue #7473, issue #7385. CKV_GCP_93 ignores the multi-key CMEK configuration pattern used for Spanner databases, producing false positives. Source: issue #7402. CKV_GCP_123 does not honor remove_default_node_pool, which is the documented GKE workaround. Source: issue #7406. And the Bicep parser fails on the extension keyword, blocking scans of real-world Azure templates. Source: issue #7364.

The standard mitigation, applied to each case, is to suppress the specific check (--skip-check CKV_…) once the false-positive root cause is understood, while tracking upstream fixes in the issue thread. Source: README.md.

See Also

• Terraform module loading architecture
• Built-in policy index (docs/5.Policy Index/all.md)
• Migration guide from v2 to v3 (docs/1.Welcome/Migration.md)
• Contributing new checks (docs/6.Contribution/Contribution Overview.md)

Related Pages

Related topics: Supported IaC, Pipeline, and SCA Frameworks, Configuration, Custom Policies, and Output Formats

Known Issues, False Positives, and Community Workarounds

Overview

Checkov is a static code analysis tool for Infrastructure-as-Code (IaC) and a software composition analysis (SCA) tool for images and open source packages Source: [README.md:1-9]. As with any large policy-as-code engine, certain checks produce false positives, edge cases in parsers cause unexpected skips, and packaging decisions can create friction in CI/CD pipelines. This page catalogs the most commonly reported issues, their root causes (where they can be traced to the source), and the workarounds that the community has converged on.

False Positives in Specific Policy Checks

GCP Policy False Positives

AWS Policy False Positives

CKV_AWS_86 validates only the legacy v1 logging configuration of a CloudFront distribution. When the newer v2 logging block is used, the check reports a failure because it does not inspect the v2 schema. Until the check is updated, users on v2 logging must suppress CKV_AWS_86 or maintain a v1 block alongside v2.

IAM Policy Evaluation Robustness

The shared cloudsplaining scanner gracefully degrades when an IAM policy cannot be parsed (for example, when ARNs are templated) and returns CheckResult.UNKNOWN rather than raising Source: [checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py:15-31]. This is the intended behavior for noisy template values but can surface as apparent false positives in dashboards that aggregate unknowns.

Module Loading and Packaging Issues

Installation Channel Discrepancies

A widely reported discrepancy exists between Homebrew and pip installs: CKV2 graph checks do not run when Checkov is installed via Homebrew, while pip installs run them correctly. Because Homebrew bundles an older Python packaging metadata, CI pipelines that provision Checkov through pip produce different results than developer machines using Homebrew. The community's workaround is to pin the pip install (pip install checkov==<version>) in CI to guarantee parity with local pip runs.

Python Module Packaging

The published Python wheel restricts packaging metadata to the 23.x line even though Checkov itself has shipped >=24 for nearly a year. Builds that share a build environment with other Python packages therefore fail on version conflicts. The recommended mitigation is to install Checkov in a dedicated virtual environment or container so that its transitive dependency constraints cannot collide with another project's resolver.

External Module Loaders

Checkov resolves Terraform module sources through a chain of loaders. The RegistryLoader speaks to the Terraform Registry and honors TF_REGISTRY_TOKEN and the legacy TFC_TOKEN for authentication Source: [checkov/terraform/module_loading/loaders/registry_loader.py:30-41]. Version constraints are parsed by VersionConstraint and matched against =, !=, >, >=, <, <=, and ~> operators Source: [checkov/terraform/module_loading/loaders/versions_parser.py:9-44].

For Git-based sources, the GenericGitLoader handles git::https://..., git::ssh://..., and git@host:... forms, including embedded submodules via the //inner-module syntax Source: [checkov/terraform/module_loading/loaders/git_loader.py:43-100]. The GithubLoader rewrites short github.com/org/repo sources to git::https://... and supports both HTTPS and SSH shorthand Source: [checkov/terraform/module_loading/loaders/github_loader.py:14-32]. When credentials are present, the GithubAccessTokenLoader and BitbucketAccessTokenLoader inject tokens into the URL, supporting BITBUCKET_USERNAME/BITBUCKET_APP_PASSWORD and BITBUCKET_TOKEN (the latter switches the username to x-token-auth) Source: [checkov/terraform/module_loading/loaders/bitbucket_access_token_loader.py:14-23].

A common failure mode is that manifest files containing ${VAR} placeholders (for example, in Kubernetes manifests) are silently skipped during scanning because the parser cannot resolve the substitution. The community workaround is to either pre-substitute the values with envsubst before running Checkov, or to provide a resolved copy of the manifest in a CI-only path.

API-Dependent Options Without an API Key

Severity-based filters such as --hard-fail-on and --soft-fail-on enrich results through Prisma Cloud's API. When BC_API_KEY is unset, those parameters produce confusing behavior. The community request is for Checkov to print an explicit warning when API-dependent options are used without a key. Until that is implemented, the workaround is to either set BC_API_KEY or pass --skip-download to opt out of API enrichment.

Parser and Framework Limitations

Bicep Parser Gaps

The Bicep parser (backed by the pycep library) does not yet recognize the extension keyword and emits a parsing error when it appears. Until upstream pycep ships support, users must either remove extension blocks from scanned files or exclude them via --skip-path. A broader community concern is that Bicep/ARM support lags behind Terraform in real-world Azure codebases, so teams adopting Checkov for Azure should pilot on a representative subset before broad rollout.

Terraform Plan Variable Exposure

Terraform plan JSON contains a top-level variables object that BaseResourceCheck.scan_resource_conf cannot currently read. This means checks cannot consult plan-time variable values when deciding pass/fail. The community workaround is to encode required values directly in the resource configuration or pass them through .tfvars files that Checkov can evaluate.

Security Hygiene

The release line 3.2.517 ships with dependencies (notably urllib3 1.26.20, asteval, and ply) that carry published CVEs. Users who cannot immediately upgrade should pin Checkov in a virtualenv and audit their transitive closure, or pin patched minimum versions in their own constraints file. The maintainers actively triage CVE reports against the dependency manifest.

CDK and Framework Test Coverage

The integration tests under cdk_integration_tests/ exercise both pass and fail scenarios for AWS CDK-synthesized CloudFormation. For example, an SNS topic without encryption is expected to fail Source: [cdk_integration_tests/src/python/SNSTopicEncryption/fail.py:15-20] Source: [cdk_integration_tests/src/typescript/SNSTopicEncryption/fail.ts:11-19], while a CodeBuild project with explicit artifact encryption is expected to pass Source: [cdk_integration_tests/src/python/CodeBuildProjectEncryption/pass.py:1-22]. When a CDK-synthesized stack reports an unexpected result, comparing against these fixtures is a fast way to determine whether a behavior is a regression or a known gap.

See Also

• Terraform Plan Scanning
• Custom Check Authoring Guide
• Suppressing Findings and skip directives
• Module Sources and External Module Downloading

Doramagic Pitfall Log

Found 35 structured pitfall item(s), including 9 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/bridgecrewio/checkov/issues/7394

2. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/bridgecrewio/checkov/issues/6645

3. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/bridgecrewio/checkov/issues/6950

4. Configuration risk: Configuration risk requires verification

• Severity: high
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/bridgecrewio/checkov/issues/7473

5. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Developers should check this security_permissions risk before relying on the project: Security: Multiple CVEs in Dependencies (urllib3, asteval, ply) - Checkov 3.2.517
• User impact: Developers may expose sensitive permissions or credentials: Security: Multiple CVEs in Dependencies (urllib3, asteval, ply) - Checkov 3.2.517
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Security: Multiple CVEs in Dependencies (urllib3, asteval, ply) - Checkov 3.2.517. Context: Observed when using python
• Evidence: failure_mode_cluster:github_issue | https://github.com/bridgecrewio/checkov/issues/7504

6. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/bridgecrewio/checkov/issues/7402

7. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/bridgecrewio/checkov/issues/7396

8. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/bridgecrewio/checkov/issues/7210

9. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/bridgecrewio/checkov/issues/7504

10. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Discrepancy Between Homebrew vs pip Installations: CKV2 Checks Not Running with Homebrew
• User impact: Developers may fail before the first successful local run: Discrepancy Between Homebrew vs pip Installations: CKV2 Checks Not Running with Homebrew
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Discrepancy Between Homebrew vs pip Installations: CKV2 Checks Not Running with Homebrew. Context: Observed when using python, docker, macos, linux
• Evidence: failure_mode_cluster:github_issue | https://github.com/bridgecrewio/checkov/issues/6645

11. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: feat(general): Add warnings when API-dependent parameters are used without API key
• User impact: Developers may fail before the first successful local run: feat(general): Add warnings when API-dependent parameters are used without API key
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: feat(general): Add warnings when API-dependent parameters are used without API key. Context: Observed when using python
• Evidence: failure_mode_cluster:github_issue | https://github.com/bridgecrewio/checkov/issues/7379

12. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: update Python module packaging
• User impact: Developers may fail before the first successful local run: update Python module packaging
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: update Python module packaging. Context: Observed when using python, docker, linux
• Evidence: failure_mode_cluster:github_issue | https://github.com/bridgecrewio/checkov/issues/6950