SSL Labs Integration with DefectDojo

SSL Labs Integration with DefectDojo

SSL Labs is a free TLS testing service run by Qualys. It connects to a public HTTPS host, inspects the certificate chain, supported protocol versions, cipher suites, and a set of known TLS weaknesses, and rates the server with a letter grade from A+ to F, with special grades for certificate trust (T) and name mismatch (M) problems. Qualys publishes ssllabs-scan, an open source command-line client for the SSL Labs API, which writes results as JSON. The current API version (v4) requires a one-time registration with an organization email. DefectDojo imports the JSON that client produces.

SSL Labs Integration with DefectDojo

We use SSL Labs because its grade is the number everyone already recognizes, including auditors and customers who run the public test against our domains themselves. Importing SSL Labs results into DefectDojo turns each host's grade into a Finding on the Asset that owns the domain, with the certificate details, protocols, and cipher suites recorded in the description. When a grade drops after a load balancer change or a certificate renewal, we see it as a new finding with an owner and an SLA instead of hearing about it from a customer.

Why SSL Labs Matters

TLS problems are easy to introduce and very visible from the outside. SSL Labs gives a consistent external view of them.

• It tests from the internet, so it sees what a client sees, including CDN and load balancer behavior.
• The letter grade condenses certificate, protocol, key exchange, and cipher strength into one comparable result.
• It checks for well-known TLS weaknesses such as Heartbleed, POODLE, FREAK, and insecure renegotiation.
• It reports HSTS status, OCSP stapling, and forward secrecy support, which matter for compliance reviews.
• A one-off web test is easy to forget. Tracking grades per host over time needs a place to store them.

Advantages of This Integration

What we gained by running SSL Labs results through DefectDojo:

• Grades mapped to severity. The parser converts A grades to Info, B to Medium, C to High, and D, F, M, and T to Critical, so TLS regressions trigger the same SLA rules as other findings.
• Grade changes are visible. The grade is part of the title, so a reimport that moves a host from A to B mitigates the old finding and opens a new Medium one.
• Endpoints for every address. Each finding records the hostname, each scanned IP address, and the URLs from SSL Labs' HTTP transactions, which helps when one domain resolves to several servers.
• Evidence in one record. Certificate subject, issuer, signature algorithm, protocol list, cipher suites, and vulnerability check results are kept in the description for later review.
• Shared triage features. Findings can be assigned, risk-accepted, or pushed to Jira like any other DefectDojo finding.

How This Integration Works

DefectDojo imports SSL Labs results with the SSL Labs Scan scan type.

1. Produce a JSON report. Register once for API v4, then scan one or more hosts with the v4 client and save the JSON output:

ssllabs-scan-v4 --quiet --email security@example.com www.example.com > ssllabs-www.json

For several domains, pass --hostfile hosts.txt. The parser expects the standard (not flattened) JSON array of host reports, so don't use --json-flat.

2. Import it. In the UI, open the Engagement, choose Import Scan Results, select SSL Labs Scan, and upload the file. To automate it, use the API in Community Edition or DefectDojo Pro:

curl "https://YOUR_INSTANCE/api/v2/import-scan/" \
  -H "Authorization: Token $DD_API_TOKEN" \
  -F "scan_type=SSL Labs Scan" \
  -F "file=@ssllabs-www.json" \
  -F "product_name=public-websites" \
  -F "engagement_name=TLS Monitoring" \
  -F "auto_create_context=true"

DefectDojo Pro users can run the same import with Universal Importer:

universal-importer import \
  --defectdojo-url "https://YOUR_INSTANCE.cloud.defectdojo.com/" \
  --scan-type "SSL Labs Scan" \
  --report-path "./ssllabs-www.json" \
  --product-name "public-websites" \
  --engagement-name "TLS Monitoring" \
  --auto-create-context

3. Reimport on a schedule. Run the scan weekly or after infrastructure changes and send the report to /api/v2/reimport-scan/ against the same Test so grade changes are tracked.

Data Granularity: What Gets Imported

The parser creates one finding per host and grade. IP endpoints of the same host that share a grade are merged into that finding.

Known TLS weaknesses are recorded as text in the description rather than as separate findings, so a Heartbleed result shows up inside the grade finding for that host.

Use Cases

External TLS monitoring: A scheduled job scans every public domain weekly and reimports into one Test per domain group. A grade drop after a certificate renewal or a CDN configuration change becomes a new finding with an owner the same day.

Certificate and load balancer changes: Before and after a TLS policy change on a load balancer, the team runs SSL Labs and compares the findings. If any IP address behind the domain grades lower than the others, it shows up as a separate grade finding for that host.

Customer and audit questions: Security questionnaires often ask for TLS configuration evidence. DefectDojo keeps the grade history, certificate details, and remediation dates per domain.

Combining with internal scanners: SSL Labs only tests publicly reachable hosts. Teams pair it with an internal TLS scanner on the same Asset so public and internal endpoints are reported together.

Operational Tips

• Treat the Info-level A grade findings as positive evidence. They record that a host was tested and passed, which is useful in reports. Filter them out of SLA dashboards or set minimum_severity=Low if you don't want them.
• Watch for Critical findings caused by a missing grade. If SSL Labs can't complete the test for an IP address, the empty grade maps to Critical, so check the raw report before escalating.
• Expect a new finding when a grade changes. The grade is in the title, so moving from B to A mitigates the B finding and opens an Info A finding on reimport.
• Keep the domain list stable per Test. A host that drops out of the scan list is mitigated on reimport, which can look like a fix when it was only skipped.
• Respect the SSL Labs API terms and rate limits. Use --usecache for frequent checks where a recent result is acceptable.
• Only public hosts can be tested, so internal services need a different scanner.