Skip to content

gbiagomba/Handshaker

BranchesTags

Repository files navigation

Handshaker

Handshaker Logo

Version: v7.3.3 | Author: Gilles Biagomba | License: GPL-3.0

Handshaker is a native Rust secure-transport posture engine that probes TLS, SSH, and RDP endpoints without shelling out to external tools. It produces stable, machine-parseable finding IDs, SSL Labs–style grades, CVSS v3.1 risk scores, and supports compliance evaluation, benchmarking, longitudinal diffing, and AI-powered analysis.

Table of Contents

  1. Features
  2. Installation
  3. Flags
  4. Usage
  5. Finding Reference
  6. Finding Audit Matrix
  7. Testssl-Class Coverage Matrix
  8. Running Tests
  9. Using Docker
  10. Using the Makefile
  11. Contributing
  12. License

Features

  • Native protocol probing for TLS (all versions), STARTTLS (SMTP/IMAP/POP3/FTP/LDAP), SSH, and RDP — no openssl CLI or external binaries required
  • Stable finding IDs (HS-{PROTOCOL}-{CATEGORY}-{NNNN}) for reliable CI gating and longitudinal tracking
  • SSL Labs–style scoring — Certificate, Protocol, Key Exchange, Cipher Strength categories and A+/A/B/C/D/F grades
  • CVSS v3.1 configuration risk scoring — max and weighted aggregate scores across all findings
  • Compliance evaluation against YAML policies (PCI-DSS, NIST 800-52r2, CIS-like profiles)
  • Benchmarking and diffing across scan runs to track remediation progress and detect regressions
  • Multiple output formats: JSON, Text, Table, HTML, CSV, SQLite — with optional file output and database persistence
  • Unified file import with handshaker scan --file auto-detection for plain targets, nmap grep/XML, nuclei JSON(L), and testssl JSON
  • Vendor-calibrated finding catalog for all 68 findings, aligned against NVD, Tenable, RFC, and related standards references where applicable
  • Documentation integrity tooling to keep FINDING_INDEX.MD and FINDING_AUDIT_MATRIX.md synchronized with the Rust catalog

Installation

Pre-built Binaries (GitHub Releases)

Download the binary for your platform from the Releases page:

OS Arch Asset name
Linux x86_64 handshaker-linux-x86_64
Linux aarch64 handshaker-linux-aarch64
macOS x86_64 handshaker-macos-x86_64
macOS aarch64 handshaker-macos-aarch64
Windows x86_64 handshaker-windows-x86_64.exe

Install via Cargo

cargo install --git https://github.com/gbiagomba/WeakSSL

Compile from Source

git clone https://github.com/gbiagomba/WeakSSL.git
cd WeakSSL
cargo build --release
# Binary at: target/release/handshaker

Install Scripts

# Linux / macOS
bash scripts/install.sh

# Windows (PowerShell)
.\scripts\install.ps1

Flags

scan

Flag Short Type Default Description
--target -t string — Single target: hostname, IP, host:port, or URL
--file -f string — File input: plain targets, nmap grep/XML, nuclei JSON(L), or testssl JSON
--stdin — bool false Read targets from stdin (one per line)
--ports -p list — Comma-separated port list (e.g. 443,8443,25)
--output — enum json Output format: json|text|table|html|csv|sqlite
--out -o string — Write output to file instead of stdout
--concurrency — number 32 Max parallel scans
--timeout-secs — number 10 Per-target connection timeout in seconds
--policy — string — YAML policy file for compliance evaluation
--fail-on-noncompliant — bool false Exit non-zero when any policy finding fails
--benchmark — string — YAML benchmark profile to evaluate results against
--db — string — SQLite database path to persist results

explain

Argument Description
<ID> Finding ID to look up (e.g. HS-TLS-PROTOCOL-0003)

score

Flag Type Description
--input string Path to JSON results file

benchmark

Flag Type Description
--input string Path to JSON results file
--profile string Path to benchmark YAML profile

diff

Flag Type Description
--left string Baseline JSON results file
--right string New JSON results file to compare against baseline

ai

Flag Type Description
--input string Path to JSON results file
--provider string AI provider name (default: built-in)

db

Subcommand Flag Type Description
init --path string Path to SQLite database file to initialize
list --path string Path to SQLite database file
export --path string Path to SQLite database file
export --run-id string Run ID to export (from db list)

Usage

Quick help

handshaker --help
handshaker scan --help
handshaker db init --help

Detailed manual

handshaker help
handshaker help scan
handshaker help db

Scan examples

# Single HTTPS target
handshaker scan --target example.com --ports 443

# Multiple ports including STARTTLS
handshaker scan --target mail.example.com --ports 25,587,465,993

# Scan a list of hosts and write an HTML report
handshaker scan --file hosts.txt --output html --out report.html

# Import targets from nmap XML output
handshaker scan --file scan.xml --output json --out results.json

# Import targets from nuclei JSONL output
handshaker scan --file nuclei.jsonl

# Import targets from testssl JSON output
handshaker scan --file testssl.json

# Read targets from stdin
cat hosts.txt | handshaker scan --stdin

# Compliance check with CI gate
handshaker scan --target example.com --policy pci.yaml --fail-on-noncompliant

