TLS Certificate Diagnosis

Diagnose TLS/SSL certificate problems for a user-provided domain: certificate not trusted, hostname/SAN mismatch, expiration issues, and HTTPS access failures. The check flow resolves DNS, tests TCP connectivity, then verifies the certificate trust chain, hostname match, and validity period. When a check fails, a network pre-check and DNS diagnosis run automatically to pinpoint the root cause.

Module Index

| Module | Purpose | File | |--------|---------|------| | DNS Diagnosis | DNS status codes and diagnostic commands | references/dns_diagnosis.md | | Prerequisites | System dependencies, OS compatibility, CA certificate setup | references/prerequisites.md | | Output Schema | Formal JSON Schema for script output | references/output_schema.md |

Load references on demand. Do not read all reference files unless the task requires them.

User Confirmation

• Before running any check, confirm the target domain with the user.
• If the user has not provided a domain, ask for it first. Never guess, derive, or scan for domains on your own.
• If you obtain the domain from task context rather than directly from the user, state the domain and its source explicitly before running any check.

Execution Principle

MANDATORY:

• Read-only: this skill only inspects and reports. It performs no write operations and requires no credentials of any kind.
• Single entry point: all checks MUST be executed through the entry script scripts/check_tls.py. Do not hand-assemble diagnostic command chains.
• User-provided targets only: only check domains the user explicitly provides.
• No scanning: never scan, sweep, or probe unknown or unspecified addresses.

Commands

Set the skill directory once, then run the entry script:

SKILL_DIR=~/.qoderwork/skills/alibabacloud-tls-cert-diagnosis

Single Domain

cd $SKILL_DIR && python3 scripts/check_tls.py example.com --pretty

Custom Port

cd $SKILL_DIR && python3 scripts/check_tls.py example.com --port 8443 --pretty

Batch Check

Create a file with one domain per line (lines starting with # are ignored), then run:

cd $SKILL_DIR && python3 scripts/check_tls.py --file domains.txt --pretty

Capabilities

| # | Capability | Description | |---|-----------|-------------| | C1 | Single-Domain Full-Chain Check | DNS resolution -> TCP connectivity -> trust chain verification, hostname/SAN matching, expiration check | | C2 | Abnormal Certificate Diagnosis | Detect and report certificate expired, certificate not trusted, and hostname mismatch, with the specific reason for each issue | | C3 | DNS Failure Root-Cause Diagnosis | When a check fails, classify the DNS failure (NXDOMAIN / SERVFAIL / REFUSED / TIMEOUT / CNAME-only) per references/dns_diagnosis.md | | C4 | Custom Port Check | Check a TLS endpoint on a non-default port via --port | | C5 | Batch Check | Check multiple domains from a file via --file, one domain per line | | C6 | Structured JSON Output | Machine-readable JSON result per references/output_schema.md |

Platform-specific tool selection (macOS / Linux / Windows) and CA bundle paths are handled automatically by the entry script; see references/prerequisites.md for details.

Check Flow

Domain input
    |
    v
Run certificate check (openssl s_client)
    |
    +-- OK  -> output cert details (trust / hostname match / expiry)
    |
    +-- FAIL -> run network pre-check (nc on macOS, telnet on Linux, Test-NetConnection on Windows)
              |
              +-- if DNS fails -> run dig / nslookup DNS diagnosis
                    |
                    +-- NXDOMAIN: domain does not exist
                    +-- SERVFAIL: DNS server failure
                    +-- REFUSED:  DNS query refused
                    +-- TIMEOUT:  DNS server no response
                    +-- NOERROR no A record: only CNAME, follow CNAME chain

Output Format

Human-Readable Summary

Normal Certificate

Domain       : example.com
Port         : 443
Status       : OK
  Trust      : trusted
  Hostname   : match
  Validity   : 2025-01-15 ~ 2026-01-15
  Days left  : 245
  Issuer     : DigiCert TLS RSA SHA256 2020 CA1
  Subject    : CN=www.example.org
  SAN        : www.example.org, example.org, example.com, www.example.com

Abnormal Certificate

Domain       : expired.example.com
Port         : 443
Status       : abnormal (3 issues)
  Trust      : trusted
  Hostname   : mismatch
  Validity   : 2023-01-15 ~ 2024-01-15
  Days left  : expired 134 days
  Issuer     : Let's Encrypt R3
  Issues     :
    - certificate expired
    - verification failed: certificate has expired
    - hostname mismatch: SAN does not contain target domain

Network Unreachable (with DNS diagnosis)

Domain       : nonexistent.example.com
Port         : 443
Status       : abnormal (1 issue)
  Network    : unreachable
  Issue      : network unreachable - TCP connection failed;
               dig: domain does not exist (NXDOMAIN)

JSON Output

The entry script outputs JSON. See references/output_schema.md for the formal schema.

Check Items

| Check Item | Description | On Failure | |-----------|-------------|-----------| | DNS Resolve | Query A / AAAA records | Report NXDOMAIN / SERVFAIL / REFUSED / TIMEOUT | | TCP Reachable | Test port connectivity on resolved IPs | Report connection failure reason | | TLS Handshake | Fetch server certificate | Report "no certificate received" | | Trust Chain | Verify certificate chain against system CA bundle | Verify code 0 = trusted; otherwise report error | | Hostname Match | Match domain against certificate SAN (wildcard restricted to one level) | Report mismatch | | Expiry | Parse notBefore / notAfter | Report expired or not yet valid |

Examples

Example 1: User: "My browser says the certificate for shop.myshop.com is not trusted, please check it."

cd $SKILL_DIR && python3 scripts/check_tls.py shop.myshop.com --pretty

Example 2: User: "Our API runs TLS on port 8443, can you verify the certificate expires soon?"

cd $SKILL_DIR && python3 scripts/check_tls.py api.example.com --port 8443 --pretty

Example 3: User: "Check the certificates for all domains in this list file."

cd $SKILL_DIR && python3 scripts/check_tls.py --file domains.txt --pretty

Notes

• Supports macOS, Linux, and Windows 10/11. On Windows, the script uses nslookup for DNS, PowerShell Test-NetConnection for TCP, and openssl (requires standalone OpenSSL for Windows). Windows CA auto-detection checks the OpenSSL-Win64 install path.
• Rely on system binaries. macOS/Linux use openssl, dig, nc, and telnet. Windows uses openssl, nslookup, and PowerShell Test-NetConnection. No external Python libraries are required.
• Only checks domains explicitly provided by the user; never probes unknown or unspecified addresses. This prevents accidental scanning of internal networks without explicit user intent.
• Set a default timeout of 5 seconds per domain. This balances between waiting for slow responses and failing fast on unreachable targets. Increase with --timeout-ms for high-latency networks.
• Match wildcard certificates *.example.com against only one-level subdomains (e.g. a.example.com). Reject multi-level matches (e.g. a.b.example.com). This follows RFC 6125 Section 6.4.3, which restricts wildcard certificates to a single label to prevent overly broad matching that could violate the subscriber's intended scope.
• If DNS returns only a CNAME with no A record, follow the CNAME chain recursively until finding the final A record IP. Some domains (e.g. CDN fronted domains) resolve through multiple CNAME hops. Stopping at the first CNAME would produce no IP and a false negative, so recursive resolution is required for accurate diagnosis.