/ssllabs/assessments

POST /api/ssllabs/assessments

Price: 5 credits

Run the SSL Labs TLS assessment for a host and return its full security report

How to use it

Assess the TLS / SSL configuration of a host (the Qualys SSL Server Test). Returns, per server endpoint (IP), the letter grade (A+ down to F, plus the trust-ignored grade), the supported TLS protocol versions and cipher suites, a full battery of vulnerability checks (Heartbleed, POODLE, FREAK, Logjam, DROWN, BEAST, Bleichenbacher, Ticketbleed, RC4, insecure renegotiation, etc.), HSTS policy, forward secrecy, OCSP stapling, handshake simulations for many client platforms, and the full certificate chain (subject, SANs, issuer, signature & key algorithm, key size, validity dates, fingerprints and PEM). Accepts a bare domain or a URL. Results are returned from a recent cache by default; set start_new to force a fresh live test.

Parameters

• access-token string required

Request body

• timeout integer — Max scrapping execution timeout (in seconds) (default: 600; min: 20; max: 1500)
• host string required — Hostname to assess (a bare domain or a URL — scheme, path and port are stripped) (examples: "github.com", "cloudflare.com", "www.ssllabs.com"; minLength: 1)
• from_cache boolean — Return a recently cached assessment when available instead of testing live (default: true)
• max_age integer nullable — Maximum age of a cached assessment in hours; older results are re-tested (min: 1)
• start_new boolean — Force a brand-new live assessment, ignoring any cached result (default: false)
• ignore_mismatch boolean — Continue assessing even when the certificate name does not match the host (default: false)
• publish boolean — Publish the result on the public SSL Labs boards (default: false)

Response

• @type string (default: "SsllabsAssessment")
• host string nullable
• port integer nullable
• protocol string nullable
• is_public boolean nullable
• status string nullable
• started_at integer nullable
• tested_at integer nullable
• engine_version string nullable
• criteria_version string nullable
• endpoints array (default: [])
  • @type string (default: "SsllabsEndpoint")
  • ip_address string nullable
  • server_name string nullable
  • status_message string nullable
  • grade string nullable
  • grade_trust_ignored string nullable
  • future_grade string nullable
  • has_warnings boolean nullable
  • is_exceptional boolean nullable
  • progress integer nullable
  • duration integer nullable
  • delegation integer nullable
  • details object nullable
    • @type string (default: "SsllabsEndpointDetails")
    • protocols array (default: [])
    • cipher_suites array (default: [])
    • named_groups array (default: [])
    • server_signature string nullable
    • prefix_delegation boolean nullable
    • non_prefix_delegation boolean nullable
    • reneg_support integer nullable
    • session_resumption integer nullable
    • session_tickets integer nullable
    • compression_methods integer nullable
    • supports_npn boolean nullable
    • supports_alpn boolean nullable
    • alpn_protocols string nullable
    • supports_aead boolean nullable
    • supports_cbc boolean nullable
    • chacha20_preference boolean nullable
    • forward_secrecy integer nullable
    • protocol_intolerance integer nullable
    • misc_intolerance integer nullable
    • has_sct integer nullable
    • ocsp_stapling boolean nullable
    • sni_required boolean nullable
    • http_status_code integer nullable
    • implements_tls13_mandatory_cs boolean nullable
    • zero_rtt_enabled integer nullable
    • hsts_policy object nullable
      • @type string (default: "SsllabsHstsPolicy")
      • status string nullable
      • max_age integer nullable
      • include_sub_domains boolean nullable
      • preload boolean nullable
      • header string nullable
    • hpkp_status string nullable
    • vulnerabilities object nullable
      • @type string (default: "SsllabsVulnerabilities")
      • beast boolean nullable
      • heartbleed boolean nullable
      • heartbeat boolean nullable
      • open_ssl_ccs integer nullable
      • open_ssl_lucky_minus20 integer nullable
      • ticketbleed integer nullable
      • bleichenbacher integer nullable
      • zombie_poodle integer nullable
      • golden_doodle integer nullable
      • zero_length_padding_oracle integer nullable
      • sleeping_poodle integer nullable
      • poodle boolean nullable
      • poodle_tls integer nullable
      • fallback_scsv boolean nullable
      • freak boolean nullable
      • logjam boolean nullable
      • dh_uses_known_primes integer nullable
      • dh_ys_reuse boolean nullable
      • drown_vulnerable boolean nullable
      • ecdh_parameter_reuse boolean nullable
      • supports_rc4 boolean nullable
      • rc4_only boolean nullable
      • rc4_with_modern boolean nullable
    • sims array (default: [])
    • cert_chains array (default: [])
• certs array (default: [])
  • @type string (default: "SsllabsCert")
  • id string nullable
  • subject string nullable
  • serial_number string nullable
  • common_names array (default: [])
  • alt_names array (default: [])
  • not_before integer nullable
  • not_after integer nullable
  • issuer_subject string nullable
  • sig_alg string nullable
  • key_alg string nullable
  • key_size integer nullable
  • key_strength integer nullable
  • is_key_known_debian_insecure boolean nullable
  • sha1_hash string nullable
  • sha256_hash string nullable
  • pin_sha256 string nullable
  • must_staple boolean nullable
  • revocation_status integer nullable
  • crl_revocation_status integer nullable
  • ocsp_revocation_status integer nullable
  • revocation_info integer nullable
  • ocsp_uris array (default: [])
  • crl_uris array (default: [])
  • issues integer nullable
  • sct boolean nullable
  • raw string nullable

Errors

• 422 — The request body did not validate Check the fields against this schema. A URN with the wrong prefix is the most common cause.
• 408 — The request ran past its time limit Raise `timeout` in the request body, up to the maximum this endpoint documents. Lowering `count` or turning off the `with_*` flags also helps, because less work finishes sooner.
• 412 — Host could not be assessed (unable to resolve the domain or no secure endpoint) Retrying will not help: either the entity does not exist, or the input points at a different one.
• 429 — Too many requests: a rate limit or a usage window is exhausted When the response carries an X-Retry-After header, wait that many seconds and retry: the same number is in the body as `detail.retry_after`, and the limit clears once that window passes. The message in the body names the limit that was hit.
• 500 — Something broke on our side Retrying will not help. If it keeps happening, send us the X-Request-ID from the response headers.
• 529 — Rate limit reached, or the endpoint is overloaded Wait at least 30 seconds, then retry.

Response headers

• X-Error — Error message text (present only on error)
• X-Request-ID — Unique request identifier
• X-Execution-Time — Execution time in seconds
• X-Result-Count — How many records the body carries. 0 means an empty result, which is a normal answer and not by itself an error. A non-zero count can come back together with X-Error when the failure happened partway through — read this header and X-Error independently.
• X-Total-Available-Results — How many records exist for this query, when the endpoint can say. On a `dry_run` request this is the answer and the body is empty. It saturates: the endpoint's documented maximum means 'at least that many', any smaller number is exact.
• X-Warning — Present when the request body carried keys this endpoint does not document. They were ignored, so any filter you meant to apply through them did not apply. Check the spelling against this schema and retry.
• X-Retry-After — Seconds to wait before retrying. Present only on 429.