Skip to main content
← back to extensions

Aws/cfn Diagnostics

@webframp/aws/cfn-diagnosticsv2026.10.14.1· Apache-2.0(was none)· 12d agoBEHAVIORS
01README

Read-only diagnostics for failed or rolled-back CloudFormation stack operations. Pulls stack event history, separates root-cause failures from cancellation cascades and rollback blockers, follows nested stacks, and looks up the CloudTrail API calls behind a failure (AccessDenied, ExpiredToken, and similar).

Authentication

Uses the default AWS credential chain. Set the optional profile global argument to resolve credentials from a named AWS shared-config profile (SSO token cache / fromIni), enabling multi-account use within a single swamp repo. Only Describe*, List* and LookupEvents calls are made, so a read-only profile is sufficient.

Required IAM Permissions

  • cloudformation:ListStacks
  • cloudformation:DescribeStacks
  • cloudformation:DescribeStackEvents
  • cloudformation:ListStackResources
  • cloudtrail:LookupEvents

Usage

swamp model create @webframp/aws/cfn-diagnostics cfn-prod \
  --global-arg region=us-east-1 --global-arg profile=prod-account

# Find the stack
swamp model method run cfn-prod list_stacks --input nameContains=my-app

# What failed, and which failure is the root cause?
swamp model method run cfn-prod list_stack_events \
  --input stackName=my-app --input since=7d

# Which API call was denied, and as which principal?
swamp model method run cfn-prod lookup_events \
  --input startTime=2026-10-09T18:00:00Z --input endTime=2026-10-09T18:15:00Z \
  --input lookupAttribute=EventSource --input lookupValue=rds.amazonaws.com

Methods

  • list_stacks - List stacks, optionally filtered by name substring and status
  • describe_stack - Stack status, parameters, tags, and every resource's state
  • list_stack_events - Events in a time window with failed events, root-cause candidates, and rollback blockers extracted; follows nested stacks
  • lookup_events - CloudTrail LookupEvents (management events, last 90 days) with principal extraction and an error roll-up
02Release Notes

2026.10.14.1

Added: The manifest now declares license: Apache-2.0 (SPDX). The registry quality rubric scores a declared license separately from the bundled LICENSE.md.

Upgrade note: Metadata only. No code, schema, or behavioral changes.

2026.10.13.1

Added: Initial release. Read-only CloudFormation failure diagnostics: list_stacks, describe_stack, list_stack_events (failed events, root-cause candidates, rollback blockers, nested-stack follow), and lookup_events (CloudTrail LookupEvents with principal extraction and an error roll-up).

03Behaviors1
@webframp/aws/cfn-diagnosticsv2026.10.14.1aws/cfn_diagnostics.ts
fn list_stacks(nameContains?: string, includeDeleted?: boolean)
List stacks whose name contains a substring. Excludes DELETE_COMPLETE stacks unless includeDeleted or statuses says otherwise. The name filter is client-side, so `truncated` can hide matches on a large account.
ArgumentTypeDescription
nameContains?stringCase-insensitive substring of the stack name
includeDeleted?booleanInclude DELETE_COMPLETE stacks (kept by CloudFormation for 90 days).
fn describe_stack(stackName: string)
Describe one stack: status, reason, parameters, tags, and every resource's current state
ArgumentTypeDescription
stackNamestringStack name or full stack ARN (required for deleted stacks)
fn list_stack_events(stackName: string, since?: string, followNested?: boolean)
Fetch stack events in a time window and extract failed events, root-cause candidates and rollback blockers. Optionally follows nested stacks.
ArgumentTypeDescription
stackNamestringStack name or full stack ARN (ARN required for deleted stacks)
since?stringWindow start (ISO date or relative: 30m, 6h, 2d)
followNested?booleanAlso fetch events for nested AWS::CloudFormation::Stack resources
fn lookup_events(startTime?: string, endTime?: string, lookupValue?: string, errorsOnly?: boolean, eventSource?: string, maxEvents?: number)
Query CloudTrail LookupEvents (management events, last 90 days) and roll up errors by code and API. Use to find AccessDenied / ExpiredToken calls behind a stack failure.
ArgumentTypeDescription
startTime?stringWindow start (ISO date or relative: 30m, 6h, 2d)
endTime?stringWindow end (default now)
lookupValue?stringValue for lookupAttribute
errorsOnly?booleanKeep only events carrying an errorCode (client-side filter)
eventSource?stringClient-side filter, e.g. rds.amazonaws.com (useful alongside a server-side filter)
maxEvents?numberMaximum matching events to keep

Resources

stack_list(1d)— CloudFormation stacks matching a name filter
stack_detail(1d)— One stack's status, parameters, tags and resource states
stack_events(7d)— Stack event history for a time window, with failures and root-cause candidates extracted
trail_events(7d)— CloudTrail LookupEvents results with error roll-up
04Previous Versions1
2026.10.13.1

2026.10.13.1

Added: Initial release. Read-only CloudFormation failure diagnostics: list_stacks, describe_stack, list_stack_events (failed events, root-cause candidates, rollback blockers, nested-stack follow), and lookup_events (CloudTrail LookupEvents with principal extraction and an error roll-up).

05Stats
A
100 / 100
Downloads
17
Archive size
234.9 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License2/2earned
  • Verified public repository2/2earned
Repository
https://github.com/webframp/swamp-extensions
06Platforms
07Labels
#aws#cloudformation#cloudtrail#incident-response#infrastructure#troubleshooting