[](https://github.com/ServierHub/)
[](https://repology.org/project/python:pnu-certwatch/versions)
[](https://repology.org/project/python:pnu-certwatch/versions)
# Installation
Once you have installed [Python](https://www.python.org/downloads/) and its packages manager [pip](https://pip.pypa.io/en/stable/installation/),
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 pytnix
```
# CERTWATCH(1)
## NAME
certwatch - Watch X509 certificates expiration dates
## SYNOPSIS
**certwatch**
\[--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 [...]
## DESCRIPTION
The **certwatch** utility monitors [X509 certificates](https://en.wikipedia.org/wiki/X.509) expiration 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 of [HTTPS](https://en.wikipedia.org/wiki/HTTPS) certificates
(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](https://en.wikipedia.org/wiki/Server_Name_Indication))
[SSL/TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security) server (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|-s* option for further analysis with other tools (such as [OpenSSL](https://www.openssl.org/)).
As it's intended to bulk process a lot of certificates, a progress bar is displayed (can be removed with the *--noprogress|-b* option)
and the time allowed to get a certificate is limited to a 10 seconds timeout
(can be specified otherwise with the *--timeout|-t* option, but is not supported on Windows systems).
In order to avoid doing a [Denial of Service attack](https://en.wikipedia.org/wiki/Denial-of-service_attack) on servers hosting many certificates,
a 1 second delay is waited between each certificate request (can be specified otherwise with the *--delay|-d* option).
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|-f* option to only show certificates expired or expiring within the specified number of days.
You can use the *--noaltnames|-a* option in order to stop displaying alternate names contained in certificates,
or the *--ip|-i* option 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|-n* option, 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|-e* option.
### OPTIONS
Options | Use
------- | ---
--delay\|-d SEC|Wait SEC (0-N) seconds between requests
--excel\|-e FILE|Output results in Excel FILE
--filter\|-f DAYS|Show results expiring in less than DAYS
--ip\|-i|Show IP address of hostnames
--new\|-n|Show unmentioned CN/alt names in input files
--noaltnames\|-a|Don't show alt names in results
--noprogress\|-b|Don't use a progress bar
--savedir\|-s DIR|Save certificates in DIR directory
--timeout\|-t SEC|Wait SEC (1-N) seconds before aborting a request
--debug|Enable debug mode
--help\|-?|Print usage and a short help message and exit
--version|Print version and exit
--|Options processing terminator
## ENVIRONMENT
The CERTWATCH_DEBUG environment variable can be set to any value to enable debug mode.
## FILES
[/usr/local/share/certwatch/tests.txt](https://github.com/HubTou/certwatch/blob/main/data/tests.txt) - config file example using the [badssl.com](https://badssl.com) Web site for testing live bogus X509 certificates,
with [text](https://github.com/HubTou/certwatch/blob/main/data/tests_output.txt)
and [Excel](https://github.com/HubTou/certwatch/blob/main/data/tests_output.xlsx) output.
The structure of configuration files is as follows:
* Everything after a '#' character is a comment
* Blank lines are allowed
* data lines are either:
* "hostname hostport"
* "hostname"
* When hostport is not provided, port 443 (HTTPS) is assumed
## EXIT STATUS
The **certwatch** utility exits 0 on success, and >0 if an error occurs.
## EXAMPLES
The following command will make **certwatch** process your certificates list in *mycertslist.txt*,
save all certificates in PEM format to *mycertsdir*, print all possible reports and details to screen
and to an Excel workbook named *certwatch.out.xlsx*, and select or highlight certificates
expired or set to expire in the coming 30 days:
```Shell
# certwatch -in -e certwatch.out.xlsx -s mycertsdir -f 30 mycertslist.txt | tee certwatch.out.txt
```
Saved certificates can then be viewed with the **openssl** command like this for a *mycert.pem* file:
```Shell
# openssl x509 -inform PEM -in mycert.pem -noout -text | more
```
## SEE ALSO
[openssl(1)](https://www.openssl.org/docs/manmaster/man1/openssl.html)
## STANDARDS
The **certwatch** utility is not a standard UNIX command.
It tries to follow the [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guide for [Python](https://www.python.org/) code.
## PORTABILITY
Tested OK under Windows.
Packaged for FreeBSD as pyXX-pnu-certwatch.
## HISTORY
This implementation was made for the [PNU project](https://github.com/HubTou/PNU).
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...
## LICENSE
It is available under the [3-clause BSD license](https://opensource.org/licenses/BSD-3-Clause).
## AUTHORS
[Hubert Tournier](https://github.com/HubTou)
## CAVEATS
Using this command through [outgoing proxies](https://en.wikipedia.org/wiki/Proxy_server) is untested and we provide no option to set the proxy address.
However it should work through reverse proxies on the server side.
## SECURITY CONSIDERATIONS
When certificate retrieval is unsuccessful, **certwatch** will try to diagnose the issue in different ways, one of which involving
running the system **[ping](https://en.wikipedia.org/wiki/Ping_(networking_utility))** command. 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 the [ICMP](https://en.wikipedia.org/wiki/Internet_Control_Message_Protocol) protocol, requires root privileges which I see as a bigger risk...
Raw data
{
"_id": null,
"home_page": "https://github.com/HubTou/certwatch/",
"name": "pnu-certwatch",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "pnu-project",
"author": "Hubert Tournier",
"author_email": "hubert.tournier@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a6/9c/83f14693d0c168377f76f247a9dffa228b1f26c8586a504900166860cff7/pnu-certwatch-1.0.3.tar.gz",
"platform": null,
"description": "[](https://github.com/ServierHub/)\n[](https://repology.org/project/python:pnu-certwatch/versions)\n[](https://repology.org/project/python:pnu-certwatch/versions)\n\n# Installation\nOnce you have installed [Python](https://www.python.org/downloads/) and its packages manager [pip](https://pip.pypa.io/en/stable/installation/),\nuse 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:\n\n```\npip install pnu-certwatch\npip install PNU\npip install pytnix\n```\n\n# CERTWATCH(1)\n\n## NAME\ncertwatch - Watch X509 certificates expiration dates\n\n## SYNOPSIS\n**certwatch**\n\\[--delay|-d SEC\\]\n\\[--excel|-e FILE\\]\n\\[--filter|-f DAYS\\]\n\\[--ip|-i\\]\n\\[--new|-n\\]\n\\[--noaltnames|-a\\]\n\\[--noprogress|-b\\]\n\\[--savedir|-s DIR\\]\n\\[--timeout|-t SEC\\]\n\\[--debug\\]\n\\[--help|-?\\]\n\\[--version\\]\n\\[--\\]\nfile [...]\n\n## DESCRIPTION\nThe **certwatch** utility monitors [X509 certificates](https://en.wikipedia.org/wiki/X.509) expiration dates\nby processing one or more data files containing lists of hostnames with optional port numbers.\n\nIt's mainly used to check the expiration date of [HTTPS](https://en.wikipedia.org/wiki/HTTPS) certificates\n(which is the default target when the port number is not indicated),\nbut the tool is protocol-agnostic and can \"talk\" to any SNI-aware ([Server Name Information](https://en.wikipedia.org/wiki/Server_Name_Indication))\n[SSL/TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security) server (smtps, imaps, ldaps, etc.)\nwithout making too much assumptions on the correctness of servers certificates.\n\nThe certificates can be saved to a specified directory with the *--savedir|-s* option for further analysis with other tools (such as [OpenSSL](https://www.openssl.org/)).\n\nAs it's intended to bulk process a lot of certificates, a progress bar is displayed (can be removed with the *--noprogress|-b* option)\nand the time allowed to get a certificate is limited to a 10 seconds timeout\n(can be specified otherwise with the *--timeout|-t* option, but is not supported on Windows systems).\n\nIn order to avoid doing a [Denial of Service attack](https://en.wikipedia.org/wiki/Denial-of-service_attack) on servers hosting many certificates,\na 1 second delay is waited between each certificate request (can be specified otherwise with the *--delay|-d* option).\n\nThe tool results are presented as text tables.\n\nThe main one is the list of certificates successfully fetched, ordered by expiration date.\nThis list can be filtered with the *--filter|-f* option to only show certificates expired or expiring within the specified number of days.\nYou can use the *--noaltnames|-a* option in order to stop displaying alternate names contained in certificates,\nor the *--ip|-i* option to include the IP addresses of servers.\n\nThe second table is the sorted list of hostnames / hostports where certificates couldn't be fetched,\nwith our best attempts to identify the reason why.\n\nTwo additional tables can be generated with the *--new|-n* option, in order to print the common names and alternate names\nunmentioned in your input data files.\n\nFinally, for user convenience, all these reports can be generated in a single multi-tabs Excel workbook specified with the *--excel|-e* option.\n\n### OPTIONS\nOptions | Use\n------- | ---\n--delay\\|-d SEC|Wait SEC (0-N) seconds between requests\n--excel\\|-e FILE|Output results in Excel FILE\n--filter\\|-f DAYS|Show results expiring in less than DAYS\n--ip\\|-i|Show IP address of hostnames\n--new\\|-n|Show unmentioned CN/alt names in input files\n--noaltnames\\|-a|Don't show alt names in results\n--noprogress\\|-b|Don't use a progress bar\n--savedir\\|-s DIR|Save certificates in DIR directory\n--timeout\\|-t SEC|Wait SEC (1-N) seconds before aborting a request\n--debug|Enable debug mode\n--help\\|-?|Print usage and a short help message and exit\n--version|Print version and exit\n--|Options processing terminator\n\n## ENVIRONMENT\nThe CERTWATCH_DEBUG environment variable can be set to any value to enable debug mode.\n\n## FILES\n[/usr/local/share/certwatch/tests.txt](https://github.com/HubTou/certwatch/blob/main/data/tests.txt) - config file example using the [badssl.com](https://badssl.com) Web site for testing live bogus X509 certificates,\nwith [text](https://github.com/HubTou/certwatch/blob/main/data/tests_output.txt)\nand [Excel](https://github.com/HubTou/certwatch/blob/main/data/tests_output.xlsx) output.\n\nThe structure of configuration files is as follows:\n* Everything after a '#' character is a comment\n* Blank lines are allowed\n* data lines are either:\n * \"hostname hostport\"\n * \"hostname\"\n* When hostport is not provided, port 443 (HTTPS) is assumed\n\n## EXIT STATUS\nThe **certwatch** utility exits 0 on success, and >0 if an error occurs.\n\n## EXAMPLES\nThe following command will make **certwatch** process your certificates list in *mycertslist.txt*,\nsave all certificates in PEM format to *mycertsdir*, print all possible reports and details to screen\nand to an Excel workbook named *certwatch.out.xlsx*, and select or highlight certificates\nexpired or set to expire in the coming 30 days:\n```Shell\n# certwatch -in -e certwatch.out.xlsx -s mycertsdir -f 30 mycertslist.txt | tee certwatch.out.txt\n```\n\nSaved certificates can then be viewed with the **openssl** command like this for a *mycert.pem* file:\n```Shell\n# openssl x509 -inform PEM -in mycert.pem -noout -text | more\n```\n\n## SEE ALSO\n[openssl(1)](https://www.openssl.org/docs/manmaster/man1/openssl.html)\n\n## STANDARDS\nThe **certwatch** utility is not a standard UNIX command.\n\nIt tries to follow the [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guide for [Python](https://www.python.org/) code.\n\n## PORTABILITY\nTested OK under Windows.\n\nPackaged for FreeBSD as pyXX-pnu-certwatch.\n\n## HISTORY\nThis implementation was made for the [PNU project](https://github.com/HubTou/PNU).\n\nBoth for my own needs and those of my company, I wanted an easy way to monitor thousands of certificates expiration dates.\n\nThe 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...\n\n## LICENSE\nIt is available under the [3-clause BSD license](https://opensource.org/licenses/BSD-3-Clause).\n\n## AUTHORS\n[Hubert Tournier](https://github.com/HubTou)\n\n## CAVEATS\nUsing this command through [outgoing proxies](https://en.wikipedia.org/wiki/Proxy_server) is untested and we provide no option to set the proxy address.\nHowever it should work through reverse proxies on the server side.\n\n## SECURITY CONSIDERATIONS\nWhen certificate retrieval is unsuccessful, **certwatch** will try to diagnose the issue in different ways, one of which involving\nrunning the system **[ping](https://en.wikipedia.org/wiki/Ping_(networking_utility))** command. This can be an issue if someone happens to place a command with the same name higher in your PATH.\nBut working at the IP layer level, which is needed in order to implement the [ICMP](https://en.wikipedia.org/wiki/Internet_Control_Message_Protocol) protocol, requires root privileges which I see as a bigger risk...\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License",
"summary": "watch X509 certificates expiration dates",
"version": "1.0.3",
"project_urls": {
"Bug Tracker": "https://github.com/HubTou/certwatch/issues",
"Homepage": "https://github.com/HubTou/certwatch/"
},
"split_keywords": [
"pnu-project"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d2c7392efc9cde32d462f8c225f9544b6fb2783298159e2eb5fb642710bbf38a",
"md5": "df97b47be175ab5773432fca2f634a97",
"sha256": "b0ed6bcf5ff23fd3c82f4a9bdec2545b4ace4aeefa91c12b87bc174ec2d9bfc7"
},
"downloads": -1,
"filename": "pnu_certwatch-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "df97b47be175ab5773432fca2f634a97",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 18751,
"upload_time": "2024-03-24T18:23:26",
"upload_time_iso_8601": "2024-03-24T18:23:26.067859Z",
"url": "https://files.pythonhosted.org/packages/d2/c7/392efc9cde32d462f8c225f9544b6fb2783298159e2eb5fb642710bbf38a/pnu_certwatch-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a69c83f14693d0c168377f76f247a9dffa228b1f26c8586a504900166860cff7",
"md5": "fa261fa6934e48899d9b9dd4df7f0833",
"sha256": "e736811765f567cb427035eb8449196638c1ea8ef7cb68755a58b2668b400f44"
},
"downloads": -1,
"filename": "pnu-certwatch-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "fa261fa6934e48899d9b9dd4df7f0833",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 22073,
"upload_time": "2024-03-24T18:23:27",
"upload_time_iso_8601": "2024-03-24T18:23:27.932859Z",
"url": "https://files.pythonhosted.org/packages/a6/9c/83f14693d0c168377f76f247a9dffa228b1f26c8586a504900166860cff7/pnu-certwatch-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-24 18:23:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "HubTou",
"github_project": "certwatch",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pnu-certwatch"
}
JSON
