@ideascol/tls-audit

A comprehensive TLS configuration audit tool for checking the security of your website's SSL/TLS implementation.

Overview

The TLS Audit tool performs in-depth security analysis of a domain's TLS configuration, providing:

• TLS protocol version detection
• Cipher suite security assessment
• Certificate validation and expiration checks
• Domain name validation against Subject Alternative Names (SAN)
• Self-signed certificate detection
• Comprehensive security scoring
• Detailed vulnerability reporting

Quick Start

# Using npm
npx @ideascol/tls-audit example.com

# Using bun
bunx @ideascol/tls-audit example.com

Installation

# Using npm
npm install -g @ideascol/tls-audit

# Using bun
bun install -g @ideascol/tls-audit

Usage as CLI

# Basic usage
tls-audit example.com

# Specify a custom port (default is 443)
 bun run start target --server="https://www.google.com/"
 bun run start target --server="142.251.215.238"  

Usage as Library

import { TslAuditor } from '@ideascol/tls-audit';

// Audit a domain (default port 443)
TslAuditor('example.com') // or IP address
  .then(result => {
    console.log(result.summary);
    
    if (result.issues.length > 0) {
      console.log('Issues found:');
      result.issues.forEach(issue => console.log(issue));
    }
    
    console.log(`Security Score: ${result.securityScore}/100`);
  })
  .catch(err => {
    console.error('Audit failed:', err.message);
  });

// Audit with a custom port
TslAuditor('example.com', 8443)
  .then(result => {
    // Process results
  });

Audit Result Structure

The audit returns a comprehensive result object with the following information:

{
  host: string;              // The audited hostname
  port: number;              // The port used for the TLS connection
  protocol: string | null;   // The TLS protocol version detected
  cipher: {                  // Information about the negotiated cipher
    name: string;            // Cipher name
    version: string;         // TLS version used
    standardName: string;    // Standard name of the cipher
  };
  certificate: {             // Cleaned certificate information
    subject: object;         // Certificate subject fields
    issuer: object;          // Certificate issuer fields
    valid_from: string;      // Certificate validity start date
    valid_to: string;        // Certificate expiration date
    fingerprint: string;     // Certificate fingerprint
    // ... additional certificate details
  };
  isSelfSigned: boolean;     // Whether certificate is self-signed
  isExpired: boolean;        // Whether certificate is expired
  expiresInDays: number;     // Days until certificate expiration
  tlsInsecure: boolean;      // If insecure TLS version is used (1.0/1.1)
  cipherInsecure: boolean;   // If weak cipher is detected
  domainMismatch: boolean;   // If domain doesn't match certificate
  handshakeTimeMs: number;   // TLS handshake time in milliseconds
  issues: string[];          // List of detected security issues
  securityScore: number;     // Overall security score (0-100)
  checklist: {               // Security checklist results
    tlsVersionSecure: boolean;
    cipherSecure: boolean;
    certValid: boolean;
    domainMatches: boolean;
    selfSigned: boolean;
    certExpiringSoon: boolean;
  };
  summary: string;           // Text summary of the audit results
  sanList?: string[];        // List of Subject Alternative Names
  domainMismatchReason?: string; // Details if domain doesn't match
}

Security Checks Performed

The tool evaluates the following security aspects:

• TLS Protocol Version: Flags TLS 1.0 and 1.1 as insecure
• Cipher Security: Detects weak ciphers including RC4, 3DES, DES, NULL, MD5, etc.
• Certificate Validity: Checks if the certificate is expired or expiring soon
• Domain Validation: Verifies hostname against certificate's Subject Alternative Names
• Certificate Trust: Detects self-signed certificates
• Handshake Performance: Measures TLS handshake time

Security Scoring

The security score starts at 100 and deducts points for various issues:

• Insecure TLS version: -30 points
• Weak cipher: -25 points
• Self-signed certificate: -20 points
• Expired certificate: -30 points
• Certificate expiring soon: -10 points
• Domain mismatch: -20 points

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Developed by IdeasCol Digital Security Team - Protecting applications through advanced security tooling.