Turn operational experience into prevention

Incident-to-rule learning

Capture the infrastructure condition behind an incident once, then enforce it during every future scan. CDK Insights creates an auditable local custom rule and a Markdown postmortem; the incident never leaves your machine.

1. Describe the incident

Create a JSON file with the impact, affected CloudFormation resource types and the property conditions that would have prevented recurrence.

{
  "incidentId": "INC-042",
  "title": "Orders table could not recover deleted items",
  "summary": "Point-in-time recovery was disabled on the production table.",
  "impact": "Support restored orders manually from an earlier export.",
  "resourceTypes": ["AWS::DynamoDB::Table"],
  "triggers": [
    {
      "propertyPath": "PointInTimeRecoverySpecification.PointInTimeRecoveryEnabled",
      "operator": "notEquals",
      "value": true
    }
  ],
  "recommendation": "Enable point-in-time recovery on every production table.",
  "severity": "HIGH",
  "wafPillar": "Reliability"
}

2. Generate the rule and postmortem

npx cdk-insights learn incidents/inc-042.json

# Write to different destinations
npx cdk-insights learn incidents/inc-042.json   --rules config/team-rules.json   --postmortem docs/postmortems/inc-042.md

By default the rule is added to .cdk-insights-rules.json and the postmortem is written to docs/incidents/inc-042.md. The generated rule ID is incident-inc-042.

3. Verify the preventive control

The default custom-rule file is loaded automatically by scans. Run locally to prove the rule detects the unsafe template without using AI credits.

npx cdk-insights scan --local

# Commit the evidence with the rule
git add .cdk-insights-rules.json docs/incidents/inc-042.md
git commit -m "docs: capture INC-042 preventive control"

Incident schema

Field	Requirement	Purpose
incidentId	Non-empty string	Stable identifier used to create the generated rule ID and default postmortem path.
title, summary, impact	Non-empty strings	Human context preserved in the rule description and postmortem.
resourceTypes	One or more strings	CloudFormation types the rule evaluates, such as AWS::S3::Bucket.
triggers	One or more conditions	Property checks combined with AND when more than one is supplied.
recommendation	Non-empty string	The remediation shown when the generated rule finds a match.
severity	CRITICAL, HIGH, MEDIUM or LOW	Finding severity.
wafPillar	AWS Well-Architected pillar	Finding category used by reports and CI gates.

Trigger operators

exists

Match when the property is present.

missing

Match when the property is absent.

equals / notEquals

Compare the property with the supplied JSON value.

matches

Match a string with the supplied regular expression.

greaterThan / lessThan

Compare the property with a numeric value.

Property paths are relative to Properties. Supplying the prefix yourself is also valid. Multiple triggers are combined with AND so every condition must match.

Options

Option	Default	What it controls
--rules <path>	.cdk-insights-rules.json	Choose the custom-rule collection to create or update.
--postmortem <path>	docs/incidents/<id>.md	Choose where the generated Markdown postmortem is written.
--force	false	Replace the rule generated from the same incident ID. Without it, duplicate IDs fail safely.