SSL Scout - Internal Certificate Monitoring

Overview

SSL Scout is a lightweight daemon that runs on your internal network to monitor SSL certificates on internal servers, applications, and services. It reports certificate data to DNS Science for centralized alerting and management.

Key Features:

Monitor internal SSL certificates that aren't publicly accessible
Automatic expiry alerts via email, WebSocket, or API
Support for CIDR notation to scan entire subnets
Configurable alert thresholds (30, 14, 7, 1 days)
Works with self-signed certificates
Lightweight Python daemon with minimal dependencies

Installation

Requirements

Python 3.8 or higher
pip (Python package manager)

Install Dependencies

pip install requests cryptography

Download SSL Scout

# Download the daemon
curl -O https://www.dnsscience.io/downloads/dnsscience_sslscoutd.py

# Make it executable
chmod +x dnsscience_sslscoutd.py

# Move to a system location (optional)
sudo mv dnsscience_sslscoutd.py /usr/local/bin/

Configuration

Generate Sample Config

dnsscience_sslscoutd.py --generate-config > /etc/dnsscience/sslscout.json

Configuration File Format

{
    "api_key": "YOUR_API_KEY_HERE",
    "api_endpoint": "https://www.dnsscience.io/api/sslscout/report",
    "scan_interval": 3600,
    "targets": [
        {"host": "internal-app.example.com", "port": 443},
        {"host": "192.168.1.100", "port": 8443},
        {"host": "10.0.0.0/24", "port": 443}
    ],
    "alert_days_before_expiry": [30, 14, 7, 1],
    "log_file": "/var/log/dnsscience_sslscout.log",
    "websocket_alerts": true,
    "timeout": 10
}

Configuration Options

Option	Description	Default
`api_key`	Your DNS Science API key	Required
`scan_interval`	Seconds between scans	3600
`targets`	List of hosts to scan (supports CIDR)	[]
`alert_days_before_expiry`	Days before expiry to alert	[30, 14, 7, 1]
`websocket_alerts`	Enable real-time WebSocket alerts	true
`timeout`	Connection timeout in seconds	10

Usage

Run Single Scan

dnsscience_sslscoutd.py --config /etc/dnsscience/sslscout.json --once

Run as Daemon

dnsscience_sslscoutd.py --config /etc/dnsscience/sslscout.json

Test Single Host

dnsscience_sslscoutd.py --scan-host internal.example.com --port 443

Run as Systemd Service

Create /etc/systemd/system/dnsscience-sslscout.service:

[Unit]
Description=DNS Science SSL Scout Daemon
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/dnsscience_sslscoutd.py --config /etc/dnsscience/sslscout.json
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable dnsscience-sslscout
sudo systemctl start dnsscience-sslscout

API Endpoints

Report Certificates

POST /api/sslscout/report

Used by the daemon to report scanned certificates. Requires API key authentication.

List Certificates

GET /api/sslscout/certificates?expiring_within=30&host=internal

curl "https://www.dnsscience.io/api/sslscout/certificates?expiring_within=30" \
  -H "X-API-Key: YOUR_API_KEY"

Get Alerts

GET /api/sslscout/alerts?unread=true

curl "https://www.dnsscience.io/api/sslscout/alerts?unread=true" \
  -H "X-API-Key: YOUR_API_KEY"

Acknowledge Alert

POST /api/sslscout/alerts/{id}/acknowledge

Certificate Data

SSL Scout extracts and reports the following certificate information:

Field	Description
Subject CN	Common Name of the certificate
Subject Alternative Names	DNS names and IP addresses
Issuer	Certificate Authority information
Validity Period	Not Before / Not After dates
Days Until Expiry	Calculated days remaining
Fingerprints	SHA-256 and SHA-1 fingerprints
Key Info	Key type and size
Self-Signed	Whether certificate is self-signed

WebSocket Alerts

When websocket_alerts is enabled, real-time notifications are sent to connected WebSocket clients when certificates approach expiry thresholds.

Coming Soon: WebSocket integration for real-time certificate expiry alerts in the DNS Science dashboard.

Common Use Cases

Monitor Internal Applications

{
    "targets": [
        {"host": "intranet.company.local", "port": 443},
        {"host": "jenkins.internal", "port": 8443},
        {"host": "gitlab.internal", "port": 443}
    ]
}

Scan Entire Subnet

{
    "targets": [
        {"host": "10.0.1.0/24", "port": 443},
        {"host": "192.168.100.0/24", "port": 8443}
    ]
}

Monitor Multiple Ports

{
    "targets": [
        {"host": "mailserver.local", "port": 993},
        {"host": "mailserver.local", "port": 995},
        {"host": "mailserver.local", "port": 465},
        {"host": "ldap.local", "port": 636}
    ]
}

Security Note: Store your API key securely. Use environment variables or a secrets manager in production environments.

Troubleshooting

Connection Refused

Ensure the target host is reachable and the SSL service is running on the specified port.

Timeout Errors

Increase the timeout value in your configuration for slow networks.

API Key Invalid

Verify your API key is active in your DNS Science account settings.

Support

For assistance with SSL Scout:

Email: support@dnsscience.io
Documentation: API Documentation