SSL/TLS Security Analyzer API

Snapshot from RAPID_README.md for source API version 0.0.2. This is source documentation, not evidence that an upstream is deployed.

Endpoint 1: GET /status

Description

Health check endpoint. Returns the service status, version, whether openssl is available, the Python runtime version, server time, and uptime. Makes zero network calls — instant and free.

Parameters

Example Request

GET /status

Response (200 OK)

{
  "status": "ok",
  "service": "SSL/TLS Security Analyzer API",
  "version": "0.0.2",
  "uptime_seconds": 42,
  "openssl_available": true,
  "python_version": "3.14.5",
  "server_time": "2026-08-26T10:00:00.000000+00:00"
}

Source contract imported from ssl:tls analyzer/app.py. Handler: status. Reference: RAPID_README.md.

Snapshot from RAPID_README.md for source API version 0.0.2. This is source documentation, not evidence that an upstream is deployed.

Endpoint 2: GET/POST /analyze

Description

Flagship endpoint. Performs a comprehensive SSL/TLS security analysis of any hostname or IP address. Returns supported TLS protocol versions, all negotiated cipher suites, weak cipher detection, full parsed certificate details, certificate chain validation, hostname match verification, forward secrecy check, weak Diffie-Hellman detection, known vulnerability flags, and an overall letter grade from A to F. The grade uses a score-based heuristic with a transparent breakdown of every deduction in grade_notes.

Query Parameters (GET)

Request Body (POST)

{
  "domain": "example.com",
  "port": 443,
  "timeout": 5
}

Example GET Request

/analyze?domain=example.com

Example POST Request

POST /analyze
Content-Type: application/json

{
  "domain": "example.com",
  "port": 443,
  "timeout": 5
}

Response (200 OK)

{
  "domain": "example.com",
  "port": 443,
  "ssl_grade": "A",
  "grade_notes": [],
  "tls_versions": ["TLSv1.2"],
  "protocols": ["TLSv1.2"],
  "best_protocol": "TLSv1.2",
  "negotiated_cipher": "ECDHE-RSA-AES128-GCM-SHA256",
  "forward_secrecy": true,
  "cipher_list": [
    "ECDHE-RSA-AES128-GCM-SHA256",
    "ECDHE-RSA-AES256-GCM-SHA384"
  ],
  "weak_ciphers": [],
  "weak_dh": {
    "weak": false,
    "bits": null
  },
  "certificate": {
    "subject": {
      "commonName": "example.com",
      "organizationName": "..."
    },
    "issuer": {
      "commonName": "Cloudflare TLS Issuing ECC CA 3",
      "organizationName": "SSL Corporation",
      "countryName": "US"
    },
    "common_name": "example.com",
    "serial_number": "0624D0AB311558780B7D...",
    "version": 3,
    "not_before": "2026-07-29T22:10:08+00:00",
    "not_after": "2026-10-27T22:17:21+00:00",
    "expired": false,
    "days_until_expiry": 79,
    "signature_algorithm": "ecdsa-with-SHA256",
    "subject_alt_names": [
      { "type": "DNS", "value": "example.com" }
    ],
    "is_ca": false,
    "has_server_auth": true,
    "has_client_auth": null
  },
  "certificate_key": {
    "algorithm": "id-ecPublicKey",
    "bits": 256,
    "serial_number": "0624D0AB311558780B7D..."
  },
  "chain": {
    "length": 3,
    "signing_order_valid": true,
    "signing_order_note": null,
    "self_signed": false
  },
  "hostname_valid": true,
  "vulnerabilities": [
    "Deep vulnerability checks (Heartbleed etc.) are not performed; use a dedicated scanner for protocol-specific exploits"
  ],
  "probe_notes": [],
  "scanned_at": "2026-08-26T10:00:00.000000+00:00",
  "duration_ms": 2350
}

Response Fields

Grading Logic (A–F)

Grades are scored from 100 with deductions for each weakness. The grade_notes array contains every deduction applied:

Error Responses

Source contract imported from ssl:tls analyzer/app.py. Handler: analyze_route. Reference: RAPID_README.md.

Snapshot from RAPID_README.md for source API version 0.0.2. This is source documentation, not evidence that an upstream is deployed.

Endpoint 2: GET/POST /analyze

Description

