CipherRun

A Fast, Modular, and Scalable TLS/SSL Security Scanner Written in Rust

CipherRun is a comprehensive TLS/SSL security scanner written in Rust, designed for superior performance, scalability, and modern security testing capabilities.

Author: Marc Rivero (@seifreed)

What Makes CipherRun Unique

Unlike traditional TLS scanners, CipherRun is a complete enterprise security platform with:

83+ Total Features: 47 tlsx-compatible features + 36 unique enterprise capabilities
18 Vulnerability Tests: From Heartbleed to ROBOT, all major CVEs covered
7 Compliance Frameworks: PCI-DSS, NIST, HIPAA, SOC 2, Mozilla, GDPR
TLS Fingerprinting: JA3, JA3S, and JARM with signature databases (91+ signatures)
Certificate Transparency: Real-time streaming from 50+ CT logs with Bloom filter deduplication
Database Backend: PostgreSQL/SQLite with time-series analytics and trend analysis
24/7 Monitoring: Certificate monitoring daemon with 5 alert channels
Policy-as-Code: YAML-based security policies with CI/CD integration
REST API: 14 endpoints + WebSocket with OpenAPI/Swagger documentation
400+ Cipher Suites: Comprehensive testing across all TLS versions (SSLv2 to TLS 1.3)
126+ Client Simulations: Real-world browser and application compatibility testing
5 CA Trust Stores: Mozilla, Apple, Linux, Microsoft, Java

Features

Protocol Testing

All SSL/TLS Protocols: SSLv2, SSLv3, TLS 1.0, TLS 1.1, TLS 1.2, TLS 1.3
Full TLS 1.3 Support: Including 0-RTT and modern extensions
Legacy Protocol Testing: Complete SSLv2/SSLv3 support for compliance checks

Cipher Suite Analysis

400+ Cipher Suites: Comprehensive cipher testing database
Per-Protocol Analysis: Test ciphers for each TLS version
Strength Categories: NULL, Export, Low, Medium, High
Forward Secrecy Detection: ECDHE/DHE cipher identification
AEAD Support: Modern authenticated encryption detection

Vulnerability Detection (18 Checks)

