Aws Cfn Orphan Sweep
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.
Global Arguments
| Argument | Type | Description |
|---|---|---|
| namePrefix | string | Only stacks whose name starts with this prefix are enumerated and |
| regions | array | Regions to fan out across in one execution. |
| profile | string | Named AWS profile (resolved via fromIni). Empty (default) uses the |
| assumeRoleName | string | Role name assumed into each member account by enumerateOrg (the role |
| Argument | Type | Description |
|---|---|---|
| onlyAccount | string | If set, restrict the sweep to this one member account (canary). |
| Argument | Type | Description |
|---|---|---|
| apply | boolean | When false (default), dry-run: write would-* preview rows |
| expectAccount | string | If set, refuse to run unless the resolved account id matches — a |
| onlyRegion | string | If set, only act on orphans in this region (canary scoping). |
| onlyStack | string | If set, only act on this exact stack name (single-stack canary). |
| retainLogicalId | string | Override the retained logical id. Honored only if it equals the |
| waitSeconds | number | Seconds between DescribeStacks polls while waiting for deletion. |
| maxWaits | number | Maximum polls before giving up on a delete. |
| verifyRole | boolean | After delete, GetRole on the captured role name to confirm removal. |
| initiateOnly | boolean | Fire the delete on each stack and return immediately without polling |
| predeleteLambda | boolean | Delete the stack's backing Lambda before deleting the stack, so the |
| Argument | Type | Description |
|---|---|---|
| apply | boolean | When false (default), dry-run: write would-* preview rows |
| onlyAccount | string | If set, restrict the sweep to this one member account (canary). |
| onlyRegion | string | If set, only act on orphans in this region (canary scoping). |
| onlyStack | string | If set, only act on this exact stack name (single-stack canary). |
| retainLogicalId | string | Override the retained logical id. Honored only if it equals the |
| waitSeconds | number | Seconds between DescribeStacks polls while waiting for deletion. |
| maxWaits | number | Maximum polls before giving up on a delete. |
| verifyRole | boolean | After delete, GetRole on the captured role name to confirm removal. |
| initiateOnly | boolean | Fire the delete on each stack and return immediately without polling |
| predeleteLambda | boolean | Delete the stack's backing Lambda before deleting the stack, so the |
Resources
- 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