sns-subscription-operator
Operates AWS SNS subscription workflows end-to-end — subscription creation (HTTP/HTTPS/SQS/Lambda/email/sms/firehose), subscription confirmation (PendingConfirmation to Confirmed via token or auto-confirm for SQS/Lambda), filter-policy design (message attributes, FilterPolicyScope), delivery policies (retry backoff, dead-letter queue via redrive), subscription attributes (RawMessageDelivery), and diagnostic loops (list-subscriptions-by-topic, get-subscription-attributes, CloudTrail events). Runs deterministic pre-checks (topic exists, endpoint reachable, topic policy permits subscription, protocol valid, filter-policy JSON valid, DLQ target exists for redrive) behind a CONFIRM gate and emits a READY, BLOCKED, or COMPLETED verdict per operation. Use when creating subscriptions, confirming pending subscriptions, debugging filter-policy matches, configuring delivery retry and DLQ, or diagnosing why messages are not delivered.
- License 许可
- Apache-2.0
- 最近更新
- 2026-09-24
- Stars
- ★ 4
- Forks
- 0
01 前言 Front Matter
- name
- sns-subscription-operator
- license
- Apache-2.0
- metadata
- { "tags": "aws, sns, app-integration, subscription, messaging, filter-policy, delivery-policy, operate", "phase": "4", "author": "Jacky Chan — AWS Community Builder", "domain": "aws-cloudops", "family": "AppIntegration", "version": "0.1.0", "keywords": "SNS, subscription, PendingConfirmation, ConfirmSubscription, filter policy, FilterPolicyScope, message attributes, delivery policy, retry backoff, dead-letter queue, DLQ, redrive policy, RawMessageDelivery, HTTP subscription, HTTPS subscription, SQS subscription, Lambda subscription, email subscription, firehose subscription, subscription attributes, SNS message data protection, cross-account subscription", "task_type": "operate", "complexity": "medium", "entry_point": "false", "skill_class": "capability", "when_to_use": "Creating an SNS subscription to a topic (HTTP/HTTPS/SQS/Lambda/ email/sms/firehose/application), confirming a subscription stuck in PendingConfirmation, designing or debugging a subscription filter policy, configuring delivery retry policy and dead-letter queue (DLQ), setting subscription attributes (RawMessageDelivery), diagnosing why messages are not delivered to a subscription, or validating SNS message data protection posture for a subscription.", "requires_llm": "true", "keywords_tags": "aws, sns, app-integration, subscription, messaging, operate", "verdict_shape": "READY | BLOCKED | COMPLETED", "lifecycle_status": "active", "invocation_schema": "Input: either (a) an SNS subscription configuration (topic ARN, protocol, endpoint, filter policy, delivery policy, subscription attributes) plus the intended operation (create, confirm, set-filter-policy, set-delivery-policy, set-attributes, delete, diagnose), OR (b) a subscription ARN + operation for live-account execution. Output: deterministic OPERATION / VERDICT / TARGET / PRE_CHECKS / STEPS / POST_VERIFY / NOTES block per operation, where VERDICT is one of READY, BLOCKED, COMPLETED.", "supports_pipeline": "true", "activation_triggers": "create SNS subscription, confirm SNS subscription, PendingConfirmation, SNS filter policy, SNS delivery policy, SNS dead-letter queue, SNS subscription redrive, SNS retry backoff, RawMessageDelivery, subscribe to SNS topic, SNS subscription not receiving messages, SNS message data protection, cross-account SNS subscription, SNS firehose subscription, get-subscription-attributes" }
- description
- Operates AWS SNS subscription workflows end-to-end — subscription creation (HTTP/HTTPS/SQS/Lambda/email/sms/firehose), subscription confirmation (PendingConfirmation to Confirmed via token or auto-confirm for SQS/Lambda), filter-policy design (message attributes, FilterPolicyScope), delivery policies (retry backoff, dead-letter queue via redrive), subscription attributes (RawMessageDelivery), and diagnostic loops (list-subscriptions-by-topic, get-subscription-attributes, CloudTrail events). Runs deterministic pre-checks (topic exists, endpoint reachable, topic policy permits subscription, protocol valid, filter-policy JSON valid, DLQ target exists for redrive) behind a CONFIRM gate and emits a READY, BLOCKED, or COMPLETED verdict per operation. Use when creating subscriptions, confirming pending subscriptions, debugging filter-policy matches, configuring delivery retry and DLQ, or diagnosing why messages are not delivered.
- 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 sns subscribe, confirm-subscription, list-subscriptions-by-topic, get-subscription-attributes, set-subscription-attributes, unsubscribe, aws sqs get-queue-attributes / set-queue-attributes (for SQS-backed subscriptions and DLQ), aws lambda get-policy (for Lambda-backed subscriptions), aws firehose describe-delivery-stream (for...
02 资源文件 20
- 参考文档eval/test-cases.yaml7.8 KB
- 参考文档evals/baselines/create-sqs-subscription-ready.md886 B
- 参考文档evals/baselines/cross-account-subscription-blocked.md609 B
- 参考文档evals/baselines/delivery-policy-dlq-setup.md855 B
- 参考文档evals/baselines/filter-policy-attribute-mismatch.md869 B
- 参考文档evals/baselines/http-subscription-pending-confirmation.md561 B
- 参考文档evals/eval_config.yaml1.9 KB
- 参考文档evals/evals.json4.4 KB
- 参考文档evals/prompts/create-sqs-subscription-ready.md963 B
- 参考文档evals/prompts/cross-account-subscription-blocked.md759 B
- 参考文档evals/prompts/delivery-policy-dlq-setup.md951 B
- 参考文档evals/prompts/filter-policy-attribute-mismatch.md985 B
- 参考文档evals/prompts/http-subscription-pending-confirmation.md714 B
- 参考文档examples/README.md5.8 KB
- 参考文档references/advanced-patterns.md9.8 KB
- 参考文档references/diagnostic-commands.md1.4 KB
- 参考文档references/subscription-confirmation-and-delivery.md6.0 KB
- 参考文档references/subscription-protocols-and-attributes.md4.5 KB
- 参考文档references/worked-examples.md5.3 KB
- 参考文档skill.usf.yaml4.5 KB
03 SKILL.md 正文
SNS Subscription Operator
What this skill does
Executes SNS subscription operations correctly and safely. Runs
deterministic pre-checks before any state-changing CLI (topic exists,
endpoint reachable, topic policy permits subscription, protocol valid,
filter-policy JSON valid, DLQ target exists for redrive), executes the
subscribe / confirm-subscription / set-subscription-attributes
CLI behind a CONFIRM gate, and verifies the result by confirming
get-subscription-attributes returns the expected state and the
endpoint receives a test message. Every create-subscription produces a
confirmation-flow note (HTTP/HTTPS/email require token-based
confirmation; SQS/Lambda can be auto-confirmed if the caller owns the
endpoint). Every filter-policy plan includes a message-attribute match
simulation. Every delivery-policy plan includes the retry math and DLQ
target verification.
Quick navigation
| Section | What it covers | When to read it |
|---|---|---|
| § Quick reference | Verdict thresholds (BLOCKED/READY/COMPLETED) + protocol matrix | Before any operation |
| § Expert heuristic | Non-obvious rules (confirmation flow, filter-policy scope, RawMessageDelivery, redrive) | Understanding the delivery model |
| § Pre-flight | Subscription metadata gate — topic exists, endpoint reachable, policy, protocol | Before executing any CLI |
| § Process | Per-operation planning: create, confirm, set-filter, set-delivery, set-attributes, delete, diagnose | When choosing which operation |
| § STRICT output contract | Structured OPERATION/VERDICT/TARGET/PRE_CHECKS/STEPS/POST_VERIFY/NOTES template | Formatting the response |
| § Anti-Patterns | Top-5 NEVER list — common mistakes that break delivery or strand messages | Review before risky operations |
Quick reference — verdict thresholds
| Verdict | Trigger condition | Action |
|---|---|---|
BLOCKED |
One or more pre-checks failed (topic does not exist, endpoint unreachable, topic policy denies subscription, invalid protocol, malformed filter-policy JSON, DLQ target does not exist for redrive, cross-account without permission) | 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 (get-subscription-attributes matches intent, test message delivered or CloudTrail event present, DLQ policy valid) |
Emit verification results, monitoring plan |
Protocol matrix — confirmation requirements and capabilities:
| Protocol | Endpoint format | Confirmation required? | RawMessageDelivery | Filter policy | Delivery policy | DLQ (redrive) |
|---|---|---|---|---|---|---|
sqs |
SQS queue ARN | No (auto-confirmed if caller owns queue) | Yes (recommended) | Yes | Yes | Yes (via subscription redrive) |
lambda |
Lambda function ARN | No (auto-confirmed if caller owns function) | Yes | Yes | Yes | Yes |
https |
HTTPS URL | Yes (token from POST) | Yes | Yes | Yes | Yes |
http |
HTTP URL | Yes (token from POST) | Yes | Yes | Yes | Yes |
email |
Email address | Yes (token from email) | N/A | Yes | No | No |
email-json |
Email address | Yes (token from email) | N/A | Yes | No | No |
sms |
Phone number (E.164) | Yes (token from SMS) | N/A | Yes | No | No |
firehose |
Firehose ARN | No (auto-confirmed if caller owns stream) | Yes | Yes | Yes | Yes |
application |
Platform endpoint ARN (mobile push) | Yes (token from push) | N/A | Yes | Yes | Yes |
Priority order for pre-checks (apply in this sequence, all must pass for READY):
- Topic reachability — topic ARN exists (
list-topics/get-topic-attributesdoes not returnNotFound). - Protocol validity — protocol is one of
sqs,lambda,https,http,email,email-json,sms,firehose,application. - Endpoint format — endpoint matches the protocol's expected format (SQS ARN for sqs, Lambda ARN for lambda, URL for http/https, email for email, E.164 phone for sms, Firehose ARN for firehose).
- Topic policy permission — the topic's resource-based policy
allows
sns:Subscribefor the caller's account/role. Cross-account subscriptions require both sides. - Filter-policy JSON validity — if a filter policy is specified, the JSON is valid and within the 30 KB limit (SNS enforces a max filter-policy size).
- DLQ target exists — if a delivery policy includes a redrive policy (DLQ), the DLQ ARN exists and the topic has permission to deliver to it.
- Confirmation flow clarity — for HTTP/HTTPS/email/sms, the operator understands that confirmation is a separate step requiring token extraction. For SQS/Lambda/firehose, confirmation is automatic if the caller owns the endpoint.
Expert heuristic — the non-obvious rules
Moved to references/advanced-patterns.md. Seven rules: auto-confirm when caller owns the endpoint, token confirmation for HTTP/HTTPS/email/sms, attribute matching, FilterPolicyScope default, RawMessageDelivery, per-subscription retry override, subscription-level redrive.
Pre-flight: subscription metadata gate
Run before classification. Misclassifying these produces wrong plans.
Pagination: list-subscriptions-by-topic paginates at 100/page —
drain --next-token to completion. list-topics paginates at 100/page.
Moved to references/diagnostic-commands.md. get-topic-attributes, list-subscriptions-by-topic, per-protocol endpoint policy checks (SQS/Lambda/Firehose/HTTP), filter-policy JSON, and DLQ validation.
Malformed input: if the input JSON is invalid or missing required
fields, emit VERDICT: ERROR with REASON: Subscription configuration is not valid JSON or is missing required fields — cannot plan. and
REMEDIATION: Re-fetch with aws sns list-subscriptions-by-topic --topic-arn <arn> --output json and re-plan.
| Subscription attribute | Effect on operation |
|---|---|
PendingConfirmation: true |
Subscription not yet confirmed. For HTTP/HTTPS/email/sms, extract the token and confirm. For SQS/Lambda/firehose cross-account, the endpoint owner must confirm. |
PendingConfirmation: false + valid SubscriptionArn |
Subscription confirmed and active. |
FilterPolicy set |
Messages without matching attributes are NOT delivered. Verify the filter matches the publisher's message attributes. |
FilterPolicyScope: MessageBody |
Filter policy matches on message body (must be valid JSON). Default is MessageAttributes. |
RawMessageDelivery: true |
Endpoint receives only the Message field, not the full SNS envelope. Required for SQS-to-Lambda triggers. |
DeliveryPolicy set |
Per-subscription retry and backoff. Overrides the topic-level delivery policy. |
RedrivePolicy set (DLQ) |
Failed deliveries go to the specified SQS DLQ after retries are exhausted. |
Topic is FIFO (*.fifo) |
Subscription must use SQS FIFO queue as endpoint. HTTP/HTTPS/Lambda/email are NOT supported for FIFO topics. |
| Cross-account topic | Topic policy must allow sns:Subscribe for the subscriber's account. Endpoint owner confirms if required. |
Process — operation planning (apply in order)
Step 0: Expert knowledge — non-obvious SNS subscription behaviors
Moved to references/advanced-patterns.md. 13 behaviors: two-phase confirmation, both-sides cross-account permission, silent filter drops, filter operators, body scope, raw payload shape, policy override, backoff, SQS-only DLQ, FIFO queue-only, data protection, Firehose ACTIVE, eventual consistency.
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:
- Topic ARN exists (
get-topic-attributesdoes not returnNotFound). - Topic is not being deleted (topic
DisplayNameandOwnerare present). - Calling identity has
sns:ListSubscriptionsByTopicandsns:GetSubscriptionAttributeson the topic ARN.
For create-subscription (subscribe --topic-arn --protocol --notification-endpoint):
4. Protocol is valid (sqs, lambda, https, http, email,
email-json, sms, firehose, application).
5. Endpoint matches protocol format (ARN for sqs/lambda/firehose, URL
for http/https, email address for email, E.164 phone for sms).
6. Topic policy allows sns:Subscribe for the caller (identity-based
OR resource-based).
7. For SQS endpoint: queue policy allows sqs:SendMessage from the
topic ARN.
8. For Lambda endpoint: Lambda resource policy allows
lambda:InvokeFunction from the topic ARN.
9. For Firehose endpoint: delivery stream is ACTIVE.
10. For FIFO topic: endpoint is an SQS FIFO queue.
11. If filter policy specified: JSON is valid, within 30 KB limit.
12. If return-subscription-arn is set: caller owns the topic OR topic
policy allows the caller to subscribe.
For confirm-subscription (confirm-subscription --topic-arn --token):
4. Token is valid (not expired — tokens are valid for 3 days).
5. Subscription is still pending confirmation (not already confirmed
or deleted).
For set-filter-policy (set-subscription-attributes --attribute-name FilterPolicy):
4. Subscription ARN is confirmed (not pending confirmation).
5. Filter policy JSON is valid and within 30 KB.
6. (Optional) The publisher's message attributes match the filter —
run a simulation to avoid silent non-delivery.
For set-delivery-policy (set-subscription-attributes --attribute-name DeliveryPolicy):
4. Subscription ARN is confirmed.
5. Delivery policy JSON is valid (retry count, backoff, delay within
SNS limits).
For set-redrive-policy / set-dlq (set-subscription-attributes --attribute-name RedrivePolicy):
4. Subscription ARN is confirmed.
5. DLQ SQS ARN exists (get-queue-attributes does not return
QueueDoesNotExist).
6. DLQ queue policy allows sqs:SendMessage from the SNS topic ARN
(or the SNS service principal).
7. DLQ is NOT the same queue as the subscription endpoint (creates a
loop).
For diagnose-subscription (read-only):
4. Read get-subscription-attributes, CloudTrail events, and the
failure-mode table to identify why messages are not delivered.
Subscription failure-mode table (use during diagnose):
| Symptom | Root cause | Fix |
|---|---|---|
get-subscription-attributes shows PendingConfirmation: true |
HTTP/HTTPS/email/sms subscription not confirmed | Extract the token from the confirmation message and call confirm-subscription |
| Subscription confirmed but no messages received | Filter policy does not match publisher's message attributes | Verify message attributes match the filter policy; use FilterPolicyScope correctly |
| Subscription confirmed but no messages received (no filter policy) | Topic message data protection policy denying messages | Check topic getDataProtectionPolicy; the policy may audit, mask, or deny messages |
| SQS endpoint not receiving messages | Queue policy does not allow sqs:SendMessage from the topic ARN |
Add sqs:SendMessage permission for the topic ARN to the queue policy |
| Lambda endpoint not invoked | Lambda resource policy does not allow lambda:InvokeFunction from the topic ARN |
Add lambda:InvokeFunction permission for the topic ARN (or re-add the trigger via the console) |
| HTTP endpoint returns 4xx/5xx | Endpoint is not handling SNS POST correctly (must return 200) | Verify the endpoint returns 200 for SNS POST; check for certificate issues on HTTPS |
| Messages go to DLQ immediately | Delivery policy retries exhausted (endpoint consistently failing) | Fix the endpoint first, then replay from DLQ |
subscribe returns AuthorizationError |
Topic policy denies caller sns:Subscribe |
Add sns:Subscribe to the topic policy for the caller's account |
subscribe cross-account fails |
Endpoint owner has not confirmed OR topic policy does not allow cross-account subscription | Both sides must have permission; confirm with confirm-subscription if needed |
FIFO topic subscription fails with InvalidParameter |
Endpoint is not an SQS FIFO queue | Use an SQS FIFO queue (.fifo suffix) for FIFO topic subscriptions |
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.
- The expected confirmation flow (auto-confirmed for SQS/Lambda/firehose owned by caller; token-based for HTTP/HTTPS/email/sms).
- The expected side-effects (subscription created, filter policy applied, delivery policy set, DLQ configured).
- The CONFIRM gate prompt.
- The verification step (
get-subscription-attributes+ test message or CloudTrail event).
Step 3: Execute behind CONFIRM gate
- MANDATORY CONFIRMATION GATE. Before any state-changing CLI
(
subscribe,confirm-subscription,set-subscription-attributes,unsubscribe), emit:CONFIRM: About to <operation> on SNS topic <topic-arn> (subscription <sub-arn-or-"new">). This will <consequence>. Proceed? (yes/no). Do NOT execute until the operator confirms. - Capture pre-state for rollback:
aws sns get-subscription-attributes --subscription-arn <arn> --output json > /tmp/<sub-arn>-pre-$(date +%s).json. - Execute the CLI.
subscribereturns immediately; for HTTP/HTTPS/ email/sms, the confirmation step follows.
Step 4: Post-verification — COMPLETED
After the CLI completes, run post-verification. ALL checks must pass
for COMPLETED.
get-subscription-attributes --subscription-arn <arn>— confirm the attribute matches intent (FilterPolicy, DeliveryPolicy, RedrivePolicy, RawMessageDelivery).- For create-subscription: confirm
PendingConfirmation: falseand a validSubscriptionArn(not"pending confirmation"). - For filter-policy changes: publish a test message with the expected attributes and confirm the endpoint receives it.
- For DLQ: publish a message that fails delivery (e.g., endpoint down) and confirm the message lands in the DLQ after retries.
- CloudTrail shows the
Subscribe/ConfirmSubscription/SetSubscriptionAttributesevent with the topic ARN and caller. - Spot-check: the endpoint (SQS queue, Lambda function, HTTP server) receives a test message published to the topic.
If ANY verification fails, emit VERDICT: ERROR with the failure
details — do not claim COMPLETED.
STRICT output contract (per operation)
OPERATION: <create | confirm | set-filter-policy | set-delivery-policy | set-redrive-policy | set-attributes | delete | diagnose>
VERDICT: READY | BLOCKED | COMPLETED
TARGET: <topic-arn> (subscription: <sub-arn-or-"new">, protocol: <protocol>, endpoint: <endpoint-or-"masked">, 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: <confirmation flow, filter-policy match, retry config, DLQ, caveats>
Worked example — create SQS subscription with filter policy
OPERATION: create
VERDICT: READY
TARGET: arn:aws:sns:us-east-1:111111111111:order-events (subscription:
new, protocol: sqs, endpoint:
arn:aws:sqs:us-east-1:111111111111:order-processing-queue,
account 111111111111, region us-east-1)
PRE_CHECKS:
- [PASS] Topic exists (arn:aws:sns:us-east-1:111111111111:order-events)
- [PASS] Protocol sqs valid
- [PASS] Endpoint is a valid SQS ARN
- [PASS] Topic policy allows sns:Subscribe for caller account
- [PASS] Queue policy allows sqs:SendMessage from topic ARN
- [PASS] Filter policy JSON valid ({"event_type": ["order_created",
"order_updated"]}, 48 bytes < 30 KB limit)
- [PASS] Caller owns the SQS queue (auto-confirmation applies)
STEPS:
1. CONFIRM: About to create an SNS subscription on topic
arn:aws:sns:us-east-1:111111111111:order-events, protocol sqs,
endpoint arn:aws:sqs:us-east-1:111111111111:order-processing-queue.
Filter policy: {"event_type": ["order_created", "order_updated"]}.
RawMessageDelivery: true. Auto-confirmation applies (caller owns
the queue). Proceed? (yes/no)
2. aws sns subscribe \
--topic-arn arn:aws:sns:us-east-1:111111111111:order-events \
--protocol sqs \
--notification-endpoint arn:aws:sqs:us-east-1:111111111111:order-processing-queue \
--attributes file://attrs.json
# attrs.json:
# {"FilterPolicy": "{\"event_type\": [\"order_created\", \"order_updated\"]}",
# "RawMessageDelivery": "true"}
3. Capture the returned SubscriptionArn for verification.
POST_VERIFY: (pending execution)
NOTES:
- Auto-confirmation applies because the caller owns the SQS queue.
The SubscriptionArn is returned immediately — no token step needed.
- Filter policy: only messages with message attribute event_type in
[order_created, order_updated] will be delivered. Messages without
this attribute are silently dropped (by design).
- RawMessageDelivery: true — the queue receives only the Message body,
not the full SNS envelope. The Lambda trigger on this queue will
receive the message body directly.
- Delivery policy: default (4 retries over 1 hour, exponential backoff).
To customize, use set-subscription-attributes --attribute-name
DeliveryPolicy after creation.
Worked example — diagnose subscription not receiving messages
Moved to references/worked-examples.md. COMPLETED diagnose block: attribute-name mismatch (filter 'event_type' vs publisher 'type'), fixed FilterPolicy plus test publish.
Worked example — set delivery policy with DLQ
Moved to references/worked-examples.md. READY block: 5-retry exponential DeliveryPolicy plus RedrivePolicy DLQ with same-queue loop check.
Worked example — cross-account subscription BLOCKED
Moved to references/worked-examples.md. BLOCKED block: cross-account missing sns:Subscribe on the topic and sqs:SendMessage on the queue — both sides must be fixed.
Anti-Patterns — NEVER (top 5)
These are the five highest-impact mistakes. Each one silently breaks message delivery or creates a security exposure.
-
NEVER assume a subscription is delivering messages just because the subscription exists. A subscription in
PendingConfirmationstate (HTTP/HTTPS/email/sms) receives ZERO messages until confirmed. Always verifyPendingConfirmation: falsebefore expecting delivery. SQS/Lambda/firehose subscriptions owned by the caller are auto- confirmed; cross-account endpoints are NOT. -
NEVER set a filter policy without verifying the publisher's message attribute names. The #1 cause of SNS non-delivery is an attribute name mismatch between the filter policy and the publisher. The filter silently drops non-matching messages — no error, no CloudTrail event, no DLQ delivery. Always run a test publish after setting a filter policy.
-
NEVER configure a subscription DLQ (redrive) pointing to the same SQS queue as the subscription endpoint. This creates a delivery loop: failed messages go to the DLQ (which is the same queue), get retried, fail again, and loop forever. Always verify the DLQ ARN is different from the endpoint ARN.
-
NEVER leave the topic policy allowing
sns:Subscribefrom*(all principals) in production. This allows any AWS account to subscribe to the topic and exfiltrate messages. Restrictsns:Subscribeto specific accounts or roles. Use SNS message data protection to audit for overly permissive topic policies. -
NEVER use
unsubscribewithout capturing the subscription attributes first. Unsubscribing is irreversible — the subscription ARN, filter policy, delivery policy, and DLQ configuration are all lost. If the subscription needs to be recreated, all attributes must be reconfigured. Always emitCONFIRM:beforeunsubscribe.
Edge-case handling
Moved to references/advanced-patterns.md. 403 on confirmation POST, FIFO+Lambda unsupported, Firehose stream CREATING, data-protection Deny.
Pre-flight safety checks (run before any remediation CLI)
-
MANDATORY CONFIRMATION GATE. Before any state-changing operation (
subscribe,confirm-subscription,set-subscription-attributes,unsubscribe), emit:CONFIRM: About to <operation> on SNS topic <topic-arn> (subscription <sub-arn>). This will <consequence>. Proceed? (yes/no). Do NOT execute until the operator confirms. -
Capture pre-state for audit. Before any subscription operation:
aws sns get-subscription-attributes --subscription-arn <arn> --output json > /tmp/<sub-id>-pre-$(date +%s).json. -
Verify topic policy before cross-account subscription. The topic policy must explicitly allow
sns:Subscribefor the subscriber's account. A missing permission producesAuthorizationError. -
Verify endpoint policy before creating the subscription. For SQS endpoints: the queue policy must allow
sqs:SendMessagefrom the topic ARN. For Lambda: the resource policy must allowlambda:InvokeFunctionfrom the topic ARN. -
Verify the DLQ is not the same as the endpoint. A redrive policy pointing to the same SQS queue as the subscription endpoint creates an infinite retry loop.
-
Verify the filter policy JSON before applying. Malformed JSON or attribute names that don't match the publisher produce silent non- delivery. Run a test publish after applying.
Recent AWS features (2024-2026)
Moved to references/advanced-patterns.md. Firehose protocol, message data protection, MessageBody filter scope, FIFO expansion, PublishBatch, cross-account CloudTrail delivery logging.
References (load on demand)
- advanced-patterns — Expert heuristic seven rules, Step 0 expert knowledge, edge-case handling, Recent AWS features
- diagnostic-commands — live-account pre-flight commands moved from SKILL.md
- subscription-confirmation-and-delivery — confirmation flows and delivery retry detail
- subscription-protocols-and-attributes — per-protocol endpoint formats and subscription attributes
- worked-examples — diagnose, delivery-policy-with-DLQ, and cross-account BLOCKED worked examples moved from SKILL.md
Domain
AWS CloudOps / SNS Subscription Operations & App Integration.
AWS documentation
- Amazon SNS Developer Guide — https://docs.aws.amazon.com/sns/latest/dg/
- SNS subscription operations — https://docs.aws.amazon.com/sns/latest/dg/sns-subscription-operations.html
- SNS filter policies — https://docs.aws.amazon.com/sns/latest/dg/sns-message-filtering.html
- SNS delivery policies — https://docs.aws.amazon.com/sns/latest/dg/sns-message-delivery-retries.html
- SNS dead-letter queues — https://docs.aws.amazon.com/sns/latest/dg/sns-dead-letter-queues.html
- SNS message data protection — https://docs.aws.amazon.com/sns/latest/dg/sns-data-protection.html
- SNS FIFO topics — https://docs.aws.amazon.com/sns/latest/dg/fifo-message-delivery.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.