Heartbleed (CVE-2014-0160)
CCS Injection (CVE-2014-0224)
Ticketbleed
ROBOT (Return of Bleichenbacher's Oracle Threat)
POODLE (SSL & TLS variants)
BEAST (CVE-2011-3389)
CRIME (CVE-2012-4929)
BREACH (CVE-2013-3587)
SWEET32 (CVE-2016-2183)
FREAK (CVE-2015-0204)
LOGJAM (CVE-2015-4000)
DROWN (CVE-2016-0800)
LUCKY13 (CVE-2013-0169)
RC4 Biases
Renegotiation Issues
TLS_FALLBACK_SCSV
Winshock
STARTTLS Injection

Certificate Analysis

Chain Validation: Against 5 major CA stores (Mozilla, Apple, Linux, Microsoft, Java)
Revocation Checking: CRL and OCSP support
Certificate Details: Subject, SAN, validity, key strength, signature algorithms
Trust Chain Verification: Complete chain analysis
Extended Validation (EV): EV certificate detection
Certificate Filters: Filter scan results by validation status (expired, self-signed, mismatched, revoked, untrusted)
- --expired / -x: Show only expired certificates
- --self-signed / -s: Show only self-signed certificates
- --mismatched / -m: Show only hostname mismatches
- --revoked / -r: Show only revoked certificates
- --untrusted / -u: Show only untrusted certificates

HTTP Security Headers

HSTS (HTTP Strict Transport Security)
HPKP (HTTP Public Key Pinning) - Deprecated, still checked
CSP (Content Security Policy)
X-Frame-Options, X-XSS-Protection, X-Content-Type-Options
Cookie Security: Secure, HttpOnly, SameSite flags
Server Fingerprinting: Banner and version detection

Client Simulation

126+ Client Profiles: Real-world browser and OS handshakes
Compatibility Testing: Determine which clients can connect
Protocol & Cipher Negotiation: See what each client would use

SSL Labs Rating System

Complete Implementation: Based on SSL Labs Rating Guide
Comprehensive Grading: A+ through F ratings
SSL Labs Compatibility Mode: Aligned with SSL Labs methodology
TLS 1.3 Requirement: Grade A or A+ requires TLS 1.3 support (capped at A- without it)
Component Scoring: Certificate (30%), Protocol (30%), Key Exchange (20%), Cipher (20%)
Smart Capping: Grade limits based on vulnerabilities and weaknesses
Instant Failures: SSLv2, NULL/EXPORT ciphers, expired certificates

STARTTLS Support (14 Protocols)

SMTP, IMAP, POP3, LMTP
FTP, LDAP
PostgreSQL, MySQL
XMPP (Client & Server), IRC
NNTP
ManageSieve (Sieve)
Telnet

Output Formats

Terminal: Colorized, formatted output
JSON: Flat and Pretty variants
CSV: Spreadsheet-compatible
HTML: Rich, styled reports
XML: XML-formatted reports
Log Files: Complete session logs

Mass Scanning

Parallel Mode: Test multiple hosts concurrently
Serial Mode: Sequential testing
Configurable Workers: Control parallelism level
MX Record Testing: Scan all mail servers for a domain
ASN/CIDR Input: Scan entire networks via ASN or CIDR ranges

TLS Fingerprinting

JA3: TLS client fingerprinting with signature database (35+ signatures)
JA3S: TLS server fingerprinting with CDN/Load Balancer detection (56+ signatures)
JARM: Active TLS server fingerprinting with 10 probe handshakes
ClientHello/ServerHello Export: Raw handshake data export (hex, base64, binary formats)

Certificate Transparency Logs

Real-time CT Log Streaming: Monitor certificates from 50+ Google CT logs
Bloom Filter Deduplication: Efficient duplicate detection with 0.01% false positive rate
Sliding Window Algorithm: 1000 entries per batch with configurable poll intervals
Multiple Start Modes: Real-time (now), beginning (full history), or custom index

Database Backend (PostgreSQL + SQLite)

Dual Backend Support: Production (PostgreSQL) and development (SQLite)
Complete Scan History: Time-series queries with certificate deduplication
SQL Migrations: 7 migrations with forward compatibility
CLI Integration: --db-config, --store, --history, --cleanup-days
Repository Pattern: Async sqlx with connection pooling
Analytics Engine: Scan comparison, change detection, trend analysis, dashboard generation

24/7 Certificate Monitoring

Continuous Monitoring: Configurable scan intervals (hourly, daily, weekly)
5 Alert Channels: Email (SMTP), Slack, Microsoft Teams, PagerDuty, Generic Webhooks
8 Change Detection Types: Certificate renewal, issuer change, key size change, etc.
Expiry Warnings: Multi-threshold alerts (30d, 14d, 7d, 1d before expiration)
Alert Deduplication: Prevent notification spam
Graceful Shutdown: SIGTERM/SIGINT signal handlers
Systemd Integration: Production-ready service unit files

Policy-as-Code Engine

YAML Policy Definitions: Declarative security policies with full schema validation
Policy Inheritance: Extends keyword for policy reuse
Exception Management: Domain wildcards, rule-specific exceptions, expiration dates
CI/CD Integration: Exit codes for pipeline integration (0=pass, 1=fail)
Multiple Action Levels: FAIL, WARN, INFO
3 Output Formats: Terminal, JSON, CSV

Compliance Framework Engine

7 Compliance Frameworks:
- PCI-DSS v4.0.1 (Payment Card Industry)
- NIST SP 800-52r2 (Federal guidelines)
- HIPAA (Healthcare encryption)
- SOC 2 Type II (Cloud/SaaS security)
- Mozilla Modern (Maximum security)
- Mozilla Intermediate (Production recommended)
- GDPR (EU data protection)
66 Compliance Requirements: Protocol, cipher, certificate, signature validation
8 Rule Checker Types: Comprehensive security rule engine
4 Output Formats: Terminal, JSON, CSV, HTML

REST API Server

14 RESTful Endpoints + WebSocket: Complete API for integration
Async Background Jobs: Concurrent scan execution with job queue
API Key Authentication: 3 permission levels (read, write, admin)
Rate Limiting: 100 req/min per key (configurable)
OpenAPI/Swagger: Auto-generated documentation
Real-time Progress: WebSocket streaming for scan updates
Production-Ready: CORS, compression (gzip/brotli), request logging

Installation

From Source

# Clone the repository
git clone https://github.com/seifreed/cipherrun.git
cd cipherrun

# Build with cargo
cargo build --release

# The binary will be in target/release/cipherrun
./target/release/cipherrun --help

Using Cargo

cargo install cipherrun

Quick Start

Basic Usage

# Scan a single host
cipherrun example.com

# Scan with specific port
cipherrun example.com:443

# Scan HTTPS URL
cipherrun https://example.com

Protocol Testing

# Test all protocols
cipherrun -p example.com

# Test cipher suites
cipherrun -E example.com              # Ciphers per protocol
cipherrun -e example.com              # All ciphers
cipherrun --fs example.com            # Forward secrecy

Vulnerability Scanning

# All vulnerabilities
cipherrun -U example.com

# Specific vulnerabilities
cipherrun -H example.com              # Heartbleed
cipherrun --robot example.com         # ROBOT
cipherrun -O example.com              # POODLE

STARTTLS Testing

# SMTP
cipherrun -t smtp mail.example.com:587

# IMAP
cipherrun -t imap mail.example.com:143

# Test all MX records for a domain
cipherrun --mx example.com

Output Formats

# JSON output
cipherrun --json results.json example.com

# JSON (pretty-printed)
cipherrun --json results.json --json-pretty example.com

# CSV output
cipherrun --csv results.csv example.com

# HTML report
cipherrun --html report.html example.com

# All formats at once
cipherrun --json --csv --html example.com

Mass Scanning

# Create targets file (one target per line)
cat > targets.txt << EOF
google.com:443
github.com:443
cloudflare.com:443
EOF

# Scan serially
cipherrun -f targets.txt

# Scan in parallel (default: 20 concurrent)
cipherrun -f targets.txt --parallel

# Custom parallelism
cipherrun -f targets.txt --parallel --max-parallel 50

# Export results
cipherrun -f targets.txt --parallel --json mass_results.json

Usage Examples

PCI DSS Compliance Check

# Check PCI DSS requirements:
# - No SSLv2/SSLv3
# - No TLS 1.0/1.1
# - No weak ciphers
# - Strong certificate
cipherrun payment.example.com:443 --html pci_report.html

Mail Server Security Audit

# Test SMTP with STARTTLS
cipherrun -t smtp smtp.example.com:587 \
  --json smtp_results.json --json-pretty \
  --html smtp_report.html

API Endpoint Testing

# Test multiple API endpoints in parallel
cat > api_endpoints.txt << EOF
api.example.com:443
api-staging.example.com:443
api-v2.example.com:443
EOF

cipherrun -f api_endpoints.txt --parallel \
  --json api_security_audit.json --json-pretty

Continuous Security Monitoring

#!/bin/bash
# Weekly security scan script
DATE=$(date +%Y%m%d)
REPORT_DIR="./reports/$DATE"
mkdir -p "$REPORT_DIR"

# Scan critical hosts
cipherrun -f critical_hosts.txt --parallel \
  --json "$REPORT_DIR/scan_results.json" --json-pretty \
  --html "$REPORT_DIR/scan_report.html"

# Check for vulnerabilities and alert
if grep -q '"vulnerable": true' "$REPORT_DIR/scan_results.json"; then
  echo "ALERT: Vulnerabilities found!" | mail -s "Security Alert" [email protected]
fi

TLS Fingerprinting Examples

JA3 Client Fingerprinting

# Calculate JA3 fingerprint and detect client
cipherrun example.com:443 --ja3

# Include full ClientHello in JSON output
cipherrun example.com:443 --ja3 --client-hello --json results.json

# Use custom JA3 signature database
cipherrun example.com:443 --ja3 --ja3-db custom_signatures.json

JA3S Server Fingerprinting

# Calculate JA3S fingerprint and detect CDN/Load Balancer
cipherrun example.com:443 --ja3s

# Include full ServerHello in JSON output
cipherrun example.com:443 --ja3s --server-hello --json results.json

# Detect CDN infrastructure
cipherrun cdn.example.com:443 --ja3s --json cdn_detection.json

JARM Active Fingerprinting

# Perform JARM fingerprinting (10 probes)
cipherrun example.com:443 --jarm

# Export JARM with custom database
cipherrun example.com:443 --jarm --jarm-db signatures.json

Certificate Transparency Log Streaming

# Start streaming certificates from CT logs
cipherrun --ct-logs

# Start from beginning of all logs
cipherrun --ct-logs --ct-beginning

# Start from custom index
cipherrun --ct-logs --ct-index argon2024=12345

# JSON output with custom poll interval
cipherrun --ct-logs --ct-json --ct-poll-interval 120

# Silent mode (no stats)
cipherrun --ct-logs --ct-silent

Database Backend Examples

Initialize Database

# Generate example config
cipherrun --db-config-example database.toml

# Initialize database (create tables)
cipherrun --db-config database.toml --db-init

Store and Query Results

# Store scan results in database
cipherrun example.com:443 --all --db-config database.toml --store

# Query scan history (last 10 scans)
cipherrun --db-config database.toml --history example.com:443

# Query with custom limit
cipherrun --db-config database.toml --history example.com:443 --history-limit 50

# Cleanup old scans (older than 30 days)
cipherrun --db-config database.toml --cleanup-days 30

Database Analytics

# Compare two specific scans
cipherrun --db-config database.toml --compare 123:456

# Detect changes in last 7 days
cipherrun --db-config database.toml --changes example.com:443:7

# Analyze trends in last 30 days
cipherrun --db-config database.toml --trends example.com:443:30

# Generate dashboard data
cipherrun --db-config database.toml --dashboard example.com:443:90

Certificate Monitoring Examples

# Start monitoring daemon
cipherrun --monitor --monitor-config monitor.toml

# Monitor specific domain
cipherrun --monitor --monitor-domain example.com:443

# Monitor multiple domains from file
cipherrun --monitor --monitor-domains domains.txt

# Test alert configuration
cipherrun --test-alert --monitor-config monitor.toml

Policy-as-Code Examples

# Evaluate policy (report mode)
cipherrun example.com:443 --policy production.yaml

# Enforce policy (CI/CD mode - exit 1 on violations)
cipherrun example.com:443 --policy production.yaml --enforce

# Policy evaluation with JSON output
cipherrun example.com:443 --policy policy.yaml --policy-format json

# Policy evaluation with CSV output
cipherrun example.com:443 --policy policy.yaml --policy-format csv

Compliance Framework Examples

# List all available compliance frameworks
cipherrun --list-compliance

# Check PCI-DSS v4.0 compliance
cipherrun example.com:443 --compliance pci-dss-v4

# Check NIST SP 800-52r2 compliance
cipherrun example.com:443 --compliance nist-sp800-52r2

# Compliance check with HTML report
cipherrun example.com:443 --compliance pci-dss-v4 --compliance-format html

# Multiple compliance checks
cipherrun example.com:443 --compliance hipaa --compliance soc2

REST API Server Examples

# Start API server (default: 0.0.0.0:8080)
cipherrun --serve

# Start with Swagger UI documentation
cipherrun --serve --api-swagger

# Custom host and port
cipherrun --serve --api-host 127.0.0.1 --api-port 9000

# Start with configuration file
cipherrun --serve --api-config api.toml

# Generate example API config
cipherrun --api-config-example api.toml

# API server with database backend
cipherrun --serve --db-config database.toml --api-swagger

API Usage Examples

# Health check
curl http://localhost:8080/api/v1/health

# Create scan
curl -X POST http://localhost:8080/api/v1/scan \
  -H "X-API-Key: demo" \
  -H "Content-Type: application/json" \
  -d '{"target": "example.com:443", "all": true}'

# Get scan results
curl http://localhost:8080/api/v1/scan/{id}/results \
  -H "X-API-Key: demo"

# WebSocket progress streaming
wscat -c ws://localhost:8080/api/v1/scan/{id}/stream

Advanced Scanning Features

Pre-Handshake Mode (Fast Certificate Retrieval)

# Fast certificate scanning (2-3x faster)
cipherrun example.com:443 --pre-handshake

# Pre-handshake with multiple targets
cipherrun -f domains.txt --pre-handshake --parallel

Anycast Detection

# Scan all resolved IPs (detect Anycast)
cipherrun example.com:443 --scan-all-ips

# Show differences across IPs
cipherrun cdn.example.com:443 --scan-all-ips --json anycast.json

Custom SNI Options

# Random SNI generation
cipherrun 1.1.1.1:443 --random-sni

# Reverse PTR SNI lookup
cipherrun 8.8.8.8:443 --reverse-ptr-sni

# Custom SNI hostname
cipherrun 1.1.1.1:443 --sni-name example.com

ASN and CIDR Scanning

# Scan entire ASN
cipherrun --asn AS13335

# Scan CIDR range
cipherrun --cidr 1.1.1.0/24

# Parallel scanning with ASN
cipherrun --asn AS13335 --parallel --max-parallel 50

Probe Status and Timing

# Show probe status and timing
cipherrun example.com:443 --probe-status

# Show handshake times
cipherrun example.com:443 --show-times

Hello Data Export

# Export ClientHello/ServerHello in hex
cipherrun example.com:443 --export-hello hex

# Export in base64
cipherrun example.com:443 --export-hello base64

# Export in binary format
cipherrun example.com:443 --export-hello binary

DNS-Only and Response-Only Modes

# Extract only domain names from certificates
cipherrun example.com:443 --dns-only

# Output response data only (no host:port prefix)
cipherrun example.com:443 --response-only

Custom DNS Resolvers and Rate Limiting

# Use custom DNS resolvers
cipherrun example.com:443 --resolvers 8.8.8.8,1.1.1.1

# Add delay between connections
cipherrun example.com:443 --delay 500ms

# Rate limiting for mass scanning
cipherrun -f targets.txt --delay 1s --parallel

Certificate Validation Filtering

Find All Expired Certificates

# Scan all domains and show only expired certificates
cipherrun -f production-domains.txt --expired --json expired-certs.json

Identify Self-Signed Certificates

# Find self-signed certificates in internal infrastructure
cipherrun -f internal-services.txt --self-signed

Detect Hostname Mismatches

# Useful after CDN migrations or multi-domain certificate updates
cipherrun -f cdn-endpoints.txt --mismatched

Find Any Certificate Issues

# Combine multiple filters (OR logic - shows certificates matching ANY filter)
cipherrun -f all-domains.txt \
  --expired \
  --self-signed \
  --untrusted \
  --revoked \
  --phone-out \
  --json certificate-issues.json

Security Audit with Filters

# Find problematic certificates and generate compliance report
cipherrun -f payment-gateways.txt \
  --expired \
  --untrusted \
  --compliance pci-dss-v4 \
  --compliance-format html

See CERTIFICATE_FILTERS.md for detailed filter documentation.

Architecture

CipherRun is built with a modular architecture:

cipherrun/
├── src/
│   ├── cli/              # Command-line interface (800+ lines)
│   ├── protocols/        # TLS/SSL protocol handling (23 modules)
│   ├── ciphers/          # Cipher suite management
│   ├── vulnerabilities/  # Vulnerability tests (18 checks, 24 modules)
│   ├── certificates/     # Certificate analysis (12 modules)
│   ├── http/             # HTTP header testing
│   ├── client_sim/       # Client simulation (126+ profiles)
│   ├── rating/           # SSL Labs rating (4 modules)
│   ├── starttls/         # STARTTLS protocols (14 types, 18 modules)
│   ├── output/           # Output formatters (13 modules: JSON, CSV, HTML, XML)
│   ├── scanner/          # Main scanning engine
│   ├── fingerprint/      # TLS fingerprinting (9 modules)
│   │   ├── ja3.rs        # JA3 client fingerprinting
│   │   ├── ja3s.rs       # JA3S server fingerprinting
│   │   └── jarm.rs       # JARM active fingerprinting
│   ├── ct_logs/          # Certificate Transparency (7 modules)
│   ├── db/               # Database backend (10 modules)
│   │   ├── models/       # Database models (6 types)
│   │   ├── repositories/ # Repository pattern
│   │   └── analytics/    # Scan analytics (4 modules)
│   ├── monitor/          # Certificate monitoring (8 modules)
│   │   └── alerts/       # Alert channels (5 types)
│   ├── policy/           # Policy-as-Code engine (6 modules)
│   │   └── rules/        # Policy rule types (4 modules)
│   ├── compliance/       # Compliance framework engine (7 modules)
│   ├── api/              # REST API server (29 modules)
│   │   ├── routes/       # API endpoints (7 routes)
│   │   ├── middleware/   # Authentication, CORS, rate limiting
│   │   ├── jobs/         # Background job queue
│   │   └── ws/           # WebSocket streaming
│   ├── input/            # Input handling (ASN/CIDR support)
│   └── utils/            # Utilities (21 modules)
├── data/                 # Reference data
│   ├── cipher-mapping.txt        # 400+ cipher definitions
│   ├── client-simulation.txt     # 126+ client profiles
│   ├── ja3_signatures.json       # 35+ JA3 signatures
│   ├── ja3s_signatures.json      # 56+ JA3S signatures
│   ├── jarm_signatures.json      # JARM signature database
│   ├── compliance/               # 7 compliance frameworks (YAML)
│   │   ├── pci_dss_v4.yaml
│   │   ├── nist_sp800_52r2.yaml
│   │   ├── hipaa.yaml
│   │   ├── soc2.yaml
│   │   ├── mozilla_modern.yaml
│   │   ├── mozilla_intermediate.yaml
│   │   └── gdpr.yaml
│   ├── Mozilla.pem               # Mozilla CA store
│   ├── Apple.pem                 # Apple CA store
│   ├── Linux.pem                 # Linux CA store
│   ├── Microsoft.pem             # Microsoft CA store
│   └── Java.pem                  # Java CA store
├── migrations/           # SQL database migrations (7 files)
├── examples/             # Example configurations
│   ├── monitor.toml      # Certificate monitoring config
│   ├── domains.txt       # Domain list for monitoring
│   ├── policies/         # Example policy files
│   └── docker-compose.monitor.yml
└── tests/                # Integration tests (68 tests)

Key Design Principles

Modularity: Each feature is encapsulated in its own module
Performance: Async/await with Tokio for efficient concurrency
Scalability: Designed to scan thousands of hosts efficiently
Accuracy: Precise implementation of security checks
Maintainability: Clear code structure, comprehensive tests

Performance

CipherRun is optimized for speed:

Async I/O: Built on Tokio runtime
Parallel Testing: Multiple hosts and checks concurrently
Minimal Allocations: Low memory footprint
Smart Caching: DNS, certificate chains, protocol results
Connection Reuse: Efficient connection management

Benchmarks

On a typical modern system:

Single Host Scan: ~1-3 seconds (full test suite)
Pre-Handshake Mode: ~0.5-1 second (2-3x faster certificate retrieval)
Parallel Scanning: 100+ hosts per minute
Mass Scanning: 1000+ hosts with --parallel --max-parallel 100
CT Log Streaming: 1000 certificates/batch with <0.01% false positives (Bloom filter)
Memory Usage: < 50MB per scan, ~200MB for CT log streaming
CPU Usage: Scales linearly with available cores
Database Operations: <10ms for inserts, <50ms for complex queries
API Response Time: <100ms for scan initiation, real-time WebSocket updates

Code Statistics

Total Lines of Code: ~50,000+ lines of production Rust
Modules: 150+ source files across 25+ top-level modules
Test Coverage: 484+ tests (unit + integration)
Dependencies: 60+ crates carefully selected for performance and security
Binary Size: ~33MB (release build with LTO and strip)
Compilation Time: ~2-3 minutes (release build)

Command-Line Options

CipherRun has 100+ command-line options organized into categories:

Basic Options

  [URI]                          Target URI (host:port or URL)
  -f, --file <FILE>              Input file with multiple targets
      --mx <DOMAIN>              Test MX records for a domain
  -t, --starttls <PROTOCOL>      STARTTLS protocol (smtp, imap, pop3, etc.)
  -h, --help                     Print help
  -V, --version                  Print version

Protocol Testing

  -p, --protocols                Test all protocols
      --ssl2                     Test only SSLv2
      --ssl3                     Test only SSLv3
      --tls10                    Test only TLS 1.0
      --tls11                    Test only TLS 1.1
      --tls12                    Test only TLS 1.2
      --tls13                    Test only TLS 1.3
      --tlsall                   Test all TLS protocols (skip SSL)

Cipher Testing

  -e, --each-cipher              Test all ciphers
  -E, --cipher-per-proto         Test ciphers per protocol
  -s, --std                      Test standard cipher categories
      --fs                       Forward secrecy ciphers only
      --show-ciphers             List all supported ciphers
      --no-ciphersuites          Skip cipher enumeration

Vulnerability Testing

  -U, --vulnerable               Test all vulnerabilities
  -H, --heartbleed               Test Heartbleed (CVE-2014-0160)
  -I, --ccs                      Test CCS injection (CVE-2014-0224)
  -T, --ticketbleed              Test Ticketbleed
      --robot                    Test ROBOT
  -R, --renegotiation            Test renegotiation vulnerabilities
  -C, --crime                    Test CRIME (CVE-2012-4929)
  -B, --breach                   Test BREACH (CVE-2013-3587)
  -O, --poodle                   Test POODLE
  -Z, --tls-fallback             Test TLS_FALLBACK_SCSV
  -W, --sweet32                  Test SWEET32 (CVE-2016-2183)
  -A, --beast                    Test BEAST (CVE-2011-3389)
  -L, --lucky13                  Test LUCKY13 (CVE-2013-0169)
      --freak                    Test FREAK (CVE-2015-0204)
  -J, --logjam                   Test LOGJAM (CVE-2015-4000)
  -D, --drown                    Test DROWN (CVE-2016-0800)
      --early-data               Test 0-RTT/Early Data (TLS 1.3)

TLS Fingerprinting

      --ja3                      Calculate JA3 client fingerprint [default: true]
      --ja3s                     Calculate JA3S server fingerprint [default: true]
      --jarm                     Calculate JARM server fingerprint [default: true]
      --client-hello             Include ClientHello in JSON output
      --server-hello             Include ServerHello in JSON output
      --ja3-db <FILE>            Custom JA3 signature database
      --ja3s-db <FILE>           Custom JA3S signature database
      --jarm-db <FILE>           Custom JARM signature database

Certificate Transparency

      --ct-logs                  Enable CT log streaming mode
      --ct-beginning             Start from beginning of CT logs
      --ct-index <SOURCE=INDEX>  Start from custom index
      --ct-poll-interval <SEC>   Poll interval in seconds [default: 60]
      --ct-batch-size <NUM>      Batch size [default: 1000]
      --ct-json                  Output CT entries as JSON
      --ct-silent                Silent mode (no stats)

Database Backend

      --db-config <FILE>         Database configuration file (TOML)
      --store                    Store scan results in database
      --history <HOST:PORT>      Query scan history
      --history-limit <NUM>      Limit for history results [default: 10]
      --cleanup-days <DAYS>      Delete scans older than N days
      --db-init                  Initialize database (create tables)
      --db-config-example <FILE> Generate example database config

Database Analytics

      --compare <ID1:ID2>        Compare two scans by ID
      --changes <HOST:PORT:DAYS> Detect changes in last N days
      --trends <HOST:PORT:DAYS>  Analyze trends in last N days
      --dashboard <HOST:PORT:DAYS> Generate dashboard data

Certificate Monitoring

      --monitor                  Start monitoring daemon
      --monitor-config <FILE>    Monitoring configuration file (TOML)
      --monitor-domains <FILE>   File with domains to monitor
      --monitor-domain <HOST:PORT> Single domain to monitor
      --test-alert               Test alert channels

Policy-as-Code

      --policy <FILE>            Policy file to enforce (YAML)
      --enforce                  Exit with error on policy violations
      --policy-format <FORMAT>   Policy output format [default: terminal]
                                 Options: terminal, json, csv

Compliance Frameworks

      --compliance <FRAMEWORK>   Compliance framework to evaluate
                                 Options: pci-dss-v4, nist-sp800-52r2,
                                 hipaa, soc2, mozilla-modern,
                                 mozilla-intermediate, gdpr
      --compliance-format <FORMAT> Compliance output format [default: terminal]
                                   Options: terminal, json, csv, html
      --list-compliance          List available compliance frameworks

REST API Server

      --serve                    Start REST API server
      --api-host <HOST>          API server host [default: 0.0.0.0]
      --api-port <PORT>          API server port [default: 8080]
      --api-config <FILE>        API configuration file (TOML)
      --api-max-concurrent <NUM> Max concurrent scans [default: 10]
      --api-swagger              Enable Swagger UI documentation
      --api-config-example <FILE> Generate example API config

Advanced Scanning

      --pre-handshake            Pre-handshake mode (fast certificate retrieval)
      --scan-all-ips             Scan all resolved IPs (Anycast detection)
      --random-sni               Use random SNI generation
      --reverse-ptr-sni          Use reverse PTR for SNI
      --probe-status             Show probe status with timing
      --export-hello <FORMAT>    Export Hello data (hex, base64, binary)

Input Options

      --asn <ASN>                Scan entire ASN (e.g., AS13335)
      --cidr <CIDR>              Scan CIDR range (e.g., 1.1.1.0/24)

Output Options

      --dns-only                 Output only domain names from certificates
      --response-only            Output response data only (no host:port)
      --resolvers <IPS>          Custom DNS resolvers (comma-separated)
      --delay <DURATION>         Delay between connections (e.g., "200ms", "1s")

Certificate Filters

  -x, --expired                  Show only expired certificates
  -s, --self-signed              Show only self-signed certificates
  -m, --mismatched               Show only hostname mismatched certificates
  -r, --revoked                  Show only revoked certificates
  -u, --untrusted                Show only untrusted certificates

Output Formats

      --json <FILE>              JSON output file
      --json-pretty              Pretty-print JSON
      --csv <FILE>               CSV output file
      --html <FILE>              HTML output file
      --xml <FILE>               XML output file
  -o, --output-all <BASENAME>    Output all formats with basename

Network Options

  -4                             Use IPv4 only
  -6                             Use IPv6 only
      --ip <IP>                  Specific IP to test
      --proxy <HOST:PORT>        HTTP proxy
      --test-all-ips             Test all resolved IPs
      --first-ip-only            Scan only first resolved IP

Timing & Retry

      --socket-timeout <SEC>     Socket timeout in seconds
      --connect-timeout <SEC>    Connection timeout in seconds
      --sleep <MSEC>             Sleep between requests in milliseconds
      --max-retries <NUM>        Max retries for failures [default: 3]
      --retry-backoff <MSEC>     Initial backoff duration [default: 100]
      --max-backoff <MSEC>       Max backoff duration [default: 5000]
      --no-retry                 Disable retry logic

Miscellaneous

  -q, --quiet                    Quiet mode (no banner)
  -v, --verbose                  Verbose output (can be repeated: -vvv)
      --parallel                 Parallel scanning mode
      --max-parallel <N>         Max parallel workers [default: 20]
      --color <MODE>             Color mode (0-3) [default: 2]
      --no-color                 Disable colored output
      --phone-out                Enable CRL/OCSP checks
      --hardfail                 Hard fail on revocation errors
      --show-times               Show handshake times
      --sni-name <NAME>          Custom SNI hostname
  -c, --client-simulation        Test client simulations
  -9, --full                     Run full test suite

For complete documentation of all 100+ options, run:

cipherrun --help

Docker Testing Environment

CipherRun includes a complete Docker testing environment with network analysis tools for debugging and development:

Quick Start with Docker

# Build and start environment
make quickstart

# Test a domain
make test-domain DOMAIN=google.com

# Compare ClientHello packets (for debugging TLS issues)
make compare DOMAIN=example.com

# Run batch tests
make batch

# Enter container for manual testing
make shell

Tools Included

Network Analysis: tcpdump, tshark, nmap
SSL/TLS Tools: openssl, sslscan, testssl.sh
CipherRun: Built in release mode
Automated Scripts: Traffic capture, ClientHello comparison, batch testing

Docker Commands

make build          # Build Docker image
make run            # Start container
make shell          # Enter container
make stop           # Stop container
make rebuild        # Rebuild from scratch

make compare DOMAIN=<host>   # Compare OpenSSL vs CipherRun ClientHello
make capture DOMAIN=<host>   # Capture traffic during scan
make results                 # Show latest results
make captures                # Show PCAP files

See docs/DOCKER.md for complete Docker documentation.

Testing

CipherRun includes comprehensive test coverage:

Unit Tests

# Run all unit tests
cargo test

# Run with output
cargo test -- --nocapture

Integration Tests

# Run integration tests (requires network)
cargo test --test integration_badssl -- --ignored
cargo test --test integration_vulnerabilities -- --ignored
cargo test --test integration_starttls -- --ignored

Real Server Testing

CipherRun's integration tests use real servers:

badssl.com: Various TLS misconfigurations
Gmail SMTP/IMAP: STARTTLS testing
Major websites: Google, GitHub, Cloudflare

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Setup

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Clone and build
git clone https://github.com/seifreed/cipherrun.git
cd cipherrun
cargo build

# Run tests
cargo test

# Run with logging
RUST_LOG=debug cargo run -- example.com

License and Attribution

This software is licensed under GPL-3.0. When using or modifying CipherRun:

Attribution to the original author (Marc Rivero / @seifreed) is required
Source code must be published if distributing
Derivative works must also use the GPL-3.0 license

See the License section below for complete details.

Support the Project

If you find CipherRun useful, consider supporting its development:

Your support helps maintain and improve CipherRun.

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
.cargo		.cargo
data		data
docker/scripts		docker/scripts
docs		docs
examples		examples
migrations		migrations
scripts		scripts
sdk/python		sdk/python
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
NOTICE		NOTICE
README.md		README.md
database.toml.example		database.toml.example
docker-compose.yml		docker-compose.yml

License

seifreed/CipherRun

Folders and files

Latest commit

History

Repository files navigation

CipherRun

What Makes CipherRun Unique

Features

Protocol Testing

Cipher Suite Analysis

Vulnerability Detection (18 Checks)

Certificate Analysis

HTTP Security Headers

Client Simulation

SSL Labs Rating System

STARTTLS Support (14 Protocols)

Output Formats

Mass Scanning

TLS Fingerprinting

Certificate Transparency Logs

Database Backend (PostgreSQL + SQLite)

24/7 Certificate Monitoring

Policy-as-Code Engine

Compliance Framework Engine

REST API Server

Installation

From Source

Using Cargo

Quick Start

Basic Usage

Protocol Testing

Vulnerability Scanning

STARTTLS Testing

Output Formats

Mass Scanning

Usage Examples

PCI DSS Compliance Check

Mail Server Security Audit

API Endpoint Testing

Continuous Security Monitoring

TLS Fingerprinting Examples

JA3 Client Fingerprinting

JA3S Server Fingerprinting

JARM Active Fingerprinting

Certificate Transparency Log Streaming

Database Backend Examples

Initialize Database

Store and Query Results

Database Analytics

Certificate Monitoring Examples

Policy-as-Code Examples

Compliance Framework Examples

REST API Server Examples

API Usage Examples

Advanced Scanning Features

Pre-Handshake Mode (Fast Certificate Retrieval)

Anycast Detection

Custom SNI Options

ASN and CIDR Scanning

Probe Status and Timing

Hello Data Export

DNS-Only and Response-Only Modes

Custom DNS Resolvers and Rate Limiting

Certificate Validation Filtering

Find All Expired Certificates

Identify Self-Signed Certificates

Detect Hostname Mismatches

Find Any Certificate Issues

Security Audit with Filters

Architecture

Key Design Principles

Performance

Benchmarks

Code Statistics

Command-Line Options

Basic Options

Protocol Testing

Cipher Testing

Vulnerability Testing

Packages