In Checkov, what are the two ways to write a custom check, and when do you need the Python form?

## Why a custom check exists at all An infrastructure-as-code scanner ships a catalog of generic misconfiguration rules — encryption off, a wide-open security group, public storage. What it cannot ship is *your* organisation's rules: only these AMIs are approved, only these instance families and sizes may be launched, only these regions, every resource carries an owner tag. Those rules exist only once somebody writes them, and a custom check is where they get written. Checkov gives you two authoring surfaces for that, and choosing between them is the first decision. ## Form 1 — the declarative YAML policy A YAML custom policy is data, not code. It has two top-level blocks: ```yaml metadata: name: "EC2 instances must use an approved AMI" id: "CKV_ACME_1" category: "GENERAL_SECURITY" definition: cond_type: attribute resource_types: - aws_instance attribute: ami operator: within value: - ami-0aaa1111 - ami-0bbb2222 ``` `metadata` carries the identity of the rule — the id that will appear in every report, the human-readable name, the category. `definition` carries the condition. A condition of `cond_type: attribute` names the resource types it applies to, the attribute path to inspect, an operator (`equals`, `not_equals`, `exists`, `not_exists`, `contains`, `regex_match`, `within`, and comparison operators), and the value to compare against. Conditions nest under `and:` / `or:` lists, so "instance type is in this list AND the owner tag exists" is a single YAML file. There is a second condition type that is easy to miss and is the main reason to know the YAML form exists: `cond_type: connection`. Checkov builds a graph of the resources it parsed, so a connection condition can assert that a resource of one type is (or is not) connected to a resource of another type — an instance attached to a security group, a bucket attached to a policy. That is a cross-resource assertion, and it is not something you get from looking at one resource block in isolation. ## Form 2 — the Python check The Python form is a class: ```python class ApprovedAmi(BaseResourceCheck): def __init__(self): super().__init__(name="EC2 instances must use an approved AMI", id="CKV_ACME_1", categories=[CheckCategories.GENERAL_SECURITY], supported_resources=["aws_instance"]) def scan_resource_conf(self, conf): ... ``` The constructor declares the same identity metadata the YAML `metadata` block does, plus `supported_resources` — the resource types this check is invoked for. `scan_resource_conf` receives the parsed resource block and returns a `CheckResult`. Instantiating the class at module scope is what registers it. There is also a value-oriented base class where you only supply the attribute path to inspect and the expected value, which is a middle ground between the two forms. Choose Python when the rule needs behaviour a fixed operator set cannot express: comparing two attributes of the same resource to each other, deriving the allowlist from something computed at load time, string-parsing an image or AMI name, or walking a nested block whose shape varies. ## What both forms must carry Whichever form you pick, the rule is not just its logic. It carries an **id** — the string that shows up in reports, in dashboards, in baselines, and in whatever suppression mechanism your team uses. Pick a namespace of your own (`CKV_ACME_1`, not a number in the vendor's range) so a custom check never shadows a built-in one and so anyone reading a report can tell at a glance that this rule came from your team. It carries a **name** that has to make sense to the developer who is blocked by it at 5pm, and a **category**. Rules that also let you attach a guideline link should have one: a finding with a URL that explains what to do instead is a very different experience from a bare rule id. ## The practical default Start in YAML. It reviews well in a pull request, a non-Python engineer can read it, and the majority of organisational rules really are "this attribute must be one of these values". Escalate to Python only when you hit a wall — and when you do, expect the parsed configuration to be less convenient than it looks, because the scanner hands you its own parsed representation rather than the source text you wrote.