ssllabs-scan

ssllabs-scan is a command-line client for the SSL Labs APIs. It is specifically designed for automated and/or bulk testing of SSL configurations.

Before using this tool, ensure you have reviewed the SSL Labs terms and conditions at https://www.ssllabs.com/about/terms.html.

The Host object represents the top-level assessment of a specific hostname or IP address. It tracks the overall status of the scan and provides access to the individual endpoints evaluated.

Key fields include:

• host: The assessment target (hostname or IP).
• status: The current state of the assessment (DNS, ERROR, IN_PROGRESS, or READY).
• statusMessage: An English description of the status (contains error details if status is ERROR).
• endpoints[]: An array of Endpoint objects representing the different IP addresses/services found.
• certHostnames[]: A list of hostnames collected from certificates seen during assessment (useful if the certificate doesn't match the requested hostname).

An Endpoint object represents a specific IP address or service discovered during the host assessment. It contains the actual security grades and technical details of the TLS configuration.

Key fields include:

• grade: The security grade (A+, A-, A-F, T for no trust, or M for certificate name mismatch).
• progress: A value from 0 to 100 (or -1 if not started).
• eta: Estimated seconds until completion.
• details: An EndpointDetails object. Note: This field is not returned by default; you must pass the all parameter to the analyze API call to enable it.
• delegation: A bitmask indicating domain name delegation (bit 0 for non-prefixed, bit 1 for prefixed).

The SSL Labs Assessment API is a RESTful service based on HTTP and JSON. All requests must use the GET method with parameters provided in the query string.

Workflow Pattern:

1. Submit Request: The client submits an assessment request.
2. Immediate Result or Job Start: If a valid report is already cached, it is returned immediately. Otherwise, the server starts a new assessment.
3. Polling: If a new assessment is started, the client must periodically poll the API to check the job status until it is complete.

Base URLs:

• Production: https://api.ssllabs.com/api/v2/
• Development/Testing: https://api.dev.ssllabs.com/api/v2/ (Note: This endpoint has reduced limits and may be inconsistent.)

To quickly get existing data without triggering new tests:

1. Request: Call analyze with fromCache=on and all=done.
2. Control Age: Use the maxAge parameter to specify the maximum age of the report you are willing to accept.
3. Fallback: If the information is not in the cache, a new assessment will be started automatically. You must then poll as described in the 'fresh test results' guide.

If you are using API v4 for the first time, you must register your organization using the ssllabs-scan-v4-register tool. This associates your scans with a registered email address.

Required flags:

• --firstName: Your first name
• --lastName: Your last name
• --organization: Your organization name
• --email: Your organization email address
• --registerApiUrl: The registration API entry point (defaults to BUILTIN)

ssllabs-scan-v4-register --firstName John --lastName Doe --organization Example --email johndoe@example.com

To avoid being rate-limited (429) or encountering overloaded errors (529), follow these best practices:

• Polling Frequency: Do not poll too often. A recommended strategy is to poll every 5 seconds until the status changes to IN_PROGRESS, then every 10 seconds until completion.
• Concurrency: Keep the number of concurrent assessments to a minimum. Ideally, test only one hostname at a time.
• Track Limits: Use the response headers X-Max-Assessments and X-Current-Assessments to calculate how many new assessments you can safely submit. Update your internal state after every complete response.

The ssllabs-scan-v4 tool allows you to scan individual hostnames or entire files of hostnames.

Note: The --email flag is required for all API v4 calls and must match your registered organization email.

To ensure you get a completely new assessment rather than a cached one, follow this sequence:

1. Initiate: Call analyze with startNew=on and all=done.
2. Poll: Call analyze periodically without the startNew parameter.
3. Monitor: Check the Host.status field in the response. Stop polling when the status is either READY or ERROR.
4. Completion: Once the status is READY, the response will contain all full assessment information.

To run or build this tool, you must have the following installed:

• Go >= 1.3

When making API calls, monitor the HTTP status codes to handle errors appropriately: