npm package: @ideascol/tls-audit
Description: Audit your tls configuration
Author: Andres Fernandez
Latest version: 0.0.1

# @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

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

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

## Installation

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

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

## Usage as CLI

```bash
# 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

```ts
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:

```ts
{
  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](https://ideascol.com) - Protecting applications through advanced security tooling.