Surveyor is a cryptographic inventory and migration-readiness tool, starting with explicit TLS-facing targets.
It starts with a narrow question: what does a TLS-facing service actually present today, and what does that imply for post-quantum migration work tomorrow?
The point is not to produce a vague “PQ score”. The point is to give teams a clear inventory of what they are running, where classical public-key dependencies still exist, and what probably needs attention first.
Surveyor is in early development, but v0.1.0 has been released.
The first milestone was intentionally narrow. It shipped as a TLS inventory MVP for explicitly provided targets.
The current repository already includes:
- target parsing and validation
- TLS connection and protocol inspection
- certificate chain parsing
- public-key and signature algorithm inventory
- conservative readiness classification
- machine-readable and human-readable reporting
The repository now includes a usable CLI path for the TLS inventory slice, with both config-driven and explicit command-line targets.
v0.1.0 is published here:
https://github.com/steadytao/surveyor/releases/tag/v0.1.0
Release assets include downloadable binaries for Linux, macOS and Windows on amd64 and arm64.
Post-quantum migration is not mainly a cryptography-library problem. For most teams it is an inventory and prioritisation problem.
Before anything can be migrated, someone needs to answer practical questions:
- where classical public-key cryptography is in use
- which services, certificates, and trust paths depend on it
- what is externally exposed
- what is straightforward to replace
- what needs manual review or architectural change
Surveyor exists to make that visible.
Version one is intentionally limited to TLS-facing services that are explicitly provided as targets.
That means Surveyor currently aims to:
- connect to explicit TLS targets
- collect handshake and certificate facts
- classify migration posture conservatively
- emit structured results and a readable report
It does not currently aim to:
- implement post-quantum cryptography
- replace PKI systems
- scan arbitrary address ranges by default
- act as a general-purpose vulnerability scanner
- produce exploit tooling
- flatten complex migration work into a binary “quantum-safe” label
Surveyor currently has implemented internal slices for:
- YAML config parsing and validation for explicit TLS targets
- TLS handshake collection against explicit targets
- X.509 certificate and chain metadata extraction
- conservative readiness classification
- canonical JSON report assembly
- derived Markdown reporting
The current code and docs are organised around JSON as the canonical result contract and Markdown as derived output.
The current CLI supports the TLS inventory path:
surveyor scan tls -c examples/targets.yaml -o report.md -j report.jsonFor ad hoc local or one-off scans, explicit command-line targets are also supported:
surveyor scan tls -t example.com:443,127.0.0.1:8000,[::1]:443Rules:
- use exactly one of
--configor--targets --targetsrequires explicithost:portentries- IPv6 targets must use bracket form, for example
[::1]:443 - if no output paths are given, Markdown is written to stdout
Example local verification:
go build ./cmd/surveyor
./surveyor scan tls -c examples/targets.yaml -o report.md -j report.jsonFor the current implementation boundaries, see:
- docs/architecture.md
- docs/output-schema.md
- docs/classification.md
- docs/references.md
- docs/safety.md
- docs/release-checklist.md
https://github.com/steadytao/surveyor/milestone/1
Status: shipped in v0.1.0
- repository baseline
- configuration loading and validation
- TLS target connection
- certificate chain parsing
- public-key and signature algorithm inventory
- initial readiness classification
- JSON reporting
- Markdown reporting
Later milestones may expand into other cryptographic surfaces, but not before the TLS path is solid.
Surveyor is written in Go.
The repository currently contains a working cmd/surveyor entrypoint for the TLS inventory slice, plus the internal packages and tests behind it.
For now, the most useful verification command is:
go build ./cmd/surveyor
go vet ./...
go test ./...The expected local build flow is:
git clone https://github.com/steadytao/surveyor.git
cd surveyor
go build ./cmd/surveyorThen run:
./surveyor scan tls -c examples/targets.yaml -o report.md -j report.jsonWell-scoped contributions are welcome.
If you want to work on Surveyor, start by reading .github/CONTRIBUTING.md. For larger changes, please open an issue first so the scope and direction can be discussed before work starts.
If you believe you have found a security issue in Surveyor itself, do not open a public issue.
See .github/SECURITY.md for reporting instructions.
Surveyor is licensed under the Apache License 2.0. See LICENSE.
See CHANGELOG.md.