@codacy/tools-checkov-3

Table of Contents

• Overview
• Updating patterns
• Updating the Checkov version
• Development
• Notes for maintainers

Overview

Infrastructure-as-Code security scanner using the Checkov binary. Scans Terraform, CloudFormation, Kubernetes, Dockerfile, and many other IaC frameworks for security misconfigurations. Uses the CLI execution strategy with Python/pip installation into an isolated virtual environment.

Updating patterns

# Re-fetch pattern metadata from the Codacy API
pnpm prefetch

# Commit the result
git add src/patterns.json

Updating the Checkov version

1. Update preferredVersion in src/adapter.ts
2. Update the PIP_PACKAGE constant in src/adapter.ts (e.g. checkov==3.2.510)
3. Run pnpm prefetch to refresh patterns (new versions may add checks)
4. Run pnpm test to verify compatibility
5. Consider creating a new package (checkov-4/) if the major version changes

Development

# Install checkov locally (requires Python 3.9+)
pip install checkov==3.3.19

# Build with tsup
pnpm build

# Run tests (skips binary-dependent tests if checkov is not installed)
pnpm test

Notes for maintainers

• Large pip install: Checkov has ~200 transitive dependencies (pydantic, boto3 stubs, networkx, etc.). First install into the venv can take several minutes. Subsequent runs use the cached venv.

• Per-tool venv isolation: The adapter installs Checkov into ~/.codacy/runtimes/Checkov/venv/ to avoid dependency conflicts with other Python-based tools.

• Multi-framework JSON output: Checkov can emit a single JSON object or an array of objects (one per framework). The adapter normalizes both to an array before parsing.

• Path normalization: repo_file_path from Checkov always has a leading / which must be stripped.

• No column information: Checkov does not provide column numbers. All issues use column: 1.

• Exit codes: Exit code 0 = no issues, 1 = issues found (normal), >1 = genuine error.

• Container mode network blocking: In container mode (ctx.runner === "container"), the adapter sets proxy env vars and RENDER_EDGES_DUPLICATE_ITER_COUNT=50 to block Bridgecrew API calls and tune performance.

• Pattern filtering: Uses --check CKV_xxx,CKV_yyy,... to run only specific checks. The Checkov_ prefix is stripped from pattern IDs to get the raw check ID.

• Config files: Looks for .checkov.yaml or .checkov.yml. When local config is active, passes --config-file <path>.

• Parsing errors: Checkov reports parsing_errors in its JSON output, which are surfaced as AnalysisError objects with kind: "ParsingError".

• Preset mappings (src/pattern-mappings.json): gates 1,280 of the 1,360 patterns on a detected IaC framework, so init --auto doesn't enable AWS resource policy in a repo with no infrastructure. Measured effect: a repo with only a package.json went from 1,225 enabled Checkov patterns to 80.

  The gate is per IaC framework, not per cloud, because a cloud resource can be declared several ways — the same bucket is an aws_s3_bucket in Terraform, an AWS::S3::Bucket in CloudFormation and a resources: block under Serverless. filterAutoPatterns enables a framework pattern when any of its keys was detected, so the same prefix is listed under several keys to mean "AWS resources, however they are declared". That OR is what makes gating safe here; an earlier revision left all ~1,091 cloud-provider checks universal precisely because gating them on .tf alone would have dropped every cloud check for a CloudFormation-only repo.

  • "lang:Terraform" maps CKV_TF_ plus every cloud-provider family (CKV_AWS_, CKV_AZURE_, CKV_GCP_, and the 10 smaller clouds). No file signal is needed: .tf is the Terraform language, so lang:Terraform already means "this repo has Terraform".
  • cloudformation and serverless-framework also claim CKV_AWS_/CKV2_AWS_; bicep also claims CKV_AZURE_/CKV2_AZURE_. Detected by file signal (samconfig.*, a root template.yaml, a cloudformation/ directory, serverless.yml, *.bicep).
  • kubernetes and helm both claim CKV_K8S_/CKV2_K8S_/CKV_ARGO_ — a chart's templates render to manifests, so either is evidence. Detected from kustomization.yaml / Chart.yaml.
  • ansible claims CKV_ANSIBLE_/CKV2_ANSIBLE_, from ansible.cfg or the roles/<name>/tasks/main.yml layout.
  • Still universal (80 patterns), each for a stated reason:
    • CKV_SECRET_ (18) and CKV_BCW_ (1) by design — secret scanning must not be suppressed by any framework gate.
    • CKV_OPENAPI_ (21) — an OpenAPI/AsyncAPI document identifies itself by its openapi:/swagger: key, which a path-only signal cannot see. Needs the content probe.
    • The VCS governance families CKV_GITHUB_ (26), CKV_GIT_ (7), CKV_GLB_ (4), CKV_GITLAB_, CKV_BITBUCKET_, CKV2_ADO_ (1 each). These are unresolved, not deferred: their titles read as platform/API settings (Checkov's github_configuration framework, which reads API data and cannot fire on a filesystem scan), while an earlier reading of this file recorded them as governance resources managed through each platform's Terraform provider — in which case they belong under lang:Terraform. The two readings imply opposite fixes (prune vs. gate), so they are left untouched until checked against Checkov's own framework declarations.
  • Known gap: a bare Kubernetes manifest (k8s/deployment.yaml) or a bare CloudFormation template is still not detected — only the conventional shells around them are. Both declare themselves in their content, so closing this needs a bounded content probe (apiVersion:, AWSTemplateFormatVersion), which is not implemented.
  • Known gap (upstream): most patterns carry languages: ["JSON", "YAML", "Terraform"], which is the tool-level fallback Codacy's API returns for a pattern with no per-pattern languages — not a claim about the check. It over-declares (JSON is why Checkov is selected almost everywhere) and under-declares (only 6 of 28 CKV_DOCKER_ checks list Dockerfile, so 22 are dropped by the language filter in a Dockerfile-only repo). The durable fix is in the cloud tool definition; see todo-checkov-languages.md.