README.md

cfn-validate

The command-line front end for the validation engine.

The CLI wires the workspace together: it parses a template with template-model, selects an engine (composite-engine, rego-engine, or cel-engine), runs the validation-engine pipeline ( including schema-validator), and renders the resulting report as JSON.

How it works

  template.yaml ──▶ cfn-validate ──▶ JSON report (stdout)
                         │
                         ├── Parse template (template-model)
                         ├── Select engine (composite, rego, or cel)
                         ├── Run validation pipeline (validation-engine)
                         │   ├── Schema validation (schema-validator)
                         │   ├── Engine rule evaluation
                         │   ├── Step Functions validation
                         │   ├── Metadata Context validation
                         │   ├── Enrichment + filtering
                         │   └── Report assembly
                         └── Format output (standard / detailed)

cfn-validate

Validates a CloudFormation template, all files in a directory, or a template piped to standard input. Recursively collects .yaml, .yml, and .json files when given a directory path. Passing - as the template argument reads the template from standard input instead of disk; its report is labelled <stdin>.

cfn-validate <TEMPLATE|DIR|-> [OPTIONS]

# validate a synthesized template without writing it to disk
cdk synth MyStack | cfn-validate -

Filter options:

Option	Description
--include-ids ID,...	Only report these rule IDs
--exclude-ids ID,...	Suppress these rule IDs
--include-categories CAT,...	Only report these categories
--exclude-categories CAT,...	Suppress these categories
--include-range E3000-E3099	Only report rules in numeric range
--exclude-range E3000-E3099	Suppress rules in numeric range
--include-resource-id ID[=RULE]	Only report rules on a logical resource ID
--exclude-resource-id ID[=RULE]	Suppress rules on a logical resource ID
--include-logical-id ID[:TYPE][=RULE]	Only report rules on a named template entity (resource, parameter, output, mapping, metadata, condition, or rule); :TYPE (e.g. :Parameter) scopes to one entity type
--exclude-logical-id ID[:TYPE][=RULE]	Suppress rules on a named template entity
--include-resource-type TYPE[=RULE]	Only report rules on a resource type
--exclude-resource-type TYPE[=RULE]	Suppress rules on a resource type
--include-service SERVICE[=RULE]	Only report rules on a service prefix (e.g. AWS::AutoScaling)
--exclude-service SERVICE[=RULE]	Suppress rules on a service prefix

Scoped filters take an optional =RULE suffix: --exclude-logical-id MyParam=W2001 suppresses only W2001 on MyParam, while --exclude-logical-id MyParam suppresses every rule on it. The logical-id flags additionally take an optional :TYPE scope: --exclude-logical-id MyThing:Parameter suppresses rules on the parameter MyThing without touching a same-named entity of another type.

Output options:

Option	Description
--format standard|detailed	Detail level (default: detailed)
--level fatal|error|warn|info|debug	Minimum severity (default: info)

Engine options:

Option	Description
--engine rego|cel|composite	Validation engine (default: composite). composite layers the external rules over the built-in rules
--rule-source <PATH>	Load a custom Rego/CEL rule file (repeatable). With --engine composite, .json files are CEL rules and other files are Rego rules layered on top of the built-ins
--guard-rule-source <PATH>	Load Guard (.guard) rule file or directory (repeatable)
--additional-schema <PATH>	Merge a CloudFormation resource provider schema (.json) file, or every .json in a directory, on top of the bundled schemas (repeatable)

--additional-schema is for templates that use a property or allowed value CloudFormation has not published to the registry yet: the supplied schema is merged into the bundled schema for its typeName, and a typeName with no bundled schema is registered as a new resource type. An overlay never silently drops a bundled constraint, though stating an extra required or dependency entry does add one. Anything that cannot be applied exits 2 rather than being ignored - a malformed or unreadable schema, a path that does not exist, a directory containing no .json file, or a schema using a construct the validator cannot represent. Directories are scanned one level deep. See validation-engine/API.md for the merge model and its scope limits.

Parameter options:

Option	Description
--region REGION	Set the AWS::Region pseudo-parameter
--parameter Key=Value	Override a template parameter value (repeatable)
--pseudo-parameter Key=Value	Override a pseudo-parameter value (repeatable)

Supported pseudo-parameters: AWS::AccountId, AWS::NotificationARNs, AWS::Partition, AWS::Region, AWS::StackId, AWS::StackName, AWS::URLSuffix.

Other options:

Option	Description
--strict	Upgrade Warn-severity diagnostics to Error
--disable-builtin-rules	Disable all built-in rules; only evaluate custom and guard rules
--list-rules	List all available rules and exit
--version	Print version and exit
--help, -h	Print usage and exit

Exit codes:

• 0 - no errors or fatal diagnostics
• 1 - errors or fatal diagnostics found
• 2 - usage error (bad arguments, file not found, engine init failure)