Flagship endpoint. Performs a comprehensive SSL/TLS security analysis of any hostname or IP address. Returns supported TLS protocol versions, all negotiated cipher suites, weak cipher detection, full parsed certificate details, certificate chain validation, hostname match verification, forward secrecy check, weak Diffie-Hellman detection, known vulnerability flags, and an overall letter grade from A to F. The grade uses a score-based heuristic with a transparent breakdown of every deduction in grade_notes.

Query Parameters (GET)

Request Body (POST)

{
  "domain": "example.com",
  "port": 443,
  "timeout": 5
}

Example GET Request

/analyze?domain=example.com

Example POST Request

POST /analyze
Content-Type: application/json

{
  "domain": "example.com",
  "port": 443,
  "timeout": 5
}

Response (200 OK)

{
  "domain": "example.com",
  "port": 443,
  "ssl_grade": "A",
  "grade_notes": [],
  "tls_versions": ["TLSv1.2"],
  "protocols": ["TLSv1.2"],
  "best_protocol": "TLSv1.2",
  "negotiated_cipher": "ECDHE-RSA-AES128-GCM-SHA256",
  "forward_secrecy": true,
  "cipher_list": [
    "ECDHE-RSA-AES128-GCM-SHA256",
    "ECDHE-RSA-AES256-GCM-SHA384"
  ],
  "weak_ciphers": [],
  "weak_dh": {
    "weak": false,
    "bits": null
  },
  "certificate": {
    "subject": {
      "commonName": "example.com",
      "organizationName": "..."
    },
    "issuer": {
      "commonName": "Cloudflare TLS Issuing ECC CA 3",
      "organizationName": "SSL Corporation",
      "countryName": "US"
    },
    "common_name": "example.com",
    "serial_number": "0624D0AB311558780B7D...",
    "version": 3,
    "not_before": "2026-07-29T22:10:08+00:00",
    "not_after": "2026-10-27T22:17:21+00:00",
    "expired": false,
    "days_until_expiry": 79,
    "signature_algorithm": "ecdsa-with-SHA256",
    "subject_alt_names": [
      { "type": "DNS", "value": "example.com" }
    ],
    "is_ca": false,
    "has_server_auth": true,
    "has_client_auth": null
  },
  "certificate_key": {
    "algorithm": "id-ecPublicKey",
    "bits": 256,
    "serial_number": "0624D0AB311558780B7D..."
  },
  "chain": {
    "length": 3,
    "signing_order_valid": true,
    "signing_order_note": null,
    "self_signed": false
  },
  "hostname_valid": true,
  "vulnerabilities": [
    "Deep vulnerability checks (Heartbleed etc.) are not performed; use a dedicated scanner for protocol-specific exploits"
  ],
  "probe_notes": [],
  "scanned_at": "2026-08-26T10:00:00.000000+00:00",
  "duration_ms": 2350
}

Response Fields

Grading Logic (A–F)

Grades are scored from 100 with deductions for each weakness. The grade_notes array contains every deduction applied:

Error Responses

Source contract imported from ssl:tls analyzer/app.py. Handler: analyze_route. Reference: RAPID_README.md.

Snapshot from RAPID_README.md for source API version 0.0.2. This is source documentation, not evidence that an upstream is deployed.

Endpoint 3: GET/POST /certificate

Description

Deep inspection of a server's SSL/TLS certificate and full certificate chain. Returns the complete leaf certificate (subject, issuer, common name, serial number, validity dates, expiry status, signature algorithm, Subject Alternative Names, key usage flags), the public key details (algorithm, bit size), the full certificate chain with chain-length count and a heuristic signing-order validation, self-signed detection, and hostname coverage verification (DNS SANs including wildcard support). This endpoint performs one handshake only — no protocol probing — making it the fastest way to inspect certificate health.

Query Parameters (GET)

Request Body (POST)

{
  "domain": "example.com",
  "port": 443
}

Example GET Request

/certificate?domain=example.com

Example POST Request

POST /certificate
Content-Type: application/json

{
  "domain": "example.com",
  "port": 443
}

Response (200 OK)

{
  "domain": "example.com",
  "port": 443,
  "certificate": {
    "subject": {
      "commonName": "example.com",
      "organizationName": "..."
    },
    "issuer": {
      "commonName": "Cloudflare TLS Issuing ECC CA 3",
      "organizationName": "SSL Corporation",
      "countryName": "US"
    },
    "common_name": "example.com",
    "serial_number": "0624D0AB311558780B7D...",
    "version": 3,
    "not_before": "2026-07-29T22:10:08+00:00",
    "not_after": "2026-10-27T22:17:21+00:00",
    "expired": false,
    "days_until_expiry": 79,
    "signature_algorithm": "ecdsa-with-SHA256",
    "subject_alt_names": [
      { "type": "DNS", "value": "example.com" }
    ],
    "is_ca": false,
    "has_server_auth": true,
    "has_client_auth": null
  },
  "certificate_key": {
    "algorithm": "id-ecPublicKey",
    "bits": 256,
    "serial_number": "0624D0AB311558780B7D..."
  },
  "chain": {
    "length": 3,
    "signing_order_valid": true,
    "signing_order_note": null,
    "self_signed": false
  },
  "hostname_valid": true,
  "fetched_at": "2026-08-26T10:00:00.000000+00:00"
}

Response Fields

Error Responses

Source contract imported from ssl:tls analyzer/app.py. Handler: certificate_route. Reference: RAPID_README.md.

Snapshot from RAPID_README.md for source API version 0.0.2. This is source documentation, not evidence that an upstream is deployed.

Endpoint 3: GET/POST /certificate

Description

Deep inspection of a server's SSL/TLS certificate and full certificate chain. Returns the complete leaf certificate (subject, issuer, common name, serial number, validity dates, expiry status, signature algorithm, Subject Alternative Names, key usage flags), the public key details (algorithm, bit size), the full certificate chain with chain-length count and a heuristic signing-order validation, self-signed detection, and hostname coverage verification (DNS SANs including wildcard support). This endpoint performs one handshake only — no protocol probing — making it the fastest way to inspect certificate health.

Query Parameters (GET)

Request Body (POST)

{
  "domain": "example.com",
  "port": 443
}

Example GET Request

/certificate?domain=example.com

Example POST Request

POST /certificate
Content-Type: application/json

{
  "domain": "example.com",
  "port": 443
}

Response (200 OK)

{
  "domain": "example.com",
  "port": 443,
  "certificate": {
    "subject": {
      "commonName": "example.com",
      "organizationName": "..."
    },
    "issuer": {
      "commonName": "Cloudflare TLS Issuing ECC CA 3",
      "organizationName": "SSL Corporation",
      "countryName": "US"
    },
    "common_name": "example.com",
    "serial_number": "0624D0AB311558780B7D...",
    "version": 3,
    "not_before": "2026-07-29T22:10:08+00:00",
    "not_after": "2026-10-27T22:17:21+00:00",
    "expired": false,
    "days_until_expiry": 79,
    "signature_algorithm": "ecdsa-with-SHA256",
    "subject_alt_names": [
      { "type": "DNS", "value": "example.com" }
    ],
    "is_ca": false,
    "has_server_auth": true,
    "has_client_auth": null
  },
  "certificate_key": {
    "algorithm": "id-ecPublicKey",
    "bits": 256,
    "serial_number": "0624D0AB311558780B7D..."
  },
  "chain": {
    "length": 3,
    "signing_order_valid": true,
    "signing_order_note": null,
    "self_signed": false
  },
  "hostname_valid": true,
  "fetched_at": "2026-08-26T10:00:00.000000+00:00"
}

Response Fields

Error Responses

Source contract imported from ssl:tls analyzer/app.py. Handler: certificate_route. Reference: RAPID_README.md.

Snapshot from RAPID_README.md for source API version 0.0.2. This is source documentation, not evidence that an upstream is deployed.

Endpoint 4: GET /expiry

Description

Fast, single-handshake certificate expiry check designed for monitoring crons and certificate-expiry alerting services. Returns only the fields relevant to expiry monitoring: domain, common name, issuer, serial number, validity dates, days until expiry, and expired status. This is the cheapest and lightest endpoint in the entire API — one Python SSL handshake, no openssl probes, no protocol scanning. Results are cached for only 2 minutes (vs 5 minutes for other endpoints) so monitoring data stays fresh. Ideal for running on a daily or hourly cron schedule.

Query Parameters (GET)

Example GET Request

/expiry?domain=example.com

Response (200 OK)

{
  "domain": "example.com",
  "port": 443,
  "common_name": "example.com",
  "issuer": "SSL Corporation",
  "serial_number": "0624D0AB311558780B7D...",
  "not_before": "2026-07-29T22:10:08+00:00",
  "not_after": "2026-10-27T22:17:21+00:00",
  "days_until_expiry": 79,
  "expired": false,
  "checked_at": "2026-08-26T10:00:00.000000+00:00"
}

Response Fields

Error Responses

Source contract imported from ssl:tls analyzer/app.py. Handler: expiry_route. Reference: RAPID_README.md.

