diff --git a/llms.txt b/llms.txt index 09c0548..af02229 100644 --- a/llms.txt +++ b/llms.txt @@ -1,12 +1,16 @@ -# AWS DevOps Agent Skills +# AWS DevOps Agent Tools -> Open-source skills for AWS DevOps Agent that extend its capabilities for incident response, root cause analysis, and operational troubleshooting. This repository contains ready-to-use skills that can be uploaded to AWS DevOps Agent, as well as templates for writing custom skills. Skills follow the open Agent Skills specification. +> Open-source tools for AWS DevOps Agent that extend its capabilities for incident response, root cause analysis, and operational troubleshooting. This repository contains skills, custom agents, and MCP servers that can be used with AWS DevOps Agent, as well as templates for writing your own. Skills follow the open Agent Skills specification; MCP servers follow the Model Context Protocol. ## About This Repository -This is the primary open-source collection of skills for AWS DevOps Agent — the AI-powered operations agent from AWS that automates incident investigation, root cause analysis, and operational tasks. Each skill provides domain-specific instructions, decision trees, and runbooks that the agent follows during investigations. +This is the primary open-source collection of tools for AWS DevOps Agent — the AI-powered operations agent from AWS that automates incident investigation, root cause analysis, and operational tasks. It contains three types of tools: -Skills can be used with these AWS DevOps Agent types: +- **Skills** — domain-specific instructions, decision trees, and runbooks the agent follows during investigations. Uploaded to DevOps Agent as zips. +- **Custom agents** — pre-built agent configurations (a system prompt plus assigned tools and skills) for recurring operational workflows such as reports and operational reviews. Created in the DevOps Agent web app. +- **MCP servers** — Model Context Protocol servers that connect the agent to external systems and data sources, tailored to work alongside the skills and custom agents here. Deployed and registered as endpoints. + +Tools can be used with these AWS DevOps Agent types: - Chat tasks — conversational operational queries and analysis - Incident RCA — automated root cause analysis during active incidents - Prevention — proactive operational reviews and best practice assessments @@ -16,6 +20,7 @@ Skills can be used with these AWS DevOps Agent types: - [AWS Health Events Skill](skills/aws-health-events/SKILL.md): Retrieves and analyzes AWS Health events (service issues, scheduled changes, account notifications) to identify AWS-side events that correlate with observed operational issues - [Support Cases Skill](skills/support-cases/SKILL.md): Searches and analyzes AWS Support cases to find historical incidents with similar symptoms, proven remediations, and recurring patterns - [EKS Operation Review Skill](skills/eks-operation-review/SKILL.md): Performs comprehensive Amazon EKS operational reviews aligned with the AWS EKS Best Practices Guide covering security, reliability, networking, and scalability +- [EKS Upgrade Readiness Skill](skills/eks-upgrade-readiness/SKILL.md): Performs read-only Amazon EKS pre-upgrade readiness assessments aligned with the AWS EKS Best Practices Guide covering infrastructure prerequisites, EKS Upgrade Insights, API deprecations, addon compatibility, data plane inventory, PDB/topology safety, and capacity planning, producing a scored READY / NOT READY / READY WITH WARNINGS verdict - [RDS Operation Review Skill](skills/rds-operation-review/SKILL.md): Performs comprehensive Amazon RDS and Aurora operational reviews aligned with the AWS Well-Architected Framework covering security, reliability, performance, cost optimization, and backups - [MSK Operations Skill](skills/msk-operations/SKILL.md): Operates, troubleshoots, and assesses Amazon MSK Provisioned clusters (Standard and Express brokers) — performance issues, consumer lag, storage and EBS problems, rolling restarts and Kafka version upgrades, CloudWatch monitoring and alarms, and Kafka client (producer/consumer) tuning - [CRM Production Investigation Guidelines Skill](skills/crm-production-investigation-guidelines/SKILL.md): Sample skill demonstrating how to write production investigation guidelines for the Incident Triage agent type, showing application-specific architecture, incident isolation rules, and structured investigation procedures @@ -23,12 +28,35 @@ Skills can be used with these AWS DevOps Agent types: - [Enrich with AWS Security Agent Skill](skills/enrich-with-aws-security-agent/SKILL.md): Queries AWS Security Agent CloudWatch logs to retrieve code-level security findings (file, line number, vulnerability type) during incident investigations with potential security root causes - [Wiz Security Context Skill](skills/wiz-security-context/SKILL.md): Queries the Wiz MCP server for a resource's security context (vulnerabilities, misconfigurations, secrets, active threats, malware, toxic combinations) to determine whether an operational anomaly is an operational issue or a security incident - [Service Quota Check Skill](skills/service-quota-check/SKILL.md): Checks AWS service quota utilization during investigations and before provisioning resources, flags quotas at 85%+ utilization, and requests increases via the Service Quotas API or recommends support cases +- [ACM Certificate Ops Review Skill](skills/acm-certificate-ops-review/SKILL.md): Performs comprehensive ACM and ACM Private CA certificate health reviews covering expiry, failed renewals, validation failures, imported certificates, weak key algorithms, missing monitoring, Private CA issues, and CA/Browser Forum validity reduction readiness - [DMS Operational Review Skill](skills/database-migration-service-expertise/SKILL.md): Conducts AWS Database Migration Service operational reviews with 5-category health scoring, task failure troubleshooting, migration cutover runbooks, version deprecation tracking, and cost optimization - [Redshift Support Specialist Skill](skills/redshift-support-specialist/SKILL.md): Amazon Redshift domain expertise for query optimization, operational reviews, and cost optimization on provisioned clusters and Serverless workgroups, via the awslabs.redshift-mcp-server MCP server - [S3 Resiliency Review Skill](skills/storage-s3-resiliency-expertise/SKILL.md): Reviews one or many S3 buckets across nine resiliency, security, and data-protection dimensions using read-only control-plane calls, producing a rated report with prioritized findings and remediation guidance - [VPC DNS Investigation Skill](skills/aws-vpc-dns-investigation/SKILL.md): Diagnoses VPC DNS resolution failures and validates DNS control-plane changes before they are applied, driving the aws-vpc-dns-diagnostics MCP server to observe live resolution from inside the affected subnet and to simulate a proposed change - [Bedrock Adoption Readiness Skill](skills/bedrock-adoption-readiness/SKILL.md): Assesses an AWS account's readiness to run Amazon Bedrock at production scale across IAM governance, data retention (ZDR), quota and capacity headroom, and operational observability, covering both the standard Bedrock and bedrock-mantle (OpenAI-compatible) surfaces with multi-region discovery - [Analytics OpenSearch Expertise Skill](skills/analytics-opensearch-expertise/SKILL.md): Performs read-only health assessments of Amazon OpenSearch Service domains through 24 deterministic checks across cluster health, storage and shards, performance, security, and cost optimization, producing a structured findings report with prioritized remediation guidance +- [AI/ML Access Diagnostics Skill](skills/aiml-access-diagnostics/SKILL.md): Diagnoses IAM and access failures for Amazon Bedrock and SageMaker calls by tracing the authorization chain from caller identity through iam:PassRole, role trust policy, role permissions, resource policies, and SCPs to identify which hop denied the call +- [Bedrock Operation Review Skill](skills/bedrock-operation-review/SKILL.md): Performs comprehensive Amazon Bedrock operational reviews aligned with the AWS Well-Architected Framework and Bedrock best practices across five pillars — security, performance, service quotas, cost optimization, and resilience — using control-plane and CloudWatch APIs only (no model invocations or prompt/response content read) +- [AgentCore Observability Setup Skill](skills/agentcore-observability-setup/SKILL.md): Validates and bootstraps Amazon Bedrock AgentCore observability across runtime agents, Memory and Gateway resources, built-in tools, and agents hosted outside the runtime, verifying telemetry wiring via read-only CloudWatch, X-Ray, and AgentCore APIs and prescribing exact remediation for gaps it cannot directly read +- [AgentCore Operational Review Skill](skills/agentcore-ops-review/SKILL.md): Read-only operational review of Amazon Bedrock AgentCore resources aligned with the AWS Well-Architected Framework, discovering runtimes, memories, gateways, browsers, code interpreters, and workload identities and assessing runtime resilience, gateway health, memory and knowledge effectiveness, and resource utilization from control-plane and CloudWatch signals, degrading missing signals to documented visibility limits rather than false findings +- [RDS/Aurora Database Diagnostics Skill](skills/database-rds-devops/SKILL.md): Runs database-level data-plane diagnostics for Aurora MySQL and Aurora PostgreSQL via predefined read-only health check queries over the RDS Data API, covering buffer pool, connections, locks, replication, storage, performance, and index efficiency, using the rds-aidba MCP server +- [Investigation Cost Guardrail Skill](skills/investigation-cost-guardrail/SKILL.md): Estimates and caps the cost of paid API calls during investigations across all AWS services and native agent tools, enforcing per-investigation budgets, flagging expensive operations, requiring time windows, and cancelling when thresholds are exceeded + +## Available Custom Agents + +- [AWS Health Report](custom-agents/aws-health-report/README.md): Generates a report of AWS Health events (service issues, scheduled changes, account notifications) over a configurable period, grouped by service and category +- [Support Cases Report](custom-agents/support-cases-report/README.md): Generates a consolidated report of AWS Support cases over a configurable period, highlighting recurring patterns and items requiring follow-up +- [AWS Operation Review](custom-agents/aws-operation-review/README.md): Performs comprehensive operational reviews of AWS services (EKS, RDS, Aurora) against best practices and the Well-Architected Framework, producing a structured report artifact +- [Service Quotas Monitor](custom-agents/service-quotas-monitor/README.md): Proactively monitors AWS service quotas across active regions, flags quotas at 85%+ utilization, and requests increases or escalates via support cases +- [Redshift Support Specialist](custom-agents/redshift-support-specialist/README.md): Amazon Redshift support agent for query optimization, operational reviews, and cost optimization, paired with the redshift-support-specialist skill + +## Available MCP Servers + +- [Redshift MCP Server](mcp/aws-redshift-mcp-server/README.md): Serverless (Lambda + API Gateway, SigV4) deployment of the standard awslabs.redshift-mcp-server, giving the agent read access to Redshift via the Redshift Data API +- [RDS AIDBA](mcp/rds-aidba/README.md): Read-only, query-allowlisted diagnostic access to Aurora MySQL and Aurora PostgreSQL clusters via the RDS Data API +- [VPC DNS Diagnostics MCP](mcp/aws-vpc-dns-diagnostics-mcp/README.md): Observes live DNS resolution from inside an affected subnet and simulates proposed DNS control-plane changes before they are applied +- [EKS Node Diagnostics MCP](mcp/aws-eks-node-diagnostics-mcp/README.md): Collects and analyzes diagnostic logs from EKS worker nodes via SSM Automation (kubelet, containerd, CNI, iptables, dmesg, and more) not accessible through the Kubernetes API or CloudWatch +- [ECS Instance Log MCP](mcp/ecs-instance-log-mcp/README.md): Collects and analyzes diagnostic logs from ECS container instances via SSM Automation (ECS agent, Docker/containerd, system logs, networking, GPU) not accessible through the ECS API or CloudWatch ## Key Concepts @@ -37,14 +65,19 @@ Skills can be used with these AWS DevOps Agent types: - Skills are uploaded as zip files via the AWS DevOps Agent Operator Web App - Each skill contains a SKILL.md file with frontmatter metadata and step-by-step instructions - Skills can reference supplementary documents in a references/ directory +- Custom agents pair a system prompt (SYSTEM_PROMPT.md) with assigned tools and skills, and are created in the DevOps Agent web app to automate recurring workflows +- MCP servers implement the Model Context Protocol to connect the agent to external systems and data sources, and are deployed and registered as endpoints ## Documentation - [AWS DevOps Agent Product Page](https://aws.amazon.com/devops-agent/) - [AWS DevOps Agent User Guide](https://docs.aws.amazon.com/devopsagent/latest/userguide/about-aws-devops-agent.html) - [AWS DevOps Agent Skills Documentation](https://docs.aws.amazon.com/devopsagent/latest/userguide/about-aws-devops-agent-devops-agent-skills.html) +- [AWS DevOps Agent Custom Agents Documentation](https://docs.aws.amazon.com/devopsagent/latest/userguide/working-with-devops-agent-custom-agents-index.html) +- [Connecting MCP Servers to DevOps Agent](https://docs.aws.amazon.com/devopsagent/latest/userguide/configuring-integrations-and-knowledge-connecting-mcp-servers.html) - [Agent Skills Specification](https://agentskills.io/home) -- [Agent Skill Eval Framework](https://github.com/aws-samples/sample-agent-skill-eval) +- [AGENTS.md Specification](https://agents.md/) +- [Model Context Protocol](https://modelcontextprotocol.io) - [Extend AWS DevOps Agent with Custom Skills](https://builder.aws.com/content/3BDdQAFY2bSmtjecZC7vbOQGSEV/extend-aws-devops-agent-with-custom-skills-for-your-operational-workflows) ## Repository Structure @@ -54,4 +87,12 @@ Skills can be used with these AWS DevOps Agent types: - skills//README.md — Human documentation, prerequisites, upload guide - skills//references/ — Supplementary reference documents included in the skill - skills//evals/ — Evaluation queries and benchmarks for testing +- custom-agents/ — All custom agent directories +- custom-agents//SYSTEM_PROMPT.md — The agent's system prompt +- custom-agents//README.md — Purpose, prerequisites, creation and execution guide +- mcp/ — All MCP server directories +- mcp//README.md — What the server does, its tools, and deployment/registration steps +- cloudformation/ — IAM policy templates that skills require +- docs/ — GitHub Pages (mkdocs) documentation site - CONTRIBUTING.md — Contribution guidelines +- llms.txt — This structured repository overview for AI tools diff --git a/skills/acm-certificate-ops-review/.skilleval.yaml b/skills/acm-certificate-ops-review/.skilleval.yaml new file mode 100644 index 0000000..686a9c7 --- /dev/null +++ b/skills/acm-certificate-ops-review/.skilleval.yaml @@ -0,0 +1,3 @@ +audit: + ignore: + - STR-016 # README alongside SKILL.md is intentional diff --git a/skills/acm-certificate-ops-review/CHANGELOG.md b/skills/acm-certificate-ops-review/CHANGELOG.md new file mode 100644 index 0000000..76054b7 --- /dev/null +++ b/skills/acm-certificate-ops-review/CHANGELOG.md @@ -0,0 +1,63 @@ +# Changelog + +All notable changes to the `acm-certificate-ops-review` skill are documented +in this file. The format is based on Keep a Changelog, and this project follows +semantic versioning. + +## [1.2.0] - 2026-09-18 + +Authors: Tejas Majamudar (majamuda) + +### Added +- Email-validated certificate detection (Step 2, check #4): identifies + `AMAZON_ISSUED` certificates where `ValidationMethod = EMAIL` and flags + them as AMBER. The CA/B Forum is deprecating email-based domain validation + for publicly trusted certificates - ACM will stop issuing email-validated + certificates on **March 31, 2027** and stop renewing them on + **September 30, 2027**. Remediation: switch in-place via + `UpdateCertificateOptions` (ARN unchanged, 72-hour CNAME window). ACME-origin + and IMPORTED/PRIVATE certificates are explicitly excluded from this check. +- New eval scenario `acm-email-validation-deprecation` covering the AMBER + classification, correct 2027 deadlines, and `UpdateCertificateOptions` + remediation assertions. + +## [1.1.0] - 2026-09-10 + +Authors: Tejas Majamudar (majamuda), Manoj Gaddam (vmgaddam) + +### Added +- AWS Workload Credentials Provider (WCP) as a second automation path in the + CA/Browser Forum migration decision tree, alongside ACM ACME. +- ACME certificate discovery: dual-axis `ListCertificates` filtering that + expands both `CertificateKeyPairOrigins` (to include `ACME`) and + `Includes.keyTypes` (to include EC key types), so ACME-origin and ECDSA + certificates are no longer silently dropped by the default filters. +- Step 1 verification step: confirm both filter axes were expanded before + reporting inventory or concluding that a certificate category is absent. +- New reference file `references/acm-detection-details.md` holding the full + key-pair origin / key-type filter values and the ACME renewal-pipeline + sub-checks (endpoint health, EAB status, ACME account status). +- Functional evaluation suite (`evals/evals.json`) covering ACME discovery, + risk classification, and negative-trigger cases. + +### Changed +- Converted the Step 1-6 headings to a checklist format for clearer sequential + execution. +- Moved the detailed detection enumerations out of `SKILL.md` into + `references/acm-detection-details.md`, keeping the body concise. +- Narrowed the declared agent type to Chat tasks only, and aligned the README. + +## [1.0.0] - 2026-07-12 + +Authors: Tejas Majamudar (majamuda), Manoj Gaddam (vmgaddam) + +### Added +- Initial release of the ACM Certificate Operations Review skill. +- Phase 1 operational investigation runbook: certificate inventory across + accounts/regions, issue detection (expiry, renewal health, validation + failures, imported-in-use, weak keys, unused certs, missing DaysToExpiry + monitoring, stale endpoints, ACM Private CA), risk classification, and a + prioritized findings report. +- Reference files: `acm-thresholds.md`, `report-format.md`, and + `cab-forum-readiness.md` (Phase 2 CA/Browser Forum readiness). +- Read-only IAM permission set documented in the README. diff --git a/skills/acm-certificate-ops-review/README.md b/skills/acm-certificate-ops-review/README.md new file mode 100644 index 0000000..e255e04 --- /dev/null +++ b/skills/acm-certificate-ops-review/README.md @@ -0,0 +1,127 @@ +# ACM Certificate Operations Review + +## Purpose + +This skill gives AWS DevOps Agent a repeatable procedure for investigating and +reviewing AWS Certificate Manager (ACM) and ACM Private CA certificate health +across one or more accounts and regions. Certificate expiry is a leading cause +of avoidable customer-facing outages, and the CA/Browser Forum is progressively +shortening TLS certificate validity (398 to 47 days by March 2029), which makes +manual certificate management increasingly risky. The skill helps the agent +catch expiring, failing, and mismanaged certificates before they cause an +incident, and prepare a strategic readiness view for the shorter validity +windows. + +## Key Capabilities + +- Inventories ACM and ACM Private CA certificates across accounts and regions + (always including us-east-1 for CloudFront). +- Detects expiring/expired certificates, failed or stuck managed renewals, + `PENDING_VALIDATION` and DNS/email validation failures, imported in-use + certificates that cannot auto-renew, weak/legacy key algorithms, unused + certificates, and missing CloudWatch `DaysToExpiry` monitoring. +- Flags ACM Private CA problems (disabled, expired, or nearing expiry). +- Classifies findings by risk (RED / AMBER / GREEN) and produces a prioritized + findings report with an executive summary and remediation list. +- Optionally assesses CA/Browser Forum validity-reduction readiness, DV vs + OV/EV strategy, renewal automation options, and cost impact. + +## Prerequisites + +The skill is read-only. The DevOps Agent role for your Agent Space needs: + +- `acm:ListCertificates` +- `acm:DescribeCertificate` +- `acm-pca:ListCertificateAuthorities` +- `acm-pca:DescribeCertificateAuthority` +- `cloudwatch:DescribeAlarmsForMetric` +- `organizations:ListAccounts` (only for org-wide scans, from the management or + delegated administrator account) + +Most of these may already be covered by the `AIDevOpsAgentAccessPolicy` managed +policy attached to the DevOps Agent role; add any that are missing. + +## Limitations + +- Read-only: the skill inventories and assesses certificates but never creates, + imports, deletes, or renews them. +- Public trust and validity-reduction dates change over time; the skill directs + the agent to confirm current CA/Browser Forum and ACM figures against + authoritative sources before quoting them. +- GovCloud and China partitions are scanned only on explicit request and are + reported separately from commercial-partition findings. +- Cost figures must be computed from current pricing at run time; the skill does + not embed pricing. +- This is sample code (see disclaimer below). + +## Agent Types + +- **Chat tasks** - posture reviews, reports, and certificate-related + investigations (for example "review the ACM certificate posture for account + 1111..." or "investigate why example.com is serving an expired certificate"). + +Select this agent type when uploading the skill to your Agent Space. + +## Uploading to AWS DevOps Agent + +From the repository root, zip the skill (allowed extensions only, excluding +non-skill files) and upload it to your Agent Space, selecting the agent types +listed above: + +```bash +cd skills +zip -r acm-certificate-ops-review.zip acm-certificate-ops-review/ \ + -i '*.md' '*.txt' '*.json' '*.yaml' '*.yml' '*.xml' '*.csv' '*.tsv' '*.html' '*.htm' '*.png' '*.jpg' '*.jpeg' '*.gif' '*.svg' '*.webp' '*.pdf' \ + -x '*/.claude/*' '*/scripts/*' '*/README.md' '*/.skilleval.yaml' '*/.skilleval.yml' '*/CHANGELOG.md' '*/evals/*' +``` + +Then, in the Agent Space Operator Web App, go to Knowledge > Skills > upload the +zip, and grant the role the IAM permissions listed under Prerequisites if they +are not already present. + +## How to Use This Skill + +Operators do not need to name the skill; it activates from the description. +Sample prompts: + +Posture reviews and reports: +- "Review the ACM certificate posture for account 111122223333." +- "Which certificates across my org expire in the next 30 days?" +- "Are we ready for the CA/Browser Forum certificate validity reductions?" +- "Do any of my in-use certificates lack an expiry alarm?" + +Certificate-related investigations: +- "Investigate why www.example.com is serving an expired certificate." +- "A managed renewal failed for api.example.com; find the root cause." +- "An endpoint is still presenting the old certificate after renewal." + +## Skill Structure + +``` +acm-certificate-ops-review/ +├── SKILL.md # Main skill instructions (6-step workflow) +├── README.md # This file +├── CHANGELOG.md # Version history +├── .skilleval.yaml # Agent Skill Eval config +├── evals/ +│ └── evals.json # Functional evaluation scenarios +└── references/ + ├── acm-thresholds.md # Risk thresholds and RED/AMBER/GREEN criteria + ├── acm-detection-details.md # ListCertificates dual-filter values, ACME sub-checks + ├── cab-forum-readiness.md # CA/Browser Forum validity-reduction guidance + └── report-format.md # Findings report layout +``` + +## Disclaimer + +This skill is **sample code**. It is **not intended for production use without +additional review and testing**. Validate it in a **non-production +environment** first, review the IAM permissions and behavior against your +organization's security policies, and confirm the findings against your live +environment before acting on them. Certificate validity dates and CA/Browser +Forum timelines change over time - verify current values against the +authoritative AWS and CA/Browser Forum sources before relying on them. + +## License + +Apache-2.0. See the repository `LICENSE` file. diff --git a/skills/acm-certificate-ops-review/SKILL.md b/skills/acm-certificate-ops-review/SKILL.md new file mode 100644 index 0000000..b0220ae --- /dev/null +++ b/skills/acm-certificate-ops-review/SKILL.md @@ -0,0 +1,280 @@ +--- +name: acm-certificate-ops-review +description: "Investigation and review procedures for AWS Certificate Manager (ACM)\ + \ and ACM Private CA certificate health across one or more accounts and regions.\ + \ Use this skill when investigating TLS/SSL certificate problems or reviewing certificate\ + \ posture - certificates expiring soon or already expired, failed or stuck managed\ + \ renewals, certificates stuck in PENDING_VALIDATION, DNS or email domain validation\ + \ failures, endpoints still serving an old certificate after renewal, imported certificates\ + \ that ACM cannot auto-renew, weak or legacy key algorithms (RSA_1024), unused or\ + \ in-use certificates, missing CloudWatch DaysToExpiry expiry monitoring, ACM Private\ + \ CA issues, and readiness for the CA/Browser Forum TLS certificate validity reductions\ + \ (398 to 47 days by March 2029). Also use it for questions about certificate expiry\ + \ as a cause of outages, certificate renewal automation, or DV vs OV/EV certificate\ + \ strategy." +metadata: + author: majamuda, vmgaddam + version: "1.2.0" + aws-devops-agent-skills.agent-types: "Chat tasks" + aws-devops-agent-skills.aws-services: "AWS Certificate Manager, AWS Private CA" + aws-devops-agent-skills.technical-domains: "Security" +--- + +> **Important:** ACM and related services evolve frequently (new features, +> protocol support, pricing changes, validity rules). Before making any +> recommendation, verify the current service capabilities against the official +> AWS documentation. Do not rely on cached assumptions from prior runs or from +> this skill's reference files alone. If a feature status is uncertain, +> check the ACM What's New page and user guide for the latest updates before +> advising. + +# ACM Certificate Operations Review + +Use this skill when investigating or reviewing AWS Certificate Manager (ACM) +and ACM Private CA certificate health. Certificate expiry is a leading cause +of avoidable customer-facing outages, and the CA/Browser Forum has mandated +progressive reductions in TLS certificate validity (398 -> 198 -> 100 -> 47 +days by March 2029), which makes manual certificate management increasingly +risky. + +This skill has two phases: + +- **Phase 1 - Operational review (always applies).** Inventory certificates, + detect health problems, and produce a prioritized findings report. This is + the core investigation runbook. +- **Phase 2 - CA/Browser Forum readiness (apply when the operator asks about + strategic impact, validity reductions, automation readiness, or cost).** + When the operator asks about strategic impact, validity reductions, + automation readiness, or cost, load + [references/cab-forum-readiness.md](references/cab-forum-readiness.md). + Note: the migration decision tree covers TWO automation paths for workloads + outside integrated AWS services: ACM ACME and AWS Workload Credentials Provider. + +Threshold values, risk levels, and the required report layout are defined in +the reference files. Read them when you reach the step that needs them. + +## When to use this skill + +Load and follow this skill when the task involves any of the following: + +- A certificate is expiring soon, has expired, or an operator wants to know + what will expire in the next N days. +- A managed renewal failed, is stuck, or a certificate is stuck in + `PENDING_VALIDATION`. +- An endpoint is still presenting an old certificate after a renewal or + re-issue. +- Domain validation (DNS `CNAME` or email) is failing. +- An imported certificate is in use and ACM cannot manage its renewal. +- A certificate uses a weak or legacy key algorithm. +- There is no CloudWatch alarm on the `DaysToExpiry` metric for an important + certificate. +- An ACM Private CA is expiring, disabled, or its certificates are affected. +- An operator wants a certificate posture review across an account or an + organization. + +## Scope of investigation + +Before scanning, establish scope: + +1. **Accounts** - a specific account, a list of accounts, or (only when + explicitly requested) all linked accounts in the organization discovered + via `organizations:ListAccounts` from the management/delegated account. +2. **Regions** - always scan `us-east-1` first, because CloudFront + certificates must live there, then the remaining commercial regions in + scope. If the operator names regions, honor them but still include + `us-east-1`. + +Guardrails: + +- Default to the specific account(s) in the incident or request. Do **not** + scan the whole organization unless the operator explicitly asks for an + org-wide review, and confirm first if the scan will span many accounts. +- Treat GovCloud and China partitions separately. Do not scan them unless + explicitly requested, and never mix their findings with commercial-partition + findings in the same output - they have separate compliance requirements. +- Scan sequentially (one account at a time). On `TooManyRequestsException`, + back off exponentially (2s -> 4s -> 8s, max 3 retries). If several + consecutive accounts return `AccessDenied`, stop and report only the + accounts you could access. + +- [ ] **Step 1: Inventory certificates** + +For each account and region in scope: + +1. Call `acm:ListCertificates` and paginate with `NextToken`. If you filter by + key type, be aware new key types (for example post-quantum algorithms) can + be missed - when in doubt, omit the key-type filter so every certificate is + returned regardless of algorithm. + **CRITICAL - always open BOTH filter axes on EVERY `ListCertificates` call.** + `ListCertificates` silently drops certificates behind TWO independent default + filters, and a certificate is only returned when BOTH are broadened together: + - **Key-pair origin** - the `CertificateKeyPairOrigins` parameter defaults to + `AWS_MANAGED` + `CUSTOMER_PROVIDED`, so ACME-origin certs are excluded. + - **Key type** - the `Includes.keyTypes` parameter defaults to `RSA_1024` + + `RSA_2048`, so ECDSA (e.g. `EC_prime256v1`) certs are excluded. + Opening only one axis is the trap: an ACME cert with an ECDSA key stays + invisible until you expand BOTH in the same call. Never issue a default or + single-axis `ListCertificates` call. When running this step, load + [references/acm-detection-details.md](references/acm-detection-details.md) + for the exact origin and key-type values to pass. + **Do NOT conclude "no ACME certs" or "no ECDSA certs exist" from a call that + did not expand both axes** - that is a false negative, not an empty result. +2. For each certificate ARN, call `acm:DescribeCertificate` to retrieve + `Status`, `NotAfter`, `NotBefore`, `Type` (`AMAZON_ISSUED`, `IMPORTED`, or + other values including ACME-origin certs which may show a distinct key source), + `RenewalEligibility`, `RenewalSummary`, `KeyAlgorithm`, `InUseBy`, + `DomainValidationOptions`, `SubjectAlternativeNames`, and key source + (check for ACME-issued certs which appear alongside standard types). +3. For imported certificates, `InUseBy` and `NotAfter` are still available; + note that ACM cannot auto-renew imported certificates. +4. **Verify filter coverage before reporting.** Before presenting the inventory + or concluding a category is absent, confirm the `ListCertificates` call(s) + for each region expanded BOTH the key-pair origin axis (including `ACME`) and + the key-type axis (including the `EC_*` types). If either axis was left at its + default, re-run the call with both expanded. Only after this check may you + state whether ACME-origin or ECDSA certificates are present or absent. +5. Present a short inventory summary (account, region, certificate count) + before moving on, and skip account/region pairs that return zero + certificates. + +- [ ] **Step 2: Detect issues** + +Evaluate every certificate against the checks below. When evaluating +certificates in this step, load +[references/acm-thresholds.md](references/acm-thresholds.md) for the thresholds +and risk levels. + +1. **Expiry** - compute days until `NotAfter`. Flag expired and + soon-to-expire certificates, weighted higher when `InUseBy` is non-empty. +2. **Renewal health** - inspect `RenewalSummary.RenewalStatus`. Flag + `PENDING_VALIDATION`, `FAILED`, and `PENDING_AUTO_RENEWAL` that is not + progressing. Capture `RenewalStatusReason` and the per-domain + `ValidationStatus`. +3. **Validation failures** - for `PENDING_VALIDATION`, check + `DomainValidationOptions`: for DNS validation confirm the required `CNAME` + `ResourceRecord` exists and resolves; for email validation note that it + blocks automated renewal. +4. **Email-validated certificates (CA/B Forum deprecation)** - identify + `AMAZON_ISSUED` certificates where `DomainValidationOptions.ValidationMethod + = EMAIL`. Classify using these rules (use `acm:DescribeCertificate` - no new + permissions required): + - `AMAZON_ISSUED` + `ValidationMethod=DNS` - DNS validated (GREEN, no action) + - `AMAZON_ISSUED` + `ValidationMethod=EMAIL` - flag as **AMBER**: email + validation is being deprecated by the CA/B Forum. ACM will stop issuing + email-validated certificates on **March 31, 2027** and stop renewing them + on **September 30, 2027**. Recommend switching to DNS validation NOW using + `UpdateCertificateOptions` (ARN stays the same - no disruption to + load balancers, CI/CD, or service integrations). The customer has 72 hours + to add the CNAME records after initiating the switch. Monitor progress via + `ListCertificateDomainValidations`. + - `AMAZON_ISSUED` + `CertificateKeyPairOrigin=ACME` - ACM ACME issued, not + in scope for email-to-DNS migration (ACME certs use client-side key and + PRE_APPROVED endpoint authorization - no email/DNS challenge at issuance). + - `IMPORTED` or `PRIVATE` - not in scope for this check. +5. **Imported certificates in use** - flag `Type = IMPORTED` with a non-empty + `InUseBy`, since these will not auto-renew and are an outage risk. +6. **Weak or legacy keys** - flag `KeyAlgorithm` of `RSA_1024` (and any + algorithm below current best practice). When flagging, recommend the + stronger alternative: + - RSA_1024 → recommend minimum RSA_2048 (or ECDSA P-256 for better + performance and smaller key size) + - RSA_2048 is acceptable today but note that ECDSA P-256 (EC_prime256v1) + or P-384 (EC_secp384r1) are the modern best practice (faster TLS + handshake, stronger security per bit, and the default for ACME clients). + Always verify the current list of algorithms ACM supports at runtime + (check ACM docs / API for supported keyTypes). When new algorithms are + added (e.g. post-quantum), include them in the recommendation if they + offer stronger security. Do not limit recommendations to a static list. +7. **Unused certificates** - flag issued certificates with an empty `InUseBy` + as cleanup or cost-optimization candidates (do not auto-delete). +8. **ACME-issued certificates** - identify certificates with key source ACME + (visible in ListCertificates / DescribeCertificate). These auto-renew via + the ACME client and have short validity (currently 45 days). Classify as + GREEN if the ACME client is active; flag as RED if the cert is expired + (suggests the client stopped renewing). + When ACME certs are found, run the renewal-pipeline sub-checks (endpoint + health, EAB status, ACME account status) to verify renewals are healthy. + When running this check, load + [references/acm-detection-details.md](references/acm-detection-details.md) + for the full sub-check procedures and their RED/AMBER classification rules. +9. **Missing expiry monitoring** - for in-use certificates, check for a + CloudWatch alarm on the ACM `DaysToExpiry` metric + (`AWS/CertificateManager`, dimension `CertificateArn`) via + `cloudwatch:DescribeAlarmsForMetric`. Flag certificates with no alarm. + Two monitoring options exist (recommend both where possible): + - **CloudWatch DaysToExpiry alarm** (per-cert, self-managed) - works for + ALL certificate types (imported, ACM-issued, and ACME). Recommended + threshold: <= 30 days, period 1 day, statistic Minimum. + - **EventBridge `ACM Certificate Approaching Expiration`** (automatic, + no per-cert setup) - fires daily starting 30 days before expiry for + public certs. NOTE: `ACM Certificate Expired` events are NOT available + for imported certificates - so CloudWatch alarms are the only safety + net for imported certs. +10. **Stale endpoint after renewal** - if a certificate was renewed or + re-issued but a dependent endpoint still serves the old certificate, + confirm the resource references the new certificate ARN and that the + distribution/load balancer has finished deploying. +11. **ACM Private CA** - where relevant, call `acm-pca:ListCertificateAuthorities` + and `acm-pca:DescribeCertificateAuthority`; flag CAs that are `DISABLED`, + `EXPIRED`, or nearing expiry, since a CA problem affects every certificate + it issued. + +- [ ] **Step 3: Classify and prioritize** + +Assign each finding a risk level (RED / AMBER / GREEN). When classifying in +this step, load [references/acm-thresholds.md](references/acm-thresholds.md) +for the criteria. Rank by risk, then by whether the certificate +is in use, then by days to expiry. In-use certificates always outrank unused +ones at the same expiry distance. + +- [ ] **Step 4: Produce the findings report** + +When producing the report in this step, load +[references/report-format.md](references/report-format.md) and generate a +prioritized findings report following its structure. It must include: + +- A one-paragraph executive summary (overall posture, count by risk level, + most urgent item). +- A prioritized findings table (account, region, certificate/domain, type, + status, days to expiry, in-use, risk, recommendation). +- A remediation list ordered by priority. + +Reporting rules: + +- Compute every number (days to expiry, counts, any cost estimate) in code or + by explicit arithmetic on retrieved values - never estimate figures. +- Include an AI-generated-content disclaimer on the report. +- If this report may be shared outside the operations team, keep it factual + and free of internal-only identifiers. + +- [ ] **Step 5: CA/B Readiness Snapshot (always run)** + +After the findings report, ALWAYS append a brief CA/B readiness snapshot +using the Phase 1 inventory. Classify each in-use certificate into: +- GREEN: fully automated renewal in place (ACM-managed on integrated services, + or ACME-issued with active client). No action needed as validity shrinks. +- AMBER: partially automated or has a constraint (e.g. email validation, + exportable cert without Workload Credentials Provider configured). +- RED: manual renewal process (imported certs with no automation path). + +Present as a 3-line summary: +- GREEN count, AMBER count, RED count +- One-sentence risk statement (e.g. "X of Y active certificates will require + manual rotation at 47-day intervals by March 2029 without remediation.") +- Offer: "For detailed migration paths and automation options, ask for the + full CA/B Forum readiness assessment." + +- [ ] **Step 6 (on request): Full CA/B Forum readiness** + +If the operator asks for the full assessment (migration paths, gap analysis, +automation options, cost), load +[references/cab-forum-readiness.md](references/cab-forum-readiness.md), which +uses the Phase 1 inventory as its input. + +## Required IAM permissions + +Read-only. See `README.md` for the full list. Core actions: +`acm:ListCertificates`, `acm:DescribeCertificate`, +`acm-pca:ListCertificateAuthorities`, `acm-pca:DescribeCertificateAuthority`, +`cloudwatch:DescribeAlarmsForMetric`, and, for org-wide scans, +`organizations:ListAccounts`. diff --git a/skills/acm-certificate-ops-review/evals/eval_queries.json b/skills/acm-certificate-ops-review/evals/eval_queries.json new file mode 100644 index 0000000..48e100e --- /dev/null +++ b/skills/acm-certificate-ops-review/evals/eval_queries.json @@ -0,0 +1,8 @@ +[ + {"query": "Which skill would help me run an ACM certificate operations review? Just name it; do not run it.", "should_trigger": true}, + {"query": "Is there a skill available for checking ACM certificate expiry and renewal health? Answer yes or no with the skill name; do not execute it.", "should_trigger": true}, + {"query": "Name the skill that covers CA/Browser Forum certificate validity readiness. Do not run any audit.", "should_trigger": true}, + {"query": "Write a Python script that sorts a list of numbers", "should_trigger": false}, + {"query": "What's the weather forecast for Sydney this weekend?", "should_trigger": false}, + {"query": "Create a CloudFormation template for an S3 bucket", "should_trigger": false} +] diff --git a/skills/acm-certificate-ops-review/evals/evals.json b/skills/acm-certificate-ops-review/evals/evals.json new file mode 100644 index 0000000..fbca139 --- /dev/null +++ b/skills/acm-certificate-ops-review/evals/evals.json @@ -0,0 +1,67 @@ +{ + "skill_name": "acm-certificate-ops-review", + "evals": [ + { + "id": "acm-acme-discovery-gap", + "task_type": "chat", + "prompt": "List all ACM certificates in this account, including any issued via ACME and any using ECDSA keys. For each, show the domain, key algorithm, and certificate origin.", + "expected_output": "A certificate listing that explicitly includes ACME-origin certificates and ECDSA (EC_prime256v1) certificates by opening up both the CertificateKeyPairOrigins filter (to include ACME) and the Includes.keyTypes filter (to include EC key types), and shows domain, key algorithm, and origin for each certificate.", + "should_trigger": true, + "assertions": [ + "The agent explicitly expanded the CertificateKeyPairOrigins filter to include ACME-origin certificates, or explicitly states it searched for ACME-origin certificates (even if none were found)", + "The agent explicitly expanded the Includes.keyTypes filter to include EC key types such as EC_prime256v1, or explicitly states it searched for ECDSA certificates (even if none were found)", + "Each certificate shows its key algorithm and origin" + ] + }, + { + "id": "acm-risk-classification", + "task_type": "chat", + "prompt": "Run an ACM certificate operations review for this account. For every certificate found, assign a RED, AMBER, or GREEN risk level and explain the basis for each rating, then call out which certificate needs attention first.", + "expected_output": "An ACM certificate review that assigns an explicit RED / AMBER / GREEN risk level to every certificate using the skill's threshold criteria, orders findings by urgency with the single highest-risk certificate identified first, and includes the ACME-origin certificate (tej007.uk) in the assessment rather than only the default RSA certificates.", + "should_trigger": true, + "assertions": [ + "Every certificate is assigned one of the three explicit labels RED, AMBER, or GREEN", + "The single highest-priority certificate is called out first with a stated reason", + "The ACME-origin certificate tej007.uk is included in the risk assessment", + { + "text": "All three risk-level labels use the skill's RED/AMBER/GREEN scheme", + "evaluator": "regex", + "pattern": "RED|AMBER|GREEN" + } + ] + }, + { + "id": "acm-email-validation-deprecation", + "task_type": "chat", + "prompt": "I have an ACM certificate for example.com that was issued using email validation. Is there anything I should be concerned about, and what should I do?", + "expected_output": "The agent flags the certificate as AMBER risk, identifies that ACM will stop issuing email-validated certificates on March 31 2027 and stop renewing them on September 30 2027 due to the CA/B Forum deprecation of email-based domain validation. It recommends switching to DNS validation now using UpdateCertificateOptions, explains that the certificate ARN remains unchanged so no disruption to load balancers or CI/CD, notes the customer has 72 hours to add the CNAME records, and mentions ListCertificateDomainValidations for monitoring. It also correctly notes that ACME-origin and imported/private certificates are out of scope for this migration.", + "should_trigger": true, + "assertions": [ + "The response flags the email-validated certificate as a risk or concern requiring action", + "The response mentions the March 31 2027 deadline for new issuance", + "The response mentions the September 30 2027 deadline for renewals", + "The response recommends UpdateCertificateOptions as the remediation", + "The response states the certificate ARN remains unchanged after switching", + "The response explains that switching to DNS validation does not require reissuing the certificate or changing the ARN" + ] + }, + { + "id": "unrelated-python-script", + "task_type": "chat", + "prompt": "Write a Python script that sorts a list of numbers.", + "should_trigger": false + }, + { + "id": "unrelated-weather", + "task_type": "chat", + "prompt": "What's the weather forecast for Sydney this weekend?", + "should_trigger": false + }, + { + "id": "unrelated-cloudformation", + "task_type": "chat", + "prompt": "Create a CloudFormation template for an S3 bucket.", + "should_trigger": false + } + ] +} diff --git a/skills/acm-certificate-ops-review/evals/files/certificate-context.json b/skills/acm-certificate-ops-review/evals/files/certificate-context.json new file mode 100644 index 0000000..0344de7 --- /dev/null +++ b/skills/acm-certificate-ops-review/evals/files/certificate-context.json @@ -0,0 +1,40 @@ +{ + "certificates": [ + { + "certificateArn": "arn:aws:acm:us-east-1:111122223333:certificate/EXAMPLE-cert-0001", + "domainName": "www.example.com", + "account": "111122223333", + "region": "us-east-1", + "type": "AMAZON_ISSUED", + "status": "ISSUED", + "notAfter": "2026-07-22T00:00:00Z", + "keyAlgorithm": "RSA_2048", + "renewalStatus": "FAILED", + "inUseBy": ["arn:aws:cloudfront::111122223333:distribution/EXAMPLE"] + }, + { + "certificateArn": "arn:aws:acm:eu-west-1:444455556666:certificate/EXAMPLE-cert-0002", + "domainName": "api.example.com", + "account": "444455556666", + "region": "eu-west-1", + "type": "IMPORTED", + "status": "ISSUED", + "notAfter": "2026-08-09T00:00:00Z", + "keyAlgorithm": "RSA_2048", + "renewalStatus": "NOT_ELIGIBLE", + "inUseBy": ["arn:aws:elasticloadbalancing:eu-west-1:444455556666:loadbalancer/app/EXAMPLE/abc"] + }, + { + "certificateArn": "arn:aws:acm:us-east-1:111122223333:certificate/EXAMPLE-cert-0003", + "domainName": "legacy.example.com", + "account": "111122223333", + "region": "us-east-1", + "type": "AMAZON_ISSUED", + "status": "ISSUED", + "notAfter": "2027-01-15T00:00:00Z", + "keyAlgorithm": "RSA_1024", + "renewalStatus": "SUCCESS", + "inUseBy": [] + } + ] +} diff --git a/skills/acm-certificate-ops-review/references/acm-detection-details.md b/skills/acm-certificate-ops-review/references/acm-detection-details.md new file mode 100644 index 0000000..a661f08 --- /dev/null +++ b/skills/acm-certificate-ops-review/references/acm-detection-details.md @@ -0,0 +1,61 @@ +# ACM detection details + +Detailed enumerations and sub-procedures for the certificate inventory and +detection steps. Load this when running Step 1 (inventory) and Step 2 check 7 +(ACME renewal-pipeline verification). + +## ListCertificates filter completeness (Step 1) + +`acm:ListCertificates` silently drops certificates unless the filter is opened +up on two independent axes. Always set both. + +### Key-pair origins + +Include every certificate key-pair origin via the `CertificateKeyPairOrigins` +parameter, which is a separate top-level filter, not inside `Includes`: + +- `AWS_MANAGED` +- `CUSTOMER_PROVIDED` +- `ACME` + +By default, `ListCertificates` excludes ACME-issued certificates. + +### Key types + +Include all key types in the `Includes.keyTypes` filter: + +- `RSA_1024` +- `RSA_2048` +- `RSA_3072` +- `RSA_4096` +- `EC_prime256v1` +- `EC_secp384r1` +- `EC_secp521r1` + +By default, only `RSA_1024` and `RSA_2048` are returned. ACME certs often use +ECDSA (`EC_prime256v1`) and are silently excluded without this. + +Always include every known key type and every known key-pair origin to avoid +missing certificates. Check current ACM docs for any newly added values (for +example post-quantum algorithms). + +## ACME renewal-pipeline sub-checks (Step 2, check 7) + +When ACME-issued certificates are found, run these additional sub-checks to +verify the renewal pipeline is healthy: + +- **7a. ACME endpoint health** - retrieve the ACME endpoint that issued the + cert (endpoint ID is in the cert metadata or `DescribeAcmeEndpoint`). Confirm + it is enabled/active. If disabled or deleted, flag RED - renewals will fail. +- **7b. EAB status** - check if the External Account Binding credential used to + register the ACME account is still valid (not revoked, not expired). Use + `ListAcmeExternalAccountBindings` for the endpoint. If the EAB is revoked or + expired, flag AMBER (existing accounts still work, but no new registrations + possible - note: revoking an EAB does NOT affect already-registered accounts). +- **7c. ACME account status** - check if the registered ACME account is active + or revoked. Use `ListAcmeAccounts` or `DescribeAcmeAccount`. If revoked, flag + RED - this is irreversible, the client can no longer issue or renew certs. + +If the endpoint is disabled OR the account is revoked, override the cert +classification to RED regardless of current expiry date - the renewal pipeline +is broken and the cert will silently expire without renewal. diff --git a/skills/acm-certificate-ops-review/references/acm-thresholds.md b/skills/acm-certificate-ops-review/references/acm-thresholds.md new file mode 100644 index 0000000..27edcc1 --- /dev/null +++ b/skills/acm-certificate-ops-review/references/acm-thresholds.md @@ -0,0 +1,67 @@ +# ACM Thresholds and Risk Levels Reference + +Use these thresholds when detecting issues (SKILL.md Step 2) and when +classifying findings (SKILL.md Step 3). Values reflect common operational +best practice; adjust to a customer's own policy when one is documented. + +## Expiry thresholds (in-use certificates) + +| Days to expiry (`NotAfter` - now) | Risk | +|---|---| +| Already expired | RED | +| <= 14 days | RED | +| 15 - 30 days | AMBER | +| 31 - 45 days | AMBER | +| > 45 days | GREEN | + +For certificates **not** in use (`InUseBy` empty), lower the risk by one level +(RED -> AMBER, AMBER -> GREEN) because there is no live traffic impact, but +still list them as cleanup candidates. + +## Renewal status + +| `RenewalSummary.RenewalStatus` | Risk | Notes | +|---|---|---| +| `FAILED` | RED | Capture `RenewalStatusReason`. | +| `PENDING_VALIDATION` | RED (in use) / AMBER | Domain validation is blocking renewal. | +| `PENDING_AUTO_RENEWAL` (progressing) | GREEN | Normal state ~60 days out. | +| `SUCCESS` | GREEN | | + +## Certificate type + +| Condition | Risk | Recommendation | +|---|---|---| +| `IMPORTED` and in use | AMBER (RED if <= 30 days) | ACM cannot auto-renew imported certs. Move to an ACM-managed (`AMAZON_ISSUED`) certificate where possible, or ensure an external renewal + re-import process exists. | +| `AMAZON_ISSUED` with DNS validation | GREEN | Eligible for managed renewal. | +| `AMAZON_ISSUED` with email validation | AMBER | Email validation does not support fully automated renewal. Recommend switching to DNS validation. | + +## Key algorithm + +| `KeyAlgorithm` | Risk | +|---|---| +| `RSA_1024` | RED (deprecated) | +| `RSA_2048`, `EC_prime256v1`, `EC_secp384r1` and stronger | GREEN | + +## Monitoring + +| Condition | Risk | +|---|---| +| In-use certificate with **no** CloudWatch alarm on `DaysToExpiry` | AMBER | +| In-use certificate with a `DaysToExpiry` alarm | GREEN | + +The ACM expiry metric is `DaysToExpiry` in the `AWS/CertificateManager` +namespace, dimension `CertificateArn`. + +## ACM Private CA + +| Condition | Risk | +|---|---| +| CA `EXPIRED` or `DISABLED` with issued certs still in use | RED | +| CA expiring within 90 days | AMBER | +| CA healthy | GREEN | + +## Overall posture rollup + +- **RED** if any RED finding exists. +- **AMBER** if no RED but one or more AMBER findings. +- **GREEN** only if every finding is GREEN. diff --git a/skills/acm-certificate-ops-review/references/cab-forum-readiness.md b/skills/acm-certificate-ops-review/references/cab-forum-readiness.md new file mode 100644 index 0000000..acbfad2 --- /dev/null +++ b/skills/acm-certificate-ops-review/references/cab-forum-readiness.md @@ -0,0 +1,143 @@ +# CA/Browser Forum Readiness Reference (Phase 2) + +Apply this only when the operator asks about the CA/Browser Forum validity reductions, automation readiness, or migration options for their certificate inventory. It uses the Phase 1 inventory (SKILL.md Steps 1-2) as its input. + +## CRITICAL: All facts are dynamic + +Every factual claim in Phase 2 (pricing, feature support, validity dates, protocol support) MUST be verified against authoritative sources at the time of execution. Do NOT assume or hardcode any of the following: + +- ACM's feature set (it evolves; e.g. ACME support was added July 2026) +- CA/Browser Forum validity dates (ballot updates can shift timelines) +- Which cert types ACM can issue (currently DV only) +- Which services support which cert types (e.g. ACME certs currently cannot be used with AWS integrated services) + +Acceptable sources are ONLY: + +- Official AWS documentation (docs.aws.amazon.com, aws.amazon.com/pricing) +- Official CA/Browser Forum ballots and guidelines (cabforum.org) +- OEM/vendor product documentation and user guides (e.g. digicert.com/docs) +- NOT blogs, third-party articles, community posts, or general web content + +If you cannot verify a fact from an official source at runtime, state that explicitly rather than guessing. + +## Background: the validity reduction timeline + +The CA/Browser Forum has approved progressive reductions to the maximum validity of publicly trusted TLS certificates. As of the last known ballot: + +- 398 days (previous baseline) +- 200 days (effective March 2026) +- 100 days (effective March 2027) +- 47 days (effective March 2029) + +ALWAYS confirm current figures against CA/Browser Forum ballot records and ACM documentation before presenting dates. Timelines can be amended. + +## Step 1: Impact classification + +For each in-use certificate from the Phase 1 inventory, classify automation readiness: + +| Class | Meaning | +| --- | --- | +| GREEN | Fully automated renewal in place. No manual action needed as validity shrinks. | +| AMBER | Partially automated or has a constraint that may require attention (e.g. email validation, ACME cert on a workload that may move to an integrated service). | +| RED | Manual renewal process. Shorter validity directly multiplies operational toil and outage risk. | + +Summarize counts per class. RED items are the migration priority. + +## Step 2: Migration path decision tree + +For each RED or AMBER certificate, determine the correct migration path. This is NOT as simple as "migrate to ACM." The decision depends on cert type and usage: + +### Decision logic + +``` +Is the imported certificate DV (domain-validated)? + | + +-- NO (OV or EV) --> CANNOT migrate to ACM-issued. + | ACM only issues DV certificates. + | Recommendation: keep on external CA. + | Check if the external CA supports ACME or other automation + | to reduce manual renewal toil. + | + +-- YES (DV) --> Is it used with an AWS integrated service? + | (ALB, CloudFront, API Gateway, Elastic Beanstalk, etc.) + | + +-- YES --> Migrate to ACM-managed certificate with DNS validation. + | (ACM handles renewal automatically for integrated services. + | ACME-issued certs CANNOT be used with integrated services + | per current ACM docs.) + | + +-- NO (self-managed: EC2, ECS, K8s, on-prem, multi-cloud) + --> Two automation paths (verify current docs for each): + | + +-- Option A: ACM ACME endpoint (recommended if an ACME client + | can run on the workload) + | Use Certbot, cert-manager, acme.sh, or other ACMEv2 client. + | ACME certs have a fixed short validity (currently 45 days) + | which is already at or below the 2029 CA/B target - no + | further adjustment needed when validity rules tighten. + | Works with any DNS provider (Route 53 not required). + | Ref: docs.aws.amazon.com/acm/latest/userguide/acm-acme.html + | + +-- Option B: AWS Workload Credentials Provider (if ACME client + cannot be installed, or exportable private key is required) + ACM issues an exportable cert (validity follows current CA/B + maximum - verify at runtime, it decreases over time). The + provider agent runs on the host (EC2 or on-prem), exports the + cert every 24h, writes to disk, and reloads the service. + ACM handles renewal centrally; the provider picks up new certs + automatically. Supports Linux (systemd) and Windows. + Ref: docs.aws.amazon.com/acm/latest/userguide/acm-certificate-automation.html + +``` + +### OV/EV certificates (cannot migrate) + +For OV/EV certs that must remain on an external CA: + +- Check if the external CA supports automated renewal (ACME, SCEP, REST API). +- If yes, recommend the operator implement that automation to reduce toil. +- If no, flag as a persistent manual-renewal risk that scales with shorter validity. Recommend evaluating whether the OV/EV requirement is regulatory (hard constraint) or preference (may be revisitable). +- In either case, ensure a `DaysToExpiry` CloudWatch alarm exists. + +## Step 3: Gap identification (operator-focused) + +Identify gaps that create operational risk as validity shrinks: + +- **Imported DV certs on integrated services** - these should have been ACM-managed all along. Straightforward migration, highest ROI. +- **Imported DV certs on self-managed workloads without ACME** - these need ACME client setup or another automation mechanism. +- **OV/EV certs with no automation** - persistent risk. Quantify: "N certs will need manual renewal every X days by 2029." +- **Email-validated ACM certs** - renewal requires human action on the approval email. Recommend switching to DNS validation. +- **Missing expiry monitoring** - any in-use cert without a `DaysToExpiry` alarm is blind to approaching expiry. + +## Step 4: Readiness summary + +Produce a concise operator-focused summary: + +1. Total certs scanned and readiness split (GREEN / AMBER / RED counts). +2. Top migration candidates (DV imported certs that can move to ACM). +3. Certs that cannot migrate and their automation status. +4. Concrete next actions ordered by risk reduction. + +Do NOT produce: + +- Detailed competitor commercial comparison tables +- Multi-year cost projection spreadsheets +- Customer-facing talking points or slide content +- Provider pricing model analysis + +Keep the output actionable for an operator, not a strategic advisory document. + +## Authoritative sources (official documentation ONLY) + +Only cite from these categories. Never cite blogs, re:Post articles, community posts, Medium, or third-party aggregators. + +- ACM What's New: [https://aws.amazon.com/about-aws/whats-new/](https://aws.amazon.com/about-aws/whats-new/) (filter by ACM) +- ACM ACME docs: [https://docs.aws.amazon.com/acm/latest/userguide/acm-acme.html](https://docs.aws.amazon.com/acm/latest/userguide/acm-acme.html) +- ACM pricing: [https://aws.amazon.com/certificate-manager/pricing/](https://aws.amazon.com/certificate-manager/pricing/) +- ACM best practices: [https://docs.aws.amazon.com/acm/latest/userguide/acm-bestpractices.html](https://docs.aws.amazon.com/acm/latest/userguide/acm-bestpractices.html) +- ACM certificate characteristics: [https://docs.aws.amazon.com/acm/latest/userguide/acm-certificate-characteristics.html](https://docs.aws.amazon.com/acm/latest/userguide/acm-certificate-characteristics.html) +- ACM integrated services: [https://docs.aws.amazon.com/acm/latest/userguide/acm-services.html](https://docs.aws.amazon.com/acm/latest/userguide/acm-services.html) +- ACM certificate automation: [https://docs.aws.amazon.com/acm/latest/userguide/acm-certificate-automation.html](https://docs.aws.amazon.com/acm/latest/userguide/acm-certificate-automation.html) +- AWS Workload Credentials Provider: [https://github.com/aws/aws-workload-credentials-provider](https://github.com/aws/aws-workload-credentials-provider) +- CA/Browser Forum ballots: [https://cabforum.org/working-groups/server/ballots/](https://cabforum.org/working-groups/server/ballots/) + diff --git a/skills/acm-certificate-ops-review/references/report-format.md b/skills/acm-certificate-ops-review/references/report-format.md new file mode 100644 index 0000000..8bd6fd1 --- /dev/null +++ b/skills/acm-certificate-ops-review/references/report-format.md @@ -0,0 +1,52 @@ +# ACM Findings Report Format Reference + +Use this layout for the report produced in SKILL.md Step 4. + +## 1. Executive summary + +One short paragraph: + +- Overall posture: RED / AMBER / GREEN (see rollup in `acm-thresholds.md`). +- Count of certificates scanned, and counts by risk level. +- The single most urgent item and its deadline. +- Scope covered (accounts, regions), and any accounts skipped + (`AccessDenied`, throttled). + +## 2. Prioritized findings table + +Sort by risk (RED first), then in-use before unused, then ascending days to +expiry. + +| Account | Region | Certificate / Domain | Type | Status | Days to expiry | In use | Risk | Recommendation | +|---|---|---|---|---|---|---|---|---| +| 1111... | us-east-1 | www.example.com | AMAZON_ISSUED | ISSUED | 9 | Yes | RED | Renewal FAILED - fix DNS CNAME, then re-validate | +| 4444... | eu-west-1 | api.example.com | IMPORTED | ISSUED | 27 | Yes | RED | Imported cert cannot auto-renew - migrate to ACM-managed | + +Include the certificate ARN in a detail section or as a tooltip/footnote +rather than in the main row, to keep the table readable. + +## 3. Remediation list + +Ordered by priority. For each item: what to do, which certificate/account it +applies to, and the AWS action or console path involved. Example ordering: + +1. Certificates expired or expiring within 14 days and in use. +2. Failed or stuck renewals (fix validation, then renewal proceeds). +3. Imported in-use certificates without a renewal path. +4. Weak-key certificates. +5. In-use certificates missing a `DaysToExpiry` alarm. +6. Unused certificates to clean up. + +## 4. Disclaimer + +End the report with an AI-generated-content disclaimer, for example: + +> This report was generated with AI assistance from ACM and CloudWatch data at +> the time of the scan. Validate findings against the live environment before +> acting. + +## Formatting notes + +- Every number must be computed from retrieved values, never estimated. +- If an interactive HTML dashboard is requested, mirror the same sections and + the same risk color coding (RED / AMBER / GREEN).