Why does a custom Checkov check comparing conf["ami"] to a string fail every instance?

## The symptom You wrote a custom check to enforce an approved-AMI allowlist. Every instance in the repository fails it, including the three that use AMIs literally present in your list. Nothing in the rule's logic looks wrong. ## What the check is actually handed The important thing about extending a scanner rather than writing a rule against raw plan JSON is that you are working inside **the scanner's own parsed model of the resource block**, and that model is not the text you wrote. Checkov parses HCL with a parser that represents every attribute as a list of values. So for: ```hcl resource "aws_instance" "web" { ami = "ami-0aaa1111" instance_type = "m6i.large" } ``` the dictionary passed to `scan_resource_conf` looks roughly like `{"ami": ["ami-0aaa1111"], "instance_type": ["m6i.large"]}`. A comparison of `conf["ami"]` against a list of approved id strings compares a list to strings, is never satisfied, and the check falls through to `FAILED` for every resource. The rule is not "broken" in any way the scanner can detect — it runs, it returns a result, and the result is wrong on every input. Nested blocks are wrapped too: a block like `root_block_device { encrypted = true }` arrives as a list containing a dictionary whose own values are lists. Any check that walks into a nested block has to unwrap at each level. ## The fix, and the second bug hiding behind it ```python ami = conf.get("ami", [None])[0] if ami in APPROVED: return CheckResult.PASSED return CheckResult.FAILED ``` Two things changed. The `[0]` unwraps the parser's list. The `.get` with a default handles the resource that has no `ami` key at all — an instance created from a launch template, a resource type variant, a module that sets it elsewhere. `conf["ami"]` on such a resource raises a `KeyError`, and an exception inside a custom check is a worse failure than a wrong verdict: depending on how the run is configured you either lose that resource's result or lose the run. Ask yourself explicitly what the *absent* attribute should mean. For an allowlist, "no AMI specified" is usually not a violation of the AMI rule — the instance is getting its image from somewhere your check cannot see, and failing it produces a finding nobody can action. Deciding the absent case deliberately is the difference between a rule that gets adopted and a rule a team demands be turned off. ## The third shape: values that are not literals A custom check is reading configuration, not a realised resource. `ami = var.approved_ami` or `ami = data.aws_ami.base.id` cannot be compared to a literal allowlist. Checkov resolves what it can — variables with defaults, values passed into modules it parsed — but plenty of values remain references, and your check will see a string that is not an AMI id. A strict allowlist comparison then fails a resource that is, in fact, compliant at apply time. The honest options are to fail closed (treat unresolvable as a violation, and accept that developers will need an exception path), to pass and rely on a second control that sees resolved values, or — the usual middle ground — to fail only on a literal that is not in the list, and let anything unresolved through with a rule you know has a hole. What you must not do is write the strict comparison and then be surprised when a team tells you the gate is wrong. ## Why this is the canonical first bug Everything about the parsed model — list wrapping, nested blocks as lists of dicts, unresolved references — is invisible from the HCL you are looking at while writing the rule. That is why the practical advice for writing any custom check is: print the `conf` dictionary for a real resource once before writing any logic, and write the check against what you actually see. It is also why writing a unit test for a custom check pays for itself immediately: a fixture with one compliant and one violating resource catches the list-wrapping bug in the first run, and it catches it again the day someone refactors the rule. ## The generalisable lesson Extending a scanner means inheriting its data model. Whether the engine hands you a Python dictionary or a document to query in Rego, the shape it hands you is the shape you must code against — not the shape of the file on disk. Every scanner-extension bug in this category is the same bug: the author wrote the rule against the source text they had in their head instead of the parsed structure the engine actually passes in.