Package: pnu-certwatch
InstallationOnce you have installedPythonand its packages managerpip,
use one of the following commands, depending on if you want only this tool, the full set of PNU tools, or PNU plus a selection of additional third-parties tools:pip install pnu-certwatch
pip install PNU
pip install pytnixCERTWATCH(1)NAMEcertwatch - watch X509 certificates expiration datesSYNOPSIScertwatch[--delay|-d SEC]
[--excel|-e FILE]
[--filter|-f DAYS]
[--ip|-i]
[--new|-n]
[--noaltnames|-a]
[--noprogress|-b]
[--savedir|-s DIR]
[--timeout|-t SEC]
[--debug]
[--help|-?]
[--version]
[--]
file [...]DESCRIPTIONThecertwatchutility monitorsX509 certificatesexpiration dates
by processing one or more data files containing lists of hostnames with optional port numbers.It's mainly used to check the expiration date ofHTTPScertificates
(which is the default target when the port number is not indicated),
but the tool is protocol-agnostic and can "talk" to any SNI-aware (Server Name Information)SSL/TLSserver (smtps, imaps, ldaps, etc.)
without making too much assumptions on the correctness of servers certificates.The certificates can be saved to a specified directory with the--savedir|-soption for further analysis with other tools (such asOpenSSL).As it's intended to bulk process a lot of certificates, a progress bar is displayed (can be removed with the--noprogress|-boption)
and the time allowed to get a certificate is limited to a 10 seconds timeout
(can be specified otherwise with the--timeout|-toption, but is not supported on Windows systems).In order to avoid doing aDenial of Service attackon servers hosting many certificates,
a 1 second delay is waited between each certificate request (can be specified otherwise with the--delay|-doption).The tool results are presented as text tables.The main one is the list of certificates successfully fetched, ordered by expiration date.
This list can be filtered with the--filter|-foption to only show certificates expired or expiring within the specified number of days.
You can use the--noaltnames|-aoption in order to stop displaying alternate names contained in certificates,
or the--ip|-ioption to include the IP addresses of servers.The second table is the sorted list of hostnames / hostports where certificates couldn't be fetched,
with our best attempts to identify the reason why.Two additional tables can be generated with the--new|-noption, in order to print the common names and alternate names
unmentioned in your input data files.Finally, for user convenience, all these reports can be generated in a single multi-tabs Excel workbook specified with the--excel|-eoption.OPTIONSOptionsUse--delay|-d SECWait SEC (0-N) seconds between requests--excel|-e FILEOutput results in Excel FILE--filter|-f DAYSShow results expiring in less than DAYS--ip|-iShow IP address of hostnames--new|-nShow unmentioned CN/alt names in input files--noaltnames|-aDon't show alt names in results--noprogress|-bDon't use a progress bar--savedir|-s DIRSave certificates in DIR directory--timeout|-t SECWait SEC (1-N) seconds before aborting a request--debugEnable debug mode--help|-?Print usage and a short help message and exit--versionPrint version and exit--Options processing terminatorENVIRONMENTThe CERTWATCH_DEBUG environment variable can be set to any value to enable debug mode.FILES/usr/local/share/certwatch/tests.txt- config file example using thebadssl.comWeb site for testing live bogus X509 certificates,
withtextandExceloutput.The structure of configuration files is as follows:Everything after a '#' character is a commentBlank lines are alloweddata lines are either:"hostname hostport""hostname"When hostport is not provided, port 443 (HTTPS) is assumedEXIT STATUSThecertwatchutility exits 0 on success, and >0 if an error occurs.EXAMPLESThe following command will makecertwatchprocess your certificates list inmycertslist.txt,
save all certificates in PEM format tomycertsdir, print all possible reports and details to screen
and to an Excel workbook namedcertwatch.out.xlsx, and select or highlight certificates
expired or set to expire in the coming 30 days:# certwatch -in -e certwatch.out.xlsx -s mycertsdir -f 30 mycertslist.txt | tee certwatch.out.txtSaved certificates can then be viewed with theopensslcommand like this for amycert.pemfile:# openssl x509 -inform PEM -in mycert.pem -noout -text | moreSEE ALSOopenssl(1)STANDARDSThecertwatchutility is not a standard UNIX command.It tries to follow thePEP 8style guide forPythoncode.PORTABILITYTested OK under Windows.HISTORYThis implementation was made for thePNU project.Both for my own needs and those of my company, I wanted an easy way to monitor thousands of certificates expiration dates.The initial idea was to use the tool to send an email report of the certificates about to expire, but an Excel report in order to perform all kind of sorts and filtering was quickly necessary...LICENSEIt is available under the3-clause BSD license.AUTHORSHubert TournierCAVEATSUsing this command throughoutgoing proxiesis untested and we provide no option to set the proxy address.
However it should work through reverse proxies on the server side.SECURITY CONSIDERATIONSWhen certificate retrieval is unsuccessful,certwatchwill try to diagnose the issue in different ways, one of which involving
running the systempingcommand. This can be an issue if someone happens to place a command with the same name higher in your PATH.
But working at the IP layer level, which is needed in order to implement theICMPprotocol, requires root privileges which I see as a bigger risk...