node-ssllabs

A node.js library for the SSL Labs API.

SSL Labs APIs expose the complete SSL/TLS server testing functionality in a programmatic fashion, allowing for scheduled and bulk assessment. We are making the APIs available to encourage site operators to regularly test their server configuration.

Install

npm install node-ssllabs

Usage

var ssllabs = require("node-ssllabs");

ssllabs.scan("www.ssllabs.com", function (err, host) {
	console.dir(host);
});

Test Usage

Testing with Mocha and Should.js.

var ssllabs = require("node-ssllabs"),
	should = require("should");

describe("www.ssllabs.com", function () {
	it("should get an A+", function (done) {
		ssllabs.scan("www.ssllabs.com", function (err, host) {
			if (err) {
				throw err;
			}
			host.endpoints.forEach(function (endpoint) {
				endpoint.grade.should.equal("A+");
			});
			done();
		});
	});
});

Advanced Usage

var ssllabs = require("node-ssllabs");

ssllabs.scan({
	"host": "www.ssllabs.com",
	"fromCache": true,
	"maxAge": 24
}, function (err, host) {
	console.dir(host);
});

ssllabs.info(function (err, info) {
	console.dir(info);
});

ssllabs.analyze({
	"host": "www.ssllabs.com",
	"publish": true,
	"startNew": true,
	"all": "done"
}, function (err, host) {
	console.dir(host);
});

ssllabs.analyze({
	"host": "www.ssllabs.com",
	"fromCache": true,
	"maxAge": 72,
	"all": "on",
	"ignoreMismatch": true
}, function (err, host) {
	console.dir(host);
});

ssllabs.getEndpointData({
	"host": "www.ssllabs.com",
	"s": "64.41.200.100",
	"fromCache": true
}, function (err, endpointData) {
	console.dir(endpointData);
});

ssllabs.getStatusCodes(function (err, statusCodes) {
	console.dir(statusCodes);
});

ssllabs.getRootCertsRaw(function (err, rootCertsRaw) {
	console.dir(rootCertsRaw);
});

ssllabs.getRootCertsRaw({
	trustStore: 5
}, function (err, rootCertsRaw) {
	console.dir(rootCertsRaw);
});

ssllabs.getRootCerts(function (err, rootCerts) {
	console.dir(rootCerts);
});

ssllabs.getRootCerts({
	trustStore: 5
}, function (err, rootCerts) {
	console.dir(rootCerts);
});

Proxy all requests via a tunneling agent

As of version 1.1.0, this library will respect your HTTPS_PROXY environment variable and tunnel all requests to the specified URL. Compatible with all protocols supported by proxy-agent.

As of version 2.1.0, this library will set the proxy agent on each request it makes and will not override the global HTTP agent.

License

node-ssllabs is available under the MIT License.

Todo

add (more) support for access rate and rate limiting
incorporate new info field, newAssessmentCoolOff, to access rate and rate limiting
add option to specify an array of hosts to scan
figure out if the maxAge parameter is required with the fromCache parameter
make API version changeable (maybe?) with createClient()?

TODO for next minor release

have the scan function emit events for polling progress

TODO for next major release

promise-ify and modernize
refactor to be a Universal ES6 module that can be used client side and server side with the fetch and URL libraries
maintain support for using tunneling proxies (server side only?)

Change Log

2.1.0— April 16, 2020

set proxy agent on each HTTP request instead

2.0.0— April 10, 2020

dropping support for node 6 because eslint and nyc no longer support it

1.1.3— April 10, 2020

added User Agent header to all requests
improved error handling

1.1.2— May 22, 2019

refactored code to reduce cognitive complexity
increased test coverage

1.1.1— May 21, 2019

refactored code to eliminate some duplicate code
added test coverage reporting

1.1.0— May 4, 2019

added support for tunneling proxies via proxy-agent

1.0.2— May 3, 2019

smaller install
better testing
faster builds

1.0.1— May 3, 2019

call callback with error instead of throwing
normalized error handling code patterns
reordered tests so the fast tests run before the slow tests
added more tests for error handling in getEndpointData() and getRootCertsRaw()

1.0.0— May 3, 2019

moved async to dev dependency (as it should have been)
removed underscore dependency (was very lightly used)
added dependency on node v4.0.0 for Object.assign

0.6.0— May 2, 2019

updated API endpoint from v2 to v3
updated dependencies
switched from JSHint to eslint for syntax checking
fixed typos
added basic support for access rate and rate limiting to scan()
added support for the trustStore parameter to the getRootCertsRaw() call
added getRootCerts() call that returns the data as a plain-old object

0.5.0 — July 14, 2016

added support for new API call, getRootCertsRaw
improved testing with Mocha
improved normalizeOptions function
updated documentation

0.4.3 — May 1, 2015

removed requirement that maxAge must be set if fromCache is set
added check that fromCache is set if maxAge is set
fixed bug where NaN was accepted for the maxAge parameter

0.4.2 — April 27, 2015

added call to info before calling analyze in the scan function

0.4.1 — April 27, 2015

refactored scan function to use analyze function for dryness
improved test to ensure parallel scanning maintains context

0.4.0 — April 23, 2015

added option to only specify a hostname for scanning
added test for lost context in parallel scans
added test if startNew and fromCache options are both true
added additional parameter tests and verification

0.3.0 — April 21, 2015

added scan function to encapsulate protocol usage

0.2.0 — April 20, 2015

updated to work properly in other packages.

0.1.0 — April 20, 2015

added support for the getEndpointData api endpoint.
added support for the getStatusCodes api endpoint.
improved error handling and reporting.

0.0.1 — April 20, 2015

Initial version
supports two api endpoints, info and analyze

Current Tags

2.1.0 ... latest (6 years ago)