certinspect 2.4.3__tar.gz → 2.4.5__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. {certinspect-2.4.3/src/certinspect.egg-info → certinspect-2.4.5}/PKG-INFO +68 -61
  2. {certinspect-2.4.3 → certinspect-2.4.5}/README.md +67 -60
  3. {certinspect-2.4.3 → certinspect-2.4.5}/pyproject.toml +1 -1
  4. {certinspect-2.4.3 → certinspect-2.4.5}/src/certinspect/__init__.py +1 -1
  5. {certinspect-2.4.3 → certinspect-2.4.5}/src/certinspect/args.py +5 -3
  6. {certinspect-2.4.3 → certinspect-2.4.5}/src/certinspect/cli.py +15 -2
  7. {certinspect-2.4.3 → certinspect-2.4.5}/src/certinspect/fetch.py +7 -3
  8. {certinspect-2.4.3 → certinspect-2.4.5}/src/certinspect/httpfetch.py +20 -3
  9. {certinspect-2.4.3 → certinspect-2.4.5/src/certinspect.egg-info}/PKG-INFO +68 -61
  10. {certinspect-2.4.3 → certinspect-2.4.5}/tests/test_cli.py +60 -0
  11. {certinspect-2.4.3 → certinspect-2.4.5}/tests/test_fetch.py +43 -0
  12. {certinspect-2.4.3 → certinspect-2.4.5}/LICENSE +0 -0
  13. {certinspect-2.4.3 → certinspect-2.4.5}/setup.cfg +0 -0
  14. {certinspect-2.4.3 → certinspect-2.4.5}/src/certinspect/completion.py +0 -0
  15. {certinspect-2.4.3 → certinspect-2.4.5}/src/certinspect/config.py +0 -0
  16. {certinspect-2.4.3 → certinspect-2.4.5}/src/certinspect/discover.py +0 -0
  17. {certinspect-2.4.3 → certinspect-2.4.5}/src/certinspect/exit_codes.py +0 -0
  18. {certinspect-2.4.3 → certinspect-2.4.5}/src/certinspect/formatter.py +0 -0
  19. {certinspect-2.4.3 → certinspect-2.4.5}/src/certinspect/models.py +0 -0
  20. {certinspect-2.4.3 → certinspect-2.4.5}/src/certinspect/parser.py +0 -0
  21. {certinspect-2.4.3 → certinspect-2.4.5}/src/certinspect/render.py +0 -0
  22. {certinspect-2.4.3 → certinspect-2.4.5}/src/certinspect/revocation.py +0 -0
  23. {certinspect-2.4.3 → certinspect-2.4.5}/src/certinspect/state.py +0 -0
  24. {certinspect-2.4.3 → certinspect-2.4.5}/src/certinspect.egg-info/SOURCES.txt +0 -0
  25. {certinspect-2.4.3 → certinspect-2.4.5}/src/certinspect.egg-info/dependency_links.txt +0 -0
  26. {certinspect-2.4.3 → certinspect-2.4.5}/src/certinspect.egg-info/entry_points.txt +0 -0
  27. {certinspect-2.4.3 → certinspect-2.4.5}/src/certinspect.egg-info/requires.txt +0 -0
  28. {certinspect-2.4.3 → certinspect-2.4.5}/src/certinspect.egg-info/top_level.txt +0 -0
  29. {certinspect-2.4.3 → certinspect-2.4.5}/tests/test_discover.py +0 -0
  30. {certinspect-2.4.3 → certinspect-2.4.5}/tests/test_formatter.py +0 -0
  31. {certinspect-2.4.3 → certinspect-2.4.5}/tests/test_parser.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: certinspect
3
- Version: 2.4.3
3
+ Version: 2.4.5
4
4
  Summary: Command-line TLS certificate inspector
5
5
  Author-email: Michele Angrisano <michele.angrisano@gmail.com>
6
6
  License-Expression: MIT
@@ -339,7 +339,10 @@ SAN:
339
339
 
340
340
  By default certinspect opens a fully verified TLS handshake (chain +
341
341
  hostname against the Python/OpenSSL trust store) and, when the certificate
342
- advertises an OCSP responder, queries it for the revocation status. If OCSP is
342
+ advertises an OCSP responder, queries it for the revocation status. The
343
+ verified handshake is a second connection: if the server presents a different
344
+ certificate on it (a load balancer mid-rotation, say), the chain is reported
345
+ as not trusted instead of vouching for a certificate that was not inspected. If OCSP is
343
346
  unavailable, certinspect falls back to the certificate's CRL distribution
344
347
  points (downloaded over HTTP and verified against the issuer). Both checks are
345
348
  soft-fail: when neither OCSP nor the CRL gives an answer the status is
@@ -613,62 +616,62 @@ certinspect example.com --export ./example.com.pem
613
616
 
614
617
  ## Options
615
618
 