Snapshot from RAPID_README.md for source API version 0.0.2. This is source documentation, not evidence that an upstream is deployed.

Endpoint 5: GET/POST /batch

Description

Analyze up to 50 domains in parallel with a single API request. Each domain is scanned concurrently across 8 parallel workers. If a domain fails input validation (e.g. invalid hostname), it is returned as an error entry in the results — a single bad domain never fails the whole batch. Results are returned in the same order you submitted the domains. Each result in the array is a complete /analyze output (grade, protocols, ciphers, certificate, vulnerabilities, etc.) for that domain. This endpoint is ideal for bulk scanning, portfolio monitoring, and CI/CD certificate checks.

Query Parameters (GET)

Request Body (POST)

{
  "domains": ["example.com", "google.com", "github.com"],
  "port": 443,
  "timeout": 5
}

• domains — required, array of strings, max 50
• port — optional, default 443
• timeout — optional, default 5

Example GET Request

/batch?domains=example.com&domains=google.com&domains=github.com

Example POST Request

POST /batch
Content-Type: application/json

{
  "domains": ["example.com", "google.com", "github.com"],
  "port": 443,
  "timeout": 5
}

Response (200 OK)

{
  "total": 3,
  "successful": 2,
  "failed": 1,
  "results": [
    {
      "domain": "example.com",
      "port": 443,
      "ssl_grade": "A",
      "grade_notes": [],
      "tls_versions": ["TLSv1.2"],
      "protocols": ["TLSv1.2"],
      "best_protocol": "TLSv1.2",
      "forward_secrecy": true,
      "cipher_list": ["ECDHE-RSA-AES128-GCM-SHA256"],
      "weak_ciphers": [],
      "certificate": { "common_name": "example.com", "expired": false, "days_until_expiry": 79 },
      "vulnerabilities": [],
      "scanned_at": "2026-08-26T10:00:00.000000+00:00",
      "duration_ms": 2350
    },
    {
      "domain": "google.com",
      "port": 443,
      "ssl_grade": "A",
      "tls_versions": ["TLSv1.2", "TLSv1.3"],
      "best_protocol": "TLSv1.3",
      "forward_secrecy": true,
      "scanned_at": "2026-08-26T10:00:00.000000+00:00",
      "duration_ms": 1800
    },
    {
      "domain": "not a host!!",
      "error": "invalid domain or IP address",
      "scanned_at": "2026-08-26T10:00:00.000000+00:00"
    }
  ]
}

Response Fields

Error Responses

Source contract imported from ssl:tls analyzer/app.py. Handler: batch_route. Reference: RAPID_README.md.

Snapshot from RAPID_README.md for source API version 0.0.2. This is source documentation, not evidence that an upstream is deployed.

Endpoint 5: GET/POST /batch

Description

Analyze up to 50 domains in parallel with a single API request. Each domain is scanned concurrently across 8 parallel workers. If a domain fails input validation (e.g. invalid hostname), it is returned as an error entry in the results — a single bad domain never fails the whole batch. Results are returned in the same order you submitted the domains. Each result in the array is a complete /analyze output (grade, protocols, ciphers, certificate, vulnerabilities, etc.) for that domain. This endpoint is ideal for bulk scanning, portfolio monitoring, and CI/CD certificate checks.

Query Parameters (GET)

Request Body (POST)

{
  "domains": ["example.com", "google.com", "github.com"],
  "port": 443,
  "timeout": 5
}

• domains — required, array of strings, max 50
• port — optional, default 443
• timeout — optional, default 5

Example GET Request

/batch?domains=example.com&domains=google.com&domains=github.com

Example POST Request

POST /batch
Content-Type: application/json

{
  "domains": ["example.com", "google.com", "github.com"],
  "port": 443,
  "timeout": 5
}

Response (200 OK)

{
  "total": 3,
  "successful": 2,
  "failed": 1,
  "results": [
    {
      "domain": "example.com",
      "port": 443,
      "ssl_grade": "A",
      "grade_notes": [],
      "tls_versions": ["TLSv1.2"],
      "protocols": ["TLSv1.2"],
      "best_protocol": "TLSv1.2",
      "forward_secrecy": true,
      "cipher_list": ["ECDHE-RSA-AES128-GCM-SHA256"],
      "weak_ciphers": [],
      "certificate": { "common_name": "example.com", "expired": false, "days_until_expiry": 79 },
      "vulnerabilities": [],
      "scanned_at": "2026-08-26T10:00:00.000000+00:00",
      "duration_ms": 2350
    },
    {
      "domain": "google.com",
      "port": 443,
      "ssl_grade": "A",
      "tls_versions": ["TLSv1.2", "TLSv1.3"],
      "best_protocol": "TLSv1.3",
      "forward_secrecy": true,
      "scanned_at": "2026-08-26T10:00:00.000000+00:00",
      "duration_ms": 1800
    },
    {
      "domain": "not a host!!",
      "error": "invalid domain or IP address",
      "scanned_at": "2026-08-26T10:00:00.000000+00:00"
    }
  ]
}

