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

### Mozilla CA Bundle

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

```bash
# Downloaded from: https://curl.se/ca/cacert.pem
# Install additional certificates in the operating system trust store.
# Certificate count: 144 CA certificates
```

## Result Format

```go
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

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

```bash
# Download latest Mozilla CA bundle
curl -fsSL -o /usr/local/share/ca-certificates/mozilla-ca-bundle.crt \
    https://curl.se/ca/cacert.pem

# Verify
grep -c "BEGIN CERTIFICATE" /usr/local/share/ca-certificates/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 operating system trust store

### 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](https://wiki.mozilla.org/CA/Included_Certificates)
- [Chrome Root Certificate Policy](https://www.chromium.org/Home/chromium-security/root-ca-policy)
- [curl CA Bundle](https://curl.se/docs/caextract.html)