kms-key-rotation-operator
Operates AWS KMS key rotation workflows end-to-end — key type classification (AWS-managed, customer-managed symmetric, asymmetric RSA/ECDSA, HMAC, Multi-Region primary/replica, custom key store / CloudHSM), automatic annual backing-key rotation enablement and verification, manual key rotation (create new CMK + re-encrypt), cryptographic material lifecycle (old material retained for decrypt, new encrypts transparently), and diagnostic loops (describe-key, get-key-rotation-status, CloudTrail EnableKeyRotation events, list-grants, key-policy diff). Runs deterministic pre-checks (key Enabled, key state not PendingDeletion, symmetric SYMMETRIC_DEFAULT usage, multi-Region primary not replica, EnableKeyRotation permission in key policy) behind a CONFIRM gate and emits a READY, BLOCKED, or COMPLETED verdict per rotation. Use when enabling automatic rotation, verifying rotation ran, planning a manual rotation, or diagnosing why rotation cannot be enabled.
- License 许可
- Apache-2.0
- 最近更新
- 2026-09-24
- Stars
- ★ 4
- Forks
- 0
01 前言 Front Matter
- name
- kms-key-rotation-operator
- license
- Apache-2.0
- metadata
- { "tags": "aws, kms, security, encryption, key-management, rotation, compliance, operate", "phase": "4", "author": "Jacky Chan — AWS Community Builder", "domain": "aws-cloudops", "family": "Security", "version": "0.1.0", "keywords": "KMS, key rotation, backing key, cryptographic material, customer managed key, CMK, AWS managed key, Multi-Region key, replica key, asymmetric key, RSA_2048, ECC_NIST_P256, HMAC_256, SYMMETRIC_DEFAULT, EnableKeyRotation, GetKeyRotationStatus, CloudHSM custom key store, key policy, re-encrypt, cryptographic agility", "task_type": "operate", "complexity": "medium", "entry_point": "false", "skill_class": "capability", "when_to_use": "Enabling automatic backing-key rotation on a customer-managed KMS key, verifying a key's rotation status and last rotation date, planning a manual rotation for asymmetric/HMAC keys that do not support automatic rotation, diagnosing why EnableKeyRotation fails (Disabled/PendingDeletion key, asymmetric usage, replica key, missing key-policy permission), confirming CloudTrail EnableKeyRotation events, or validating cryptographic-agility posture across a fleet of CMKs.", "requires_llm": "true", "verdict_shape": "READY | BLOCKED | COMPLETED", "lifecycle_status": "active", "invocation_schema": "Input: either (a) a KMS key configuration (describe-key output) plus the intended operation (enable-rotation, verify-rotation, disable-rotation, plan-manual-rotation, diagnose-rotation), OR (b) a key-id + operation for live-account execution. Output: deterministic OPERATION / VERDICT / PRE_CHECKS / STEPS / POST_VERIFY / NOTES block per rotation, where VERDICT is one of READY, BLOCKED, COMPLETED.", "supports_pipeline": "true", "activation_triggers": "enable KMS key rotation, rotate KMS key, verify key rotation, GetKeyRotationStatus, EnableKeyRotation, automatic key rotation, manual key rotation, backing key, Multi-Region key rotation, replica key rotation, asymmetric key rotation, HMAC key rotation, re-encrypt with new key, cryptographic agility, KMS rotation failed" }
- description
- Operates AWS KMS key rotation workflows end-to-end — key type classification (AWS-managed, customer-managed symmetric, asymmetric RSA/ECDSA, HMAC, Multi-Region primary/replica, custom key store / CloudHSM), automatic annual backing-key rotation enablement and verification, manual key rotation (create new CMK + re-encrypt), cryptographic material lifecycle (old material retained for decrypt, new encrypts transparently), and diagnostic loops (describe-key, get-key-rotation-status, CloudTrail EnableKeyRotation events, list-grants, key-policy diff). Runs deterministic pre-checks (key Enabled, key state not PendingDeletion, symmetric SYMMETRIC_DEFAULT usage, multi-Region primary not replica, EnableKeyRotation permission in key policy) behind a CONFIRM gate and emits a READY, BLOCKED, or COMPLETED verdict per rotation. Use when enabling automatic rotation, verifying rotation ran, planning a manual rotation, or diagnosing why rotation cannot be enabled.
- compatibility
- Agent runtime that reads SKILL.md (Claude Code, Cursor, Windsurf, Codex, Gemini). No AWS CLI required for offline plan classification. Live-account operations use aws kms describe-key, get-key-rotation- status, enable-key-rotation, disable-key-rotation, list-grants, get-key-policy, list-resource-tags, aws cloudtrail lookup-events (AWS CLI v2, SSO or key-based credentials).
02 资源文件 21
- 参考文档eval/test-cases.yaml8.2 KB
- 参考文档evals/baselines/enable-rotation-asymmetric-key-blocked.md442 B
- 参考文档evals/baselines/enable-rotation-disabled-key-blocked.md438 B
- 参考文档evals/baselines/enable-rotation-symmetric-cmk-ready.md578 B
- 参考文档evals/baselines/multi-region-replica-rotation-blocked.md497 B
- 参考文档evals/baselines/verify-rotation-enabled-completed.md384 B
- 参考文档evals/eval_config.yaml1.9 KB
- 参考文档evals/evals.json4.3 KB
- 参考文档evals/prompts/enable-rotation-asymmetric-key-blocked.md593 B
- 参考文档evals/prompts/enable-rotation-disabled-key-blocked.md794 B
- 参考文档evals/prompts/enable-rotation-symmetric-cmk-ready.md1.2 KB
- 参考文档evals/prompts/multi-region-replica-rotation-blocked.md973 B
- 参考文档evals/prompts/verify-rotation-enabled-completed.md1.1 KB
- 参考文档examples/README.md7.2 KB
- 参考文档references/advanced-patterns.md7.2 KB
- 参考文档references/diagnostic-commands.md3.4 KB
- 参考文档references/error-handling.md2.6 KB
- 参考文档references/key-type-and-rotation-matrix.md8.6 KB
- 参考文档references/manual-rotation-procedures.md7.2 KB
- 参考文档references/worked-examples.md3.9 KB
- 参考文档skill.usf.yaml4.6 KB
03 SKILL.md 正文
KMS Key Rotation Operator
What this skill does
Executes KMS key rotation operations correctly and safely. Runs
deterministic pre-checks before any state-changing CLI (key Enabled,
not PendingDeletion, symmetric SYMMETRIC_DEFAULT usage, Multi-Region
primary not replica, EnableKeyRotation permission in the key policy,
not a custom key store with external rotation), executes the
enable-key-rotation / disable-key-rotation CLI behind a CONFIRM
gate, and verifies the result by confirming
get-key-rotation-status returns Enabled: true and CloudTrail shows
the EnableKeyRotation event. Every enable-rotation produces a
cryptographic-material lifecycle note (old backing material retained
for decrypt of existing ciphertext; new material encrypts all new
operations transparently). Every asymmetric/HMAC key plan routes to
manual rotation (create new key, update callers, re-encrypt) since
automatic rotation is not supported.
Quick navigation
| Section | What it covers | When to read it |
|---|---|---|
| § Quick reference | Verdict thresholds (BLOCKED/READY/COMPLETED) + pre-check priority | Before any operation |
| § Mindset | Why rotation is transparent, the asymmetric-gap, the confirm gate | Understanding the safety model |
| § Pre-flight | Key metadata gate — Enabled state, PendingDeletion, Multi-Region, custom key store | Before executing any CLI |
| § Process | Per-operation planning: enable, verify, disable, plan-manual, diagnose | When choosing which operation to run |
| § Output format | Structured OPERATION/VERDICT/PRE_CHECKS/STEPS/POST_VERIFY template | Formatting the response |
| § Anti-Patterns | NEVER list — common mistakes that break encryption or strand data | Review before risky operations |
| § Pre-flight safety | Capture pre-state, CloudTrail trail verification, key policy check | Defense-in-depth |
Quick reference — verdict thresholds
| Verdict | Trigger condition | Action |
|---|---|---|
BLOCKED |
One or more pre-checks failed (key Disabled, key PendingDeletion, asymmetric/HMAC usage with auto-rotation requested, replica key with auto-rotation requested, missing EnableKeyRotation permission, custom key store with external rotation) | List failures, do NOT execute |
READY |
All pre-checks passed; awaiting CONFIRM gate | Emit exact CLI sequence, wait for operator yes |
COMPLETED |
Rotation enable/disable finished and post-verification passed (get-key-rotation-status matches intent, CloudTrail event present, key policy unchanged, applications using key ARN still work) |
Emit verification results, monitoring plan |
Priority order for pre-checks (apply in this sequence, all must pass for READY):
- Key reachability — key exists (
describe-keydoes not returnNotFoundException),Enabledtrue,KeyState: Enabled. - No deletion pending —
KeyStateis NOTPendingDeletion(no rotation during the deletion window). - Key supports automatic rotation —
KeySpecisSYMMETRIC_DEFAULT(orAES_256for multi-Region primary) ANDKeyUsage: ENCRYPT_DECRYPTANDOrigin: AWS_KMS. Asymmetric, HMAC, and external-key-material keys do NOT support automatic rotation. - Multi-Region primary — for Multi-Region keys, rotation is
controlled by the primary key. A replica key
(
MultiRegionConfiguration.PrimaryArmy!= self) inherits the primary's rotation status;EnableKeyRotationon a replica fails. - Key policy permission — the calling identity must have
kms:EnableKeyRotation(orkms:DisableKeyRotation) on the key ARN. The key's own resource-based policy must allow the caller, or the caller's identity-based policy must grant it. Cross-account callers need both sides. - Custom key store check — for
Origin: AWS_CLOUDHSM, rotation is supported (KMS rotates the backing key in the CloudHSM cluster), but the cluster must beACTIVE. ForOrigin: EXTERNAL, rotation is NOT supported (you manage the key material externally). - Schedule intent clarity —
enable-key-rotationaccepts an optional--rotation-period-in-days(7-365, default 365). Confirm the intended cadence before enabling.
Cost/time baselines (2026):
- Customer-managed CMK: $1.00/key/month (regardless of rotation).
- Automatic rotation: no additional per-rotation fee. The CMK keeps its key ID and ARN; KMS retains old backing material for decrypt.
- Asymmetric keys (RSA, ECC): $1.00/key/month; do NOT support automatic rotation. Manual rotation = create new key + update callers + optional re-encrypt.
- HMAC keys: $1.00/key/month; do NOT support automatic rotation.
- Multi-Region keys: $1.00 per primary + $1.00 per replica.
- CloudTrail
EnableKeyRotation/DisableKeyRotationevents: free (management events). - Re-encryption cost (manual rotation):
$0.03per 10,000Encrypt/Decryptrequests. Re-encrypting a large S3 bucket or DynamoDB table is the dominant cost, not KMS itself.
Mindset
One-line takeaway: automatic KMS key rotation is transparent to applications — the key ID and ARN do not change, and old backing material is retained so existing ciphertext remains decryptable. Driven by three KMS realities:
-
Rotation swaps backing material, not the key. A KMS key is a logical construct (key ID + ARN + policy) backed by cryptographic material. Automatic rotation creates new backing material under the same key ID. All new
Encryptoperations use the new material; allDecryptoperations on existing ciphertext use the material that originally encrypted it (KMS tracks which material produced each ciphertext via the encryption context). Applications see no change. -
Asymmetric and HMAC keys are the rotation blind spot. Automatic rotation is supported ONLY on symmetric ENCRYPT_DECRYPT keys with
Origin: AWS_KMS(and CloudHSM-backed symmetric keys). RSA, ECDSA, HMAC, and external-material keys do NOT support automatic rotation. For these, you must rotate manually: create a new key, update all callers to use the new key ARN, and optionally re-encrypt old data. This is a significant operational gap — auditors asking "are all keys rotating annually?" need to be told that asymmetric keys are manually rotated. -
A Multi-Region replica key's rotation is set on the primary. Calling
EnableKeyRotationon a replica returnsInvalidOperationException. Multi-Region replica keys share the same cryptographic material as the primary — when the primary's backing material rotates, replicas receive the new material automatically. Verify rotation on the primary'sget-key-rotation-status.
Pre-flight: key metadata gate
Run before classification. Misclassifying these produces wrong plans.
Pagination + live-account pre-flight commands moved verbatim to
references/diagnostic-commands.md (load on demand).
Malformed input: if the input JSON is invalid or missing required
fields, emit VERDICT: ERROR with REASON: Key configuration is not valid JSON or is missing required fields — cannot plan. and
REMEDIATION: Re-fetch with aws kms describe-key --key-id <id> --output json and re-plan.
| Key attribute | Effect on operation |
|---|---|
KeyState: PendingDeletion + DeletionDate set |
BLOCKED — key in deletion window (7-30 days). Cancel deletion (schedule-key-deletion with --pending-window-in-days 0 is not supported; you must wait or use cancel-key-deletion to restore). |
KeyState: Disabled |
BLOCKED — key disabled. EnableKeyRotation requires Enabled: true. Call enable-key first. |
KeyUsage: SIGN_VERIFY (asymmetric) |
BLOCKED for automatic rotation. Manual rotation required. |
KeyUsage: GENERATE_VERIFY_MAC (HMAC) |
BLOCKED for automatic rotation. Manual rotation required. |
KeySpec: RSA_2048 / ECC_NIST_P256 etc. |
BLOCKED for automatic rotation. Manual rotation required. |
Origin: EXTERNAL (BYOK / imported material) |
BLOCKED for automatic rotation. Re-import new material to rotate. |
Origin: AWS_CLOUDHSM |
Supported if the cluster is ACTIVE. KMS rotates the backing key in the CloudHSM. |
MultiRegionConfiguration.MultiRegionKeyType: REPLICA |
BLOCKED for EnableKeyRotation on the replica. Enable on the primary; replica inherits. |
MultiRegionConfiguration.MultiRegionKeyType: PRIMARY |
OK — rotation propagates to all replicas automatically. |
Key policy denies caller kms:EnableKeyRotation |
BLOCKED — add the permission to the policy (or call from a role that already has it). |
Enabled: false in get-key-rotation-status |
Not an error — rotation is currently disabled. The operation enable-rotation will enable it. |
Enabled: true in get-key-rotation-status |
If the operation is enable-rotation, no-op or update RotationPeriodInSeconds. If disable-rotation, plan the disable. |
Process — operation planning (apply in order)
Step 0: Expert knowledge — non-obvious KMS behaviors
Step-0 expert behaviors moved verbatim to references/advanced-patterns.md
(backing material, rotation period, aliases, grants, AWS-managed keys, more).
Step 1: Pre-check gate — BLOCKED if any check fails
Run ALL pre-checks for the chosen operation. If ANY fails, the verdict is BLOCKED with the failed checks in PRE_CHECKS. Do NOT execute.
For ALL operations:
- Key exists (
describe-keydoes not returnNotFoundException). - Key is NOT
PendingDeletion(DeletionDateabsent,KeyState != PendingDeletion). - Calling identity has
kms:GetKeyRotationStatuson the key (for verify-rotation and diagnose-rotation).
For enable-rotation (enable-key-rotation --key-id):
4. KeyState: Enabled (not Disabled).
5. KeySpec: SYMMETRIC_DEFAULT (or AES variant).
6. KeyUsage: ENCRYPT_DECRYPT.
7. Origin: AWS_KMS OR Origin: AWS_CLOUDHSM (with cluster ACTIVE).
8. NOT a Multi-Region replica
(MultiRegionConfiguration.MultiRegionKeyType == PRIMARY or key is
single-region).
9. Calling identity has kms:EnableKeyRotation on the key ARN.
10. (Optional) --rotation-period-in-days is in [7, 365], if
specified.
For verify-rotation (read-only, no BLOCKED gate for state):
4. get-key-rotation-status returns Enabled and NextRotationDate.
5. CloudTrail shows an EnableKeyRotation event matching the key ARN
(within the last rotation period).
6. (Optional) NextRotationDate is within the expected window.
For disable-rotation (disable-key-rotation --key-id):
4. KeyState: Enabled.
5. Current get-key-rotation-status.Enabled: true (otherwise it is a
no-op).
6. Calling identity has kms:DisableKeyRotation on the key ARN.
7. (Advisory) Disabling rotation is rare and usually a compliance
violation. Confirm the operator has a documented reason.
For plan-manual-rotation (asymmetric / HMAC / external-material):
4. Key is asymmetric (KeyUsage: SIGN_VERIFY), HMAC
(GENERATE_VERIFY_MAC), or Origin: EXTERNAL.
5. Operator has kms:CreateKey permission (to create the new key).
6. List of all callers / aliases that reference the key — needed to
plan the cutover.
7. (Optional) The set of ciphertexts / signatures / MACs that need
re-encryption or re-signing (for compliance).
For diagnose-rotation (read-only):
4. Read get-key-rotation-status, CloudTrail events, and the
failure-mode table to identify why rotation cannot be enabled or
why it did not run.
Rotation failure-mode table (use during diagnose-rotation):
Rotation failure-mode table (API errors -> fixes) moved verbatim to
references/error-handling.md (load on demand).
Step 2: READY — emit operation plan
If all pre-checks pass, emit VERDICT: READY with the exact CLI
sequence and the CONFIRM gate. The plan includes:
- The exact AWS CLI command with all flags populated from the key configuration.
- The expected
RotationPeriodInSeconds(365 days default, or the specified value). - The expected side-effects (rotation status flips to
Enabled,NextRotationDateis set to ~365 days from now, key policy unchanged, applications unaffected). - The CONFIRM gate prompt.
- The verification step (
get-key-rotation-status+ CloudTrail + application spot-check).
Step 3: Execute behind CONFIRM gate
- MANDATORY CONFIRMATION GATE. Before any state-changing CLI
(
enable-key-rotation,disable-key-rotation,enable-key,disable-key,schedule-key-deletion,cancel-key-deletion,create-key,update-alias), emit:CONFIRM: About to <operation> on KMS key <key-id> (account <account> region <region>). This will <consequence>. Proceed? (yes/no). Do NOT execute until the operator confirms. - Capture pre-state for rollback:
aws kms describe-key --key-id <id> --output json > /tmp/<id>-describe-pre-$(date +%s).jsonANDaws kms get-key-rotation-status --key-id <id> --output json > /tmp/<id>-rotation-pre-$(date +%s).json. - Execute the CLI.
enable-key-rotationis synchronous — it returns once the rotation schedule is set. The actual material rotation happens atNextRotationDate. - For manual rotations: the cutover (alias update or caller update) is the state-changing step. Capture the alias pre-state.
Step 4: Post-verification — COMPLETED
After the CLI completes, run post-verification. ALL checks must pass
for COMPLETED.
get-key-rotation-status --key-id <id>— confirmEnabled: true(orfalsefor disable-rotation) andNextRotationDateis set (or absent for disable).- CloudTrail shows the
EnableKeyRotation(orDisableKeyRotation) event with the key ARN and the caller's identity. describe-key --key-id <id>— confirmKeyState: Enabled(the key itself is unaffected by the rotation-status change).get-key-policy --key-id <id> --policy-name default— confirm the policy is unchanged (rotation does not modify policy).list-grants --key-id <id>— confirm grants are unchanged.- Spot-check: an application using the key ARN performs a test
Encrypt+Decryptcycle successfully (or confirm via metrics that noKMSKeyUnavailableExceptionorAccessDeniedExceptionspike occurred).
If ANY verification fails, emit VERDICT: ERROR with the failure
details — do not claim COMPLETED. A failed verification typically
means the key policy was inadvertently modified or the key was
simultaneously disabled by another process.
Output format (per operation)
OPERATION: <enable-rotation | verify-rotation | disable-rotation | plan-manual-rotation | diagnose-rotation>
VERDICT: READY | BLOCKED | COMPLETED
TARGET: <key-id> (alias: <alias-or-"none">, account <account>, region <region>)
PRE_CHECKS:
- [PASS] <check description>
- [FAIL] <check description> — <reason>
STEPS:
1. <CLI command with flags populated>
2. <wait / monitoring command>
3. <next step>
POST_VERIFY:
- [PASS] <verification description>
- [FAIL] <verification description> — <reason>
NOTES: <rotation period, material lifecycle, monitoring, caveats>
Worked example — enable-rotation (symmetric CMK)
OPERATION: enable-rotation
VERDICT: READY
TARGET: arn:aws:kms:us-east-1:111111111111:key/abcd1234-... (alias:
alias/prod-app-encryption-key, account 111111111111, region
us-east-1)
PRE_CHECKS:
- [PASS] Key exists, KeyState: Enabled
- [PASS] Not PendingDeletion (DeletionDate absent)
- [PASS] KeySpec: SYMMETRIC_DEFAULT, KeyUsage: ENCRYPT_DECRYPT
- [PASS] Origin: AWS_KMS (supports automatic rotation)
- [PASS] Single-region key (not a Multi-Region replica)
- [PASS] Calling role has kms:EnableKeyRotation via key policy
statement allowing arn:aws:iam::111111111111:role/SecurityAdmin
- [PASS] RotationPeriodInSeconds: 365 (default — annual)
STEPS:
1. CONFIRM: About to enable automatic backing-key rotation on KMS
key alias/prod-app-encryption-key
(arn:aws:kms:us-east-1:111111111111:key/abcd1234-...) in account
111111111111 region us-east-1. Rotation period: 365 days. The key
ID, ARN, policy, grants, and aliases are unchanged. Existing
ciphertext remains decryptable. New Encrypt operations use the
new backing material after the first rotation. Proceed? (yes/no)
2. aws kms enable-key-rotation \
--key-id arn:aws:kms:us-east-1:111111111111:key/abcd1234-...
3. (Optional) Verify immediately:
aws kms get-key-rotation-status \
--key-id arn:aws:kms:us-east-1:111111111111:key/abcd1234-...
POST_VERIFY:
- (pending execution)
NOTES:
- The first rotation will occur within 24 hours of NextRotationDate
(approximately 365 days from enablement). KMS performs the
material swap; no application action is needed.
- Old backing material is retained indefinitely (until the key is
deleted). Existing ciphertext encrypted with old material remains
decryptable — no re-encryption required.
- CloudTrail will log the EnableKeyRotation event immediately. The
actual material rotation does NOT produce a separate CloudTrail
event; verify via NextRotationDate advancing.
- For compliance evidence, capture quarterly:
aws kms get-key-rotation-status --key-id <id>
and store the output with NextRotationDate.
Worked example — plan-manual-rotation (asymmetric RSA key)
Full plan-manual-rotation worked example moved verbatim to
references/worked-examples.md (load on demand).
Worked example — diagnose-rotation (BLOCKED with remediation)
Full diagnose-rotation worked example moved verbatim to
references/worked-examples.md (load on demand).
Anti-Patterns — NEVER
-
NEVER call
enable-key-rotationon an asymmetric, HMAC, or external-material key without first confirming it is a symmetric AWS_KMS-origin key. The API returnsInvalidOperationException; the operator should plan a manual rotation instead. -
NEVER call
enable-key-rotationon a Multi-Region replica key. The API returnsInvalidOperationException. Enable rotation on the primary; the replica inherits the status. -
NEVER disable or delete an old key immediately after a manual rotation. Existing ciphertext, signatures, or MACs produced with the old key require the old key to be
Enabledfor decrypt / verify. Disable only after confirming all artifacts have been re-encrypted / re-signed or are no longer needed (typically 90+ days). -
NEVER assume
get-key-rotation-status.Enabled: truemeans a rotation has occurred. It means rotation is SCHEDULED. The actual material swap happens atNextRotationDate. For proof that a rotation ran, compareNextRotationDateadvancing over time or inspect the key's internal material versions (KMS does not expose material IDs publicly —NextRotationDateadvancing is the observable signal). -
NEVER assume AWS-managed keys (
aws/s3,aws/rds, etc.) rotate annually. They rotate approximately every 3 years on an AWS-managed schedule. You CANNOT enable, disable, or configure rotation on AWS-managed keys. For annual rotation compliance, use customer- managed keys. -
NEVER modify the key policy as part of a rotation operation. The policy is independent of the backing material. A policy change during rotation creates confusion about which change caused any subsequent access issue.
-
NEVER assume
RotationPeriodInSecondsis fixed at 365 days. It is configurable (7-365 days, default 365). Always read the current value fromget-key-rotation-statusbefore planning. -
NEVER confuse
enable-key-rotationwithrotate-key-on-demand(2024+ feature for immediate material rotation on symmetric keys).enable-key-rotationschedules recurring rotation;rotate-key-on-demandperforms an immediate material swap. Use on-demand for incident response (suspected key compromise); use scheduled for routine cryptographic agility. -
NEVER call
schedule-key-deletionto "force a rotation." Deletion is irreversible within the 7-30 day window;cancel-key-deletionrestores the key but cancels its rotation schedule. Userotate-key-on-demandfor an immediate rotation instead. -
NEVER hard-code a key ARN in application configuration if you can use an alias. Aliases make manual rotation a one-line
update-aliascutover; ARNs require updating every caller. -
NEVER assume CloudTrail logs the actual material rotation. CloudTrail logs
EnableKeyRotationandDisableKeyRotation(management events). The material swap itself is an internal KMS operation with no separate CloudTrail event. UseNextRotationDateadvancing as the observable signal. -
NEVER enable rotation on a key whose CloudHSM cluster is
DEGRADEDorDISCONNECTED. Theenable-key-rotationAPI may succeed but the actual rotation will fail until the cluster isACTIVE. Verify cluster state first. -
NEVER re-create grants after an automatic rotation. Grants are per- key-ID and survive rotation. Re-creating grants can create conflicting permissions and is unnecessary.
-
NEVER call
disable-key-rotationwithout a documented compliance exception. Disabling rotation is almost always a policy violation. If the goal is to "pause" rotation temporarily, leave rotation enabled and address the underlying concern instead. -
NEVER auto-execute a state-changing KMS CLI without the CONFIRM gate. Rotation operations are reversible, but disabling a key or scheduling deletion during a "rotation" workflow can cause immediate application outages.
Pre-flight safety checks (run before any remediation CLI)
Pre-flight safety checks moved verbatim to
references/diagnostic-commands.md (load on demand).
Recent AWS features (2024-2026)
Recent-feature details moved verbatim to
references/advanced-patterns.md (load on demand).
References (load on demand)
references/worked-examples.md— secondary worked examples: plan-manual-rotation (asymmetric RSA), diagnose-rotation (BLOCKED replica key).references/advanced-patterns.md— Step-0 expert KMS rotation behaviors, recent AWS features 2024-2026.references/error-handling.md— rotation failure-mode table (symptom / root cause / fix).references/diagnostic-commands.md— sweep pagination, live-account pre-flight command listing, pre-flight safety checks.references/key-type-and-rotation-matrix.md— key type rotation support matrix and procedures.references/manual-rotation-procedures.md— manual rotation procedures (caller identification, cutover).
Domain
AWS CloudOps / KMS Key Rotation, Cryptographic Agility & Compliance.
AWS documentation
- AWS KMS Developer Guide — https://docs.aws.amazon.com/kms/latest/developerguide/
- Rotating keys — https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html
- Automatic key rotation — https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html#rotate-keys-how-it-works
- Manual key rotation — https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html#rotating-keys-manually
- Multi-Region keys — https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-manage.html
- Custom key stores — https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html
- KMS API Reference — https://docs.aws.amazon.com/kms/latest/APIReference/
- KMS CLI Reference — https://docs.aws.amazon.com/cli/latest/reference/kms/
- KMS key quotas — https://docs.aws.amazon.com/kms/latest/developerguide/resource-limits.html
04 同仓库更多 Skills
xray-tracing-deployer
Deploys AWS X-Ray distributed tracing with production-grade configuration: X-Ray daemon deployment (EC2 systemd, ECS sidecar, EKS DaemonSet, Lambda built-in), SDK instrumentation (Java, Python, Node.js, Go, .NET) with annotations and metadata, sampling rules (default reservoir + rate vs custom rules with URL / method / service-name predicates), service map generation, trace query and retrieval, groups and insights, CloudWatch ServiceLens integration, IAM permissions (PutTraceSegments, GetSamplingRules), and latest features (Lambda Powertools tracing, OpenTelemetry / ADOT Collector support, W3C trace context). Emits a READY_TO_DEPLOY checklist with every configuration item verified. Use when enabling X-Ray on a new application, adding tracing to ECS / EKS / Lambda, validating a sampling configuration, or generating daemon deployment CLI and IaC templates. Triggers: X-Ray, distributed tracing, X-Ray daemon, sampling rules, service map, X-Ray SDK, OpenTelemetry, ADOT, Lambda Powertools, CloudWatch ServiceLens.
wellarchitected-workload-auditor
Audits AWS Well-Architected Tool workloads for review staleness, per-pillar high-risk issue counts, milestone tracking gaps, and remediation plan completeness. Emits a deterministic verdict (STALE_REVIEW | HIGH_RISK | CONFIG_GAP | OK) per workload with per-pillar risk breakdown, milestone trend analysis, and specific remediation. Use when reviewing Well-Architected workloads, checking WA review freshness, auditing high-risk issues per pillar, validating milestone coverage, or tracking remediation plans.
wellarchitected-review-operator
Operates AWS Well-Architected Tool reviews end-to-end — creates workloads, runs pillar reviews (operational excellence, security, reliability, performance, cost optimization, sustainability, Prosperity), answers questions with risk-tier rationale, generates reports and improvement plans, creates milestones, and integrates with Trusted Advisor and Well-Architected Labs. Runs deterministic pre-checks (workload existence, lens availability, pillar coverage), emits the exact update-answer / get-consolidated-report CLI behind a CONFIRM gate, and verifies risk-tier transitions. Emits READY | BLOCKED | COMPLETED. Use when creating a workload, answering pillar questions, generating an improvement plan, creating a milestone, or integrating with Trusted Advisor. Triggers: well-architected tool, well architected review, workload review, pillar, operational excellence, security, reliability, performance, cost optimization, sustainability, prosperity, improvement plan, milestone, trusted advisor.
wafv2-web-acl-deployer
Provisions AWS WAFv2 Web ACLs with correct production defaults: scope selection (CLOUDFRONT vs REGIONAL), managed rule groups (AWSManagedRulesCommonRuleSet, SQLiRuleSet, LinuxRuleSet, WindowsRuleSet, IPReputationList, BotControlRuleSet, AmazonIpReputationList, ATP), custom rules (byte match, IP set, regex pattern, geo match, size constraint, rate-based), rule priority ordering, logging destinations (Kinesis Firehose, CloudWatch Logs, S3), resource association (ALB, API Gateway, CloudFront), rate-based rules with aggregate keys (IP, forwarded IP), Challenge and CAPTCHA actions, and account takeover prevention. Emits a READY_TO_DEPLOY checklist. Use when creating a Web ACL, attaching managed rules, configuring rate limiting, enabling WAF logging, associating a Web ACL with an ALB/API Gateway/CloudFront, or configuring CAPTCHA/Challenge actions. Triggers: create WAF Web ACL, WAFv2, managed rule groups, WAF rate limiting, WAF logging, WAF CAPTCHA, WAF Challenge action, bot control, ATP managed rules.
wafv2-web-acl-auditor
Audits AWS WAFv2 Web ACL configurations to determine whether the ACL provides effective protection: default-action posture (Allow vs Block), managed-rule-group coverage gaps, rule effectiveness (BLOCK vs COUNT, shadow/bypass rules, stale exclusions), rate-based rule correctness, logging and visibility configuration, and text-transformation bypass vectors. Emits a deterministic verdict per Web ACL. Use when reviewing a WAFv2 Web ACL for security posture, checking managed-rule coverage, validating rate-limit configuration, auditing WAF logging, or hardening a WAF before production deployment. Triggers: WAF, WAFv2, Web ACL, managed rule group, AWSManagedRules, rate-based rule, CAPTCHA, Challenge, OverrideAction, Count mode, forwarded IP, Bot Control, ATP, text transformation, WAF logging, WAF visibility, OWASP, SQLi, XSS, RFI.
waf-rule-deployer
Provisions AWS WAFv2 rule sets with production defaults: Web ACL creation (CloudFront scope in us-east-1 vs Regional scope), rule groups (managed vs custom) with capacity planning in WCU (Web ACL Capacity Units, 1500 default per ACL), managed rule groups (AWSManagedRulesCommonRuleSet, AWSManagedRulesSQLiRuleSet, AWSManagedRulesAmazonIpReputationList, AWSManagedRulesLinuxRuleSet, AWSManagedRulesWindowsRuleSet, AWSManagedRulesUnixRuleSet), custom rules (byte-match, regex pattern set, geo-match, rate-based), IP set and regex pattern set resources, rule priority ordering (lowest number evaluated first), action types (allow, block, count, CAPTCHA, Challenge), bot control managed rule group, account takeover. Triggers: create WAF rule, WAF managed rule group, WAF custom rule, WAF byte match, WAF geo match, WAF rate based rule, WAF IP set, WAF regex pattern set, WAF WCU budget, WAF CloudFront ACL, WAF logging Kinesis Firehose, WAF bot control, WAF ATP, WAF label matching, WAF Challenge action, WAF CAPTCHA.