tlsanalyzer

README

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.

What It Does

• Tests TLS protocol support from TLS 1.0 through TLS 1.3.
• Reports negotiated and supported cipher suites.
• 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.
• Evaluates simple TLS policy checks for CI workflows.
• Prints a concise summary for supported TLS versions, certificate validation and cipher findings.
• Builds multi-platform release binaries 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
tlsanalyzer --host example.com --cert --output example.pem
tlsanalyzer --host 203.0.113.10 --sni example.com

Policy failures return exit code 3, which makes --policy modern useful in CI. Certificate policy checks fail when validation is invalid, skipped or unavailable.

Documentation

• User manual: installation, flags, examples, output formats and operational notes.
• JSON schema v1: machine-readable output contract.
• Sample Markdown report: example of the generated report format.
• Changelog: release history.
• Backlog: prioritized future work.

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

Project Status

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.

Stability & Guarantees

• JSON output uses schema_version: "1.0" 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 observed from handshakes, not forced individually, due to Go TLS API limitations.
• --policy modern is intentionally conservative: invalid, skipped or unavailable certificate validation fails certificate policy checks, and unclassified cipher suites fail weak-cipher checks.
• 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, then uses the matching CHANGELOG.md section as the GitHub release body.