TLS Certificate Validation Failure Recovery Prompt

This prompt is a diagnostic and corrective tool for security engineers and SRE teams who need to resolve TLS certificate validation failures in production or staging environments. It is designed to be embedded inside an automated remediation harness or a security operations copilot. The primary job-to-be-done is to ingest raw certificate data, chain information, and the specific OpenSSL or client error output, then produce a structured diagnosis and a corrected certificate configuration block. Use this prompt when a connection fails with errors such as 'certificate verify failed', 'hostname mismatch', 'self-signed certificate in chain', or 'certificate has expired'. The prompt assumes you already have access to the failing endpoint, the certificate bundle, and the exact error message from the client or OpenSSL command.

The ideal user is an engineer who understands TLS fundamentals but needs to accelerate root-cause analysis and correction under incident pressure. You must provide the prompt with the raw certificate text (PEM-encoded), the full certificate chain as presented by the server, and the verbatim error output from openssl s_client -connect, curl -v, or your application logs. The prompt is not a substitute for a PKI design workshop. Do not use this prompt for initial certificate generation, designing a certificate authority hierarchy from scratch, or performing cryptographic algorithm selection for a new system. It is a recovery and correction tool, not a greenfield design assistant.

Before invoking this prompt, confirm that you have captured the complete certificate chain and the exact error message. A partial error log or a truncated certificate will lead to an incomplete or incorrect diagnosis. The prompt is most effective when the failure is reproducible and the error message is unambiguous. If the failure is intermittent—caused by network flakiness, load balancer timeouts, or client-side clock skew—this prompt may misattribute the root cause to a certificate misconfiguration. In those cases, rule out transient infrastructure issues before using the prompt.

The output of this prompt is a structured JSON object containing a diagnosis summary, the specific validation failure type, and a corrected certificate configuration block. The corrected configuration may include a revised certificate bundle, updated SAN entries, or a reordered chain. Because the output may be applied directly to production endpoints, you must validate the corrected configuration in a staging environment before deployment. The prompt does not replace your change management process; it accelerates the analysis and drafting phase. Always review the suggested configuration for alignment with your organization's certificate policies, key protection requirements, and compliance obligations.

This prompt template is designed to be pasted directly into your AI harness for TLS certificate validation failure recovery. It instructs the model to act as a senior security engineer, analyze the provided certificate chain and OpenSSL error output, and produce a corrected certificate configuration. The template uses square-bracket placeholders for all dynamic inputs, allowing you to inject the specific error context, certificate bundle, and operational constraints for each incident.

textCopy
You are a senior TLS security engineer. Your task is to diagnose a TLS certificate validation failure and produce a corrected certificate configuration.

## INPUT
- OpenSSL Error Output:
[OPENSSL_ERROR_OUTPUT]

- Certificate Bundle (PEM format):
[CERTIFICATE_BUNDLE]

- Target Hostname:
[TARGET_HOSTNAME]

- Port:
[PORT]

## CONSTRAINTS
- [CONSTRAINTS]

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "diagnosis": {
    "failure_type": "string (e.g., 'hostname_mismatch', 'expired_certificate', 'incomplete_chain', 'untrusted_root', 'revoked_certificate', 'weak_cipher', 'protocol_mismatch')",
    "summary": "string (concise explanation of the failure)",
    "affected_certificate": "string (subject CN or SAN of the problematic cert)"
  },
  "remediation": {
    "action": "string (e.g., 'replace_certificate', 'add_intermediate', 'update_trust_store', 'correct_san', 'renew_certificate')",
    "corrected_certificate_pem": "string (the corrected certificate or chain in PEM format, if applicable)",
    "configuration_changes": [
      {
        "file_path": "string",
        "key": "string",
        "old_value": "string",
        "new_value": "string"
      }
    ],
    "verification_command": "string (the OpenSSL command to verify the fix)"
  },
  "risk_assessment": {
    "severity": "string (low, medium, high, critical)",
    "requires_human_review": boolean,
    "downtime_required": boolean
  }
}

## INSTRUCTIONS
1. Parse the OpenSSL error output to identify the exact failure mode.
2. Inspect the certificate bundle for chain completeness, expiry dates, SAN entries, and signature algorithms.
3. Cross-reference the SAN entries and CN against the target hostname.
4. If the failure is a hostname mismatch, suggest the correct certificate or SAN update.
5. If the chain is incomplete, identify the missing intermediate and construct the full chain.
6. If the certificate is expired, note the expiry date and recommend renewal.
7. If the root is untrusted, identify which trust store needs updating.
8. Always include a verification command that can be run to confirm the fix.
9. Flag any remediation that requires human review, especially for production certificate replacement or trust store modification.
10. Do not generate private keys. Only work with public certificates and chains.

To adapt this template for your environment, replace the square-bracket placeholders with actual values from your incident context. The [OPENSSL_ERROR_OUTPUT] should contain the raw stderr from your openssl s_client -connect or validation command. The [CERTIFICATE_BUNDLE] should include the full PEM-encoded certificate chain being validated. Use [CONSTRAINTS] to specify operational boundaries such as 'no production changes without change approval' or 'prefer updating the trust store over replacing certificates.' After receiving the model output, always validate the corrected_certificate_pem field by running the provided verification_command in a sandboxed environment before applying any changes. For high-severity or production remediation actions, route the output through a human approval step as indicated by the requires_human_review flag.

This prompt is designed to be called after a TLS handshake failure is detected by your monitoring or deployment system. The harness should capture the full OpenSSL error output (e.g., openssl s_client -connect host:port), the certificate chain as returned by the server, and the intended hostname. Do not pass raw certificate files directly; instead, extract the text output of openssl x509 -text for each certificate in the chain. The prompt expects these three inputs—[ERROR_OUTPUT], [CERTIFICATE_CHAIN_TEXT], and [TARGET_HOSTNAME]—to be assembled into a single structured context block before invocation.

Wire the prompt into a retry loop with a hard limit of three attempts. After each response, parse the suggested certificate configuration from the model's output. Validate the proposed certificate against the original error using a scripted check: re-run openssl verify -CAfile <suggested_chain> and confirm that the SAN field matches [TARGET_HOSTNAME]. If validation passes, apply the configuration and re-test the TLS handshake. If validation fails or the handshake still errors, feed the new error output back into the prompt as [ERROR_OUTPUT] for the next retry attempt. Log every attempt, the model's raw output, and the validation result for auditability.

For model choice, prefer a model with strong instruction-following and structured output capabilities, such as gpt-4o or claude-3.5-sonnet. Set the temperature low (0.1–0.2) to reduce variability in configuration suggestions. The prompt should be called with a tool definition that enforces the output schema, requiring fields for certificate_configuration, root_cause, and verification_steps. If the model cannot produce a valid configuration after three retries, escalate to a human operator via your incident management system, attaching the full log of attempts and the original error context. Never automatically apply a certificate configuration that fails openssl verify or SAN matching.

Avoid running this prompt in environments where the certificate chain contains sensitive private key material. The harness should strip any private key data from [CERTIFICATE_CHAIN_TEXT] before sending it to the model. If the recovery requires generating a new private key or CSR, the prompt can suggest the command, but the harness must execute key generation locally and never transmit private keys to the model API.