aws-systems-manager

name	aws-systems-manager
description	Use when working with Aws Systems Manager — aWS Systems Manager parameter store management, session management, patch compliance tracking, and Run Command analysis. Covers parameter inventory, managed instance status, automation execution, maintenance windows, and inventory collection.
connection_type	aws
preload	false

AWS Systems Manager Skill

Analyze AWS Systems Manager resources with parallel execution and anti-hallucination guardrails.

Relationship to other AWS skills:

• aws-systems-manager/ → SSM-specific analysis (parameters, sessions, patches, commands)
• aws/ → "How to execute" (parallel patterns, throttling, output format)

CRITICAL: Parallel Execution Requirement

ALL independent operations MUST run in parallel using background jobs (&) and wait.

#!/bin/bash
export AWS_PAGER=""

for instance in $instances; do
  get_patch_compliance "$instance" &
done
wait

Helper Functions

#!/bin/bash
export AWS_PAGER=""

# List parameters (paginated)
list_parameters() {
  aws ssm describe-parameters --max-results 50 \
    --output text \
    --query 'Parameters[].[Name,Type,LastModifiedDate,Version]'
}

# Get parameter value
get_parameter() {
  local name=$1
  aws ssm get-parameter --name "$name" --with-decryption \
    --output text \
    --query 'Parameter.[Name,Type,Value,Version,LastModifiedDate]'
}

# List parameters by path
get_parameters_by_path() {
  local path=$1
  aws ssm get-parameters-by-path --path "$path" --recursive \
    --output text \
    --query 'Parameters[].[Name,Type,Version,LastModifiedDate]'
}

# List managed instances
list_managed_instances() {
  aws ssm describe-instance-information \
    --output text \
    --query 'InstanceInformationList[].[InstanceId,PingStatus,PlatformType,PlatformName,AgentVersion,IsLatestVersion]'
}

# Get patch compliance for an instance
get_patch_compliance() {
  local instance_id=$1
  aws ssm describe-instance-patch-states --instance-ids "$instance_id" \
    --output text \
    --query 'InstancePatchStates[].[InstanceId,PatchGroup,InstalledCount,MissingCount,FailedCount,InstalledRejectedCount,OperationEndTime]'
}

# List recent command invocations
list_commands() {
  aws ssm list-commands --max-results 20 \
    --output text \
    --query 'Commands[].[CommandId,DocumentName,Status,InstanceIds[0],RequestedDateTime]'
}

Common Operations

1. Parameter Store Inventory

#!/bin/bash
export AWS_PAGER=""
aws ssm describe-parameters --max-results 50 \
  --output text \
  --query 'Parameters[].[Name,Type,LastModifiedDate,Version,Tier]' | sort -k1

2. Managed Instance Health

#!/bin/bash
export AWS_PAGER=""
aws ssm describe-instance-information \
  --output text \
  --query 'InstanceInformationList[].[InstanceId,PingStatus,PlatformType,PlatformName,AgentVersion,IsLatestVersion,LastPingDateTime]' \
  | sort -k2

3. Patch Compliance Summary

#!/bin/bash
export AWS_PAGER=""
INSTANCES=$(aws ssm describe-instance-information --output text --query 'InstanceInformationList[].InstanceId')
for inst in $INSTANCES; do
  aws ssm describe-instance-patch-states --instance-ids "$inst" \
    --output text \
    --query 'InstancePatchStates[].[InstanceId,InstalledCount,MissingCount,FailedCount,NotApplicableCount,OperationEndTime]' &
done
wait

4. Run Command History

#!/bin/bash
export AWS_PAGER=""
aws ssm list-commands --max-results 20 \
  --output text \
  --query 'Commands[].[CommandId,DocumentName,Status,StatusDetails,TargetCount,CompletedCount,ErrorCount,RequestedDateTime]' | sort -k8 -r

5. Session Manager Activity

#!/bin/bash
export AWS_PAGER=""
aws ssm describe-sessions --state Active \
  --output text \
  --query 'Sessions[].[SessionId,Target,Status,StartDate,Owner]' &

aws ssm describe-sessions --state History --max-results 20 \
  --output text \
  --query 'Sessions[].[SessionId,Target,Status,StartDate,EndDate,Owner]' &
wait

Anti-Hallucination Rules

1. SecureString parameters are encrypted - get-parameter without --with-decryption returns encrypted values for SecureString. Always use --with-decryption for readable values.
2. PingStatus reflects SSM agent - PingStatus "Online" means the SSM agent is responding, not that the instance is healthy. "ConnectionLost" means no agent response in 5+ minutes.
3. Parameter tiers - Standard (free, 4KB, 10K max), Advanced ($0.05/month, 8KB, 100K max), Intelligent-Tiering (auto). Tier affects cost.
4. Patch baselines are OS-specific - Each OS has a separate default patch baseline. Custom baselines must match the target OS.
5. Run Command != SSH - Run Command executes documents via SSM agent, not SSH. No SSH keys or open ports required.

Output Format

Present results as a structured report:

Aws Systems Manager Report
══════════════════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≤50 lines of output. Use tables for multi-resource comparisons.

Counter-Rationalizations

Shortcut	Counter	Why
"I'll skip discovery and check known resources"	Always run Phase 1 discovery first	Resource names change, new resources appear — assumed names cause errors
"The user only asked for a quick check"	Follow the full discovery → analysis flow	Quick checks miss critical issues; structured analysis catches silent failures
"Default configuration is probably fine"	Audit configuration explicitly	Defaults often leave logging, security, and optimization features disabled
"Metrics aren't needed for this"	Always check relevant metrics when available	API/CLI responses show current state; metrics reveal trends and intermittent issues
"I don't have access to that"	Try the command and report the actual error	Assumed permission failures prevent useful investigation; actual errors are informative

Common Pitfalls

• Parameter path hierarchy: Parameters use / path separators. get-parameters-by-path with --recursive fetches all under a path prefix.
• Parameter versions: Each update creates a new version. Use :version suffix to reference specific versions (e.g., /app/config:3).
• Patch group assignment: Instances must have a Patch Group tag to be associated with a patch baseline. Untagged instances use the default baseline.
• CloudWatch statistics syntax: Use spaces not commas: --statistics Average Maximum.
• Document permissions: SSM documents can be shared with specific accounts or publicly. Audit with describe-document-permission.