fix: match KMS name filters against bare alias name as well as full alias (#1162)

* fix: match KMS exclusion against full alias so dedicated-test-key survives nuke

The KMSCustomerKeys exclusion used '^dedicated-test-key$', but cloud-nuke
filters KMS keys on the full alias from ListAliases, which includes the
'alias/' prefix. The anchored pattern never matched, so the key was deleted
on every run despite the exclusion being in place since #1025.

Confirmed in CloudTrail: cloud-nuke-gha scheduled the key for deletion on
2026-05-26 and again on 2026-07-25, each time within hours of it being
manually recreated.

* fix: match KMS name filters against bare alias name as well as full alias

KMS keys are filtered on the alias returned by ListAliases, which carries an
'alias/' prefix. A pattern written against the name users actually think in,
such as '^dedicated-test-key$', silently matched nothing, so keys were deleted
despite an exclusion being configured. This is what happened to the shared
dedicated-test-key in PhxDevOps: the exclusion added in #1025 never took effect
and the key was nuked repeatedly.

Name filters now match against both the full alias and the bare name, so either
form works. Patterns written against the prefixed form keep working unchanged.

Exclusions are now also evaluated across every alias on a key: if any alias
matches an exclude rule the key is protected, rather than being deleted because
some other alias on it was not excluded.

Note for the changelog: an include rule written against a bare name previously
matched nothing and now matches, so such a rule will start selecting keys for
deletion as its author intended.

* test: pin that a matching exclude rule always protects a KMS key

Verified by differential testing against the previous implementation across 600
combinations of alias sets and name patterns: with exclude-only configs there is
no case where the new logic deletes a key the old logic protected.

Author: james00012

.github/nuke_config.yml

@@ -131,7 +131,9 @@ KMSCustomerKeys:
   exclude:
     names_regex:
       # Shared test key referenced by multiple repos (terragrunt, terraform-aws-security, terraform-aws-eks, etc.)
-      - "^dedicated-test-key$"
+      # Either "^alias/dedicated-test-key$" or "^dedicated-test-key$" matches. The prefixed
+      # form is spelled out here so the exclusion holds regardless of cloud-nuke version.
+      - "^alias/dedicated-test-key$"
 
 VPC:
   exclude:

aws/resources/kms_customer_key.go

@@ -2,6 +2,7 @@ package resources
 
 import (
 	"context"
+	"strings"
 
 	"github.com/aws/aws-sdk-go-v2/aws"
 	"github.com/aws/aws-sdk-go-v2/service/kms"
@@ -125,22 +126,59 @@ func getKeyAliasesMap(ctx context.Context, client KmsCustomerKeysAPI) (map[strin
 	return keyAliases, nil
 }
 
-// shouldIncludeKey determines if a key should be included for deletion.
-func shouldIncludeKey(ctx context.Context, client KmsCustomerKeysAPI, keyId string, aliases []string, cfg config.ResourceType, includeUnaliasedKeys bool) (bool, error) {
-	// Skip keys without aliases unless explicitly configured to include them
-	if len(aliases) == 0 && !includeUnaliasedKeys {
-		return false, nil
-	}
+// kmsAliasPrefix is the prefix AWS returns on every alias from ListAliases.
+const kmsAliasPrefix = "alias/"
 
-	// Check if any alias matches the name filter
-	matchedByName := len(aliases) == 0 && includeUnaliasedKeys // Unaliased keys pass if configured
+// aliasNameCandidates returns the strings that name filters are matched against for a
+// given set of aliases. AWS reports aliases as "alias/my-key", but the "alias/" prefix is
+// an API artifact rather than part of the name users think in, so both the full alias and
+// the bare name are considered. A pattern matching either form applies to the key.
+func aliasNameCandidates(aliases []string) []string {
+	candidates := make([]string, 0, len(aliases)*2)
 	for _, alias := range aliases {
-		if config.ShouldInclude(&alias, cfg.IncludeRule.NamesRegExp, cfg.ExcludeRule.NamesRegExp) {
-			matchedByName = true
-			break
+		candidates = append(candidates, alias)
+		if bare := strings.TrimPrefix(alias, kmsAliasPrefix); bare != alias {
+			candidates = append(candidates, bare)
+		}
+	}
+	return candidates
+}
+
+// matchesNameFilters reports whether a key passes the configured name filters.
+//
+// An exclude rule matching any form of any alias protects the whole key, so that a key
+// carrying several aliases cannot be deleted just because one of its other aliases was
+// not excluded. When include rules are present, at least one form must match.
+func matchesNameFilters(aliases []string, cfg config.ResourceType) bool {
+	candidates := aliasNameCandidates(aliases)
+
+	for _, name := range candidates {
+		if !config.ShouldInclude(&name, nil, cfg.ExcludeRule.NamesRegExp) {
+			return false
+		}
+	}
+
+	if len(cfg.IncludeRule.NamesRegExp) == 0 {
+		return true
+	}
+
+	for _, name := range candidates {
+		if config.ShouldInclude(&name, cfg.IncludeRule.NamesRegExp, nil) {
+			return true
 		}
 	}
-	if !matchedByName {
+	return false
+}
+
+// shouldIncludeKey determines if a key should be included for deletion.
+func shouldIncludeKey(ctx context.Context, client KmsCustomerKeysAPI, keyId string, aliases []string, cfg config.ResourceType, includeUnaliasedKeys bool) (bool, error) {
+	// Skip keys without aliases unless explicitly configured to include them. Unaliased
+	// keys have no name to match, so they bypass name filtering entirely.
+	if len(aliases) == 0 {
+		if !includeUnaliasedKeys {
+			return false, nil
+		}
+	} else if !matchesNameFilters(aliases, cfg) {
 		return false, nil
 	}
 

aws/resources/kms_customer_key_test.go

@@ -92,6 +92,27 @@ func TestListKmsCustomerKeys(t *testing.T) {
 			},
 			expected: []string{key2},
 		},
+		// Anchored patterns written against the full alias must keep working, since
+		// existing configs rely on the "alias/" prefix being matchable.
+		"prefixedAnchoredExclusionFilter": {
+			configObj: config.ResourceType{
+				ExcludeRule: config.FilterRule{
+					NamesRegExp: []config.Expression{{RE: *regexp.MustCompile(`^alias/key1$`)}},
+				},
+			},
+			expected: []string{key2},
+		},
+		// Anchored patterns written against the bare name must also work. Before this was
+		// supported, a pattern like "^key1$" silently matched nothing and the key was
+		// deleted despite an exclusion being configured.
+		"bareNameAnchoredExclusionFilter": {
+			configObj: config.ResourceType{
+				ExcludeRule: config.FilterRule{
+					NamesRegExp: []config.Expression{{RE: *regexp.MustCompile(`^key1$`)}},
+				},
+			},
+			expected: []string{key2},
+		},
 		"nameInclusionFilter": {
 			configObj: config.ResourceType{
 				IncludeRule: config.FilterRule{
@@ -100,6 +121,14 @@ func TestListKmsCustomerKeys(t *testing.T) {
 			},
 			expected: []string{key1},
 		},
+		"bareNameAnchoredInclusionFilter": {
+			configObj: config.ResourceType{
+				IncludeRule: config.FilterRule{
+					NamesRegExp: []config.Expression{{RE: *regexp.MustCompile(`^key1$`)}},
+				},
+			},
+			expected: []string{key1},
+		},
 		"timeAfterExclusionFilter": {
 			configObj: config.ResourceType{
 				ExcludeRule: config.FilterRule{
@@ -119,6 +148,89 @@ func TestListKmsCustomerKeys(t *testing.T) {
 	}
 }
 
+// TestListKmsCustomerKeys_MultiAliasExclusion covers a key carrying more than one alias.
+// An exclusion matching any one of them protects the key, so a key cannot be deleted
+// merely because one of its other aliases was not excluded.
+func TestListKmsCustomerKeys_MultiAliasExclusion(t *testing.T) {
+	t.Parallel()
+
+	now := time.Now()
+	protectedKey, otherKey := "protected", "other"
+
+	mock := &mockKmsClient{
+		ListKeysOutput: kms.ListKeysOutput{
+			Keys: []types.KeyListEntry{
+				{KeyId: aws.String(protectedKey)},
+				{KeyId: aws.String(otherKey)},
+			},
+		},
+		ListAliasesOutput: kms.ListAliasesOutput{
+			Aliases: []types.AliasListEntry{
+				{AliasName: aws.String("alias/dedicated-test-key"), TargetKeyId: aws.String(protectedKey)},
+				{AliasName: aws.String("alias/some-other-name"), TargetKeyId: aws.String(protectedKey)},
+				{AliasName: aws.String("alias/unrelated"), TargetKeyId: aws.String(otherKey)},
+			},
+		},
+		DescribeKeyOutput: map[string]kms.DescribeKeyOutput{
+			protectedKey: {KeyMetadata: &types.KeyMetadata{
+				KeyId:        aws.String(protectedKey),
+				KeyManager:   types.KeyManagerTypeCustomer,
+				CreationDate: aws.Time(now),
+			}},
+			otherKey: {KeyMetadata: &types.KeyMetadata{
+				KeyId:        aws.String(otherKey),
+				KeyManager:   types.KeyManagerTypeCustomer,
+				CreationDate: aws.Time(now),
+			}},
+		},
+	}
+
+	cfg := config.ResourceType{
+		ExcludeRule: config.FilterRule{
+			NamesRegExp: []config.Expression{{RE: *regexp.MustCompile(`^dedicated-test-key$`)}},
+		},
+	}
+
+	names, err := listKmsCustomerKeys(context.Background(), mock, cfg, false)
+	require.NoError(t, err)
+	require.Equal(t, []string{otherKey}, aws.ToStringSlice(names))
+}
+
+// TestMatchesNameFilters_ExclusionIsAlwaysHonored pins the safety property that matters
+// most for a deletion tool: whenever an exclude rule matches any form of any alias on a
+// key, the key is protected. Regressing this silently deletes keys operators believe are
+// safe, which is exactly how dedicated-test-key was lost.
+func TestMatchesNameFilters_ExclusionIsAlwaysHonored(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		aliases []string
+		exclude string
+	}{
+		{"bare name, anchored", []string{"alias/dedicated-test-key"}, `^dedicated-test-key$`},
+		{"full alias, anchored", []string{"alias/dedicated-test-key"}, `^alias/dedicated-test-key$`},
+		{"unanchored substring", []string{"alias/dedicated-test-key"}, `dedicated-test-key`},
+		{"prefix wildcard", []string{"alias/dedicated-test-key"}, `^alias/`},
+		{"match everything", []string{"alias/dedicated-test-key"}, `.*`},
+		{"excluded alias listed first", []string{"alias/dedicated-test-key", "alias/other"}, `^dedicated-test-key$`},
+		{"excluded alias listed second", []string{"alias/other", "alias/dedicated-test-key"}, `^dedicated-test-key$`},
+		{"excluded alias among several", []string{"alias/a", "alias/b", "alias/dedicated-test-key"}, `^dedicated-test-key$`},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			cfg := config.ResourceType{
+				ExcludeRule: config.FilterRule{
+					NamesRegExp: []config.Expression{{RE: *regexp.MustCompile(tc.exclude)}},
+				},
+			}
+			require.False(t, matchesNameFilters(tc.aliases, cfg),
+				"exclude %q must protect a key with aliases %v", tc.exclude, tc.aliases)
+		})
+	}
+}
+
 func TestListKmsCustomerKeys_IncludeUnaliasedKeys(t *testing.T) {
 	t.Parallel()
 

docs/configuration.md

@@ -40,6 +40,22 @@ S3:
 
 Filtering is **commutative** — include and exclude filters can be applied in any order with the same result. In the example above, buckets matching `^alb-.*-access-logs$` are included unless they also match `public` or `prod`.
 
+Patterns are not implicitly anchored: they match anywhere in the name unless you add `^` and `$` yourself.
+
+#### KMS key names
+
+KMS customer-managed keys are matched by alias. AWS returns aliases with an `alias/` prefix, so both the full alias and the bare name are matched, and a pattern matching either form applies. These are equivalent:
+
+```yaml
+KMSCustomerKeys:
+  exclude:
+    names_regex:
+      - ^alias/my-key$
+      - ^my-key$
+```
+
+When a key carries several aliases, an exclusion matching any one of them protects the key.
+
 ### time_after / time_before
 
 Filter resources by creation time.