Pim van Pelt
e18a89dcf0
Introduces a static-binary build and Debian package (amd64/arm64) with version/commit/date stamped via -ldflags. Ships section-1 manpages for ctool, ctfetch, and ctail. Adds a `version` subcommand reachable as `ctool version`, `ctool -version`, `ctool --version`, `ctool fetch version`, `ctool tail version`, and via the ctfetch/ctail symlinks. Adds tests covering the dispatcher, fetch/tail argument parsing, and the formatter/helper functions. Adds a retrofit design document modelled on the vpp-maglev one, with FRs and NFRs for each tool and the dispatcher. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
131 lines
3.1 KiB
Groff
131 lines
3.1 KiB
Groff
.TH CTFETCH 1 "April 2026" "ctool" "User Commands"
|
|
.SH NAME
|
|
ctfetch \- fetch and decode Static CT log entries as JSON
|
|
.SH SYNOPSIS
|
|
.B ctfetch
|
|
[\fIflags\fR] \fIlog\-url\fR \fIleaf\-index\fR [\fB+sct\fR] [\fB+issuer\fR] [\fB+ctlog\fR] [\fB+all\fR]
|
|
.PP
|
|
.B ctfetch
|
|
[\fIflags\fR] \fItile\-url\-or\-file\fR [\fB+sct\fR] [\fB+issuer\fR] [\fB+ctlog\fR] [\fB+all\fR]
|
|
.PP
|
|
.B ctfetch version
|
|
.SH DESCRIPTION
|
|
.B ctfetch
|
|
reads entries from a Static CT API log (c2sp.org/static\-ct\-api) and
|
|
writes them to stdout as pretty\-printed JSON.
|
|
It is also available as the
|
|
.B fetch
|
|
subcommand of
|
|
.BR ctool (1);
|
|
the two invocations are equivalent.
|
|
.PP
|
|
Two modes are distinguished by whether the second positional argument
|
|
parses as an integer.
|
|
.SS Leaf\-index mode
|
|
.PP
|
|
.RS
|
|
.EX
|
|
ctfetch <log\-url> <leaf\-index> [modifiers...]
|
|
.EE
|
|
.RE
|
|
.PP
|
|
Fetches the data tile that contains
|
|
.IR leaf\-index ,
|
|
decompresses it, and decodes the single entry at that position.
|
|
.SS Tile\-dump mode
|
|
.PP
|
|
.RS
|
|
.EX
|
|
ctfetch <tile\-url\-or\-file> [modifiers...]
|
|
.EE
|
|
.RE
|
|
.PP
|
|
Fetches (or reads from disk) one tile and decodes every entry in it.
|
|
Hash tiles (\fB/tile/N/\fR..., N \(>= 0) produce the list of 32\-byte
|
|
SHA\-256 node hashes; output modifiers are an error in this case.
|
|
Data tiles (\fB/tile/data/\fR...) produce the full decoded
|
|
entry list.
|
|
.SH OUTPUT MODIFIERS
|
|
The modifiers are positional tokens beginning with
|
|
.BR + .
|
|
They control which optional fields are computed and included in the
|
|
JSON output.
|
|
.TP
|
|
.B +sct
|
|
Parse the embedded Signed Certificate Timestamp list from final
|
|
(non\-precert) certificates and include it alongside the entry.
|
|
.TP
|
|
.B +issuer
|
|
Fetch the issuer certificate from the log's
|
|
.B /issuer/<fp>
|
|
endpoint and include parsed issuer details.
|
|
.TP
|
|
.B +ctlog
|
|
Look up each SCT's log ID in the CT log list (see
|
|
.BR \-\-logs\-list\-url )
|
|
and enrich it with operator and state information.
|
|
.TP
|
|
.B +all
|
|
Shorthand for
|
|
.BR +sct " " +issuer " " +ctlog .
|
|
.SH FLAGS
|
|
.TP
|
|
.BI \-\-logs\-list\-url " url"
|
|
CT log list JSON used for
|
|
.B +ctlog
|
|
enrichment.
|
|
Default:
|
|
.IR https://www.gstatic.com/ct/log_list/v3/all_logs_list.json .
|
|
.TP
|
|
.BI \-\-monitoring\-url " url"
|
|
Log root URL used for
|
|
.B +issuer
|
|
lookups when the input is a local tile file. Ignored when the input
|
|
is already an HTTP(S) URL; in that case the root is derived by
|
|
stripping
|
|
.I /tile/...
|
|
from the path.
|
|
.SH SUBCOMMANDS
|
|
.TP
|
|
.B version
|
|
Print the binary's version, git commit hash, and build date, then
|
|
exit.
|
|
.SH EXAMPLES
|
|
Fetch one entry with all enrichments:
|
|
.PP
|
|
.RS
|
|
.EX
|
|
$ ctfetch https://halloumi2026h1.mon.ct.ipng.ch 629794635 +all
|
|
.EE
|
|
.RE
|
|
.PP
|
|
Dump a data tile straight off the web:
|
|
.PP
|
|
.RS
|
|
.EX
|
|
$ ctfetch https://halloumi2026h1.mon.ct.ipng.ch/tile/data/x002/x460/135 +sct +ctlog
|
|
.EE
|
|
.RE
|
|
.PP
|
|
Dump a tile from disk, pointing at a monitoring URL so
|
|
.B +issuer
|
|
lookups can find the issuer endpoint:
|
|
.PP
|
|
.RS
|
|
.EX
|
|
$ ctfetch \-\-monitoring\-url https://halloumi2026h1.mon.ct.ipng.ch tile.bin +issuer
|
|
.EE
|
|
.RE
|
|
.SH NOTES
|
|
Partial tiles (the
|
|
.I .p/N
|
|
suffix) are tried first; on 404 the full tile is fetched
|
|
automatically.
|
|
The CT log list and any fetched issuer certificates are cached in
|
|
memory for the lifetime of a single invocation.
|
|
.SH SEE ALSO
|
|
.BR ctool (1),
|
|
.BR ctail (1)
|
|
.SH AUTHOR
|
|
Pim van Pelt <pim@ipng.ch>
|