certinspect 2.4.4__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.
- {certinspect-2.4.4/src/certinspect.egg-info → certinspect-2.4.5}/PKG-INFO +64 -60
- {certinspect-2.4.4 → certinspect-2.4.5}/README.md +63 -59
- {certinspect-2.4.4 → certinspect-2.4.5}/pyproject.toml +1 -1
- {certinspect-2.4.4 → certinspect-2.4.5}/src/certinspect/__init__.py +1 -1
- {certinspect-2.4.4 → certinspect-2.4.5}/src/certinspect/args.py +5 -3
- {certinspect-2.4.4 → certinspect-2.4.5}/src/certinspect/cli.py +2 -0
- {certinspect-2.4.4 → certinspect-2.4.5}/src/certinspect/httpfetch.py +20 -3
- {certinspect-2.4.4 → certinspect-2.4.5/src/certinspect.egg-info}/PKG-INFO +64 -60
- {certinspect-2.4.4 → certinspect-2.4.5}/tests/test_cli.py +25 -0
- {certinspect-2.4.4 → certinspect-2.4.5}/tests/test_fetch.py +43 -0
- {certinspect-2.4.4 → certinspect-2.4.5}/LICENSE +0 -0
- {certinspect-2.4.4 → certinspect-2.4.5}/setup.cfg +0 -0
- {certinspect-2.4.4 → certinspect-2.4.5}/src/certinspect/completion.py +0 -0
- {certinspect-2.4.4 → certinspect-2.4.5}/src/certinspect/config.py +0 -0
- {certinspect-2.4.4 → certinspect-2.4.5}/src/certinspect/discover.py +0 -0
- {certinspect-2.4.4 → certinspect-2.4.5}/src/certinspect/exit_codes.py +0 -0
- {certinspect-2.4.4 → certinspect-2.4.5}/src/certinspect/fetch.py +0 -0
- {certinspect-2.4.4 → certinspect-2.4.5}/src/certinspect/formatter.py +0 -0
- {certinspect-2.4.4 → certinspect-2.4.5}/src/certinspect/models.py +0 -0
- {certinspect-2.4.4 → certinspect-2.4.5}/src/certinspect/parser.py +0 -0
- {certinspect-2.4.4 → certinspect-2.4.5}/src/certinspect/render.py +0 -0
- {certinspect-2.4.4 → certinspect-2.4.5}/src/certinspect/revocation.py +0 -0
- {certinspect-2.4.4 → certinspect-2.4.5}/src/certinspect/state.py +0 -0
- {certinspect-2.4.4 → certinspect-2.4.5}/src/certinspect.egg-info/SOURCES.txt +0 -0
- {certinspect-2.4.4 → certinspect-2.4.5}/src/certinspect.egg-info/dependency_links.txt +0 -0
- {certinspect-2.4.4 → certinspect-2.4.5}/src/certinspect.egg-info/entry_points.txt +0 -0
- {certinspect-2.4.4 → certinspect-2.4.5}/src/certinspect.egg-info/requires.txt +0 -0
- {certinspect-2.4.4 → certinspect-2.4.5}/src/certinspect.egg-info/top_level.txt +0 -0
- {certinspect-2.4.4 → certinspect-2.4.5}/tests/test_discover.py +0 -0
- {certinspect-2.4.4 → certinspect-2.4.5}/tests/test_formatter.py +0 -0
- {certinspect-2.4.4 → 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
|
+
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
|
|
@@ -616,62 +616,62 @@ certinspect example.com --export ./example.com.pem
|
|
|
616
616
|
|
|
617
617
|
## Options
|
|
618
618
|
|
|
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). Without it, the environment proxy (`HTTPS_PROXY`, honouring `NO_PROXY`) is used, like curl.
|
|
642
|
-
| `--no-proxy` | Force
|
|
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.
|
|
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. |
|
|
675
675
|
|
|
676
676
|
## Options in action
|
|
677
677
|
|
|
@@ -995,12 +995,16 @@ Status: VALID
|
|
|
995
995
|
|
|
996
996
|
Tunnel the TLS connection through an HTTP `CONNECT` proxy, so a host reachable
|
|
997
997
|
only through a corporate/cloud egress proxy can still be inspected. Basic proxy
|
|
998
|
-
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.
|
|
999
1002
|
|
|
1000
1003
|
Like curl, certinspect also uses the environment proxy automatically when
|
|
1001
1004
|
`--proxy` is not given: it reads `HTTPS_PROXY`/`HTTP_PROXY` (and the system
|
|
1002
|
-
proxy on macOS/Windows) and honours `NO_PROXY`. Use `--no-proxy` to force
|
|
1003
|
-
direct
|
|
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.
|
|
1004
1008
|
|
|
1005
1009
|
```console
|
|
1006
1010
|
$ certinspect example.com --proxy http://proxy.corp:8080 # explicit
|
|
@@ -590,62 +590,62 @@ certinspect example.com --export ./example.com.pem
|
|
|
590
590
|
|
|
591
591
|
## Options
|
|
592
592
|
|
|
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). Without it, the environment proxy (`HTTPS_PROXY`, honouring `NO_PROXY`) is used, like curl.
|
|
616
|
-
| `--no-proxy` | Force
|
|
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.
|
|
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. |
|
|
649
649
|
|
|
650
650
|
## Options in action
|
|
651
651
|
|
|
@@ -969,12 +969,16 @@ Status: VALID
|
|
|
969
969
|
|
|
970
970
|
Tunnel the TLS connection through an HTTP `CONNECT` proxy, so a host reachable
|
|
971
971
|
only through a corporate/cloud egress proxy can still be inspected. Basic proxy
|
|
972
|
-
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.
|
|
973
976
|
|
|
974
977
|
Like curl, certinspect also uses the environment proxy automatically when
|
|
975
978
|
`--proxy` is not given: it reads `HTTPS_PROXY`/`HTTP_PROXY` (and the system
|
|
976
|
-
proxy on macOS/Windows) and honours `NO_PROXY`. Use `--no-proxy` to force
|
|
977
|
-
direct
|
|
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.
|
|
978
982
|
|
|
979
983
|
```console
|
|
980
984
|
$ certinspect example.com --proxy http://proxy.corp:8080 # explicit
|
|
@@ -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)
|
|
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
|
|
237
|
-
"environment. Mutually
|
|
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,
|
|
@@ -742,6 +743,7 @@ def main() -> None:
|
|
|
742
743
|
|
|
743
744
|
_apply_profile(args)
|
|
744
745
|
_validate_args(args, parser)
|
|
746
|
+
httpfetch.use_proxy(args.proxy, args.no_proxy)
|
|
745
747
|
|
|
746
748
|
if args.discover_only:
|
|
747
749
|
code = _run_discover_only(args)
|
|
@@ -182,9 +182,26 @@ class _PinnedHTTPSHandler(urllib.request.HTTPSHandler):
|
|
|
182
182
|
)
|
|
183
183
|
|
|
184
184
|
|
|
185
|
-
|
|
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
|
+
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
|
|
@@ -616,62 +616,62 @@ certinspect example.com --export ./example.com.pem
|
|
|
616
616
|
|
|
617
617
|
## Options
|
|
618
618
|
|
|
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). Without it, the environment proxy (`HTTPS_PROXY`, honouring `NO_PROXY`) is used, like curl.
|
|
642
|
-
| `--no-proxy` | Force
|
|
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.
|
|
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. |
|
|
675
675
|
|
|
676
676
|
## Options in action
|
|
677
677
|
|
|
@@ -995,12 +995,16 @@ Status: VALID
|
|
|
995
995
|
|
|
996
996
|
Tunnel the TLS connection through an HTTP `CONNECT` proxy, so a host reachable
|
|
997
997
|
only through a corporate/cloud egress proxy can still be inspected. Basic proxy
|
|
998
|
-
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.
|
|
999
1002
|
|
|
1000
1003
|
Like curl, certinspect also uses the environment proxy automatically when
|
|
1001
1004
|
`--proxy` is not given: it reads `HTTPS_PROXY`/`HTTP_PROXY` (and the system
|
|
1002
|
-
proxy on macOS/Windows) and honours `NO_PROXY`. Use `--no-proxy` to force
|
|
1003
|
-
direct
|
|
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.
|
|
1004
1008
|
|
|
1005
1009
|
```console
|
|
1006
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"]
|
|
@@ -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
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|