Skip to content

opensite-ai/opensite-skills / aws-cloudformation

aws-cloudformation

Unverified

Authors, validates, and troubleshoots AWS CloudFormation templates. Covers template authoring with secure defaults, local validation with either cfn-lint or cloudformation-validate, cfn-guard security and compliance checks as a recommended default, account-aware CloudFormation service pre-deployment validation, CloudFormation Express mode for faster deployments, and root-cause diagnosis of failed stacks using CloudFormation events and CloudTrail correlation. Also covers author-time template intelligence with the CloudFormation Language Server and published cloudformation-validate libraries.

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

View on GitHub
# Validate with cfn-lint

## Overview

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](https://github.com/aws-cloudformation/cfn-lint#install) 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](validate-with-cloudformation-validate.script.md) 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

### 5. Recommend Next Steps

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](check-cloudformation-template-compliance.script.md) 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](security-considerations.md) when handling templates, outputs, secrets, tools, and installation artifacts.

## Examples

### Example Input
```yaml
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](validate-with-cloudformation-validate.script.md) as the alternate local validator or stop. Never report the template as locally validated when no local validator ran.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall