tlsanalyzer

tlsanalyzer is a small, dependency-free TLS inspection CLI inspired by sslscan.

It is built for environments where the scanner should be easy to carry, easy to audit and able to run without installing extra packages or fetching runtime dependencies.

Project Status

tlsanalyzer is in beta-readiness review on the v0.31.x line. Feature growth is paused for now; patch releases are limited to bug fixes, documentation updates and compatibility-preserving hardening while the project gathers real-world usage before a future beta/v1 decision.

External feedback is welcome, especially endpoint compatibility reports, policy false positives/negatives, JSON automation issues and installation or release-verification problems. See Feedback and compatibility reports for useful commands and what to include.

What It Does

• Tests TLS protocol support from TLS 1.0 through TLS 1.3.
• Reports negotiated and supported cipher suites.
• Raw-probes TLS 1.3 cipher support when full cipher probing is enabled.
• Reports negotiated key exchange group, ALPN protocol and certificate key/signature metadata.
• Keeps TLS support separate from certificate validation status.
• Supports explicit SNI/certificate name overrides for IP and load balancer scans.
• Prints certificate summaries and optional PEM certificate chains.
• Exports human-readable Markdown reports.
• Emits JSON for scripts and automation.
• Writes SARIF and JUnit XML reports for CI and security dashboards.
• Reads dependency-free JSON config files for repeatable scans.
• Scans target lists with bounded concurrency and retry controls.
• Evaluates configurable TLS policy checks for CI workflows.
• Prints a concise summary for supported TLS versions, certificate validation and cipher findings.
• Builds multi-platform release binaries, Linux packages and verifiable release metadata with GitHub Actions.

Quick Start

Download a binary from the GitHub releases page, then run:

tlsanalyzer --host example.com

Common examples:

tlsanalyzer --host example.com --min-version 1.2
tlsanalyzer --host example.com --json
tlsanalyzer --host example.com --markdown example.com.md
tlsanalyzer --host example.com --policy modern --sarif tls.sarif --junit tls.xml
tlsanalyzer --host example.com --policy modern
tlsanalyzer --config tlsanalyzer.json --target production --profile modern-ci
tlsanalyzer --targets-file targets.json --concurrency 4 --retries 2 --json
tlsanalyzer --host example.com --require-tls 1.3 --forbid-tls 1.0,1.1 --min-cert-days 30
tlsanalyzer --host example.com --compact
tlsanalyzer --host example.com --cert --output example.pem
tlsanalyzer --host 203.0.113.10 --sni example.com
tlsanalyzer --version

Exit codes are stable for CI: 0 means success, 1 means input/runtime/report failure, 2 means CLI flag parsing failed and 3 means enabled policy checks failed. Single-target input validation reports all detected input errors in one run. Certificate policy checks fail when validation is invalid, skipped or unavailable.

Documentation

• Documentation site: GitHub Pages entry point for the project documentation.
• User manual: installation, flags, examples, output formats and operational notes.
• JSON schema v1: machine-readable output contract.
• Compatibility policy: preview stability promises for CLI, JSON, policy and release behavior.
• TLS probe Go package: preview API for raw TLS 1.3 cipher probing.
• Sample Markdown report: example of the generated report format.
• Output examples: small console, JSON, Markdown and CI snippets with evidence semantics.
• Validation matrix: manual real-world smoke checks for release confidence.
• Feedback and compatibility reports: what to report, useful commands and issue guidance for real-world usage.
• P24 readiness audit: beta/v1 and raw-probe-library readiness notes.
• P29 beta-readiness audit: final preview contract review before a beta decision.
• Changelog: release history.
• Backlog: prioritized future work.

Use As A Go Package

The analyzer package exposes the same single-target scan orchestration used by the CLI:

opts := analyzer.DefaultOptions("example.com")
opts.MinVersion = tls.VersionTLS12
opts.PolicyConfig = policy.Config{Name: policy.NameModern}

result, err := analyzer.Run(opts, analyzer.Hooks{})
if err != nil {
	var hookErr *analyzer.HookError
	if errors.As(err, &hookErr) {
		// A caller-provided hook failed.
	}
}

