Deterministic procedure for local CloudFormation template validation with cfn-lint. Use this SOP when the user explicitly requests cfn-lint, the project configures it, or it is already installed. Prefer the CLI; the Python API is also available for local validation.

Parameters

template_content (required): The CloudFormation template as a YAML or JSON string, a file path, or a URL to the template.
regions (optional): List of AWS regions to validate against (e.g., ["us-east-1", "eu-west-1"]). Defaults to cfn-lint’s default region if omitted.
ignore_checks (optional): List of cfn-lint rule IDs to suppress (e.g., ["W2001", "E3012"]).

Constraints for parameter acquisition:

You MUST ask for all required parameters upfront in a single prompt rather than one at a time
You MUST support multiple input methods for the template:
- Direct input: Template content pasted directly in the conversation
- File path: Path to a local template file
- URL: Link to a template in a repository or S3
You MUST use appropriate tools to read the template content based on the input method
You MUST confirm successful acquisition of the template content before proceeding

Steps

1. Verify Dependencies

Check which validation mechanism is available.

Constraints:

You MUST check in this order of preference:
1. cfn-lint CLI available on the user’s system (verify with which cfn-lint or cfn-lint --version)
2. Python cfnlint library (verify by attempting import cfnlint in a throwaway Python command)
If cfn-lint is not installed, You MUST consult the cfn-lint installation documentation (opens in a new tab) and authoritative package registry, resolve a compatible release, and ask the user: “I can install the exact cfn-lint version <resolved-version> from PyPI. Do you want me to install it, or would you prefer to install it manually?”
You MUST install ONLY the exact user-approved cfn-lint version from PyPI, with no extra packages. If installation is not possible — pip missing, PyPI unreachable, or the user declines — You MUST NOT attempt another cfn-lint installation mechanism. Tell the user that cfn-lint cannot run, note the reduced local validation coverage, and ask whether to use the cloudformation-validate SOP as the alternate local validator or stop.
When a supported cfn-lint mechanism is available, You SHOULD proceed with local validation without asking the user to opt in
You MUST NOT run an install command without the user’s explicit approval because it changes the user’s environment
If no cfn-lint mechanism is available and the user declines both installation and the alternate local validator, You MUST stop and state that local validation did not run
You MUST respect the user’s decision to proceed, install, or abort

2. Acquire Template Content

Obtain the CloudFormation template from the user.

Constraints:

You MUST ask the user which template(s) to validate even if templates are discoverable in the working directory, because the user may only want a subset validated
You MUST read the template content from the provided source (file path, direct input, or URL)
You MUST confirm the template is non-empty and parseable as YAML or JSON before proceeding
If the template cannot be read or parsed, You MUST inform the user with the specific error and stop

3. Run Validation

Execute cfn-lint against the template using the best available mechanism.

Constraints:

If cfn-lint CLI is available, You MUST invoke it on the template file with appropriate flags:
- Regions: --regions us-east-1 eu-west-1
- Ignore checks: --ignore-checks W2001 E3012
- Output format: --format json for structured output
- Example: cfn-lint --format json --regions us-east-1 template.yaml
Otherwise, if the Python cfnlint library is available, You MUST invoke cfnlint.api.lint(s=template_content, config={"regions": [...], "ignore_checks": [...]})
You MUST NOT modify the template content before validation because the user needs to see errors against their actual template
You MUST capture validator output for local parsing, including rule IDs, severity levels (E=error, W=warning, I=info), line numbers, and messages

4. Present Results

Report validation findings to the user.

Constraints:

You MUST start the summary with the total count: “Your template has X errors, Y warnings, Z info messages”
You MUST group related issues by resource or template section (e.g., all MyBucket errors together)
You MUST prioritize errors first, then warnings, then informational messages
You MUST include the rule ID, line number, and property path for each issue so the user can locate it
For each error, You MUST provide the specific YAML/JSON fix showing the corrected property
You SHOULD use inline comments in code fixes to explain why each change is needed
For similar errors across multiple resources, You SHOULD show the pattern once with the list of affected resources
If the template is valid with no issues, You MUST confirm this clearly

Guide the user on what to do after validation.

Constraints:

If errors were found, You MUST recommend fixing all errors before proceeding to other checks
Once the template is error-free, You SHOULD run the cfn-guard security and compliance SOP by default to check security and compliance
You MUST skip the security and compliance SOP only when the user explicitly requests it or confirms that an equivalent project security and compliance check already passed
You MUST explain what each recommended next step does so the user can make an informed decision

Security Considerations

Follow the shared security guidance when handling templates, outputs, secrets, tools, and installation artifacts.

Examples

Example Input

AWSTemplateFormatVersion: '2010-09-09'
Resources:
  MyFunction:
    Type: AWS::Lambda::Function
    Properties:
      FunctionNam: my-function
      Runtime: python3.9
      Handler: index.handler
      Role: arn:aws:iam::123456789012:role/my-function-role
      Code:
        ZipFile: |
          def handler(event, context):
              return {'statusCode': 200}

Example Output

Your template has 1 error, 0 warnings, 0 info messages.

**MyFunction (AWS::Lambda::Function):**
- E3002 at line 6: Invalid Property Resources/MyFunction/Properties/FunctionNam

Fix (line 6):
  FunctionName: my-function  # Typo: FunctionNam → FunctionName

Troubleshooting

Template fails to parse

If the tool or CLI returns a parsing error, the template has invalid YAML or JSON syntax. Check for indentation issues, missing colons, or unquoted special characters. Fix the syntax and re-run validation.

Unexpected rule violations

If cfn-lint reports errors you believe are incorrect, suppress specific rules using ignore_checks. Verify the rule ID from the output (e.g., W2001) and pass it in the parameter.

Region-specific failures

Some resource properties are only valid in certain regions. If you see region-related errors, pass the target deployment region in the regions parameter to get accurate validation.

cfn-lint not installed

Resolve a compatible cfn-lint release from the official installation documentation and authoritative PyPI metadata, then install that exact user-approved version. Do not encode a version range in this SOP. If installation is not possible (pip missing, PyPI unreachable, or the user declines), do not try another cfn-lint installation mechanism. Ask whether to use the cloudformation-validate SOP as the alternate local validator or stop. Never report the template as locally validated when no local validator ran.

references/validate-with-cfn-lint.script.md

Raw file

aws/agent-toolkit-for-aws