node-ssl-validator

Scan and validate SSL certificates

Table of contents

• CLI
  • Install
  • Help
  • Basic example
  • Advanced example
• Module
  • Install
  • Help
  • Basic example
  • Advanced example
• Hooks
  • Hook arguments
  • Success example
  • Failure example

CLI

Install globally:

npm install -g cmr1-ssl-validator

Show help:

ssl-validator --help

Basic cli example:

# Scan & validate current directory
ssl-validator 

# Scan & validate default Let's Encrypt directory
ssl-validator /etc/letsencrypt/live --recursive

# Scan & validate default dehydrated directory
ssl-validator /etc/dehydrated/certs --recursive

Advanced cli example:

ssl-validator \
  # Use recursive flag to group certs by directory
  --recursive \

  # Scan & validate default dehydrated directory
  --directory /etc/dehydrated/certs \          
  
  # Provide cert & key file regular expressions
  --certfile "^(fullchain|cert).pem$" \
  --keyfile "^privkey.pem$" \

  # Provide expiration period in days
  --time 30 \

  # Provide a slack webhook URL for notifications
  --slack https://hooks.slack.com/services/foo/bar/foobar \

  # Provide an executable hook to trigger with invalid certificate info
  --hook /usr/bin/foo-bar \

  # Validate certificates stored on AWS Certificate Manager (ACM)
  --acm

Back to Top

Module

Install locally:

npm install --save cmr1-ssl-validator

Basic code example:

// Require cmr1-ssl-validator module
const SslValidator = require('cmr1-ssl-validator');

// Create a new validator with default options
const validator = new SslValidator();

// Run validator with default options
validator.run(err => {
  if (err) {
    // Something went wrong
    validator.error(err);
  } else {
    // All finished
    validator.log('Finished.');
  }
});

Advanced code example:

// Require cmr1-ssl-validator module
const SslValidator = require('cmr1-ssl-validator');

// Create a new validator with default options
const validator = new SslValidator({
  // Use recursive flag to group certs by directory
  recursive: true,

  // Scan & validate default dehydrated directory
  directory: '/etc/dehydrated/certs',

  // Provide cert & key file regular expressions
  certfile: '^(fullchain|cert).pem$',
  keyfile: '^privkey.pem$',

  // Provide expiration period in days
  time: 30,

  // Provide a slack webhook URL for notifications
  slack: 'https://hooks.slack.com/services/foo/bar/foobar',

  // Provide an executable hook to trigger with invalid certificate info
  hook: '/usr/bin/foo-bar',

  // Validate certificates stored on AWS Certificate Manager (ACM)
  acm: true
});

// Run validator with default options
validator.run(err => {
  if (err) {
    // Something went wrong
    validator.error(err);
  } else {
    // All finished
    validator.log('Finished.');
  }
});

Back to Top

Hooks

An executable can be called after completion with information about failure(s).

Hook arguments:

/path/to/hook EXIT_CODE [DOMAIN_LIST]

• EXIT_CODE is the exit status of the validator (0 or 1)
• DOMAIN_LIST a list of invalid domains, grouped by certificate
  • Domains are joined by ,
  • Groups are joined by ;
  • Example: abc.co,www.abc.co;xyz.co,www.xyz.co
    • Two certs: abc.co & xyz.co, both with alternate domain name: www.

Success example:

/path/to/hook 0

Failure example:

/path/to/hook 1 abc.co,www.abc.co;xyz.co,www.xyz.co

Back to Top