Operational scan failures are returned as structured scan.TLSScanResult statuses such as network_error, timeout and handshake_error. analyzer.Run returns an error only when caller-provided hooks fail.

The tlsprobe package exposes the preview raw TLS 1.3 cipher probe used by the scanner:

results, err := tlsprobe.ProbeTLS13CipherSuites(context.Background(), tlsprobe.Options{
	Address:    net.JoinHostPort("example.com", "443"),
	ServerName: "example.com",
	Timeout:    5 * time.Second,
}, tlsprobe.SupportedTLS13CipherSuites())

tlsprobe is ClientHello-only evidence and does not complete full TLS handshakes. See the TLS probe package documentation for status semantics and current limits.

Build From Source

Requirements:

• Go 1.26.3 or newer

CGO_ENABLED=0 go build -v -ldflags="-X 'github.com/olelbis/tlsanalyzer/build.Version=$(cat VERSION)' -X 'github.com/olelbis/tlsanalyzer/build.BuildUser=Team tlsanalyzer' -X 'github.com/olelbis/tlsanalyzer/build.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)'" -o tlsanalyzer .

Or use the build script:

./scripts/build.sh
./scripts/build.sh --all

Stability & Guarantees

tlsanalyzer is preview software. The core workflow is covered by unit tests, local TLS integration tests, CI and automated release builds, and the JSON v1 output contract is documented for automation consumers.

The scanner is suitable for controlled operational checks and CI policy gates, but findings should still be validated before using them as the sole basis for compliance, audit or production security decisions.

• The documented compatibility policy defines stable preview contracts for exit codes, JSON schema v1, policy behavior and TLS 1.3 evidence labels.
• JSON output uses schema_version: "1.1" and follows the documented JSON schema v1 contract.
• Minor releases may add optional JSON fields; removing or renaming fields requires a new schema version.
• TLS 1.3 cipher suites are raw-probed with minimal ClientHello handshakes when cipher probing is enabled, with per-cipher report evidence and observed-handshake fallback for inconclusive raw probes.
• Raw probe reports include ClientHello-only evidence level, selected key share group, HelloRetryRequest retry metadata and TLS alert codes when available.
• The raw TLS 1.3 probe is available as the preview tlsprobe package inside this module.
• --policy modern is intentionally conservative: invalid, skipped or unavailable certificate validation fails certificate policy checks, and unclassified cipher suites fail weak-cipher checks.
• Custom policy gates can require or forbid TLS versions and ALPN protocols, enforce minimum certificate key size and require a minimum certificate validity window.
• The project remains dependency-free at runtime and uses only the Go standard library.

Release Process

Releases are created by pushing a semantic version tag:

git tag -a vX.Y.Z -m "tlsanalyzer release vX.Y.Z"
git push origin vX.Y.Z

Release checklist:

1. Update VERSION, build/build.go and CHANGELOG.md.
2. Run go test ./..., go test -race ./... and go vet ./....
3. Commit the release preparation changes.
4. Create and push an annotated tag.
5. Run scripts/check-release-alignment.sh to confirm main points at the latest release tag.

GitHub Actions builds Linux, macOS and Windows binaries for amd64 and arm64, Linux .deb and .rpm packages, an SPDX SBOM, SHA256 checksums and GitHub artifact attestations. The matching CHANGELOG.md section is used as the GitHub release body.

Verifying Releases

Download the release assets you need together with checksums.txt, then verify the files:

sha256sum --ignore-missing -c checksums.txt

GitHub artifact attestations can be verified with the GitHub CLI:

gh attestation verify tlsanalyzer-linux-amd64 --repo olelbis/tlsanalyzer

Linux packages include the tlsanalyzer(1) man page:

sudo dpkg -i tlsanalyzer_*.deb
sudo rpm -i tlsanalyzer-*.rpm
man tlsanalyzer

Container Image

Release tags publish a minimal multi-arch image to GitHub Container Registry:

docker run --rm ghcr.io/olelbis/tlsanalyzer:v0.31.3 --host example.com --no-clear
docker run --rm ghcr.io/olelbis/tlsanalyzer:latest --host example.com --policy modern --no-clear

Images are published for linux/amd64 and linux/arm64 with registry SBOM and provenance attestations.