ssm-patch-operator
Operates SSM Patch Manager workflows safely — patch baseline authoring (AWS-managed and custom), patch group tag targeting, AWS-RunPatchBaseline Scan and Install operations, maintenance window task scheduling, and patch compliance reporting. Runs deterministic pre-checks (instance managed-status, SSM Agent health, baseline association, free disk space, reboot tolerance, maintenance-window target membership, rate-control budget), executes the patching operation behind a CONFIRM gate, and emits a verdict (READY | BLOCKED | COMPLETED) per operation with the exact send-command sequence, expected side-effects (reboot, compliance delta), and post-verification. Use when running a security patch sweep, scheduling a maintenance-window patch task, diagnosing a NON_COMPLIANT instance, planning a fleet-wide Install with rate-control, or building a custom baseline with approval rules.
- License 许可
- Apache-2.0
- 最近更新
- 2026-09-24
- Stars
- ★ 4
- Forks
- 0
01 前言 Front Matter
- name
- ssm-patch-operator
- license
- Apache-2.0
- metadata
- { "tags": "ssm, systems-manager, patch-manager, management, patching, compliance, maintenance-window, operate", "phase": "4", "author": "Jacky Chan — AWS Community Builder", "domain": "aws-cloudops", "family": "Management", "version": "0.1.0", "keywords": "Systems Manager, SSM, Patch Manager, patch baseline, AWS-RunPatchBaseline, AWS-ApplyPatchBaseline, patch group, Scan, Install, compliance, NON_COMPLIANT, maintenance window, rate-control, ApprovalRules, ApproveAfterDays, AmazonSSMManagedInstanceCore, AmazonLinux2, Ubuntu, Windows, macOS, kernel panic, reboot, NoReboot, SSM Quick Setup", "task_type": "operate", "complexity": "medium", "entry_point": "false", "skill_class": "capability", "when_to_use": "Running a security patch sweep against an EC2 or hybrid fleet, creating or modifying a custom patch baseline with approval rules, scheduling a maintenance-window task that runs AWS-RunPatchBaseline with Operation=Install, diagnosing a NON_COMPLIANT instance, planning a fleet-wide Install with rate-control and max-errors, switching an association from Scan to Install, or pre-checking a host before the next patch window.", "dependencies": "aws-orchestrator", "requires_llm": "true", "verdict_shape": "READY | BLOCKED | COMPLETED", "lifecycle_status": "active", "invocation_schema": "Input: either (a) a patch operation request (operation=scan|install| create-baseline|update-baseline|create-mw|register-task) paired with instance(s), patch baseline, and optional maintenance-window context, OR (b) an instance-id / baseline-id / maintenance-window-id for live- account execution. Output: deterministic OPERATION/VERDICT/PRE_CHECKS/ STEPS/POST_VERIFY block per operation, where VERDICT is one of READY, BLOCKED, COMPLETED.", "supports_pipeline": "true", "activation_triggers": "patch this instance, run AWS-RunPatchBaseline, scan for missing patches, install missing patches, create patch baseline, custom patch baseline rules, patch group tag, schedule patching maintenance window, diagnose NON_COMPLIANT patch, Operation=Install, Operation=Scan, rate-control patching, approve after days, NoReboot patch install" }
- description
- Operates SSM Patch Manager workflows safely — patch baseline authoring (AWS-managed and custom), patch group tag targeting, AWS-RunPatchBaseline Scan and Install operations, maintenance window task scheduling, and patch compliance reporting. Runs deterministic pre-checks (instance managed-status, SSM Agent health, baseline association, free disk space, reboot tolerance, maintenance-window target membership, rate-control budget), executes the patching operation behind a CONFIRM gate, and emits a verdict (READY | BLOCKED | COMPLETED) per operation with the exact send-command sequence, expected side-effects (reboot, compliance delta), and post-verification. Use when running a security patch sweep, scheduling a maintenance-window patch task, diagnosing a NON_COMPLIANT instance, planning a fleet-wide Install with rate-control, or building a custom baseline with approval rules.
- 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 ssm describe-instance-information, describe-patch-baseline, describe-patch-baselines, describe-patch-states, list-compliance-items, send-command (AWS-RunPatchBaseline), get-command-invocation, create-association, update-association, create-maintenance-window, register-task-with-maintenance-window, and aws ec2 describe-instances...
02 资源文件 19
- 参考文档eval/test-cases.yaml8.0 KB
- 参考文档evals/baselines/install-blocked-disk-full.md478 B
- 参考文档evals/baselines/install-blocked-no-patch-group.md513 B
- 参考文档evals/baselines/install-single-host-ready.md513 B
- 参考文档evals/baselines/mw-register-task-ready.md696 B
- 参考文档evals/baselines/scan-association-missing-patches.md543 B
- 参考文档evals/eval_config.yaml1.8 KB
- 参考文档evals/evals.json4.6 KB
- 参考文档evals/prompts/install-blocked-disk-full.md1.5 KB
- 参考文档evals/prompts/install-blocked-no-patch-group.md1.4 KB
- 参考文档evals/prompts/install-single-host-ready.md1.6 KB
- 参考文档evals/prompts/mw-register-task-ready.md1.1 KB
- 参考文档evals/prompts/scan-association-missing-patches.md1.4 KB
- 参考文档examples/README.md10.9 KB
- 参考文档references/advanced-patterns.md8.8 KB
- 参考文档references/diagnostic-commands.md2.1 KB
- 参考文档references/patch-baseline-design.md11.0 KB
- 参考文档references/worked-examples.md3.6 KB
- 参考文档skill.usf.yaml4.4 KB
03 SKILL.md 正文
SSM Patch Operator
What this skill does
Executes SSM Patch Manager operations on EC2 and hybrid (mi-*) fleets
correctly and safely. Runs deterministic pre-checks (instance managed
status, SSM Agent health, baseline association, free disk space, reboot
tolerance, maintenance-window target membership), plans the exact
aws ssm send-command / association / maintenance-window sequence, and
verifies the result via compliance items and command invocations. Every
state-changing operation runs behind a CONFIRM gate — Operation=Install
can reboot hosts and restart services, never auto-trigger.
Quick navigation
| Section | What it covers | When to read it |
|---|---|---|
| § Quick reference | Verdict thresholds + pre-check priority order + OS-by-OS baseline matrix | Before any operation |
| § Mindset | Why pre-checks matter, the Scan-vs-Install trap, the reboot surprise | Understanding the safety model |
| § Pre-flight | Instance metadata gate — managed status, agent, baseline, free disk | Before executing any CLI |
| § Process | Per-operation planning: scan, install, baseline author, maintenance window | When choosing which operation to run |
| § Output format | Structured VERDICT block with COMMANDS, COMPLIANCE_DELTA, REBOOT | Formatting the response |
| § Anti-Patterns | NEVER list — common mistakes that reboot fleets or miss compliance drift | Review before any Install |
| § Pre-flight safety | CONFIRM gate, rate-control, snapshot pre-state, rollback | Defense-in-depth |
Quick reference — verdict thresholds
| Verdict | Trigger condition | Action |
|---|---|---|
BLOCKED |
One or more pre-checks failed (instance UNMANAGED, agent offline, no baseline associated, free disk < 2 GB on root, instance-state not running, maintenance-window target empty, baseline auto-approves more than expected) |
List failures, do NOT execute |
READY |
All pre-checks passed; awaiting CONFIRM gate | Emit exact CLI sequence, wait for operator yes |
COMPLETED |
Operation finished and post-verification passed (command Success, compliance delta verified, host back online if rebooted) |
Emit compliance summary, side-effects, follow-ups |
Priority order for pre-checks (apply in this sequence, all must pass for READY):
- Managed status — instance must appear in
describe-instance-informationwithPingStatus: ActiveandLastPingDateTime< 30 min ago. Downstream pre-checks are noise on an unreachable host. - IAM role — EC2 instance profile (or hybrid activation role) must carry
AmazonSSMManagedInstanceCore(or verified-equivalent) so the agent can runAWS-RunPatchBaseline. - Disk space —
AWS-RunPatchBaselinewithOperation=Installneeds roughly 2 GB free on the root volume (and on Windows%SystemDrive%) to stage packages and backups. Install on a full disk fails mid-way and leaves the package manager in a broken state. - Patch baseline association — instance must reach a baseline either via
the regional default, a
Patch Grouptag, or an explicitAWS-ApplyPatchBaseline/AWS-RunPatchBaselineassociation. No baseline → Scan returns zero findings (silent false-clean), Install no-ops. - Baseline scope — surface what the baseline auto-approves. A custom
baseline with
ApproveAfterDays: 0and broad classifications will install far more than the operator expects. Always dumpdescribe-patch-baselinebefore the first Install. - Reboot tolerance & maintenance window — Install may reboot the host; if the instance is in an ASG without ELB grace, in a Multi-AZ RDS primary pair, or outside the maintenance window, BLOCK until the operator confirms.
Moved to references/advanced-patterns.md. Scan ~30 s-5 min/host, Install minutes to ~1 h/host (Windows cumulative updates dominate), baseline export/import metadata-only, in-region command output free.
OS-by-OS baseline matrix
Moved to references/advanced-patterns.md. Default baseline, default document, and reboot-on-Install semantics for AL2/AL2023, Ubuntu, RHEL, SLES, Windows, macOS; default only applies when no custom default and no Patch Group tag matches.
Mindset
One-line takeaway: Operation=Scan writes a compliance record without
touching packages; Operation=Install mutates the host and may reboot it.
Driven by three Patch Manager realities:
- Scan is non-destructive, Install is state-changing. A bare
send-command AWS-RunPatchBaselinedefaults toOperation=Scan. Many operators assume the association they "enabled" is patching; in reality the default is to report compliance, not remediate it. A fleet can sitNON_COMPLIANTfor years while every association showsSuccess— the scan knew about the gap and nothing installed patches. - Baseline scope is the install contract.
ApprovalRulesdecide what the Install actually applies.ApproveAfterDays: 0approves every patch on release (aggressive);ApproveAfterDays: 7waits a week. Classification + Severity filters narrow which package classes are in scope. An Install without first dumping the baseline'sApprovalRules.PatchRules[]is "sign without reading". - Patch Group is a tag, not an association. Instances link to a custom
baseline via the case-sensitive tag key
Patch Group(space, capital G). Without the tag, the instance falls back to the regional default baseline — silently. A "patched" fleet with noPatch Grouptags may be patching against the wrong baseline entirely.
Pre-flight: instance metadata gate
Run before classification. Misclassifying these produces wrong plans.
Moved to references/diagnostic-commands.md. Pagination limits (50/page describe-instance-information, 100/page describe-patch-states) and the 9 live-account pre-flight probes: managed status, EC2 state, custom/AWS baselines, effective baseline, patch states, compliance rows, associations, MW executions, free-disk check.
Malformed input: if the input JSON is invalid or missing required fields,
emit VERDICT: ERROR with REASON: Instance/operation configuration is not valid JSON or is missing required fields — cannot plan. and
REMEDIATION: Re-fetch with aws ssm describe-instance-information --instance-information-filter-list Key=InstanceIds,ValueSet=<id> --output json and aws ssm get-patch-baseline-for-instance --instance-id <id> --output json, then re-plan.
| Instance attribute | Effect on operation |
|---|---|
PingStatus: Active + LastPingDateTime < 30 min |
Pre-check passes. |
PingStatus: ConnectionLost / Inactive |
BLOCKED — host unreachable. Classify UNMANAGED and stop. |
ResourceType: EC2Instance, no IamInstanceProfile |
BLOCKED — no SSM role. |
ResourceType: ManagedInstance (mi-*), role lacks AmazonSSMManagedInstanceCore |
BLOCKED — hybrid activation role gap. |
PlatformType: Linux / Windows / macOS |
Selects the OS-family default baseline and the patch-filter taxonomy. |
IsLatestVersion: false |
WARN — old agent; may misreport compliance. Surface but do not BLOCK. |
No Patch Group tag AND no explicit association |
Falls back to the regional default. Surface as a CONFIG_GAP-style note, not a BLOCKED unless the operator's intent is to use a custom baseline. |
Instance State: stopped, stopping, shutting-down |
BLOCKED — patch execution requires running. |
Free disk < 2 GB on root (Linux) / %SystemDrive% (Windows) |
BLOCKED for Install; Scan can still proceed. |
AWS-RunPatchBaseline association with Operation=Scan only |
Install will not run on schedule; surface for explicit Install command or association update. |
Process — operation planning (apply in order)
Step 0: Expert knowledge — non-obvious Patch Manager behaviors
Moved to references/advanced-patterns.md. Run-vs-Apply documents, Scan-only default, NoReboot deferral, Patch Group case sensitivity, dead custom baselines, AND/OR rule logic, ApproveAfterDays counted from patch release, effective-baseline reporting, fleet rate-control, MW target membership timing, OS-native reboot, agent not auto-updated, eventual consistency after Scan, manual cross-account/region replication, Ubuntu Snapshot Ids holds.
Step 1: Pre-check gate — BLOCKED if any check fails
Run ALL of the following pre-checks. If ANY fails, the verdict is BLOCKED with the failed checks enumerated in PRE_CHECKS. Do NOT execute the operation.
For ALL operations:
- Instance is
running(ec2 describe-instances) andPingStatus: ActivewithLastPingDateTime< 30 min (ssm describe-instance-information). - IAM role includes
AmazonSSMManagedInstanceCore(or verified equivalent that grantsssm:SendCommand,ssm:GetCommandInvocation,ssm:StartSession, and the patch-related SSM actions). - The caller (operator role) holds
ssm:SendCommand,ssm:GetCommandInvocation,ssm:DescribePatch*,ssm:ListComplianceItems, and (for Install)ssm:StartAssociationsOnce. - No concurrent command on the instance (
ssm list-commands --filters Key=InstanceId,Values=<id> Key=Status,Values=Pending,InProgress). Default per-instance concurrency is 1; a second command returnsTargetNotConnectedorInvalidInstanceId.
For Scan (send-command AWS-RunPatchBaseline Operation=Scan):
5. The instance's effective baseline is non-empty (verify via
get-patch-baseline-for-instance). A baseline with zero rules produces
a Scan that returns zero findings — silent false-clean.
6. SSM Agent version is recent enough for the OS (Amazon Linux 2023 needs
agent v3.x+).
For Install (send-command AWS-RunPatchBaseline Operation=Install):
5. ALL of the Scan pre-checks.
6. Free disk on root (Linux) / %SystemDrive% (Windows) >= 2 GB. Verify
via a quick AWS-RunShellScript "df -m /" (Linux) or
Get-PSDrive C (Windows) before the Install command.
7. Snapshot pre-state for rollback: tag the AMI or capture
describe-instances JSON. Patch Manager does NOT auto-snapshot.
8. Reboot tolerance confirmed: instance is NOT in an active ALB target
without deregistration, is NOT a Multi-AZ RDS primary's only EC2
dependency, and IS inside the maintenance window (if applicable).
9. Baseline ApprovalRules reviewed and matches operator intent. A
custom baseline with ApproveAfterDays: 0 and broad classifications
will install far more than expected. Dump
aws ssm describe-patch-baseline --baseline-id <id> and surface the
approval scope in NOTES.
10. (Optional but recommended) Pre-Install snapshot:
aws ec2 create-snapshot --volume-id <root-volume-id> --description "pre-patch $(date -u +%FT%TZ)".
For create/update patch baseline:
5. The baseline payload references valid OperatingSystem, Product
values (AmazonLinux2, AmazonLinux2023, Ubuntu2004, Ubuntu2204,
Ubuntu2404, RedhatEnterpriseLinux7/8/9, Suse15,
WindowsServer2019, WindowsServer2022, macOS12.5 etc.).
6. ApprovalRules.PatchRules[] PatchFilterGroup values match the
supported classification/severity taxonomy for that OS.
7. The baseline is being set as default OR has a Patch Group tag value
mapped to its name. Otherwise the baseline is dead configuration.
8. (For update) --baseline-version is being incremented intentionally;
the previous version is preserved in baseline history but not auto-
rolled back.
For maintenance window create / register-task:
5. --schedule cron expression is valid and points to the intended time
zone (--schedule-timezone, default UTC).
6. --duration 2 (hours) and --cutoff 1 (hours) leave a safe buffer.
7. --targets resolves to a non-empty set at the planned execution time
(verify via aws ssm describe-maintenance-window-targets --window-id <id> after registration).
8. The task's --task-parameters reference Operation=Install (or
Scan), the right Snapshot Ids, and NoReboot as intended.
9. The maintenance window's IAM service role (--service-role-arn) trusts
ssm.amazonaws.com and has AmazonSSMAutomationRole or equivalent.
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 baseline + instance configuration.
- The expected duration (Scan: 30 s – 5 min; Install: minutes to ~1 hour; maintenance window: until scheduled end).
- The expected side-effects (compliance delta for Scan; potential reboot +
InstalledPendingcount for Install). - The CONFIRM gate prompt.
Step 3: Execute behind CONFIRM gate
- MANDATORY CONFIRMATION GATE. Before any state-changing CLI
(Install, association update to Install, baseline create/update, MW
create/register-task), emit:
CONFIRM: About to <operation> on <instance-id or fleet-tag> in account <account> region <region>. This will <consequence, e.g. install patches and may reboot the host(s)>. Proceed? (yes/no). - Capture pre-state for rollback: tag the AMI or run
aws ec2 create-create-snapshot --volume-id <root> --description "pre-patch $(date -u +%FT%TZ)"for Install. - Execute the CLI. Capture the
CommandId. - For long-running commands, poll
aws ssm get-command-invocation --command-id <id> --instance-id <id>untilStatusisSuccess/Failed/TimedOut/Cancelled. - For maintenance window task, capture the
WindowTaskIdand polldescribe-maintenance-window-executions.
Step 4: Post-verification — COMPLETED
After the operation finishes, run post-verification. ALL checks must pass
for COMPLETED.
get-command-invocationreturnsStatus: Success(or the maintenance window executionStatus: COMPLETED).- For Scan: re-fetch
describe-patch-states --instance-ids <id>and verify theOperationEndTimeis fresh. Surface the missing-count delta. - For Install: re-fetch
list-compliance-itemsand verifyComplianceStatus: COMPLIANT(or surface remainingNON_COMPLIANTitems by severity). - Verify the host came back online after any reboot:
describe-instance-informationPingStatus: ActiveANDec2 describe-instancesState: running. - For Windows
NoReboot=trueInstalls: surface theInstalledPendingcount and the explicit next-reboot requirement. - Surface side-effects: changed services, applied patch list (from the
command output's
InstalledPatchesfield), reboot happened Y/N. - Plan follow-up: re-scan in 24 h to catch reverted patches; remove pre-patch snapshots after the verification window (e.g., 7 days).
If ANY verification fails, emit VERDICT: ERROR with the failure details
— do not claim COMPLETED.
Output format (per operation)
OPERATION: <scan | install | create-baseline | update-baseline | create-mw | register-mw-task>
VERDICT: READY | BLOCKED | COMPLETED
TARGET: <instance-id | tag:Patch Group,Values=<group> | baseline-id | window-id>
PRE_CHECKS:
- [PASS] <check description>
- [FAIL] <check description> — <reason>
STEPS:
1. <CLI command with flags populated>
2. <wait / poll command>
3. <next step>
POST_VERIFY:
- [PASS] <verification description>
- [FAIL] <verification description> — <reason>
COMPLIANCE_DELTA: <before: missing X / after: missing Y>
REBOOT: <yes | no | deferred>
NOTES: <rate-control, snapshot, caveats, follow-ups>
Worked example — Install on a single Linux host
OPERATION: install
VERDICT: READY
TARGET: i-0abc123def456789a
PRE_CHECKS:
- [PASS] i-0abc123def456789a PingStatus Active, LastPingDateTime 2 min ago
- [PASS] IAM role AmazonSSMManagedInstanceCore-Role includes
AmazonSSMManagedInstanceCore
- [PASS] EC2 State running
- [PASS] Free disk on / is 18 GB (>= 2 GB)
- [PASS] Effective baseline pb-0aaa1234 (custom prod-linux-critical)
via Patch Group tag "prod-linux-critical"
- [PASS] Baseline ApprovalRules: Classification=Security,
Severity=Critical+Important, ApproveAfterDays=3 — 14 patches qualify
- [PASS] No concurrent command in flight
- [PASS] Instance is in maintenance window mw-0aaa (cutoff in 95 min)
STEPS:
1. CONFIRM: About to send-command AWS-RunPatchBaseline Operation=Install
on i-0abc123def456789a in account 111111111111 region us-east-1.
This will install up to 14 Security patches (Critical+Important) and
MAY REBOOT the host if a kernel update is in scope. Proceed? (yes/no)
2. aws ec2 create-snapshot --volume-id vol-0root123 \
--description "pre-patch $(date -u +%FT%TZ)"
3. aws ssm send-command \
--instance-ids i-0abc123def456789a \
--document-name "AWS-RunPatchBaseline" \
--parameters '{"Operation":["Install"],"SnapshotIds":[""],"RebootOption":["NoReboot"]}' \
--comment "Install Security/Critical+Important on prod host" \
--output-s3-bucket-name audit-ssm-output \
--output-s3-key-prefix patch-install/$(date -u +%Y/%m/%d)
4. aws ssm get-command-invocation \
--command-id <CommandId from step 3> \
--instance-id i-0abc123def456789a
(poll until Status is Success / Failed / TimedOut)
POST_VERIFY:
- (pending execution)
COMPLIANCE_DELTA: (before: 14 missing / after: pending)
REBOOT: deferred (NoReboot=true; kernel patch will activate on next reboot,
host is running stale kernel until then)
NOTES:
- The host will report COMPLIANT only after the next reboot activates the
kernel patch. Plan a reboot via maintenance window or ASG instance
refresh within the next 7 days.
- Re-scan in 24 h to catch any patches reverted by package-manager hooks.
- Pre-patch snapshot snap-0prepatch123 retained for 7 days; delete after
the verification window.
- Rate-control: single-instance target — no --max-concurrency needed.
For fleet Installs, add `--max-errors 0 --max-concurrency "10%"`.
Worked example — Scan-only association missing patches
Moved to references/worked-examples.md. Full BLOCKED block: no Patch Group tag so the effective baseline is the AWS default; remediation via create-tags Key="Patch Group" or set-default-patch-baseline.
Worked example — Maintenance window register-task
Moved to references/worked-examples.md. Full READY block: register-task-with-maintenance-window with tag targets, NoReboot, max-concurrency 10% / max-errors 0, weekly target-membership verification.
Anti-Patterns — NEVER do these things
-
NEVER run
Operation=Installwithout first dumping the effective baseline'sApprovalRules.PatchRules[]viadescribe-patch-baseline. A baseline withApproveAfterDays: 0and broad classifications will install far more than the operator expects — including major-version package upgrades that break applications. -
NEVER assume
NoReboot=truemeans "no reboot needed." It suppresses the Patch Manager-initiated reboot, but kernel patches on Linux and cumulative updates on Windows still require a reboot to activate. The host runs stale code until the next reboot; compliance will showInstalledPendinguntil then. -
NEVER issue a fleet-wide
Operation=Installviasend-command --instance-ids i-a,i-b,...,i-zwithout--max-errors 0 --max-concurrency "10%". Without rate-control, every target reboots in parallel — a fleet-wide outage from a single bad patch. -
NEVER trust an association
Status: Successas proof of patch compliance. ASuccessassociation withOperation=Scanreports green while leaving the hostNON_COMPLIANT— the scan ran, the patches are still missing. Always cross-checklist-compliance-itemsComplianceStatus. -
NEVER tag instances with
patch group,PatchGroup, orpatch-group. The recognized tag key isPatch Group(space, capital G). Wrong-case tags silently fall back to the default baseline. -
NEVER create a custom patch baseline without either setting it as the regional default OR mapping a
Patch Grouptag to its name. A baseline that is neither is dead configuration — the operator thinks they have custom rules in effect, but instances use the default. -
NEVER delete an association as the first remediation step. Modify-then- test (
update-associationto changeOperation=ScantoInstall) preserves targeting and schedule; deleting loses the configuration context. -
NEVER rely on
describe-patch-baselines --filters Key=OWNER,Values=Selfto find the effective baseline for an instance. Useget-patch-baseline-for-instance— it resolves the regional default, thePatch Grouptag, and any explicit association in priority order. -
NEVER evaluate patch compliance on an instance with
PingStatus: ConnectionLostorInactive. Downstream data is stale; reporting it produces noise. Restore coverage first, re-scan, then evaluate. -
NEVER assume
AmazonEC2RoleforSSM(legacy) is equivalent toAmazonSSMManagedInstanceCore(modern). The legacy policy lacks several patch and inventory permissions and breaks Session Manager. Flag instances still on the legacy policy. -
NEVER run an Install in a private subnet without confirming the SSM VPC endpoints (
ssm,ssmmessages,ec2messages) are present. Without them, the agent cannot return command output and the Install appears to hang. -
NEVER auto-execute
Operation=Installduring business hours without a maintenance window. EvenNoReboot=trueInstalls restart services (httpd, nginx, docker) that can drop in-flight requests. -
NEVER use
--targets Key=InstanceIds,Values=*or a tag-based wildcard for an Install without explicit operator confirmation. Always scope to a knownPatch Groupvalue or an explicit instance-id list. -
NEVER skip the free-disk check before Install. A full root volume causes the package manager to fail mid-Install, leaving the host in a broken state that requires manual rescue.
-
NEVER assume Scan results are immediately visible.
describe-patch-statesandlist-compliance-itemsare eventually consistent after a Scan (~30 s – 2 min). Re-poll before declaring the result. -
NEVER assume
AWS-RunPatchBaselineis the same asAWS-ApplyPatchBaseline.Applyis the legacy Windows-only document;Runis the modern cross- OS document. New associations should always useRun. -
NEVER claim "fully patched" based on a single Scan. Re-scan in 24 h to catch reverted patches, package-manager hook rollbacks, and Windows cumulative-update supersession.
Pre-flight safety checks (run before any remediation CLI)
-
MANDATORY CONFIRMATION GATE. Before any state-changing operation (
send-command Operation=Install,update-associationtoInstall,create/update-patch-baseline,set-default-patch-baseline,create/register-task-with-maintenance-window), emit:CONFIRM: About to <operation> on <target> in account <account> region <region>. This will <consequence>. Proceed? (yes/no). Do NOT execute until the operator confirms. -
Capture pre-state for rollback. Before any Install:
aws ec2 create-snapshot --volume-id <root> --description "pre-patch $(date -u +%FT%TZ)". Patch Manager does NOT auto-snapshot. An AMI is even safer for fleet operations. -
Always pass explicit
--instance-ids <id>or a scoped--targets Key=tag:"Patch Group",Values=<group>for Installs. Wildcards andValues=*are fleet-outage vectors. -
Rate-control is MANDATORY for fleet Installs. Set
--max-errors 0(halt on first error) and--max-concurrency "10%"(or"1"for high-risk patches). Halting on first error contains a bad patch to the first batch. -
Verify target membership before the maintenance window opens.
describe-maintenance-window-targets --window-id <id>— empty targets means the window will no-op. -
Verify the baseline scope before the first Install on a new custom baseline. Run a Scan on a single instance; review the
InstalledPendingCountandMissingCountdeltas before fleet-wide Install. -
Prefer reversible changes. For baseline updates, increment the baseline version (
--baseline-version) so the previous version is preserved in baseline history. For association updates, snapshotdescribe-association --association-id <id>first. -
Test patches on a single instance before fleet rollout. Use a "canary"
Patch Group(e.g.,prod-linux-canary) targeting one or two hosts; observe for 24-48 h; then promote to the production group.
Recent AWS features (2024-2026)
Moved to references/advanced-patterns.md. Quick Setup org-wide patching, Patch Manager for macOS, AL2023 baseline, Ubuntu 24.04 snap holds, SSM document versioning, PatchBaseline CloudFormation resources, Config PatchCompliance reporting.
References (load on demand)
- advanced-patterns — OS-by-OS baseline matrix, cost/time baselines, Step 0 expert knowledge (non-obvious Patch Manager behaviors), Recent AWS features (2024-2026)
- diagnostic-commands — pagination limits and the nine live-account pre-flight probes moved from SKILL.md
- patch-baseline-design — baseline archetypes, approval-rule shapes, OS product taxonomy, Patch Group targeting, maintenance-window task contract
- worked-examples — BLOCKED scan-only-association and READY maintenance-window register-task examples moved from SKILL.md
Domain
AWS CloudOps / Systems Manager Patch Manager Operations & Compliance.
AWS documentation
- AWS Systems Manager User Guide — https://docs.aws.amazon.com/systems-manager/latest/userguide/what-is-systems-manager.html
- AWS Systems Manager Patch Manager — https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-patch.html
- Working with patch baselines — https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-patch-baselines.html
- About the AWS-RunPatchBaseline document — https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-patch-runbaseline.html
- Working with maintenance windows — https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-maintenance.html
- Patch compliance — https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-compliance.html
- AWS Systems Manager Quick Setup — https://docs.aws.amazon.com/systems-manager/latest/userguide/quick-setup.html
- AWS CLI Command Reference: ssm — https://docs.aws.amazon.com/cli/latest/reference/ssm/
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.