CertHound

Internet-scale TLS certificate anomaly hunter. Scans networks, clusters certificates by fingerprint, scores anomalies against vendor baselines and fleet-wide statistics, and hunts for malicious certificate infrastructure (botnets, C2 servers, APT campaigns).

Quick Start

# Build
cargo build --release

# Scan a single host
certhound scan -t 1.1.1.1 -p 443

# Scan with JARM fingerprinting and HTTP banner grabbing
certhound scan -t 1.1.1.1 -p 443 --jarm --banner -o scan.ndjson

# Scan a subnet on multiple ports
certhound scan -t 192.168.1.0/24 -p 443,8443,8080 --jarm --banner -o scan.ndjson

# Scan targets from a file
certhound scan --targets-file targets.txt -p 443,8443 -o scan.ndjson

Analyze Scan Results

Run offline anomaly detection against saved scan data. The analyzer applies 10 rule categories (crypto strength, validity period, subject fields, vendor baseline deviations, fleet statistical outliers, geographic anomalies, serial number patterns, JARM correlation, and C2 signature matching).

# Basic analysis
certhound analyze -i scan.ndjson

# With vendor baselines and C2 signatures
certhound analyze -i scan.ndjson --baselines baselines/ --signatures signatures/

# Only show findings scored 5.0 or higher
certhound analyze -i scan.ndjson --baselines baselines/ --signatures signatures/ --min-score 5.0

Output is both a human-readable text report and JSON to stdout. Use -o report.json to write to a file instead.

Scoring

Each finding is scored 0.0 to 10.0. Host scores use weighted-max aggregation (max + 0.5 * avg(rest), capped at 10.0). Severity tiers: critical >= 8.0, warning >= 5.0, info >= 1.0.

Compare Scans Over Time

Detect certificate changes, new hosts, and disappeared hosts between two scans.

certhound scan -t 10.0.0.0/24 -p 443 -o monday.ndjson
# ... wait ...
certhound scan -t 10.0.0.0/24 -p 443 -o friday.ndjson

certhound correlate -s monday.ndjson -B friday.ndjson

Reports new hosts, disappeared hosts, changed certificates, and new/gone fingerprints.

Hunt for Campaigns via Driftnet

Run predefined queries against the Driftnet API to find anomalous certificate clusters at scale. Requires a Driftnet API token.

# Set token via environment (recommended)
export DRIFTNET_API_TOKEN=your_token_here

# Hunt for SOHO device anomalies
certhound hunt -f hunts/wrthug_asus.yaml --baselines baselines/ --signatures signatures/ --html report.html

# Hunt for C2 infrastructure
certhound hunt -f hunts/c2_hunt.yaml --baselines baselines/ --signatures signatures/ --html c2_report.html

# Save raw records for later offline analysis
certhound hunt -f hunts/c2_hunt.yaml --baselines baselines/ --save-records raw.ndjson

Hunt YAML Format

queries:
  - name: "ASUS AiCloud default certs"
    expression: "title:AiCloud"
    vendor_hint: "asus_wrt"

Included hunt files:

File	Purpose
hunts/wrthug_asus.yaml	WrtHug botnet detection on ASUS routers
hunts/c2_hunt.yaml	Known C2 certificate patterns
hunts/c2_jarm_hunt.yaml	JARM-based C2 detection
hunts/c2_discover.yaml	Broad C2 discovery queries
hunts/campaign_hunt.yaml	General anomaly campaign hunting
hunts/unknown_c2_hunt.yaml	Behavioral anomaly queries for novel C2
hunts/scam_discover.yaml	Fraud, phishing, and impersonation hunting
hunts/all_soho_devices.yaml	All SOHO device classes

Discover Unknown Campaigns

Automated pipeline that finds widely-shared certificate fingerprints across the internet, filters out known vendors and known C2, and scores the remaining unknowns using 12 statistical detectors (Benford's law, JARM matching, Kolmogorov complexity, normalized compression distance, network topology, spectral graph analysis, VPS concentration, Zipf distribution, Jensen-Shannon divergence, and more).

# C2 discovery profile (tuned thresholds, all strategies)
certhound discover -f hunts/c2_discover.yaml \
  --baselines baselines/ --signatures signatures/ \
  --profile c2 \
  --html discover_report.html

# Scam/phishing discovery
certhound discover -f hunts/scam_discover.yaml \
  --baselines baselines/ --signatures signatures/ \
  --profile scam \
  --html scam_report.html

# Deep investigation: re-fetch full data + live-scan top unknowns
certhound discover -f hunts/c2_discover.yaml \
  --baselines baselines/ --signatures signatures/ \
  --profile c2 \
  --deep-investigate 10 --live-scan \
  --html deep_report.html

Profiles

Profile	Min Hosts	Max Hosts	Strategies	Use Case
soho (default)	5	unlimited	fingerprint	SOHO device anomalies
c2	3	500	fingerprint, jarm, property	C2/botnet infrastructure
scam	5	2000	fingerprint, property	Fraud and phishing campaigns

Verdicts

The discover scoring pipeline produces verdicts: MALICIOUS (>= 0.65), SUSPICIOUS (>= 0.35), or BENIGN.

Continuous Monitoring

Poll certificate sources on an interval with alerting to webhooks or Slack.

# Watch via Driftnet with Slack alerts
export DRIFTNET_API_TOKEN=your_token
certhound watch -q "title:AiCloud" \
  --driftnet-api-token "$DRIFTNET_API_TOKEN" \
  --slack-webhook-url https://hooks.slack.com/services/... \
  --baselines baselines/ \
  --interval 300 \
  --min-score 5.0

Supports Driftnet, Censys, and Shodan as data sources. State is persisted to a JSON file for deduplication across restarts.

Vendor Baselines

57 vendor baseline TOML files in baselines/ define what "normal" looks like for each device class. Used to reduce false positives and flag deviations.

Each baseline defines:

• Detection rules: how to identify the device (HTTP title, server banner, cert subject CN, JARM prefix)
• Expected properties: legitimate cert fields (subject CN, issuer, key size, validity, self-signed status)
• Scoring weights: per-deviation scoring adjustments

C2 Signatures

signatures/c2_signatures.toml contains known-bad certificate patterns, JARM fingerprints, and subject regex patterns for C2 frameworks (Cobalt Strike, Metasploit, QuasarRAT, AsyncRAT, SoftEther proxy fleets, and others).

Enrichment Options

Flag	Effect
--jarm	JARM TLS fingerprinting (10 extra connections per host)
--banner	HTTP banner grabbing (Server header, page title)
--geoip-db path.mmdb	MaxMind GeoLite2-City for geographic enrichment
--asn-db path.mmdb	MaxMind GeoLite2-ASN for network enrichment

Requirements

• Rust 1.75+ (edition 2024)
• Network access to targets (scan) or Driftnet API (hunt/discover/watch)
• Optional: MaxMind GeoLite2 databases for GeoIP enrichment

License

See LICENSE file.