Response Fields

Error Responses

Source contract imported from ssl:tls analyzer/app.py. Handler: batch_route. Reference: RAPID_README.md.

Snapshot from RAPID_README.md for source API version 0.0.2. This is source documentation, not evidence that an upstream is deployed.

Endpoint 6: GET /ciphers

Description

Enumerate all cipher suites a server supports for a given TLS version (TLS 1.2 or TLS 1.3) by testing every locally available cipher suite in parallel. The API builds a list of cipher suite names from the local openssl installation, then attempts a handshake for each one (up to limit attempts) using a thread pool of 8 parallel workers. Only suites the server actually accepts are returned in the supported array. This is the most resource-intensive endpoint — it makes dozens of TLS handshakes per call. Requires the openssl CLI on the server.

Query Parameters (GET)

Example GET Request

/ciphers?domain=example.com&tls_version=TLSv1.2&limit=50

Response (200 OK)

{
  "tls_version": "TLSv1.2",
  "tested": 50,
  "supported_count": 2,
  "supported": [
    "ECDHE-RSA-AES256-GCM-SHA384",
    "ECDHE-RSA-CHACHA20-POLY1305"
  ],
  "notes": []
}

Response Fields

Notes

• For TLS 1.3, use tls_version=TLSv1.3. Suites use names like TLS_AES_256_GCM_SHA384 and are tested via the -ciphersuites flag.
• For TLS 1.2, suites use names like ECDHE-RSA-AES256-GCM-SHA384 and are tested via the -cipher flag.
• Higher limit values are more thorough but take longer. Each handshake takes roughly 0.1–0.4 seconds.

Error Responses

Source contract imported from ssl:tls analyzer/app.py. Handler: ciphers_route. Reference: RAPID_README.md.

Snapshot from RAPID_README.md for source API version 0.0.2. This is source documentation, not evidence that an upstream is deployed.

Endpoint 7: GET /cipher/check

Description

Test whether a server supports one specific cipher suite with a single TLS handshake. Returns supported: true if the server negotiated the cipher, or supported: false if it rejected it. This is a fast, lightweight endpoint — one handshake, one result. Useful for verifying compliance with specific security standards, checking whether a particular cipher is available on a server, answering pinning questions, and debugging TLS handshake failures. Works for both TLS 1.2 and TLS 1.3 suites.

Query Parameters (GET)

Example GET Request (TLS 1.2)

/cipher/check?domain=example.com&cipher=ECDHE-RSA-AES256-GCM-SHA384

Example GET Request (TLS 1.3)

/cipher/check?domain=example.com&cipher=TLS_AES_256_GCM_SHA384&tls_version=TLSv1.3

Response — Supported (200 OK)

{
  "cipher": "ECDHE-RSA-AES256-GCM-SHA384",
  "tls_version": "TLSv1.2",
  "supported": true,
  "note": null
}

Response — Not Supported (200 OK)

{
  "cipher": "AES128-SHA",
  "tls_version": "TLSv1.2",
  "supported": false,
  "note": null
}

Response Fields

Common Cipher Suite Names

TLS 1.2 suites:

• ECDHE-RSA-AES256-GCM-SHA384 — strong, forward secrecy
• ECDHE-RSA-AES128-GCM-SHA256 — strong, forward secrecy
• ECDHE-RSA-CHACHA20-POLY1305 — strong, modern
• AES256-SHA256 — strong but no forward secrecy
• AES128-SHA — weak, no forward secrecy

TLS 1.3 suites:

• TLS_AES_256_GCM_SHA384 — strongest TLS 1.3
• TLS_CHACHA20_POLY1305_SHA256 — strong, mobile-friendly
• TLS_AES_128_GCM_SHA256 — strong, standard TLS 1.3

Error Responses

Source contract imported from ssl:tls analyzer/app.py. Handler: cipher_check_route. Reference: RAPID_README.md.