616
- | Option | Description |
617
- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
618
- | `target...` | One or more domains, URLs or `host:port` to inspect. Omit when using `--file`. |
619
- | `--config PATH` | Load default option values from a TOML file (keys use the argparse destination name); an explicit flag always overrides it. Auto-discovered at `~/.config/certinspect/config.toml` when omitted. |
620
- | `--file PATH` | Inspect a local certificate (PEM or DER) instead of a host. Use `-` to read from standard input. Repeatable to inspect several files in one run; cannot be combined with host targets. |
621
- | `--port N` | TCP port to connect to (default: 443). |
622
- | `--timeout N` | Connection timeout in seconds (default: 5). Used for both connect and read unless the two below are set. |
623
- | `--connect-timeout N` | TCP connect timeout in seconds (default: `--timeout`). |
624
- | `--read-timeout N` | Handshake/read timeout in seconds (default: `--timeout`). |
625
- | `--retries N` | Retry transient connection failures (timeouts, refused/reset, DNS) this many times (default: 0). |
626
- | `--json` | Print the result as JSON instead of human-readable text. |
627
- | `--csv` | Print the results as CSV (one row per target, with a header). |
628
- | `--csv-delimiter SEP` | Field separator for `--csv` (default `,`). Use `;` for Numbers/Excel in locales that expect it. |
629
- | `--quiet` | Only print certificates that have a problem. |
630
- | `--schema {1,2}` | JSON schema version for `--json` (default `2`, the nested/versioned document). `--schema 1` is the legacy flat array. |
631
- | `--verify` | Force chain verification (already the default). A verified handshake plus OCSP/CRL revocation for a host, or the bundle validated offline for `--file`. |
632
- | `--no-verify` | Skip chain verification (and revocation for hosts); only inspect the certificate itself. |
633
- | `--cafile PATH` | Verify the chain against this CA bundle (PEM) instead of the system trust store; for internal/private PKI. Incompatible with `--no-verify`. |
634
- | `--capath DIR` | Verify the chain against the hashed CA certificates in this directory (OpenSSL `c_rehash` layout). Incompatible with `--no-verify`; may be combined with `--cafile`. |
635
- | `--chain` | Show the certificate chain: presented by the server for a host, or every certificate in the bundle for `--file`. |
636
- | `--client-cert PATH` | Present a client certificate (PEM) for mutual-TLS endpoints (host targets only). Use `--client-key` when the key is stored separately. |
637
- | `--client-key PATH` | Private key (PEM) for `--client-cert` when stored separately from the certificate. |
638
- | `--proxy URL` | Tunnel the connection through an HTTP CONNECT proxy, e.g. `http://proxy:8080` or `http://user:pass@proxy:8080` (host targets only). Without it, the environment proxy (`HTTPS_PROXY`, honouring `NO_PROXY`) is used, like curl. |
639
- | `--no-proxy` | Force a direct connection, ignoring any proxy set in the environment. Mutually exclusive with `--proxy`. |
640
- | `--pin SHA256` | Fail (exit 7) unless the SHA-256 fingerprint matches (colons/case ignored). |
641
- | `--servername NAME` | Override the SNI hostname sent in the handshake (hosts only); the hostname match is checked against `NAME`. For reaching a backend by IP behind a load balancer. |
642
- | `--expect-san NAME` | Assert the certificate's SAN covers `NAME` (wildcards honored); exit 8 if missing. Repeatable; works for host and `--file` targets. |
643
- | `--not-after-max N` | Fail (exit 9) when the total validity exceeds N days (use 398 for the CA/Browser Forum maximum). Opt-in; works for host and `--file` targets. |
644
- | `--cab-forum` | Fail (exit 9) when the total validity exceeds the CA/Browser Forum maximum in effect today (398 days now, then 200, 100 and 47 on 2026/2027/2029-03-15). Date-aware shorthand for `--not-after-max`; mutually exclusive with it. |
645
- | `--min-key-size N` | Fail (exit 9) when an RSA/DSA public key is smaller than N bits (e.g. 2048). EC/EdDSA keys are not size-checked. Opt-in. |
646
- | `--fail-weak` | Turn the weak-crypto warnings (small key, SHA-1/MD5 signature) into a hard failure (exit 9) instead of a mere warning. |
647
- | `--require-sct` | Fail (exit 9) when the certificate embeds no Signed Certificate Timestamps (Certificate Transparency). Checks embedded SCTs only, not those from the TLS handshake or OCSP. Opt-in. |
648
- | `--require-must-staple` | Fail (exit 9) when the certificate lacks the OCSP Must-Staple extension (RFC 7633 TLS Feature `status_request`). Opt-in. |
649
- | `--require-revocation-check` | Fail (exit 9) unless OCSP or CRL returns a definitive `GOOD` revocation verdict. Host targets only; incompatible with `--no-verify`. Opt-in. |
650
- | `--min-tls-version VER` | Fail (exit 9) when the connection negotiates a TLS version older than `VER` (`TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`). Host targets only; opt-in. |
651
- | `--profile {lenient,standard,strict}` | Apply a named bundle of the opt-in policy checks in one go (exit 9 on violation). Intensity ladder, not an official standard; explicit flags override it. See [Policy profiles](#policy-profiles). |
652
- | `--input PATH` | Read extra targets from a file, one per line ('-' for stdin). |
653
- | `--discover DOMAIN` | Discover hostnames from Certificate Transparency logs (crt.sh) for DOMAIN and inspect each one, surfacing forgotten or shadow certificates. Repeatable (queried concurrently per `--concurrency`); host targets only. |
654
- | `--discover-only` | With `--discover`, list the CT inventory (expiry, issuer, hostnames, soonest expiry first, wildcards included) for the domain(s) without connecting, then exit. Good for a fast audit or spotting a certificate from an unexpected CA. Supports `--json`/`--csv`. |
655
- | `--expect-issuer SUBSTRING` | With `--discover-only`, flag any certificate whose issuer matches none of these substrings (case-insensitive) and exit 9 — a Certificate Transparency mis-issuance check. Repeatable. |
656
- | `--discover-timeout N` | Timeout in seconds for the `--discover` crt.sh query (default: 30), separate from `--timeout` since a log search can be slower than a handshake. |
657
- | `--days N` | Warn if the certificate expires within N days (default: 30). |
658
- | `--critical-days N` | Escalate to CRITICAL (exit code 4) when the certificate expires within N days. Must be `<= --days`; feeds Nagios CRITICAL and the `--summary` `critical` count. |
659
- | `--max-days N` | Only show certificates expiring within N days (expired ones always shown; filters display only). |
660
- | `--sort host\|expiry` | Sort the output by host (alphabetical) or by soonest expiry (display only; does not affect exit code). |
661
- | `--summary` | Print a one-line tally (valid/expiring/expired/errors) to stderr; counts every target before filtering. |
662
- | `--field NAME` | Print only the given field(s), one tab-separated line per target (repeatable; `target` for the host). For scripting without a JSON tool. |
663
- | `--exit-zero` | Always exit 0, even on problems or fetch errors. Report-only mode for dashboards/CI that read the output, not the exit code. |
664
- | `--export PATH` | Save the inspected certificate as a PEM file at PATH. Single target only. |
665
- | `--starttls {smtp,imap,pop3,ftp}` | Upgrade a plaintext connection to TLS before inspecting (standard port unless `--port` is given). |
666
- | `--exporter {nagios,prometheus}` | Emit machine-readable monitoring output (ignores `--quiet`). |
667
- | `--concurrency N` | Inspect up to N hosts in parallel in batch mode (default: 1; order is preserved). Also governs `--discover`'s per-domain concurrency. |
668
- | `--state-file PATH` | Persist each host target's status across runs at PATH (JSON) and compare against the previous run. Host targets only. |
669
- | `--only-changed` | Show only targets whose status differs from the previous `--state-file` run (a first-seen target counts as changed). Requires `--state-file`; display only. |
670
- | `--print-completion {bash,zsh}` | Print a shell completion script for bash or zsh to stdout, then exit. Generated from the parser, so it always matches the installed flags. |
671
- | `--version` | Print the version and exit. |
619
+ | Option | Description |
620
+ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
621
+ | `target...` | One or more domains, URLs or `host:port` to inspect. Omit when using `--file`. |
622
+ | `--config PATH` | Load default option values from a TOML file (keys use the argparse destination name); an explicit flag always overrides it. Auto-discovered at `~/.config/certinspect/config.toml` when omitted. |
623
+ | `--file PATH` | Inspect a local certificate (PEM or DER) instead of a host. Use `-` to read from standard input. Repeatable to inspect several files in one run; cannot be combined with host targets. |
624
+ | `--port N` | TCP port to connect to (default: 443). |
625
+ | `--timeout N` | Connection timeout in seconds (default: 5). Used for both connect and read unless the two below are set. |
626
+ | `--connect-timeout N` | TCP connect timeout in seconds (default: `--timeout`). |
627
+ | `--read-timeout N` | Handshake/read timeout in seconds (default: `--timeout`). |
628
+ | `--retries N` | Retry transient connection failures (timeouts, refused/reset, DNS) this many times (default: 0). |
629
+ | `--json` | Print the result as JSON instead of human-readable text. |
630
+ | `--csv` | Print the results as CSV (one row per target, with a header). |
631
+ | `--csv-delimiter SEP` | Field separator for `--csv` (default `,`). Use `;` for Numbers/Excel in locales that expect it. |
632
+ | `--quiet` | Only print certificates that have a problem. |
633
+ | `--schema {1,2}` | JSON schema version for `--json` (default `2`, the nested/versioned document). `--schema 1` is the legacy flat array. |
634
+ | `--verify` | Force chain verification (already the default). A verified handshake plus OCSP/CRL revocation for a host, or the bundle validated offline for `--file`. |
635
+ | `--no-verify` | Skip chain verification (and revocation for hosts); only inspect the certificate itself. |
636
+ | `--cafile PATH` | Verify the chain against this CA bundle (PEM) instead of the system trust store; for internal/private PKI. Incompatible with `--no-verify`. |
637
+ | `--capath DIR` | Verify the chain against the hashed CA certificates in this directory (OpenSSL `c_rehash` layout). Incompatible with `--no-verify`; may be combined with `--cafile`. |
638
+ | `--chain` | Show the certificate chain: presented by the server for a host, or every certificate in the bundle for `--file`. |
639
+ | `--client-cert PATH` | Present a client certificate (PEM) for mutual-TLS endpoints (host targets only). Use `--client-key` when the key is stored separately. |
640
+ | `--client-key PATH` | Private key (PEM) for `--client-cert` when stored separately from the certificate. |
641
+ | `--proxy URL` | Tunnel the connection through an HTTP CONNECT proxy, e.g. `http://proxy:8080` or `http://user:pass@proxy:8080` (host targets only); OCSP/CRL/CA-Issuer/CT-log requests use it too. Without it, the environment proxy (`HTTPS_PROXY`, honouring `NO_PROXY`) is used, like curl. |
642
+ | `--no-proxy` | Force direct connections (OCSP/CRL requests included), ignoring any proxy set in the environment. Mutually exclusive with `--proxy`. |
643
+ | `--pin SHA256` | Fail (exit 7) unless the SHA-256 fingerprint matches (colons/case ignored). |
644
+ | `--servername NAME` | Override the SNI hostname sent in the handshake (hosts only); the hostname match is checked against `NAME`. For reaching a backend by IP behind a load balancer. |
645
+ | `--expect-san NAME` | Assert the certificate's SAN covers `NAME` (wildcards honored); exit 8 if missing. Repeatable; works for host and `--file` targets. |
646
+ | `--not-after-max N` | Fail (exit 9) when the total validity exceeds N days (use 398 for the CA/Browser Forum maximum). Opt-in; works for host and `--file` targets. |
647
+ | `--cab-forum` | Fail (exit 9) when the total validity exceeds the CA/Browser Forum maximum in effect today (398 days now, then 200, 100 and 47 on 2026/2027/2029-03-15). Date-aware shorthand for `--not-after-max`; mutually exclusive with it. |
648
+ | `--min-key-size N` | Fail (exit 9) when an RSA/DSA public key is smaller than N bits (e.g. 2048). EC/EdDSA keys are not size-checked. Opt-in. |
649
+ | `--fail-weak` | Turn the weak-crypto warnings (small key, SHA-1/MD5 signature) into a hard failure (exit 9) instead of a mere warning. |
650
+ | `--require-sct` | Fail (exit 9) when the certificate embeds no Signed Certificate Timestamps (Certificate Transparency). Checks embedded SCTs only, not those from the TLS handshake or OCSP. Opt-in. |
651
+ | `--require-must-staple` | Fail (exit 9) when the certificate lacks the OCSP Must-Staple extension (RFC 7633 TLS Feature `status_request`). Opt-in. |
652
+ | `--require-revocation-check` | Fail (exit 9) unless OCSP or CRL returns a definitive `GOOD` revocation verdict. Host targets only; incompatible with `--no-verify`. Opt-in. |
653
+ | `--min-tls-version VER` | Fail (exit 9) when the connection negotiates a TLS version older than `VER` (`TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`). Host targets only; opt-in. |
654
+ | `--profile {lenient,standard,strict}` | Apply a named bundle of the opt-in policy checks in one go (exit 9 on violation). Intensity ladder, not an official standard; explicit flags override it. See [Policy profiles](#policy-profiles). |
655
+ | `--input PATH` | Read extra targets from a file, one per line ('-' for stdin). |
656
+ | `--discover DOMAIN` | Discover hostnames from Certificate Transparency logs (crt.sh) for DOMAIN and inspect each one, surfacing forgotten or shadow certificates. Repeatable (queried concurrently per `--concurrency`); host targets only. |
657
+ | `--discover-only` | With `--discover`, list the CT inventory (expiry, issuer, hostnames, soonest expiry first, wildcards included) for the domain(s) without connecting, then exit. Good for a fast audit or spotting a certificate from an unexpected CA. Supports `--json`/`--csv`. |
658
+ | `--expect-issuer SUBSTRING` | With `--discover-only`, flag any certificate whose issuer matches none of these substrings (case-insensitive) and exit 9 — a Certificate Transparency mis-issuance check. Repeatable. |
659
+ | `--discover-timeout N` | Timeout in seconds for the `--discover` crt.sh query (default: 30), separate from `--timeout` since a log search can be slower than a handshake. |
660
+ | `--days N` | Warn if the certificate expires within N days (default: 30). |
661
+ | `--critical-days N` | Escalate to CRITICAL (exit code 4) when the certificate expires within N days. Must be `<= --days`; feeds Nagios CRITICAL and the `--summary` `critical` count. |
662
+ | `--max-days N` | Only show certificates expiring within N days (expired ones always shown; filters display only). |
663
+ | `--sort host\|expiry` | Sort the output by host (alphabetical) or by soonest expiry (display only; does not affect exit code). |
664
+ | `--summary` | Print a one-line tally (valid/expiring/expired/errors) to stderr; counts every target before filtering. |
665
+ | `--field NAME` | Print only the given field(s), one tab-separated line per target (repeatable; `target` for the host). For scripting without a JSON tool. |
666
+ | `--exit-zero` | Always exit 0, even on problems or fetch errors. Report-only mode for dashboards/CI that read the output, not the exit code. |
667
+ | `--export PATH` | Save the inspected certificate as a PEM file at PATH. Single target only. |
668
+ | `--starttls {smtp,imap,pop3,ftp}` | Upgrade a plaintext connection to TLS before inspecting (standard port unless `--port` is given). |
669
+ | `--exporter {nagios,prometheus}` | Emit machine-readable monitoring output (ignores `--quiet`). |
670
+ | `--concurrency N` | Inspect up to N hosts in parallel in batch mode (default: 1; order is preserved). Also governs `--discover`'s per-domain concurrency. |
671
+ | `--state-file PATH` | Persist each host target's status across runs at PATH (JSON) and compare against the previous run. Host targets only. |
672
+ | `--only-changed` | Show only targets whose status differs from the previous `--state-file` run (a first-seen target counts as changed). Requires `--state-file`; display only. |
673
+ | `--print-completion {bash,zsh}` | Print a shell completion script for bash or zsh to stdout, then exit. Generated from the parser, so it always matches the installed flags. |
674
+ | `--version` | Print the version and exit. |
672
675
 
673
676
  ## Options in action
674
677
 
@@ -992,12 +995,16 @@ Status: VALID
992
995
 
993
996
  Tunnel the TLS connection through an HTTP `CONNECT` proxy, so a host reachable
994
997
  only through a corporate/cloud egress proxy can still be inspected. Basic proxy
995
- auth is supported via `user:pass@`.
998
+ auth is supported via `user:pass@`. The OCSP, CRL, CA-Issuer and CT-log
999
+ (`--discover`) requests use the same proxy, so revocation still works where
1000
+ only the proxy reaches the Internet. Their host names are still resolved
1001
+ locally for the internal-address check.
996
1002
 
997
1003
  Like curl, certinspect also uses the environment proxy automatically when
998
1004
  `--proxy` is not given: it reads `HTTPS_PROXY`/`HTTP_PROXY` (and the system
999
- proxy on macOS/Windows) and honours `NO_PROXY`. Use `--no-proxy` to force a
1000
- direct connection regardless of the environment.
1005
+ proxy on macOS/Windows) and honours `NO_PROXY`. Use `--no-proxy` to force
1006
+ direct connections, for the OCSP/CRL requests too, regardless of the
1007
+ environment.
1001
1008
 
1002
1009
  ```console
1003
1010
  $ certinspect example.com --proxy http://proxy.corp:8080 # explicit
@@ -313,7 +313,10 @@ SAN:
313
313
 
314
314
  By default certinspect opens a fully verified TLS handshake (chain +
315
315
  hostname against the Python/OpenSSL trust store) and, when the certificate
316
- advertises an OCSP responder, queries it for the revocation status. If OCSP is
316
+ advertises an OCSP responder, queries it for the revocation status. The
317
+ verified handshake is a second connection: if the server presents a different
318
+ certificate on it (a load balancer mid-rotation, say), the chain is reported
319
+ as not trusted instead of vouching for a certificate that was not inspected. If OCSP is
317
320
  unavailable, certinspect falls back to the certificate's CRL distribution
318
321
  points (downloaded over HTTP and verified against the issuer). Both checks are
319
322
  soft-fail: when neither OCSP nor the CRL gives an answer the status is
@@ -587,62 +590,62 @@ certinspect example.com --export ./example.com.pem
587
590
 
588
591
  ## Options
589
592
 
590
- | Option | Description |
591
- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
592
- | `target...` | One or more domains, URLs or `host:port` to inspect. Omit when using `--file`. |
593
- | `--config PATH` | Load default option values from a TOML file (keys use the argparse destination name); an explicit flag always overrides it. Auto-discovered at `~/.config/certinspect/config.toml` when omitted. |
594
- | `--file PATH` | Inspect a local certificate (PEM or DER) instead of a host. Use `-` to read from standard input. Repeatable to inspect several files in one run; cannot be combined with host targets. |
595
- | `--port N` | TCP port to connect to (default: 443). |
596
- | `--timeout N` | Connection timeout in seconds (default: 5). Used for both connect and read unless the two below are set. |
597
- | `--connect-timeout N` | TCP connect timeout in seconds (default: `--timeout`). |
598
- | `--read-timeout N` | Handshake/read timeout in seconds (default: `--timeout`). |
599
- | `--retries N` | Retry transient connection failures (timeouts, refused/reset, DNS) this many times (default: 0). |
600
- | `--json` | Print the result as JSON instead of human-readable text. |
601
- | `--csv` | Print the results as CSV (one row per target, with a header). |
602
- | `--csv-delimiter SEP` | Field separator for `--csv` (default `,`). Use `;` for Numbers/Excel in locales that expect it. |
603
- | `--quiet` | Only print certificates that have a problem. |
604
- | `--schema {1,2}` | JSON schema version for `--json` (default `2`, the nested/versioned document). `--schema 1` is the legacy flat array. |
605
- | `--verify` | Force chain verification (already the default). A verified handshake plus OCSP/CRL revocation for a host, or the bundle validated offline for `--file`. |
606
- | `--no-verify` | Skip chain verification (and revocation for hosts); only inspect the certificate itself. |
607
- | `--cafile PATH` | Verify the chain against this CA bundle (PEM) instead of the system trust store; for internal/private PKI. Incompatible with `--no-verify`. |
608
- | `--capath DIR` | Verify the chain against the hashed CA certificates in this directory (OpenSSL `c_rehash` layout). Incompatible with `--no-verify`; may be combined with `--cafile`. |
609
- | `--chain` | Show the certificate chain: presented by the server for a host, or every certificate in the bundle for `--file`. |
610
- | `--client-cert PATH` | Present a client certificate (PEM) for mutual-TLS endpoints (host targets only). Use `--client-key` when the key is stored separately. |
611
- | `--client-key PATH` | Private key (PEM) for `--client-cert` when stored separately from the certificate. |
612
- | `--proxy URL` | Tunnel the connection through an HTTP CONNECT proxy, e.g. `http://proxy:8080` or `http://user:pass@proxy:8080` (host targets only). Without it, the environment proxy (`HTTPS_PROXY`, honouring `NO_PROXY`) is used, like curl. |
613
- | `--no-proxy` | Force a direct connection, ignoring any proxy set in the environment. Mutually exclusive with `--proxy`. |
614
- | `--pin SHA256` | Fail (exit 7) unless the SHA-256 fingerprint matches (colons/case ignored). |
615
- | `--servername NAME` | Override the SNI hostname sent in the handshake (hosts only); the hostname match is checked against `NAME`. For reaching a backend by IP behind a load balancer. |
616
- | `--expect-san NAME` | Assert the certificate's SAN covers `NAME` (wildcards honored); exit 8 if missing. Repeatable; works for host and `--file` targets. |
617
- | `--not-after-max N` | Fail (exit 9) when the total validity exceeds N days (use 398 for the CA/Browser Forum maximum). Opt-in; works for host and `--file` targets. |
618
- | `--cab-forum` | Fail (exit 9) when the total validity exceeds the CA/Browser Forum maximum in effect today (398 days now, then 200, 100 and 47 on 2026/2027/2029-03-15). Date-aware shorthand for `--not-after-max`; mutually exclusive with it. |
619
- | `--min-key-size N` | Fail (exit 9) when an RSA/DSA public key is smaller than N bits (e.g. 2048). EC/EdDSA keys are not size-checked. Opt-in. |
620
- | `--fail-weak` | Turn the weak-crypto warnings (small key, SHA-1/MD5 signature) into a hard failure (exit 9) instead of a mere warning. |
621
- | `--require-sct` | Fail (exit 9) when the certificate embeds no Signed Certificate Timestamps (Certificate Transparency). Checks embedded SCTs only, not those from the TLS handshake or OCSP. Opt-in. |
622
- | `--require-must-staple` | Fail (exit 9) when the certificate lacks the OCSP Must-Staple extension (RFC 7633 TLS Feature `status_request`). Opt-in. |
623
- | `--require-revocation-check` | Fail (exit 9) unless OCSP or CRL returns a definitive `GOOD` revocation verdict. Host targets only; incompatible with `--no-verify`. Opt-in. |
624
- | `--min-tls-version VER` | Fail (exit 9) when the connection negotiates a TLS version older than `VER` (`TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`). Host targets only; opt-in. |
625
- | `--profile {lenient,standard,strict}` | Apply a named bundle of the opt-in policy checks in one go (exit 9 on violation). Intensity ladder, not an official standard; explicit flags override it. See [Policy profiles](#policy-profiles). |
626
- | `--input PATH` | Read extra targets from a file, one per line ('-' for stdin). |
627
- | `--discover DOMAIN` | Discover hostnames from Certificate Transparency logs (crt.sh) for DOMAIN and inspect each one, surfacing forgotten or shadow certificates. Repeatable (queried concurrently per `--concurrency`); host targets only. |
628
- | `--discover-only` | With `--discover`, list the CT inventory (expiry, issuer, hostnames, soonest expiry first, wildcards included) for the domain(s) without connecting, then exit. Good for a fast audit or spotting a certificate from an unexpected CA. Supports `--json`/`--csv`. |
629
- | `--expect-issuer SUBSTRING` | With `--discover-only`, flag any certificate whose issuer matches none of these substrings (case-insensitive) and exit 9 — a Certificate Transparency mis-issuance check. Repeatable. |
630
- | `--discover-timeout N` | Timeout in seconds for the `--discover` crt.sh query (default: 30), separate from `--timeout` since a log search can be slower than a handshake. |
631
- | `--days N` | Warn if the certificate expires within N days (default: 30). |
632
- | `--critical-days N` | Escalate to CRITICAL (exit code 4) when the certificate expires within N days. Must be `<= --days`; feeds Nagios CRITICAL and the `--summary` `critical` count. |
633
- | `--max-days N` | Only show certificates expiring within N days (expired ones always shown; filters display only). |
634
- | `--sort host\|expiry` | Sort the output by host (alphabetical) or by soonest expiry (display only; does not affect exit code). |
635
- | `--summary` | Print a one-line tally (valid/expiring/expired/errors) to stderr; counts every target before filtering. |
636
- | `--field NAME` | Print only the given field(s), one tab-separated line per target (repeatable; `target` for the host). For scripting without a JSON tool. |
637
- | `--exit-zero` | Always exit 0, even on problems or fetch errors. Report-only mode for dashboards/CI that read the output, not the exit code. |
638
- | `--export PATH` | Save the inspected certificate as a PEM file at PATH. Single target only. |
639
- | `--starttls {smtp,imap,pop3,ftp}` | Upgrade a plaintext connection to TLS before inspecting (standard port unless `--port` is given). |
640
- | `--exporter {nagios,prometheus}` | Emit machine-readable monitoring output (ignores `--quiet`). |
641
- | `--concurrency N` | Inspect up to N hosts in parallel in batch mode (default: 1; order is preserved). Also governs `--discover`'s per-domain concurrency. |
642
- | `--state-file PATH` | Persist each host target's status across runs at PATH (JSON) and compare against the previous run. Host targets only. |
643
- | `--only-changed` | Show only targets whose status differs from the previous `--state-file` run (a first-seen target counts as changed). Requires `--state-file`; display only. |
644
- | `--print-completion {bash,zsh}` | Print a shell completion script for bash or zsh to stdout, then exit. Generated from the parser, so it always matches the installed flags. |
645
- | `--version` | Print the version and exit. |
593
+ | Option | Description |
594
+ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
595
+ | `target...` | One or more domains, URLs or `host:port` to inspect. Omit when using `--file`. |
596
+ | `--config PATH` | Load default option values from a TOML file (keys use the argparse destination name); an explicit flag always overrides it. Auto-discovered at `~/.config/certinspect/config.toml` when omitted. |
597
+ | `--file PATH` | Inspect a local certificate (PEM or DER) instead of a host. Use `-` to read from standard input. Repeatable to inspect several files in one run; cannot be combined with host targets. |
598
+ | `--port N` | TCP port to connect to (default: 443). |
599
+ | `--timeout N` | Connection timeout in seconds (default: 5). Used for both connect and read unless the two below are set. |
600
+ | `--connect-timeout N` | TCP connect timeout in seconds (default: `--timeout`). |
601
+ | `--read-timeout N` | Handshake/read timeout in seconds (default: `--timeout`). |
602
+ | `--retries N` | Retry transient connection failures (timeouts, refused/reset, DNS) this many times (default: 0). |
603
+ | `--json` | Print the result as JSON instead of human-readable text. |
604
+ | `--csv` | Print the results as CSV (one row per target, with a header). |
605
+ | `--csv-delimiter SEP` | Field separator for `--csv` (default `,`). Use `;` for Numbers/Excel in locales that expect it. |
606
+ | `--quiet` | Only print certificates that have a problem. |
607
+ | `--schema {1,2}` | JSON schema version for `--json` (default `2`, the nested/versioned document). `--schema 1` is the legacy flat array. |
608
+ | `--verify` | Force chain verification (already the default). A verified handshake plus OCSP/CRL revocation for a host, or the bundle validated offline for `--file`. |
609
+ | `--no-verify` | Skip chain verification (and revocation for hosts); only inspect the certificate itself. |
610
+ | `--cafile PATH` | Verify the chain against this CA bundle (PEM) instead of the system trust store; for internal/private PKI. Incompatible with `--no-verify`. |
611
+ | `--capath DIR` | Verify the chain against the hashed CA certificates in this directory (OpenSSL `c_rehash` layout). Incompatible with `--no-verify`; may be combined with `--cafile`. |
612
+ | `--chain` | Show the certificate chain: presented by the server for a host, or every certificate in the bundle for `--file`. |
613
+ | `--client-cert PATH` | Present a client certificate (PEM) for mutual-TLS endpoints (host targets only). Use `--client-key` when the key is stored separately. |
614
+ | `--client-key PATH` | Private key (PEM) for `--client-cert` when stored separately from the certificate. |
615
+ | `--proxy URL` | Tunnel the connection through an HTTP CONNECT proxy, e.g. `http://proxy:8080` or `http://user:pass@proxy:8080` (host targets only); OCSP/CRL/CA-Issuer/CT-log requests use it too. Without it, the environment proxy (`HTTPS_PROXY`, honouring `NO_PROXY`) is used, like curl. |
616
+ | `--no-proxy` | Force direct connections (OCSP/CRL requests included), ignoring any proxy set in the environment. Mutually exclusive with `--proxy`. |
617
+ | `--pin SHA256` | Fail (exit 7) unless the SHA-256 fingerprint matches (colons/case ignored). |
618
+ | `--servername NAME` | Override the SNI hostname sent in the handshake (hosts only); the hostname match is checked against `NAME`. For reaching a backend by IP behind a load balancer. |
619
+ | `--expect-san NAME` | Assert the certificate's SAN covers `NAME` (wildcards honored); exit 8 if missing. Repeatable; works for host and `--file` targets. |
620
+ | `--not-after-max N` | Fail (exit 9) when the total validity exceeds N days (use 398 for the CA/Browser Forum maximum). Opt-in; works for host and `--file` targets. |
621
+ | `--cab-forum` | Fail (exit 9) when the total validity exceeds the CA/Browser Forum maximum in effect today (398 days now, then 200, 100 and 47 on 2026/2027/2029-03-15). Date-aware shorthand for `--not-after-max`; mutually exclusive with it. |
622
+ | `--min-key-size N` | Fail (exit 9) when an RSA/DSA public key is smaller than N bits (e.g. 2048). EC/EdDSA keys are not size-checked. Opt-in. |
623
+ | `--fail-weak` | Turn the weak-crypto warnings (small key, SHA-1/MD5 signature) into a hard failure (exit 9) instead of a mere warning. |
624
+ | `--require-sct` | Fail (exit 9) when the certificate embeds no Signed Certificate Timestamps (Certificate Transparency). Checks embedded SCTs only, not those from the TLS handshake or OCSP. Opt-in. |
625
+ | `--require-must-staple` | Fail (exit 9) when the certificate lacks the OCSP Must-Staple extension (RFC 7633 TLS Feature `status_request`). Opt-in. |
626
+ | `--require-revocation-check` | Fail (exit 9) unless OCSP or CRL returns a definitive `GOOD` revocation verdict. Host targets only; incompatible with `--no-verify`. Opt-in. |
627
+ | `--min-tls-version VER` | Fail (exit 9) when the connection negotiates a TLS version older than `VER` (`TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`). Host targets only; opt-in. |
628
+ | `--profile {lenient,standard,strict}` | Apply a named bundle of the opt-in policy checks in one go (exit 9 on violation). Intensity ladder, not an official standard; explicit flags override it. See [Policy profiles](#policy-profiles). |
629
+ | `--input PATH` | Read extra targets from a file, one per line ('-' for stdin). |
630
+ | `--discover DOMAIN` | Discover hostnames from Certificate Transparency logs (crt.sh) for DOMAIN and inspect each one, surfacing forgotten or shadow certificates. Repeatable (queried concurrently per `--concurrency`); host targets only. |
631
+ | `--discover-only` | With `--discover`, list the CT inventory (expiry, issuer, hostnames, soonest expiry first, wildcards included) for the domain(s) without connecting, then exit. Good for a fast audit or spotting a certificate from an unexpected CA. Supports `--json`/`--csv`. |
632
+ | `--expect-issuer SUBSTRING` | With `--discover-only`, flag any certificate whose issuer matches none of these substrings (case-insensitive) and exit 9 — a Certificate Transparency mis-issuance check. Repeatable. |
633
+ | `--discover-timeout N` | Timeout in seconds for the `--discover` crt.sh query (default: 30), separate from `--timeout` since a log search can be slower than a handshake. |
634
+ | `--days N` | Warn if the certificate expires within N days (default: 30). |
635
+ | `--critical-days N` | Escalate to CRITICAL (exit code 4) when the certificate expires within N days. Must be `<= --days`; feeds Nagios CRITICAL and the `--summary` `critical` count. |
636
+ | `--max-days N` | Only show certificates expiring within N days (expired ones always shown; filters display only). |
637
+ | `--sort host\|expiry` | Sort the output by host (alphabetical) or by soonest expiry (display only; does not affect exit code). |
638
+ | `--summary` | Print a one-line tally (valid/expiring/expired/errors) to stderr; counts every target before filtering. |
639
+ | `--field NAME` | Print only the given field(s), one tab-separated line per target (repeatable; `target` for the host). For scripting without a JSON tool. |
640
+ | `--exit-zero` | Always exit 0, even on problems or fetch errors. Report-only mode for dashboards/CI that read the output, not the exit code. |
641
+ | `--export PATH` | Save the inspected certificate as a PEM file at PATH. Single target only. |
642
+ | `--starttls {smtp,imap,pop3,ftp}` | Upgrade a plaintext connection to TLS before inspecting (standard port unless `--port` is given). |
643
+ | `--exporter {nagios,prometheus}` | Emit machine-readable monitoring output (ignores `--quiet`). |
644
+ | `--concurrency N` | Inspect up to N hosts in parallel in batch mode (default: 1; order is preserved). Also governs `--discover`'s per-domain concurrency. |
645
+ | `--state-file PATH` | Persist each host target's status across runs at PATH (JSON) and compare against the previous run. Host targets only. |
646
+ | `--only-changed` | Show only targets whose status differs from the previous `--state-file` run (a first-seen target counts as changed). Requires `--state-file`; display only. |
647
+ | `--print-completion {bash,zsh}` | Print a shell completion script for bash or zsh to stdout, then exit. Generated from the parser, so it always matches the installed flags. |
648
+ | `--version` | Print the version and exit. |
646
649
 
647
650
  ## Options in action
648
651
 
@@ -966,12 +969,16 @@ Status: VALID
966
969
 
967
970
  Tunnel the TLS connection through an HTTP `CONNECT` proxy, so a host reachable
968
971
  only through a corporate/cloud egress proxy can still be inspected. Basic proxy
969
- auth is supported via `user:pass@`.
972
+ auth is supported via `user:pass@`. The OCSP, CRL, CA-Issuer and CT-log
973
+ (`--discover`) requests use the same proxy, so revocation still works where
974
+ only the proxy reaches the Internet. Their host names are still resolved
975
+ locally for the internal-address check.
970
976
 
971
977
  Like curl, certinspect also uses the environment proxy automatically when
972
978
  `--proxy` is not given: it reads `HTTPS_PROXY`/`HTTP_PROXY` (and the system
973
- proxy on macOS/Windows) and honours `NO_PROXY`. Use `--no-proxy` to force a
974
- direct connection regardless of the environment.
979
+ proxy on macOS/Windows) and honours `NO_PROXY`. Use `--no-proxy` to force
980
+ direct connections, for the OCSP/CRL requests too, regardless of the
981
+ environment.
975
982
 
976
983
  ```console
977
984
  $ certinspect example.com --proxy http://proxy.corp:8080 # explicit
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "certinspect"
3
- version = "2.4.3"
3
+ version = "2.4.5"
4
4
  description = "Command-line TLS certificate inspector"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.12"
@@ -1,3 +1,3 @@
1
1
  """certinspect — command-line TLS certificate inspector."""
2
2
 
3
- __version__ = "2.4.3"
3
+ __version__ = "2.4.5"
@@ -224,7 +224,8 @@ def build_parser() -> argparse.ArgumentParser:
224
224
  help=(
225
225
  "Tunnel the connection through an HTTP CONNECT proxy, e.g. "
226
226
  "http://proxy:8080 or http://user:pass@proxy:8080 (host targets "
227
- "only). With no --proxy the environment proxy (HTTPS_PROXY, honouring "
227
+ "only); the OCSP, CRL, CA-Issuer and CT-log requests go through it "
228
+ "too. With no --proxy the environment proxy (HTTPS_PROXY, honouring "
228
229
  "NO_PROXY) is used automatically, like curl."
229
230
  ),
230
231
  )
@@ -233,8 +234,9 @@ def build_parser() -> argparse.ArgumentParser:
233
234
  action="store_true",
234
235
  dest="no_proxy",
235
236
  help=(
236
- "Force a direct connection, ignoring any proxy set in the "
237
- "environment. Mutually exclusive with --proxy."
237
+ "Force direct connections, the OCSP/CRL/CA-Issuer/CT-log requests "
238
+ "included, ignoring any proxy set in the environment. Mutually "
239
+ "exclusive with --proxy."
238
240
  ),
239
241
  )
240
242
  parser.add_argument(
@@ -28,6 +28,7 @@ from certinspect.fetch import (
28
28
  verify_chain,
29
29
  verify_chain_offline,
30
30
  )
31
+ from certinspect import httpfetch
31
32
  from certinspect.revocation import check_revocation
32
33
  from certinspect.parser import (
33
34
  load_certificate,
@@ -254,7 +255,9 @@ def _inspect(
254
255
  if opts.file and (opts.verify or opts.chain):
255
256
  file_bundle = load_certificates(der)
256
257
 
257
- override, chain_certs = _check_chain(info, target, port, conn, opts, file_bundle)
258
+ override, chain_certs = _check_chain(
259
+ info, target, port, cert, conn, opts, file_bundle
260
+ )
258
261
  codes.append(override)
259
262
  if opts.verify and target:
260
263
  codes.append(_check_revocation(info, cert, chain_certs, opts))
@@ -288,6 +291,7 @@ def _check_chain(
288
291
  info: CertificateInfo,
289
292
  target: str | None,
290
293
  port: int,
294
+ cert,
291
295
  conn: dict | None,
292
296
  opts: InspectOptions,
293
297
  file_bundle: list | None,
@@ -298,7 +302,9 @@ def _check_chain(
298
302
  Sets ``chain_trusted``/``chain_error`` and, when it fails,
299
303
  ``chain_diagnosis``. Returns UNTRUSTED_OR_REVOKED when the chain is not
300
304
  trusted (else None) and the verified chain, leaf first ([] when
301
- unavailable).
305
+ unavailable). A host whose verification handshake presented a different
306
+ leaf than ``cert`` (a load balancer mid-rotation, say) is not trusted: the
307
+ verdict would belong to another certificate.
302
308
  """
303
309
  if not opts.verify:
304
310
  return None, []
@@ -315,6 +321,12 @@ def _check_chain(
315
321
  opts.retries,
316
322
  )
317
323
  presented = conn.get("chain") if conn else None
324
+ if trusted and verified and verified[0] != cert:
325
+ trusted, verified = False, []
326
+ reason = (
327
+ "the server presented a different certificate on the "
328
+ "verification handshake"
329
+ )
318
330
  else:
319
331
  return None, []
320
332
 
@@ -731,6 +743,7 @@ def main() -> None:
731
743
 
732
744
  _apply_profile(args)
733
745
  _validate_args(args, parser)
746
+ httpfetch.use_proxy(args.proxy, args.no_proxy)
734
747
 
735
748
  if args.discover_only:
736
749
  code = _run_discover_only(args)
@@ -350,8 +350,9 @@ def verify_chain(
350
350
 
351
351
  Open a fully verified TLS handshake (system trust store, hostname check)
352
352
  as a browser would. Return ``(trusted, reason, chain)`` where ``chain`` is
353
- the verified certificate chain (leaf first) when the interpreter exposes
354
- it (Python 3.13+) and verification succeeds, otherwise an empty list.
353
+ the verified certificate chain (leaf first) on success — just the leaf on
354
+ interpreters without ``get_verified_chain`` (before 3.13) — and an empty
355
+ list on failure.
355
356
  ``reason`` is None on success or the verification message on failure.
356
357
  Network-level failures are left to propagate. When ``starttls`` is set the
357
358
  plaintext protocol is upgraded to TLS before the handshake.
@@ -381,7 +382,10 @@ def verify_chain(
381
382
  if starttls:
382
383
  _negotiate_starttls(sock, starttls, read_timeout)
383
384
  with context.wrap_socket(sock, server_hostname=servername or host) as ssock:
384
- return True, None, _chain(ssock, "get_verified_chain")
385
+ chain = _chain(ssock, "get_verified_chain") or [
386
+ x509.load_der_x509_certificate(ssock.getpeercert(binary_form=True))
387
+ ]
388
+ return True, None, chain
385
389
  except ssl.SSLCertVerificationError as err:
386
390
  return False, err.verify_message or str(err), []
387
391
 
@@ -182,9 +182,26 @@ class _PinnedHTTPSHandler(urllib.request.HTTPSHandler):
182
182
  )
183
183
 
184
184
 
185
- _OPENER = urllib.request.build_opener(
186
- _GuardedRedirectHandler, _PinnedHTTPHandler, _PinnedHTTPSHandler
187
- )
185
+ def _build_opener(proxy: str | None = None, no_proxy: bool = False):
186
+ handlers = [_GuardedRedirectHandler, _PinnedHTTPHandler, _PinnedHTTPSHandler]
187
+ if no_proxy:
188
+ handlers.append(urllib.request.ProxyHandler({}))
189
+ elif proxy:
190
+ handlers.append(urllib.request.ProxyHandler({"http": proxy, "https": proxy}))
191
+ return urllib.request.build_opener(*handlers)
192
+
193
+
194
+ _OPENER = _build_opener()
195
+
196
+
197
+ def use_proxy(proxy: str | None, no_proxy: bool = False) -> None:
198
+ """Route every later fetch through ``proxy``, or directly with ``no_proxy``.
199
+
200
+ Mirrors --proxy/--no-proxy for the TLS connections; with neither, the
201
+ environment proxy (``HTTPS_PROXY``/``HTTP_PROXY``, ``NO_PROXY``) applies.
202
+ """
203
+ global _OPENER
204
+ _OPENER = _build_opener(proxy, no_proxy)
188
205
 
189
206
 
190
207
  def fetch(url: str, *, data: bytes | None = None, timeout: float) -> bytes:
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: certinspect
3
- Version: 2.4.3
3
+ Version: 2.4.5
4
4
  Summary: Command-line TLS certificate inspector
5
5
  Author-email: Michele Angrisano <michele.angrisano@gmail.com>
6
6
  License-Expression: MIT
@@ -339,7 +339,10 @@ SAN:
339
339
 
340
340
  By default certinspect opens a fully verified TLS handshake (chain +
341
341
  hostname against the Python/OpenSSL trust store) and, when the certificate
342
- advertises an OCSP responder, queries it for the revocation status. If OCSP is
342
+ advertises an OCSP responder, queries it for the revocation status. The
343
+ verified handshake is a second connection: if the server presents a different
344
+ certificate on it (a load balancer mid-rotation, say), the chain is reported
345
+ as not trusted instead of vouching for a certificate that was not inspected. If OCSP is
343
346
  unavailable, certinspect falls back to the certificate's CRL distribution
344
347
  points (downloaded over HTTP and verified against the issuer). Both checks are
345
348
  soft-fail: when neither OCSP nor the CRL gives an answer the status is
@@ -613,62 +616,62 @@ certinspect example.com --export ./example.com.pem
613
616
 
614
617
  ## Options
615
618
 
616
- | Option | Description |
617
- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
618
- | `target...` | One or more domains, URLs or `host:port` to inspect. Omit when using `--file`. |
619
- | `--config PATH` | Load default option values from a TOML file (keys use the argparse destination name); an explicit flag always overrides it. Auto-discovered at `~/.config/certinspect/config.toml` when omitted. |
620
- | `--file PATH` | Inspect a local certificate (PEM or DER) instead of a host. Use `-` to read from standard input. Repeatable to inspect several files in one run; cannot be combined with host targets. |
621
- | `--port N` | TCP port to connect to (default: 443). |
622
- | `--timeout N` | Connection timeout in seconds (default: 5). Used for both connect and read unless the two below are set. |
623
- | `--connect-timeout N` | TCP connect timeout in seconds (default: `--timeout`). |
624
- | `--read-timeout N` | Handshake/read timeout in seconds (default: `--timeout`). |
625
- | `--retries N` | Retry transient connection failures (timeouts, refused/reset, DNS) this many times (default: 0). |
626
- | `--json` | Print the result as JSON instead of human-readable text. |
627
- | `--csv` | Print the results as CSV (one row per target, with a header). |
628
- | `--csv-delimiter SEP` | Field separator for `--csv` (default `,`). Use `;` for Numbers/Excel in locales that expect it. |
629
- | `--quiet` | Only print certificates that have a problem. |
630
- | `--schema {1,2}` | JSON schema version for `--json` (default `2`, the nested/versioned document). `--schema 1` is the legacy flat array. |
631
- | `--verify` | Force chain verification (already the default). A verified handshake plus OCSP/CRL revocation for a host, or the bundle validated offline for `--file`. |
632
- | `--no-verify` | Skip chain verification (and revocation for hosts); only inspect the certificate itself. |
633
- | `--cafile PATH` | Verify the chain against this CA bundle (PEM) instead of the system trust store; for internal/private PKI. Incompatible with `--no-verify`. |
634
- | `--capath DIR` | Verify the chain against the hashed CA certificates in this directory (OpenSSL `c_rehash` layout). Incompatible with `--no-verify`; may be combined with `--cafile`. |
635
- | `--chain` | Show the certificate chain: presented by the server for a host, or every certificate in the bundle for `--file`. |
636
- | `--client-cert PATH` | Present a client certificate (PEM) for mutual-TLS endpoints (host targets only). Use `--client-key` when the key is stored separately. |
637
- | `--client-key PATH` | Private key (PEM) for `--client-cert` when stored separately from the certificate. |
638
- | `--proxy URL` | Tunnel the connection through an HTTP CONNECT proxy, e.g. `http://proxy:8080` or `http://user:pass@proxy:8080` (host targets only). Without it, the environment proxy (`HTTPS_PROXY`, honouring `NO_PROXY`) is used, like curl. |
639
- | `--no-proxy` | Force a direct connection, ignoring any proxy set in the environment. Mutually exclusive with `--proxy`. |
640
- | `--pin SHA256` | Fail (exit 7) unless the SHA-256 fingerprint matches (colons/case ignored). |
641
- | `--servername NAME` | Override the SNI hostname sent in the handshake (hosts only); the hostname match is checked against `NAME`. For reaching a backend by IP behind a load balancer. |
642
- | `--expect-san NAME` | Assert the certificate's SAN covers `NAME` (wildcards honored); exit 8 if missing. Repeatable; works for host and `--file` targets. |
643
- | `--not-after-max N` | Fail (exit 9) when the total validity exceeds N days (use 398 for the CA/Browser Forum maximum). Opt-in; works for host and `--file` targets. |
644
- | `--cab-forum` | Fail (exit 9) when the total validity exceeds the CA/Browser Forum maximum in effect today (398 days now, then 200, 100 and 47 on 2026/2027/2029-03-15). Date-aware shorthand for `--not-after-max`; mutually exclusive with it. |
645
- | `--min-key-size N` | Fail (exit 9) when an RSA/DSA public key is smaller than N bits (e.g. 2048). EC/EdDSA keys are not size-checked. Opt-in. |
646
- | `--fail-weak` | Turn the weak-crypto warnings (small key, SHA-1/MD5 signature) into a hard failure (exit 9) instead of a mere warning. |
647
- | `--require-sct` | Fail (exit 9) when the certificate embeds no Signed Certificate Timestamps (Certificate Transparency). Checks embedded SCTs only, not those from the TLS handshake or OCSP. Opt-in. |
648
- | `--require-must-staple` | Fail (exit 9) when the certificate lacks the OCSP Must-Staple extension (RFC 7633 TLS Feature `status_request`). Opt-in. |
649
- | `--require-revocation-check` | Fail (exit 9) unless OCSP or CRL returns a definitive `GOOD` revocation verdict. Host targets only; incompatible with `--no-verify`. Opt-in. |
650
- | `--min-tls-version VER` | Fail (exit 9) when the connection negotiates a TLS version older than `VER` (`TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`). Host targets only; opt-in. |
651
- | `--profile {lenient,standard,strict}` | Apply a named bundle of the opt-in policy checks in one go (exit 9 on violation). Intensity ladder, not an official standard; explicit flags override it. See [Policy profiles](#policy-profiles). |
652
- | `--input PATH` | Read extra targets from a file, one per line ('-' for stdin). |
653
- | `--discover DOMAIN` | Discover hostnames from Certificate Transparency logs (crt.sh) for DOMAIN and inspect each one, surfacing forgotten or shadow certificates. Repeatable (queried concurrently per `--concurrency`); host targets only. |
654
- | `--discover-only` | With `--discover`, list the CT inventory (expiry, issuer, hostnames, soonest expiry first, wildcards included) for the domain(s) without connecting, then exit. Good for a fast audit or spotting a certificate from an unexpected CA. Supports `--json`/`--csv`. |
655
- | `--expect-issuer SUBSTRING` | With `--discover-only`, flag any certificate whose issuer matches none of these substrings (case-insensitive) and exit 9 — a Certificate Transparency mis-issuance check. Repeatable. |
656
- | `--discover-timeout N` | Timeout in seconds for the `--discover` crt.sh query (default: 30), separate from `--timeout` since a log search can be slower than a handshake. |
657
- | `--days N` | Warn if the certificate expires within N days (default: 30). |
658
- | `--critical-days N` | Escalate to CRITICAL (exit code 4) when the certificate expires within N days. Must be `<= --days`; feeds Nagios CRITICAL and the `--summary` `critical` count. |
659
- | `--max-days N` | Only show certificates expiring within N days (expired ones always shown; filters display only). |
660
- | `--sort host\|expiry` | Sort the output by host (alphabetical) or by soonest expiry (display only; does not affect exit code). |
661
- | `--summary` | Print a one-line tally (valid/expiring/expired/errors) to stderr; counts every target before filtering. |
662
- | `--field NAME` | Print only the given field(s), one tab-separated line per target (repeatable; `target` for the host). For scripting without a JSON tool. |
663
- | `--exit-zero` | Always exit 0, even on problems or fetch errors. Report-only mode for dashboards/CI that read the output, not the exit code. |
664
- | `--export PATH` | Save the inspected certificate as a PEM file at PATH. Single target only. |
665
- | `--starttls {smtp,imap,pop3,ftp}` | Upgrade a plaintext connection to TLS before inspecting (standard port unless `--port` is given). |
666
- | `--exporter {nagios,prometheus}` | Emit machine-readable monitoring output (ignores `--quiet`). |
667
- | `--concurrency N` | Inspect up to N hosts in parallel in batch mode (default: 1; order is preserved). Also governs `--discover`'s per-domain concurrency. |
668
- | `--state-file PATH` | Persist each host target's status across runs at PATH (JSON) and compare against the previous run. Host targets only. |
669
- | `--only-changed` | Show only targets whose status differs from the previous `--state-file` run (a first-seen target counts as changed). Requires `--state-file`; display only. |
670
- | `--print-completion {bash,zsh}` | Print a shell completion script for bash or zsh to stdout, then exit. Generated from the parser, so it always matches the installed flags. |
671
- | `--version` | Print the version and exit. |
619
+ | Option | Description |
620
+ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
621
+ | `target...` | One or more domains, URLs or `host:port` to inspect. Omit when using `--file`. |
622
+ | `--config PATH` | Load default option values from a TOML file (keys use the argparse destination name); an explicit flag always overrides it. Auto-discovered at `~/.config/certinspect/config.toml` when omitted. |
623
+ | `--file PATH` | Inspect a local certificate (PEM or DER) instead of a host. Use `-` to read from standard input. Repeatable to inspect several files in one run; cannot be combined with host targets. |
624
+ | `--port N` | TCP port to connect to (default: 443). |
625
+ | `--timeout N` | Connection timeout in seconds (default: 5). Used for both connect and read unless the two below are set. |
626
+ | `--connect-timeout N` | TCP connect timeout in seconds (default: `--timeout`). |
627
+ | `--read-timeout N` | Handshake/read timeout in seconds (default: `--timeout`). |
628
+ | `--retries N` | Retry transient connection failures (timeouts, refused/reset, DNS) this many times (default: 0). |
629
+ | `--json` | Print the result as JSON instead of human-readable text. |
630
+ | `--csv` | Print the results as CSV (one row per target, with a header). |
631
+ | `--csv-delimiter SEP` | Field separator for `--csv` (default `,`). Use `;` for Numbers/Excel in locales that expect it. |
632
+ | `--quiet` | Only print certificates that have a problem. |
633
+ | `--schema {1,2}` | JSON schema version for `--json` (default `2`, the nested/versioned document). `--schema 1` is the legacy flat array. |
634
+ | `--verify` | Force chain verification (already the default). A verified handshake plus OCSP/CRL revocation for a host, or the bundle validated offline for `--file`. |
635
+ | `--no-verify` | Skip chain verification (and revocation for hosts); only inspect the certificate itself. |
636
+ | `--cafile PATH` | Verify the chain against this CA bundle (PEM) instead of the system trust store; for internal/private PKI. Incompatible with `--no-verify`. |
637
+ | `--capath DIR` | Verify the chain against the hashed CA certificates in this directory (OpenSSL `c_rehash` layout). Incompatible with `--no-verify`; may be combined with `--cafile`. |
638
+ | `--chain` | Show the certificate chain: presented by the server for a host, or every certificate in the bundle for `--file`. |
639
+ | `--client-cert PATH` | Present a client certificate (PEM) for mutual-TLS endpoints (host targets only). Use `--client-key` when the key is stored separately. |
640
+ | `--client-key PATH` | Private key (PEM) for `--client-cert` when stored separately from the certificate. |
641
+ | `--proxy URL` | Tunnel the connection through an HTTP CONNECT proxy, e.g. `http://proxy:8080` or `http://user:pass@proxy:8080` (host targets only); OCSP/CRL/CA-Issuer/CT-log requests use it too. Without it, the environment proxy (`HTTPS_PROXY`, honouring `NO_PROXY`) is used, like curl. |
642
+ | `--no-proxy` | Force direct connections (OCSP/CRL requests included), ignoring any proxy set in the environment. Mutually exclusive with `--proxy`. |
643
+ | `--pin SHA256` | Fail (exit 7) unless the SHA-256 fingerprint matches (colons/case ignored). |
644
+ | `--servername NAME` | Override the SNI hostname sent in the handshake (hosts only); the hostname match is checked against `NAME`. For reaching a backend by IP behind a load balancer. |
645
+ | `--expect-san NAME` | Assert the certificate's SAN covers `NAME` (wildcards honored); exit 8 if missing. Repeatable; works for host and `--file` targets. |
646
+ | `--not-after-max N` | Fail (exit 9) when the total validity exceeds N days (use 398 for the CA/Browser Forum maximum). Opt-in; works for host and `--file` targets. |
647
+ | `--cab-forum` | Fail (exit 9) when the total validity exceeds the CA/Browser Forum maximum in effect today (398 days now, then 200, 100 and 47 on 2026/2027/2029-03-15). Date-aware shorthand for `--not-after-max`; mutually exclusive with it. |
648
+ | `--min-key-size N` | Fail (exit 9) when an RSA/DSA public key is smaller than N bits (e.g. 2048). EC/EdDSA keys are not size-checked. Opt-in. |
649
+ | `--fail-weak` | Turn the weak-crypto warnings (small key, SHA-1/MD5 signature) into a hard failure (exit 9) instead of a mere warning. |
650
+ | `--require-sct` | Fail (exit 9) when the certificate embeds no Signed Certificate Timestamps (Certificate Transparency). Checks embedded SCTs only, not those from the TLS handshake or OCSP. Opt-in. |
651
+ | `--require-must-staple` | Fail (exit 9) when the certificate lacks the OCSP Must-Staple extension (RFC 7633 TLS Feature `status_request`). Opt-in. |
652
+ | `--require-revocation-check` | Fail (exit 9) unless OCSP or CRL returns a definitive `GOOD` revocation verdict. Host targets only; incompatible with `--no-verify`. Opt-in. |
653
+ | `--min-tls-version VER` | Fail (exit 9) when the connection negotiates a TLS version older than `VER` (`TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`). Host targets only; opt-in. |
654
+ | `--profile {lenient,standard,strict}` | Apply a named bundle of the opt-in policy checks in one go (exit 9 on violation). Intensity ladder, not an official standard; explicit flags override it. See [Policy profiles](#policy-profiles). |
655
+ | `--input PATH` | Read extra targets from a file, one per line ('-' for stdin). |
656
+ | `--discover DOMAIN` | Discover hostnames from Certificate Transparency logs (crt.sh) for DOMAIN and inspect each one, surfacing forgotten or shadow certificates. Repeatable (queried concurrently per `--concurrency`); host targets only. |
657
+ | `--discover-only` | With `--discover`, list the CT inventory (expiry, issuer, hostnames, soonest expiry first, wildcards included) for the domain(s) without connecting, then exit. Good for a fast audit or spotting a certificate from an unexpected CA. Supports `--json`/`--csv`. |
658
+ | `--expect-issuer SUBSTRING` | With `--discover-only`, flag any certificate whose issuer matches none of these substrings (case-insensitive) and exit 9 — a Certificate Transparency mis-issuance check. Repeatable. |
659
+ | `--discover-timeout N` | Timeout in seconds for the `--discover` crt.sh query (default: 30), separate from `--timeout` since a log search can be slower than a handshake. |
660
+ | `--days N` | Warn if the certificate expires within N days (default: 30). |
661
+ | `--critical-days N` | Escalate to CRITICAL (exit code 4) when the certificate expires within N days. Must be `<= --days`; feeds Nagios CRITICAL and the `--summary` `critical` count. |
662
+ | `--max-days N` | Only show certificates expiring within N days (expired ones always shown; filters display only). |
663
+ | `--sort host\|expiry` | Sort the output by host (alphabetical) or by soonest expiry (display only; does not affect exit code). |
664
+ | `--summary` | Print a one-line tally (valid/expiring/expired/errors) to stderr; counts every target before filtering. |
665
+ | `--field NAME` | Print only the given field(s), one tab-separated line per target (repeatable; `target` for the host). For scripting without a JSON tool. |
666
+ | `--exit-zero` | Always exit 0, even on problems or fetch errors. Report-only mode for dashboards/CI that read the output, not the exit code. |
667
+ | `--export PATH` | Save the inspected certificate as a PEM file at PATH. Single target only. |
668
+ | `--starttls {smtp,imap,pop3,ftp}` | Upgrade a plaintext connection to TLS before inspecting (standard port unless `--port` is given). |
669
+ | `--exporter {nagios,prometheus}` | Emit machine-readable monitoring output (ignores `--quiet`). |
670
+ | `--concurrency N` | Inspect up to N hosts in parallel in batch mode (default: 1; order is preserved). Also governs `--discover`'s per-domain concurrency. |
671
+ | `--state-file PATH` | Persist each host target's status across runs at PATH (JSON) and compare against the previous run. Host targets only. |
672
+ | `--only-changed` | Show only targets whose status differs from the previous `--state-file` run (a first-seen target counts as changed). Requires `--state-file`; display only. |
673
+ | `--print-completion {bash,zsh}` | Print a shell completion script for bash or zsh to stdout, then exit. Generated from the parser, so it always matches the installed flags. |
674
+ | `--version` | Print the version and exit. |
672
675
 
673
676
  ## Options in action
674
677
 
@@ -992,12 +995,16 @@ Status: VALID
992
995
 
993
996
  Tunnel the TLS connection through an HTTP `CONNECT` proxy, so a host reachable
994
997
  only through a corporate/cloud egress proxy can still be inspected. Basic proxy
995
- auth is supported via `user:pass@`.
998
+ auth is supported via `user:pass@`. The OCSP, CRL, CA-Issuer and CT-log
999
+ (`--discover`) requests use the same proxy, so revocation still works where
1000
+ only the proxy reaches the Internet. Their host names are still resolved
1001
+ locally for the internal-address check.
996
1002
 
997
1003
  Like curl, certinspect also uses the environment proxy automatically when
998
1004
  `--proxy` is not given: it reads `HTTPS_PROXY`/`HTTP_PROXY` (and the system
999
- proxy on macOS/Windows) and honours `NO_PROXY`. Use `--no-proxy` to force a
1000
- direct connection regardless of the environment.
1005
+ proxy on macOS/Windows) and honours `NO_PROXY`. Use `--no-proxy` to force
1006
+ direct connections, for the OCSP/CRL requests too, regardless of the
1007
+ environment.
1001
1008
 
1002
1009
  ```console
1003
1010
  $ certinspect example.com --proxy http://proxy.corp:8080 # explicit
@@ -1103,6 +1103,31 @@ def test_main_forwards_no_proxy(monkeypatch, capsys, make_cert):
1103
1103
  assert recorded.get("no_proxy") is True
1104
1104
 
1105
1105
 
1106
+ @pytest.mark.parametrize(
1107
+ "flags, expected",
1108
+ [
1109
+ (["--proxy", "http://proxy:8080"], ("http://proxy:8080", False)),
1110
+ (["--no-proxy"], (None, True)),
1111
+ ([], (None, False)),
1112
+ ],
1113
+ )
1114
+ def test_main_applies_the_proxy_choice_to_http_fetches(
1115
+ monkeypatch, make_cert, flags, expected
1116
+ ):
1117
+ """OCSP/CRL/CA-Issuer/CT-log requests follow --proxy/--no-proxy too."""
1118
+ calls = []
1119
+ monkeypatch.setattr(
1120
+ "certinspect.cli.get_server_cert",
1121
+ _recording_fetch(make_cert(san=["example.com"]), {}),
1122
+ )
1123
+ monkeypatch.setattr(
1124
+ "certinspect.cli.httpfetch.use_proxy",
1125
+ lambda proxy, no_proxy=False: calls.append((proxy, no_proxy)),
1126
+ )
1127
+ _run_main(monkeypatch, ["example.com", *flags])
1128
+ assert calls == [expected]
1129
+
1130
+
1106
1131
  def test_main_proxy_and_no_proxy_conflict(monkeypatch, capsys):
1107
1132
  code = _run_main(
1108
1133
  monkeypatch, ["example.com", "--proxy", "http://p:8080", "--no-proxy"]
@@ -1723,6 +1748,41 @@ def test_main_verify_revocation_unavailable_is_soft_fail(
1723
1748
  assert code == 0
1724
1749
 
1725
1750
 
1751
+ def _verified_leaf(der):
1752
+ """Return a verify_chain replacement trusting a chain whose leaf is ``der``."""
1753
+ from cryptography import x509
1754
+
1755
+ leaf = x509.load_der_x509_certificate(der)
1756
+ return lambda *a, **k: (True, None, [leaf])
1757
+
1758
+
1759
+ def test_main_verify_rejects_a_different_leaf_on_the_verification_handshake(
1760
+ monkeypatch, capsys, make_cert
1761
+ ):
1762
+ """A load balancer serving another certificate to the verification
1763
+ handshake must not make the inspected certificate look trusted."""
1764
+ inspected = make_cert(san=["example.com"])
1765
+ monkeypatch.setattr("certinspect.cli.get_server_cert", _const_fetch(inspected))
1766
+ monkeypatch.setattr(
1767
+ "certinspect.cli.verify_chain", _verified_leaf(make_cert(san=["example.com"]))
1768
+ )
1769
+ code = _run_main(monkeypatch, ["example.com", "--json"])
1770
+ result = json.loads(capsys.readouterr().out)["results"][0]
1771
+ assert code == 6
1772
+ assert result["chain"]["trusted"] is False
1773
+ assert "different certificate" in result["chain"]["error"]
1774
+
1775
+
1776
+ def test_main_verify_trusts_the_same_leaf(monkeypatch, capsys, make_cert):
1777
+ inspected = make_cert(san=["example.com"])
1778
+ monkeypatch.setattr("certinspect.cli.get_server_cert", _const_fetch(inspected))
1779
+ monkeypatch.setattr("certinspect.cli.verify_chain", _verified_leaf(inspected))
1780
+ code = _run_main(monkeypatch, ["example.com", "--json"])
1781
+ result = json.loads(capsys.readouterr().out)["results"][0]
1782
+ assert code == 0
1783
+ assert result["chain"]["trusted"] is True
1784
+
1785
+
1726
1786
  def test_main_file_verify_reports_untrusted_self_signed(
1727
1787
  monkeypatch, capsys, tmp_path, make_cert
1728
1788
  ):
@@ -998,6 +998,49 @@ def test_http_malformed_response_is_a_value_error(monkeypatch, serve):
998
998
  httpfetch.fetch(f"{public}/crl", timeout=3.0)
999
999
 
1000
1000
 
1001
+ def _resolve_publicly(monkeypatch, name):
1002
+ """Make ``name`` pass the address check without real DNS."""
1003
+ import socket as _socket
1004
+
1005
+ from certinspect import httpfetch
1006
+
1007
+ real_getaddrinfo = _socket.getaddrinfo
1008
+
1009
+ def fake(host, *args, **kwargs):
1010
+ if host == name:
1011
+ return _addrinfo("93.184.215.14")
1012
+ return real_getaddrinfo(host, *args, **kwargs)
1013
+
1014
+ monkeypatch.setattr(httpfetch.socket, "getaddrinfo", fake)
1015
+
1016
+
1017
+ def test_use_proxy_routes_fetches_through_the_proxy(monkeypatch, serve):
1018
+ from certinspect import httpfetch
1019
+
1020
+ hits = []
1021
+ proxy = serve(_body(b"VIA-PROXY", hits))
1022
+ _resolve_publicly(monkeypatch, "ocsp.example")
1023
+
1024
+ httpfetch.use_proxy(proxy)
1025
+ assert httpfetch.fetch("http://ocsp.example/ca.crl", timeout=3.0) == b"VIA-PROXY"
1026
+ assert hits == ["http://ocsp.example/ca.crl"]
1027
+
1028
+
1029
+ def test_use_proxy_no_proxy_ignores_the_environment(monkeypatch, serve):
1030
+ from certinspect import httpfetch
1031
+
1032
+ proxy_hits, direct_hits = [], []
1033
+ proxy = serve(_body(b"VIA-PROXY", proxy_hits))
1034
+ direct = serve(_body(b"DIRECT", direct_hits))
1035
+ _guard_allowing(monkeypatch, direct)
1036
+ monkeypatch.setenv("http_proxy", proxy)
1037
+ monkeypatch.delenv("no_proxy", raising=False)
1038
+
1039
+ httpfetch.use_proxy(None, no_proxy=True)
1040
+ assert httpfetch.fetch(f"{direct}/ca.crl", timeout=3.0) == b"DIRECT"
1041
+ assert proxy_hits == []
1042
+
1043
+
1001
1044
  # --- OCSP response freshness ------------------------------------------------
1002
1045
 
1003
1046
 
File without changes
File without changes