search

SSLMate / certspotter

Certificate Transparency Log Monitor
https://sslmate.com/certspotter
Mozilla Public License 2.0
955 stars 83 forks source link

Write a man page #11

Closed AGWA closed 1 year ago

gene1wood commented 8 years ago

Ya, details about the -script argument and the fact that the information about the cert is passed to the script you call via environment variables (and not stdin for example) would be great. Had to do a lot of testing and reading the code to figure out how to use -script

gene1wood commented 8 years ago

And for anyone who's curious before the man page is created, here are the environment variables made available to the script and some example values

Variable Example Value
NOT_AFTER_UNIXTIME 1478711520
CERT_FILENAME /home/jdoe/.certspotter/certs/56/56a6db8cb4906944f6b01c2dc67975ea4d92d541804108d018218a1565599d0d.cert.pem
CERT_PARSEABLE yes
NOT_AFTER 2016-11-09 17:12:00 +0000 UTC
IP_ADDRESSES
ENTRY_INDEX 25955228
FINGERPRINT 56a6db8cb4906944f6b01c2dc67975ea4d92d541804108d018218a1565599d0d
NOT_BEFORE 2016-08-11 17:12:00 +0000 UTC
LOG_URI https://ct.googleapis.com/pilot
CERT_TYPE cert
ISSUER_DN C=US, O=Let's Encrypt, CN=Let's Encrypt Authority X3
DNS_NAMES example.com
SERIAL 3e6f0e8d0083c3393994bb2baedc14cc164
SUBJECT_DN CN=example.com
NOT_BEFORE_UNIXTIME 1470935520
PUBKEY_HASH d646aa65b62452d01025461a66041fd34f9eb1dc43366ea4eef16f79b1ae8a8d
AGWA commented 8 years ago

Yes, that's correct. Note that DNS_NAMES and IP_ADDRESSES are comma-separated.

There might be some changes to how -script works in a future release, which is one of the reasons I didn't document it for version 0.1. Go ahead and use it, just be prepared to update your scripts at some point.

paravoid commented 1 year ago

Hi - Debian maintainer here. I recently wrote manpages for certspotter(8) and certspotter-script(8) (documenting the latter before I even saw this bug even!). This are shipped as of the 0.14.0-1 release, soon in a Debian sid near you. I did not document the other utilities, and in fact stopped shipping submitct in Debian as well (we never shipped ctparsewatch) -- but feel free to tell me I should ;)

In the meantime, you can find these here: https://salsa.debian.org/go-team/packages/certspotter/-/tree/master/debian/man

These are in Markdown for my own sanity, and converted to the man format using lowdown using (basically) lowdown -s -Tman -M name:certspotter -M section:8 -Mdate:2023-01-08. (I like lowdown enough to also maintain it in Debian; if you don't share the sentiments, you can always use something like e.g. pandoc for the conversion!). There is a tiny bit of extra complexity around it as you can see here: https://salsa.debian.org/go-team/packages/certspotter/-/blob/master/debian/rules

Hope these are appropriate and I didn't state anything that wasn't accurate or misrepresent something. Feel free to import these upstream and make any changes you'd like. Happy to help in any other way.

PS. There are some other changes in the Debian package, such as a systemd service/timer/hook system that may be of interest to you. Feel free to have a look.

AGWA commented 1 year ago

Thank you @paravoid ! I took a look at the certspotter man page in 0.14.0-1, and it looks great. I will be importing it and augmenting it with additional detail.

Also, I completely agree with not shipping ctparsewatch or submitct.