worker/checks/cbssl/README.md

CBSSL - Browser-Based SSL Certificate Chain Checker

Overview

The cbssl (Browser SSL) check validates SSL/TLS certificates against actual browser CA root stores. Unlike the standard cssl check which uses Go's system certificate pool, this check validates certificates against the same CA roots used by Chrome and Firefox on Linux.

Features

• Dual Browser Validation: Validates certificates against both Chrome and Firefox CA roots
• Full Chain Information: Returns complete certificate chain details for each browser
• Expiration Tracking: Monitors certificate expiration dates and warns before expiry
• Detailed Metrics: Provides InfluxDB-compatible metrics with detailed validation results

How It Works

Browser CA Roots

On Linux, both Chrome and Firefox use the system's CA certificate store:

• Chrome/Chromium: Uses /etc/ssl/certs/ca-certificates.crt (on Alpine/Debian)
• Firefox: Uses NSS library or falls back to system certificates

The check loads these CA certificates and validates the target site's certificate chain against each browser's root store independently.

Certificate Sources

The checker looks for CA certificates in the following locations (in order):

1. /etc/ssl/certs/ca-certificates.crt - Alpine/Debian system certificates
2. /etc/ssl/cert.pem - macOS system certificates
3. /etc/pki/tls/certs/ca-bundle.crt - RHEL/CentOS system certificates
4. /usr/local/share/ca-certificates/ - Custom certificate directory
5. /data/rsmon/docker/cert-bundles/output/ - Project-specific certificate bundles

Mozilla CA Bundle

The project includes the Mozilla CA certificate bundle which contains the same CA certificates used by Firefox:

# Downloaded from: https://curl.se/ca/cacert.pem
# Location: docker/cert-bundles/output/mozilla-ca-bundle.crt
# Certificate count: 144 CA certificates

Result Format

type Result struct {
    // Standard check result
    cr.CheckResult

    // Chrome-specific results
    ChromeValid  bool       // true if certificate validates against Chrome roots
    ChromeError  string     // error message if Chrome validation fails
    ChromeChain  []CertInfo // certificate chain as validated by Chrome

    // Firefox-specific results
    FirefoxValid  bool       // true if certificate validates against Firefox roots
    FirefoxError  string     // error message if Firefox validation fails
    FirefoxChain  []CertInfo // certificate chain as validated by Firefox

    // Certificate details
    Expires  *time.Time // certificate expiration date
    Subject  string     // certificate subject (CN)
    Issuer   string     // certificate issuer (CN)
    DNSNames []string   // certificate SANs
}

Check Parameters

Currently, the check validates against both browsers. Future versions may support:

• browser - Specify which browser to validate against: "chrome", "firefox", or "all" (default)

InfluxDB Metrics

The check provides the following metrics:

Fields:

• took - Request duration in milliseconds
• chrome_valid - Whether certificate validated against Chrome roots (1/0)
• firefox_valid - Whether certificate validated against Firefox roots (1/0)
• expires_at - Unix timestamp of certificate expiration
• days_until_expiry - Days until certificate expires

Tags:

• check - Check ID
• state - Check state (OK, WARN, ERR, FAIL)
• subject - Certificate subject CN
• issuer - Certificate issuer CN
• chrome_error - Chrome validation error (if any)
• firefox_error - Firefox validation error (if any)
• dns_names - Comma-separated list of DNS names in certificate

Example Usage

import "rocketgit.ru/rsmon/worker/checks/cbssl"

// Perform the check
result := cbssl.Perform(check)

// Check results
if result.ChromeValid && result.FirefoxValid {
    // Certificate is valid for both browsers
} else if !result.ChromeValid {
    // Certificate fails Chrome validation
    fmt.Printf("Chrome error: %s\n", result.ChromeError)
}

Differences from cssl

Feature	cssl	cbssl
CA Root Source	Go's system pool	Browser-specific CA roots
Browser Validation	Single (system)	Dual (Chrome + Firefox)
Chain Information	Basic leaf cert	Full chain per browser
Use Case	General SSL validation	Browser compatibility verification

Certificate Bundle Management

To update the CA certificate bundles:

# Download latest Mozilla CA bundle
cd /data/rsmon
curl -fsSL -o docker/cert-bundles/output/mozilla-ca-bundle.crt \
    https://curl.se/ca/cacert.pem

# Verify
grep -c "BEGIN CERTIFICATE" docker/cert-bundles/output/mozilla-ca-bundle.crt

Troubleshooting

"failed to load any CA certificates"

This error occurs when no CA certificates can be found. Solutions:

1. Ensure the system has ca-certificates package installed
2. Place custom CA certificates in /usr/local/share/ca-certificates/
3. Add certificates to the project bundle at docker/cert-bundles/output/

Certificate validation failures

If validation fails for a site that works in browsers:

1. Check if the site uses a custom CA not in the Mozilla bundle
2. Verify the site's intermediate certificates are properly configured
3. Check for expired or malformed certificate chains

References

• Mozilla Included CA Certificate List
• Chrome Root Certificate Policy
• curl CA Bundle