diff --git a/llms.txt b/llms.txt index f106887..7e55a1e 100644 --- a/llms.txt +++ b/llms.txt @@ -22,7 +22,7 @@ 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 ## Key Concepts - AWS DevOps Agent skills are structured instruction sets that teach the agent how to investigate specific operational scenarios 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..e0999a7 --- /dev/null +++ b/skills/acm-certificate-ops-review/CHANGELOG.md @@ -0,0 +1,20 @@ +# 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.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..a0c4254 --- /dev/null +++ b/skills/acm-certificate-ops-review/README.md @@ -0,0 +1,111 @@ +# 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 and reports (for example "review the ACM + certificate posture for account 1111..."). +- **Incident RCA** and **Incident Triage** - certificate-related incidents (for + example "investigate why example.com is serving an expired certificate"). + +Select these agent types 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: + +**Chat tasks** +- "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?" + +**Incident RCA / Incident Triage** +- "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." + +## 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..cf7fbf7 --- /dev/null +++ b/skills/acm-certificate-ops-review/SKILL.md @@ -0,0 +1,187 @@ +--- +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.0.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).** + See `references/cab-forum-readiness.md`. + +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. +2. For each certificate ARN, call `acm:DescribeCertificate` to retrieve + `Status`, `NotAfter`, `NotBefore`, `Type` (`AMAZON_ISSUED` vs `IMPORTED`), + `RenewalEligibility`, `RenewalSummary`, `KeyAlgorithm`, `InUseBy`, + `DomainValidationOptions`, and `SubjectAlternativeNames`. +3. For imported certificates, `InUseBy` and `NotAfter` are still available; + note that ACM cannot auto-renew imported certificates. +4. 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. Use the thresholds and +risk levels in `references/acm-thresholds.md`. + +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. **Imported certificates in use** - flag `Type = IMPORTED` with a non-empty + `InUseBy`, since these will not auto-renew and are an outage risk. +5. **Weak or legacy keys** - flag `KeyAlgorithm` of `RSA_1024` (and any + algorithm below current best practice). +6. **Unused certificates** - flag issued certificates with an empty `InUseBy` + as cleanup or cost-optimization candidates (do not auto-delete). +7. **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. +8. **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. +9. **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) using the criteria in +`references/acm-thresholds.md`. 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 + +Generate a prioritized findings report using the structure in +`references/report-format.md`. 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 (optional): CA/Browser Forum readiness + +If the operator asks about the CA/Browser Forum validity reductions, strategic +posture, renewal automation readiness, DV vs OV/EV strategy, or cost impact, +continue with the procedure in `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..a91abff --- /dev/null +++ b/skills/acm-certificate-ops-review/evals/evals.json @@ -0,0 +1,59 @@ +[ + { + "id": "acm-review-smoke-test", + "prompt": "Read certificate-context.json. List each certificate's domain name, type (AMAZON_ISSUED or IMPORTED), status, region, and account. No analysis needed.", + "expected_output": "Lists every certificate from files/certificate-context.json with its domain name, type, status, region, and account exactly as defined in the file.", + "files": ["files/certificate-context.json"], + "assertions": [ + "matches regex /[a-z]{2}-[a-z]+-\\d/", + "matches regex /\\b\\d{12}\\b/", + "contains 'AMAZON_ISSUED'", + "contains 'IMPORTED'", + "contains 'account'" + ] + }, + { + "id": "acm-review-highest-risk-identification", + "prompt": "Read certificate-context.json. Identify which certificate is the highest operational risk and briefly explain why. Do not run a full audit.", + "expected_output": "Identifies www.example.com (renewal FAILED, in use on a CloudFront distribution, expiring within ~14 days) as the highest risk, referencing its failed renewal and in-use status.", + "files": ["files/certificate-context.json"], + "assertions": [ + "contains 'www.example.com'", + "contains 'FAILED' or contains 'failed' or contains 'renewal'", + "contains 'in use' or contains 'in-use' or contains 'CloudFront'" + ] + }, + { + "id": "acm-review-data-source-priority", + "prompt": "According to the skill, which AWS APIs does the ACM certificate operations review use to collect data? Name at least three specific API calls the skill mentions. No AWS access required.", + "expected_output": "States the skill uses ACM, ACM Private CA, and CloudWatch APIs. Names specific calls such as acm:ListCertificates, acm:DescribeCertificate, acm-pca:DescribeCertificateAuthority, or cloudwatch:DescribeAlarmsForMetric.", + "files": [], + "assertions": [ + "contains 'acm:ListCertificates' or contains 'ListCertificates'", + "contains 'acm:DescribeCertificate' or contains 'DescribeCertificate'", + "contains 'DescribeAlarmsForMetric' or contains 'CloudWatch' or contains 'cloudwatch'" + ] + }, + { + "id": "acm-review-risk-levels", + "prompt": "List the risk levels the skill uses to classify certificate findings, in order from most to least urgent. No AWS access required.", + "expected_output": "Lists RED, AMBER, GREEN in that order.", + "files": [], + "assertions": [ + "contains 'RED'", + "contains 'AMBER'", + "contains 'GREEN'" + ] + }, + { + "id": "acm-review-cab-timeline", + "prompt": "According to the skill, what is the CA/Browser Forum TLS certificate validity reduction timeline, and what is the final target and date? No AWS access required.", + "expected_output": "Describes the progressive reduction (398 to 198 to 100 to 47 days) with the final target of 47 days by March 2029.", + "files": [], + "assertions": [ + "contains '47'", + "contains '2029'", + "contains '398' or contains 'validity'" + ] + } +] 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..0f1e401 --- /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/aaaa1111-bbbb-2222-cccc-333344445555", + "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/E1ABCDEF2GHIJ"] + }, + { + "certificateArn": "arn:aws:acm:eu-west-1:444455556666:certificate/dddd4444-eeee-5555-ffff-666677778888", + "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/prod-alb/abc123"] + }, + { + "certificateArn": "arn:aws:acm:us-east-1:111122223333:certificate/9999aaaa-8888-bbbb-7777-cccc6666dddd", + "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-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..1dda858 --- /dev/null +++ b/skills/acm-certificate-ops-review/references/cab-forum-readiness.md @@ -0,0 +1,146 @@ +# 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) + --> Migrate to ACM ACME endpoint. + (Use Certbot, cert-manager, acme.sh, or other ACMEv2 client. + Note: ACME certs have 45-day validity, verify current docs.) +``` + +### 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/ (filter by ACM) +- ACM ACME docs: https://docs.aws.amazon.com/acm/latest/userguide/acm-acme.html +- ACM pricing: https://aws.amazon.com/certificate-manager/pricing/ +- ACM best practices: + 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 +- ACM integrated services: + 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 +- AWS Workload Credentials Provider: + https://github.com/aws/aws-workload-credentials-provider +- CA/Browser Forum 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).