Skip to main content

Aws Cfn Orphan Sweep

@jentz/aws-cfn-orphan-sweepv2026.07.20.0· 12d agoMODELS
01README

Find and (optionally) clean up the standalone CloudFormation stacks a retired StackSet leaves behind, single-account or org-wide from the management account. Retiring a StackSet with delete-stack-instances --retain-stacks drops the StackSet records but leaves each member stack behind as an ordinary standalone stack named StackSet-<setname>-<guid>; this model finds those orphans and removes them safely.

enumerate and enumerateOrg are READ-ONLY and suitable for a *-readonly profile — they only ever call List* / sts:GetCallerIdentity (plus organizations:ListAccounts and sts:AssumeRole for the org variant, which assumes a uniformly-named role into each ACTIVE member account). They write per-account orphan / summary rows plus an org-summary rollup.

MUTATING: cleanup and cleanupOrg DELETE stacks — including each stack's backing Lambda and IAM role — when run with apply: true. Both default to a dry-run that writes plan rows and mutates nothing. Guardrails: stacks outside namePrefix are refused, nothing but the detected dead custom resource is ever retained, and cleanupOrg runs every member account with an internal expectAccount landing check so a misconfigured role can never delete in the wrong account. Applying needs cloudformation:DeleteStack + lambda:DeleteFunction + iam:GetRole — a *-readonly profile cannot run the mutating path, by design.

02Models1
@jentz/aws-cfn-orphan-sweepv2026.07.20.0aws_cfn_orphan_sweep.ts

Global Arguments

ArgumentTypeDescription
namePrefixstringOnly stacks whose name starts with this prefix are enumerated and
regionsarrayRegions to fan out across in one execution.
profilestringNamed AWS profile (resolved via fromIni). Empty (default) uses the
assumeRoleNamestringRole name assumed into each member account by enumerateOrg (the role
fn enumerate()
READ-ONLY fan-out: ListStacks (active statuses) per region, keep names
fn enumerateOrg(onlyAccount: string)
READ-ONLY cross-account fan-out — the recommended first action for an
ArgumentTypeDescription
onlyAccountstringIf set, restrict the sweep to this one member account (canary).
fn cleanup(apply: boolean, expectAccount: string, onlyRegion: string, onlyStack: string, retainLogicalId: string, waitSeconds: number, maxWaits: number, verifyRole: boolean, initiateOnly: boolean, predeleteLambda: boolean)
MUTATING when apply=true (dry-run otherwise). By default predeletes
ArgumentTypeDescription
applybooleanWhen false (default), dry-run: write would-* preview rows
expectAccountstringIf set, refuse to run unless the resolved account id matches — a
onlyRegionstringIf set, only act on orphans in this region (canary scoping).
onlyStackstringIf set, only act on this exact stack name (single-stack canary).
retainLogicalIdstringOverride the retained logical id. Honored only if it equals the
waitSecondsnumberSeconds between DescribeStacks polls while waiting for deletion.
maxWaitsnumberMaximum polls before giving up on a delete.
verifyRolebooleanAfter delete, GetRole on the captured role name to confirm removal.
initiateOnlybooleanFire the delete on each stack and return immediately without polling
predeleteLambdabooleanDelete the stack's backing Lambda before deleting the stack, so the
fn cleanupOrg(apply: boolean, onlyAccount: string, onlyRegion: string, onlyStack: string, retainLogicalId: string, waitSeconds: number, maxWaits: number, verifyRole: boolean, initiateOnly: boolean, predeleteLambda: boolean)
MUTATING cross-account cleanup when apply=true (dry-run otherwise —
ArgumentTypeDescription
applybooleanWhen false (default), dry-run: write would-* preview rows
onlyAccountstringIf set, restrict the sweep to this one member account (canary).
onlyRegionstringIf set, only act on orphans in this region (canary scoping).
onlyStackstringIf set, only act on this exact stack name (single-stack canary).
retainLogicalIdstringOverride the retained logical id. Honored only if it equals the
waitSecondsnumberSeconds between DescribeStacks polls while waiting for deletion.
maxWaitsnumberMaximum polls before giving up on a delete.
verifyRolebooleanAfter delete, GetRole on the captured role name to confirm removal.
initiateOnlybooleanFire the delete on each stack and return immediately without polling
predeleteLambdabooleanDelete the stack's backing Lambda before deleting the stack, so the

Resources

orphan(infinite)— One standalone CloudFormation stack matching namePrefix, with its
summary(infinite)— Per-account rollup: regions scanned, orphan count, counts by region
deletion(infinite)— One delete attempt (or dry-run plan) for an orphan stack: action,
org-summary(infinite)— Cross-account rollup written once per enumerateOrg or cleanupOrg run,
03Previous Versions2
2026.07.19.0
2026.07.03.1
04Stats
A
100 / 100
Downloads
0
Archive size
322.5 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
  • License declared1/1earned
  • Verified public repository2/2earned
05Platforms
06Labels