Skip to content
sec-slyonePublic

About

Credential-free TLS certificate inventory for VMware and other infrastructure estates. Standard library only, read only.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

vcertscan

Credential-free TLS certificate inventory for VMware and other infrastructure estates.

It connects to each endpoint, reads the certificate presented, and tells you what it is and when it expires. It sends no credentials, changes nothing, and needs nothing installed beyond the Python standard library.

It exists to replace the spreadsheet of certificate expiry dates that every large estate has, that was accurate the day it was written, and that nobody has trusted since.

Why it works this way

No credentials in the default mode. A tool that needs a vCenter service account needs an approval, and an approval needs a sponsor. A tool that opens a TLS socket and reads what comes back needs neither, so it can run on the day somebody decides to find out. That matters more than it sounds like it should.

No dependencies. Standard library only. No pip install, no proxy exception, no package approval, no virtualenv on a jump host that is not supposed to have one. If cryptography happens to be present it is used to add key size and signature algorithm, and if it is not, everything else still works.

No API version coupling. What an endpoint presents on port 443 does not change shape between vCenter releases. An API client does. This runs against vCenter 6.7 and 9.1.1 and an F5 and a printer, without caring which is which.

Read only, and provably so. The code is short enough to read before you run it, which is the point. There is no write path.

Install

git clone https://github.com/sec-slyone/vcertscan.git
cd vcertscan

Python 3.9 or later. Nothing else.

Use

# a few endpoints
python3 vcertscan.py --hosts vc01.corp.example,esx01.corp.example

# a generated list, flagging anything inside 90 days
python3 vcertscan.py --file hosts.txt --warn 90

# monthly cron, writes evidence and exits non-zero if anything is inside 30 days
python3 vcertscan.py --file hosts.txt --csv inventory-$(date +%Y%m).csv --fail-under 30

Output

ENDPOINT                            SUBJECT CN             ISSUER CN                 EXPIRES                    DAYS    SELF
----------------------------------  ---------------------  ------------------------  -------------------------  ------  -----
vc01.corp.example:443               vc01.corp.example      CORP Issuing CA 02        Dec  3 09:14:02 2026 GMT   39      no     WARN
esx07.corp.example:443              esx07.corp.example     CA                        Jan 18 22:40:11 2027 GMT   85      yes    WARN
vc02.corp.example:443               vc02.corp.example      CORP Issuing CA 02        Aug 14 09:02:55 2027 GMT   293     no
nsx01.corp.example:443              ! TimeoutError: timed out

Sorted by days remaining, so the thing you need to act on is at the top and unreachable endpoints are at the bottom where they read as a finding rather than a failure.

Options

Option Purpose
--hosts a,b,c Comma separated targets. host or host:port.
--file hosts.txt File of targets, one per line. Repeatable. # comments allowed.
--warn N Days at which to flag WARN in the table. Default 90.
--fail-under N Exit 1 if any certificate expires within N days. For cron and CI.
--strict Exit 2 if any endpoint could not be reached.
--csv FILE / --json FILE Write full results, including fields the table omits.
--timeout / --workers Per-endpoint timeout and parallelism. Defaults 6s and 16.
--no-sni For endpoints that mishandle SNI.

Exit codes: 0 clean, 1 something inside the --fail-under window, 2 an endpoint was unreachable and --strict was set.

Build the host list from something other than memory

The value of this depends entirely on the list being complete, and a hand-maintained list never is. Generate it.

# from a DNS zone transfer, where you are permitted one
dig axfr corp.example @ns1.corp.example | awk '/\sA\s/ {print $1}' | sed 's/\.$//' > hosts.txt

# from vCenter inventory, via govc
govc ls -t HostSystem /DC/host/... | xargs -n1 basename >> hosts.txt

Then compare what the scan finds against whatever record you currently keep. On every estate I have done this on, the two have disagreed, and the disagreement has been more useful than the inventory.

Authenticated enrichment

Two certificates are not presented on port 443 and so cannot be read without credentials: the vCenter Security Token Service signing certificate, and the trusted root chains. STS is the one that causes an authentication outage across an otherwise healthy platform, so it is worth the extra step.

export VC_USER='administrator@vsphere.local'
read -rs VC_PASS; export VC_PASS
python3 vcenter_api.py --host vc01.corp.example --json vc01-certs.json

Credentials come from the environment rather than the command line so they stay out of shell history and out of a process listing. TLS verification is on by default; --insecure exists because a VMCA-signed vCenter will not validate against a public trust store, which is itself a finding worth recording.

This is read only. It calls GET against the certificate management endpoints and deletes its session afterwards.

What this does not do

It does not renew anything, install anything, or change anything. Renewal belongs in the platform that owns the certificate, with a change record attached. This tool exists to tell you what you have, which is the step everybody skips.

It also will not see certificates behind a load balancer that terminates TLS itself. Point it at the pool members as well as the virtual server, and expect them to differ.

Licence

MIT. Deliberately. An operations tool that a bank cannot run because of its licence is not an operations tool, and a non-commercial clause turns a five minute decision into a legal review. MIT means the question does not get asked.

About

Credential-free TLS certificate inventory for VMware and other infrastructure estates. Standard library only, read only.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages