A Python command-line tool for assessing TLS/SSL configuration of web servers using the Qualys SSL Labs API. Produces human-readable reports with graded findings, vulnerability detection, certificate analysis, and actionable security warnings.
Built on original work by Jonathan C. Trull (2015), extended and modernized by Aaron Dutton (2026).
- Python API integration (REST, JSON parsing, polling loops)
- Defensive programming (error handling, partial data, rate limiting)
- Security assessment concepts (TLS vulnerabilities, certificate lifecycle, cipher suites)
- GRC-relevant output (findings mapped to PCI-DSS, HSTS policy, certificate expiry thresholds)
- Bitmask decoding for multi-flag API values
- Refactoring for DRY code (
collect_warnings()helper used in two contexts) - Systematic tool validation against known-good and known-bad targets
- Grade decoding — translates SSL Labs letter grades (A+ through F, T, M) into plain-English descriptions
- Vulnerability detection — Heartbleed, POODLE, FREAK, Logjam, BEAST, RC4, 3DES/SWEET32
- Legacy protocol warnings — flags TLS 1.0, TLS 1.1, SSL 2.0, SSL 3.0 with compliance context (PCI-DSS)
- Certificate analysis — subject, issuer, signature algorithm, SCT, valid from, expiry with days remaining
- Certificate issues bitmask decoder — decodes composite issue codes into individual findings
- HSTS detection — distinguishes absent, present-but-not-preloaded, and unknown states
- Forward secrecy decoding — translates numeric FS scores into descriptive labels
- Per-endpoint warnings — findings scoped correctly to each endpoint
- Multi-endpoint summary — deduplicates findings across CDN/load-balanced hosts (shown for 2+ endpoints only)
- File export — saves timestamped reports as
.txtfiles - Cache mode — optionally retrieves cached SSL Labs results for recently scanned hosts
- Graceful error handling — rate limiting, stale cache, partial data, and failed endpoints all handled cleanly
Python 3.8+
requests
Install dependencies:
pip install requestsNo API key required. The tool uses the free public SSL Labs Assessment API v2.
python ssllabscanner.pyThe tool prompts interactively:
Enter hostname to scan: example.com
Use cached results if available? (y/n): n
Save report to file? (y/n): y
Filename [ssl_report_example_com_20260508_143022.txt]:
Running fresh scan. This can take several minutes. Please be patient.
Cache mode (y) retrieves a previously completed scan from SSL Labs' servers. Useful for re-running reports without consuming API capacity. Cache results may be incomplete or stale — the tool detects and reports this.
Fresh scan (n) initiates a new assessment. Scans typically take 1–5 minutes depending on the number of endpoints. The tool polls every 30 seconds until complete.
============================================================
SSL Labs Scan Results: revoked.badssl.com
Report generated : 2026-05-08 22:18:52
============================================================
Status : READY
Protocol : HTTP
Public : False
────────────────────────────────────────────────────────
Endpoint : 104.154.89.105
Grade : F (Failed / critically insecure)
Status : Ready
Warnings : True
Certificate:
Subject : CN=revoked.badssl.com
Issuer : E8
Sig Alg : SHA384withECDSA
SCT : True
Valid From: 2026-03-10
Expires : 2026-06-08 (30 days remaining)
Protocols Supported:
TLS 1.0
TLS 1.1
TLS 1.2
Vulnerabilities:
Heartbleed : False
POODLE (TLS) : Not vulnerable
FREAK : False
Logjam : False
BEAST : True
Forward Secrecy : All simulated clients support FS
RC4 Supported : False
HSTS:
Status : absent
Warnings & Findings:
[!] BEAST vulnerability present (TLS 1.0 + CBC ciphers)
[!] TLS 1.0 supported (deprecated, prohibited by PCI-DSS)
[!] TLS 1.1 supported (deprecated)
[!] HSTS not configured (no HTTP Strict Transport Security)
[!] Certificate expiring in 30 days (critical)
[!] Certificate issue: Certificate not trusted
[!] Certificate issue: Certificate chain contains errors
============================================================
The tool was validated against the following targets. All findings were verified against expected behavior.
| Host | Grade | What it tests |
|---|---|---|
badssl.com |
B | Baseline: legacy TLS without weak ciphers |
tls-v1-0.badssl.com |
B | TLS 1.0, BEAST, legacy protocol warnings |
3des.badssl.com |
C | 3DES cipher prioritized, SWEET32 detection |
rc4.badssl.com |
F | RC4, F grade, degraded forward secrecy |
revoked.badssl.com |
F | Revoked cert, bitmask code 17 (not trusted + chain errors) |
self-signed.badssl.com |
T | Self-signed cert, T grade, issuer detection |
untrusted-root.badssl.com |
T | Unknown CA, T grade |
expired.badssl.com |
T | Cert expired since 2015, EXPIRED path, bitmask decoder |
wrong.host.badssl.com |
T | SNI fallback cert, name mismatch + chain incomplete + expired simultaneously |
http.badssl.com |
B | Missing HSTS |
neverssl.com |
A | HTTP fallback site with valid TLS; IPv4/IPv6 HSTS inconsistency |
| Host | Grade | What it tests |
|---|---|---|
cnn.com |
A | 8 CDN endpoints, HSTS absent, cert expiry; summary deduplication |
connectivity-check.ubuntu.com |
A | 12 endpoints; demonstrates summary value at scale |
| Grade | Meaning |
|---|---|
| A+ | Exceptional — HSTS preloaded, strong configuration |
| A | Strong |
| A- | Strong with minor issues |
| B | Adequate — legacy configuration present |
| C | Weak configuration |
| D | Insecure |
| E | Severely misconfigured |
| F | Failed / critically insecure |
| T | Certificate not trusted (self-signed, untrusted CA, revoked, expired) |
| M | Certificate name mismatch |
The SSL Labs API is a free public service with capacity limits. If a scan returns:
[!] API error: Running at full capacity. Please try again later.
Wait 15–30 minutes between scan sessions. Use cache mode (y) to retrieve results from recent scans without consuming additional capacity.
Reports are saved as plain text with timestamped filenames:
ssl_report_example_com_20260508_143022.txt
Files are written to the working directory. Useful for tracking posture over time or including findings in risk register entries.
This project is based on original work by Jonathan C. Trull (2015), used under the MIT License. Modifications by Aaron Dutton (2026) are also released under the MIT License.
See source file for full license text.
- Jonathan C. Trull — original SSL Labs API wrapper
- Qualys SSL Labs — free public TLS assessment API
- badssl.com — intentionally misconfigured test targets used for validation