# Scan and benchmark simultaneously
handshaker scan --target example.com --policy pci.yaml --benchmark profile.yaml --db results.db

Explain a finding

handshaker explain HS-TLS-PROTOCOL-0003
handshaker explain HS-SSH-HOSTKEY-0105
handshaker explain HS-TLS-CIPHER-0001

Score results

handshaker score --input results.json

Benchmark results

handshaker benchmark --input results.json --profile default.yaml
handshaker benchmark --input results.json --profile pci-dss.yaml

Diff two scans

# Track remediation progress
handshaker diff --left before.json --right after.json

# Detect weekly regressions
handshaker diff --left week1.json --right week2.json

AI-powered analysis

handshaker ai --input results.json
handshaker ai --input results.json --provider openai

Database workflow

# Initialize a new database
handshaker db init --path handshaker.db

# Store scan results
handshaker scan --target example.com --db handshaker.db

# List stored runs
handshaker db list --path handshaker.db

# Export a specific run as JSON
handshaker db export --path handshaker.db --run-id <RUN-ID>

Finding Reference

FINDING_INDEX.MD is the authoritative reference for all 68 security findings Handshaker can detect. For each finding it lists:

  • ID — stable identifier in HS-{PROTOCOL}-{CATEGORY}-{NNNN} format
  • Title and Severity (Critical / High / Medium / Low / Info)
  • CVSS 3.1 score and vector
  • Description — what the finding means and why it matters
  • Testssl-class mapping — which testssl.sh check category it corresponds to
  • Policy coverage — whether it is enforced under Default, PCI-DSS, NIST 800-52r2, or CIS-Like profiles

Quick lookup from the CLI:

handshaker explain HS-TLS-PROTOCOL-0003

Finding Audit Matrix

FINDING_AUDIT_MATRIX.md is the compact audit companion to FINDING_INDEX.MD. It maps every finding to:

  • current severity
  • current CVSS vector
  • external source basis used during calibration

Generate it from the Rust catalog:

python3 scripts/generate_finding_audit_matrix.py

Verify both finding documents are still synchronized with src/findings/catalog.rs:

python3 scripts/check_finding_index_sync.py

Testssl-Class Coverage Matrix

testssl class Handshaker implementation
protocol enumeration TLS version probing in src/protocols/tls/versions.rs
cipher enumeration Cipher list probing in src/protocols/tls/ciphers.rs
weak ciphers NULL/aNULL/EXPORT/RC4/3DES/MEDIUM checks
certificate validation Expired/not-yet-valid/self-signed/hostname/SHA1/RSA size checks
hostname mismatch HS-TLS-CERT-0004
RSA key size HS-TLS-CERT-0006
SHA1 signature HS-TLS-CERT-0005
forward secrecy indicators HS-TLS-CIPHER-0009
renegotiation posture HS-TLS-PROTOCOL-0008
TLS compression HS-TLS-PROTOCOL-0009
session resumption indicators HS-TLS-SCENARIO-0003
downgrade resilience testing HS-TLS-SCENARIO-0001/0002
SWEET32 exposure HS-TLS-SCENARIO-0005
BEAST exposure HS-TLS-SCENARIO-0006
Logjam weak DH HS-TLS-SCENARIO-0004

Running Tests

# Run the full test suite
make test
# or
cargo test --all

# Run with CI lint + format check
make ci
# equivalent to: cargo fmt --all && cargo test --all && cargo build --release

Current suite size: 101 tests.

Using Docker

# Build the image
docker build -t handshaker .

# Scan a target
docker run --rm handshaker scan --target example.com --ports 443

# Scan a local file (mount current directory)
docker run --rm -v "$(pwd)":/data handshaker scan --file /data/hosts.txt --output html --out /data/report.html

Using the Makefile

Target Description
make build Compile release binary (target/release/handshaker)
make debug Compile debug binary
make run ARGS="..." Build and run with arguments
make install Run install script (scripts/install.sh)
make test Run the full test suite
make verify-docs Verify FINDING_INDEX.MD and FINDING_AUDIT_MATRIX.md against the Rust catalog
make generate-audit-matrix Regenerate FINDING_AUDIT_MATRIX.md from src/findings/catalog.rs
make fmt Format all Rust source files
make ci Run fmt + test + build (for CI pipelines)
make clean Remove build artifacts

Contributing

  1. Fork the repository on GitHub
  2. Create a feature branch: git checkout -b feature/my-change
  3. Make your changes and add tests
  4. Ensure make ci passes without errors
  5. Commit with a descriptive message following Conventional Commits
  6. Open a pull request against main describing the change and its motivation

Please report bugs and request features via GitHub Issues.

License

Handshaker is released under the GNU General Public License v3.0 (GPL-3.0). See the LICENSE file for the full terms.

For commercial use cases that require a different licensing arrangement, contact the author.

About

This tool is designed to test for older versions of TLS/SSL and weak ciphers across a multitude of protocols (e.g., HTTPS, SSH, RDP, etc.)

Resources

Readme

License

GPL-3.0 license
Activity

Stars

1 star

Watchers

1 watching

Forks

1 fork
Report repository

Releases 6

Handshaker v7.5.0 — Scan fix + TLS Posture output Latest
Mar 18, 2026
+ 5 releases

Packages

 
 
 

Contributors

Languages