certinspect 2.3.3__tar.gz → 2.4.0__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.3.3/src/certinspect.egg-info → certinspect-2.4.0}/PKG-INFO +42 -31
  2. {certinspect-2.3.3 → certinspect-2.4.0}/README.md +41 -30
  3. {certinspect-2.3.3 → certinspect-2.4.0}/pyproject.toml +1 -1
  4. {certinspect-2.3.3 → certinspect-2.4.0}/src/certinspect/__init__.py +1 -1
  5. {certinspect-2.3.3 → certinspect-2.4.0}/src/certinspect/args.py +3 -2
  6. {certinspect-2.3.3 → certinspect-2.4.0}/src/certinspect/cli.py +39 -35
  7. {certinspect-2.3.3 → certinspect-2.4.0}/src/certinspect/exit_codes.py +26 -0
  8. {certinspect-2.3.3 → certinspect-2.4.0}/src/certinspect/fetch.py +40 -8
  9. {certinspect-2.3.3 → certinspect-2.4.0}/src/certinspect/formatter.py +10 -1
  10. {certinspect-2.3.3 → certinspect-2.4.0}/src/certinspect/httpfetch.py +33 -6
  11. {certinspect-2.3.3 → certinspect-2.4.0}/src/certinspect/models.py +2 -1
  12. {certinspect-2.3.3 → certinspect-2.4.0}/src/certinspect/parser.py +36 -8
  13. certinspect-2.4.0/src/certinspect/revocation.py +445 -0
  14. {certinspect-2.3.3 → certinspect-2.4.0/src/certinspect.egg-info}/PKG-INFO +42 -31
  15. {certinspect-2.3.3 → certinspect-2.4.0}/tests/test_cli.py +167 -4
  16. {certinspect-2.3.3 → certinspect-2.4.0}/tests/test_fetch.py +602 -1
  17. {certinspect-2.3.3 → certinspect-2.4.0}/tests/test_formatter.py +10 -0
  18. {certinspect-2.3.3 → certinspect-2.4.0}/tests/test_parser.py +33 -0
  19. certinspect-2.3.3/src/certinspect/revocation.py +0 -257
  20. {certinspect-2.3.3 → certinspect-2.4.0}/LICENSE +0 -0
  21. {certinspect-2.3.3 → certinspect-2.4.0}/setup.cfg +0 -0
  22. {certinspect-2.3.3 → certinspect-2.4.0}/src/certinspect/completion.py +0 -0
  23. {certinspect-2.3.3 → certinspect-2.4.0}/src/certinspect/config.py +0 -0
  24. {certinspect-2.3.3 → certinspect-2.4.0}/src/certinspect/discover.py +0 -0
  25. {certinspect-2.3.3 → certinspect-2.4.0}/src/certinspect/render.py +0 -0
  26. {certinspect-2.3.3 → certinspect-2.4.0}/src/certinspect.egg-info/SOURCES.txt +0 -0
  27. {certinspect-2.3.3 → certinspect-2.4.0}/src/certinspect.egg-info/dependency_links.txt +0 -0
  28. {certinspect-2.3.3 → certinspect-2.4.0}/src/certinspect.egg-info/entry_points.txt +0 -0
  29. {certinspect-2.3.3 → certinspect-2.4.0}/src/certinspect.egg-info/requires.txt +0 -0
  30. {certinspect-2.3.3 → certinspect-2.4.0}/src/certinspect.egg-info/top_level.txt +0 -0
  31. {certinspect-2.3.3 → certinspect-2.4.0}/tests/test_discover.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: certinspect
3
- Version: 2.3.3
3
+ Version: 2.4.0
4
4
  Summary: Command-line TLS certificate inspector
5
5
  Author-email: Michele Angrisano <michele.angrisano@gmail.com>
6
6
  License-Expression: MIT
@@ -61,7 +61,7 @@ Subject: CN=example.com
61
61
  Status: VALID
62
62
  Days to expiry: 64
63
63
  Signature: ecdsa-with-SHA256
64
- Key size: 256 bit
64
+ Key size: 256 bit (EC)
65
65
  TLS version: TLSv1.3
66
66
  Cipher: TLS_AES_256_GCM_SHA384
67
67
  Hostname match: True
@@ -161,7 +161,7 @@ $ echo $? # 0 = healthy, 3 = expiring, 4 = expired, 6 = revoked, ...
161
161
  | Triage helpers | Only certs expiring within N days (`--max-days`), sort by host or soonest expiry (`--sort`), one-line tally (`--summary`), tighter CRITICAL threshold (`--critical-days`) |
162
162
  | Protocols | Direct TLS plus STARTTLS — SMTP, IMAP, POP3, FTP (`--starttls`) |
163
163
  | Connectivity | Mutual-TLS client certificates (`--client-cert`/`--client-key`) and HTTP CONNECT proxy tunnelling — explicit (`--proxy`) or from the environment (`HTTPS_PROXY`/`NO_PROXY`, like curl; `--no-proxy` to opt out) — for hosts behind a corporate/cloud egress proxy |
164
- | Automation | Meaningful exit codes for cron/CI (or force success with `--exit-zero`), no telemetry, single runtime dependency, defaults from a `--config` file, low-noise recurring runs with `--state-file`/`--only-changed`, shell completion (`--print-completion`) |
164
+ | Automation | Meaningful exit codes for cron/CI (or force success with `--exit-zero`), no telemetry, single runtime dependency, defaults from a `--config` file, low-noise recurring runs with `--state-file`/`--only-changed`, shell completion (`--print-completion`) |
165
165
 
166
166
  ## Requirements
167
167
 
@@ -318,7 +318,7 @@ Total validity: 396 days
318
318
 
319
319
  Serial number: 1587345912129534630556007389588586994
320
320
  Signature: sha256WithRSAEncryption
321
- Key size: 2048 bit
321
+ Key size: 2048 bit (RSA)
322
322
  Fingerprint: 15:58:1C:41:02:3F:07:89:85:31:4E:7D:4C:4F:8A:CA:BF:05:C7:F6:...
323
323
  CA: False
324
324
  Self-Signed: False
@@ -614,8 +614,8 @@ certinspect example.com --export ./example.com.pem
614
614
  | Option | Description |
615
615
  | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
616
616
  | `target...` | One or more domains, URLs or `host:port` to inspect. Omit when using `--file`. |
617
- | `--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. |
618
- | `--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. |
617
+ | `--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. |
618
+ | `--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. |
619
619
  | `--port N` | TCP port to connect to (default: 443). |
620
620
  | `--timeout N` | Connection timeout in seconds (default: 5). Used for both connect and read unless the two below are set. |
621
621
  | `--connect-timeout N` | TCP connect timeout in seconds (default: `--timeout`). |
@@ -640,7 +640,7 @@ certinspect example.com --export ./example.com.pem
640
640
  | `--expect-san NAME` | Assert the certificate's SAN covers `NAME` (wildcards honored); exit 8 if missing. Repeatable; works for host and `--file` targets. |
641
641
  | `--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. |
642
642
  | `--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. |
643
- | `--min-key-size N` | Fail (exit 9) when the public key is smaller than N bits (e.g. 2048 for RSA). Opt-in. |
643
+ | `--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. |
644
644
  | `--fail-weak` | Turn the weak-crypto warnings (small key, SHA-1/MD5 signature) into a hard failure (exit 9) instead of a mere warning. |
645
645
  | `--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. |
646
646
  | `--require-must-staple` | Fail (exit 9) when the certificate lacks the OCSP Must-Staple extension (RFC 7633 TLS Feature `status_request`). Opt-in. |
@@ -648,7 +648,7 @@ certinspect example.com --export ./example.com.pem
648
648
  | `--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. |
649
649
  | `--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). |
650
650
  | `--input PATH` | Read extra targets from a file, one per line ('-' for stdin). |
651
- | `--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. |
651
+ | `--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. |
652
652
  | `--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`. |
653
653
  | `--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. |
654
654
  | `--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. |
@@ -663,9 +663,9 @@ certinspect example.com --export ./example.com.pem
663
663
  | `--starttls {smtp,imap,pop3,ftp}` | Upgrade a plaintext connection to TLS before inspecting (standard port unless `--port` is given). |
664
664
  | `--exporter {nagios,prometheus}` | Emit machine-readable monitoring output (ignores `--quiet`). |
665
665
  | `--concurrency N` | Inspect up to N hosts in parallel in batch mode (default: 1; order is preserved). Also governs `--discover`'s per-domain concurrency. |
666
- | `--state-file PATH` | Persist each host target's status across runs at PATH (JSON) and compare against the previous run. Host targets only. |
667
- | `--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. |
668
- | `--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. |
666
+ | `--state-file PATH` | Persist each host target's status across runs at PATH (JSON) and compare against the previous run. Host targets only. |
667
+ | `--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. |
668
+ | `--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. |
669
669
  | `--version` | Print the version and exit. |
670
670
 
671
671
  ## Options in action
@@ -689,7 +689,7 @@ Total validity: 90 days
689
689
 
690
690
  Serial number: 35428337808578903465180920265426569102
691
691
  Signature: ecdsa-with-SHA256
692
- Key size: 256 bit
692
+ Key size: 256 bit (EC)
693
693
  Fingerprint: BE:AB:14:CF:39:67:8F:DA:0E:F1:60:6E:ED:B8:18:C2:...
694
694
  CA: False
695
695
  Self-Signed: False
@@ -787,6 +787,7 @@ $ certinspect example.com --json
787
787
  "is_ca": false,
788
788
  "san": ["example.com", "*.example.com"],
789
789
  "key": {
790
+ "type": "EC",
790
791
  "size": 256,
791
792
  "signature_algorithm": "ecdsa-with-SHA256",
792
793
  "usage": ["digital_signature"],
@@ -1047,13 +1048,16 @@ $ echo $?
1047
1048
 
1048
1049
  ### `--min-key-size N`
1049
1050
 
1050
- Fail (exit code 9) when the public key is smaller than N bits — e.g. reject
1051
- any RSA key below 2048 bit. Opt-in.
1051
+ Fail (exit code 9) when an RSA or DSA public key is smaller than N bits — e.g.
1052
+ reject any RSA key below 2048 bit. EC and EdDSA keys are not compared against
1053
+ N (their bit lengths are on a different scale: a 256-bit EC key is roughly as
1054
+ strong as 3072-bit RSA); `--fail-weak` still flags an EC key below 256 bit.
1055
+ Opt-in.
1052
1056
 
1053
1057
  ```console
1054
1058
  $ certinspect example.com --min-key-size 2048
1055
1059
  ...
1056
- Key size: 1024 bit
1060
+ Key size: 1024 bit (RSA)
1057
1061
  ...
1058
1062
  Policy: FAIL
1059
1063
  WARNING: policy violation (key size 1024 bit is below the 2048-bit minimum)
@@ -1192,7 +1196,7 @@ Precedence and edge cases a sysadmin should know:
1192
1196
  ```console
1193
1197
  $ certinspect example.com --profile standard
1194
1198
  ...
1195
- Key size: 1024 bit
1199
+ Key size: 1024 bit (RSA)
1196
1200
  TLS version: TLSv1.3
1197
1201
  Policy: FAIL
1198
1202
  WARNING: policy violation (key size 1024 bit is below the 2048-bit minimum)
@@ -1430,7 +1434,7 @@ the repository with the most commonly-set options — copy the ones you want.
1430
1434
 
1431
1435
  ### `--state-file PATH` / `--only-changed`
1432
1436
 
1433
- For a recurring job (cron, CI) where you only care when something *changes* —
1437
+ For a recurring job (cron, CI) where you only care when something _changes_ —
1434
1438
  not being reminded every run that a certificate is still fine. `--state-file`
1435
1439
  records each host's status in a small JSON file; `--only-changed` then limits
1436
1440
  the report to targets whose status differs from the previous run (a target
@@ -1539,20 +1543,27 @@ certinspect_policy_ok{target="example.com"} 0
1539
1543
 
1540
1544
  ## Exit codes
1541
1545
 
1542
- Designed for automation (cron, CI, monitoring scripts). In batch mode the
1543
- worst code across all targets is returned.
1544
-
1545
- | Code | Meaning |
1546
- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
1547
- | 0 | Valid certificate |
1548
- | 1 | Runtime error (network, file, parse) |
1549
- | 2 | Command-line usage error |
1550
- | 3 | Expiring within the `--days` threshold |
1551
- | 4 | Expired, not yet valid, or with invalid dates |
1552
- | 5 | Hostname does not match the certificate |
1553
- | 6 | Chain not trusted or revoked (`--verify`) |
1554
- | 7 | Fingerprint does not match `--pin` |
1555
- | 8 | Expected SAN missing (`--expect-san`) |
1546
+ Designed for automation (cron, CI, monitoring scripts). A single number can
1547
+ report only one problem, so when a certificate has several (e.g. expired _and_
1548
+ a weak key), or a batch has several targets, the **most severe** one is
1549
+ returned. The codes are labels, not a scale; severity follows this order, most
1550
+ severe first:
1551
+
1552
+ `6` untrusted/revoked → `7` pin mismatch → `4` expired/not yet valid → `5`
1553
+ hostname mismatch → `1` runtime error (e.g. unreachable host) → `8` SAN
1554
+ missing → `9` policy → `3` expiring → `0` valid.
1555
+
1556
+ | Code | Meaning |
1557
+ | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1558
+ | 0 | Valid certificate |
1559
+ | 1 | Runtime error (network, file, parse) |
1560
+ | 2 | Command-line usage error |
1561
+ | 3 | Expiring within the `--days` threshold |
1562
+ | 4 | Expired, not yet valid, or with invalid dates |
1563
+ | 5 | Hostname does not match the certificate |
1564
+ | 6 | Chain not trusted or revoked (`--verify`) |
1565
+ | 7 | Fingerprint does not match `--pin` |
1566
+ | 8 | Expected SAN missing (`--expect-san`) |
1556
1567
  | 9 | Policy violation (`--not-after-max`/`--cab-forum`, `--min-key-size`, `--fail-weak`, `--require-sct`, `--require-must-staple`, `--require-revocation-check`, `--min-tls-version`) |
1557
1568
 
1558
1569
  Example in a script:
@@ -35,7 +35,7 @@ Subject: CN=example.com
35
35
  Status: VALID
36
36
  Days to expiry: 64
37
37
  Signature: ecdsa-with-SHA256
38
- Key size: 256 bit
38
+ Key size: 256 bit (EC)
39
39
  TLS version: TLSv1.3
40
40
  Cipher: TLS_AES_256_GCM_SHA384
41
41
  Hostname match: True
@@ -135,7 +135,7 @@ $ echo $? # 0 = healthy, 3 = expiring, 4 = expired, 6 = revoked, ...
135
135
  | Triage helpers | Only certs expiring within N days (`--max-days`), sort by host or soonest expiry (`--sort`), one-line tally (`--summary`), tighter CRITICAL threshold (`--critical-days`) |
136
136
  | Protocols | Direct TLS plus STARTTLS — SMTP, IMAP, POP3, FTP (`--starttls`) |
137
137
  | Connectivity | Mutual-TLS client certificates (`--client-cert`/`--client-key`) and HTTP CONNECT proxy tunnelling — explicit (`--proxy`) or from the environment (`HTTPS_PROXY`/`NO_PROXY`, like curl; `--no-proxy` to opt out) — for hosts behind a corporate/cloud egress proxy |
138
- | Automation | Meaningful exit codes for cron/CI (or force success with `--exit-zero`), no telemetry, single runtime dependency, defaults from a `--config` file, low-noise recurring runs with `--state-file`/`--only-changed`, shell completion (`--print-completion`) |
138
+ | Automation | Meaningful exit codes for cron/CI (or force success with `--exit-zero`), no telemetry, single runtime dependency, defaults from a `--config` file, low-noise recurring runs with `--state-file`/`--only-changed`, shell completion (`--print-completion`) |
139
139
 
140
140
  ## Requirements
141
141
 
@@ -292,7 +292,7 @@ Total validity: 396 days
292
292
 
293
293
  Serial number: 1587345912129534630556007389588586994
294
294
  Signature: sha256WithRSAEncryption
295
- Key size: 2048 bit
295
+ Key size: 2048 bit (RSA)
296
296
  Fingerprint: 15:58:1C:41:02:3F:07:89:85:31:4E:7D:4C:4F:8A:CA:BF:05:C7:F6:...
297
297
  CA: False
298
298
  Self-Signed: False
@@ -588,8 +588,8 @@ certinspect example.com --export ./example.com.pem
588
588
  | Option | Description |
589
589
  | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
590
590
  | `target...` | One or more domains, URLs or `host:port` to inspect. Omit when using `--file`. |
591
- | `--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. |
592
- | `--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. |
591
+ | `--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. |
592
+ | `--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. |
593
593
  | `--port N` | TCP port to connect to (default: 443). |
594
594
  | `--timeout N` | Connection timeout in seconds (default: 5). Used for both connect and read unless the two below are set. |
595
595
  | `--connect-timeout N` | TCP connect timeout in seconds (default: `--timeout`). |
@@ -614,7 +614,7 @@ certinspect example.com --export ./example.com.pem
614
614
  | `--expect-san NAME` | Assert the certificate's SAN covers `NAME` (wildcards honored); exit 8 if missing. Repeatable; works for host and `--file` targets. |
615
615
  | `--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. |
616
616
  | `--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. |
617
- | `--min-key-size N` | Fail (exit 9) when the public key is smaller than N bits (e.g. 2048 for RSA). Opt-in. |
617
+ | `--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. |
618
618
  | `--fail-weak` | Turn the weak-crypto warnings (small key, SHA-1/MD5 signature) into a hard failure (exit 9) instead of a mere warning. |
619
619
  | `--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. |
620
620
  | `--require-must-staple` | Fail (exit 9) when the certificate lacks the OCSP Must-Staple extension (RFC 7633 TLS Feature `status_request`). Opt-in. |
@@ -622,7 +622,7 @@ certinspect example.com --export ./example.com.pem
622
622
  | `--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. |
623
623
  | `--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). |
624
624
  | `--input PATH` | Read extra targets from a file, one per line ('-' for stdin). |
625
- | `--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. |
625
+ | `--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. |
626
626
  | `--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`. |
627
627
  | `--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. |
628
628
  | `--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. |
@@ -637,9 +637,9 @@ certinspect example.com --export ./example.com.pem
637
637
  | `--starttls {smtp,imap,pop3,ftp}` | Upgrade a plaintext connection to TLS before inspecting (standard port unless `--port` is given). |
638
638
  | `--exporter {nagios,prometheus}` | Emit machine-readable monitoring output (ignores `--quiet`). |
639
639
  | `--concurrency N` | Inspect up to N hosts in parallel in batch mode (default: 1; order is preserved). Also governs `--discover`'s per-domain concurrency. |
640
- | `--state-file PATH` | Persist each host target's status across runs at PATH (JSON) and compare against the previous run. Host targets only. |
641
- | `--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. |
642
- | `--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. |
640
+ | `--state-file PATH` | Persist each host target's status across runs at PATH (JSON) and compare against the previous run. Host targets only. |
641
+ | `--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. |
642
+ | `--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. |
643
643
  | `--version` | Print the version and exit. |
644
644
 
645
645
  ## Options in action
@@ -663,7 +663,7 @@ Total validity: 90 days
663
663
 
664
664
  Serial number: 35428337808578903465180920265426569102
665
665
  Signature: ecdsa-with-SHA256
666
- Key size: 256 bit
666
+ Key size: 256 bit (EC)
667
667
  Fingerprint: BE:AB:14:CF:39:67:8F:DA:0E:F1:60:6E:ED:B8:18:C2:...
668
668
  CA: False
669
669
  Self-Signed: False
@@ -761,6 +761,7 @@ $ certinspect example.com --json
761
761
  "is_ca": false,
762
762
  "san": ["example.com", "*.example.com"],
763
763
  "key": {
764
+ "type": "EC",
764
765
  "size": 256,
765
766
  "signature_algorithm": "ecdsa-with-SHA256",
766
767
  "usage": ["digital_signature"],
@@ -1021,13 +1022,16 @@ $ echo $?
1021
1022
 
1022
1023
  ### `--min-key-size N`
1023
1024
 
1024
- Fail (exit code 9) when the public key is smaller than N bits — e.g. reject
1025
- any RSA key below 2048 bit. Opt-in.
1025
+ Fail (exit code 9) when an RSA or DSA public key is smaller than N bits — e.g.
1026
+ reject any RSA key below 2048 bit. EC and EdDSA keys are not compared against
1027
+ N (their bit lengths are on a different scale: a 256-bit EC key is roughly as
1028
+ strong as 3072-bit RSA); `--fail-weak` still flags an EC key below 256 bit.
1029
+ Opt-in.
1026
1030
 
1027
1031
  ```console
1028
1032
  $ certinspect example.com --min-key-size 2048
1029
1033
  ...
1030
- Key size: 1024 bit
1034
+ Key size: 1024 bit (RSA)
1031
1035
  ...
1032
1036
  Policy: FAIL
1033
1037
  WARNING: policy violation (key size 1024 bit is below the 2048-bit minimum)
@@ -1166,7 +1170,7 @@ Precedence and edge cases a sysadmin should know:
1166
1170
  ```console
1167
1171
  $ certinspect example.com --profile standard
1168
1172
  ...
1169
- Key size: 1024 bit
1173
+ Key size: 1024 bit (RSA)
1170
1174
  TLS version: TLSv1.3
1171
1175
  Policy: FAIL
1172
1176
  WARNING: policy violation (key size 1024 bit is below the 2048-bit minimum)
@@ -1404,7 +1408,7 @@ the repository with the most commonly-set options — copy the ones you want.
1404
1408
 
1405
1409
  ### `--state-file PATH` / `--only-changed`
1406
1410
 
1407
- For a recurring job (cron, CI) where you only care when something *changes* —
1411
+ For a recurring job (cron, CI) where you only care when something _changes_ —
1408
1412
  not being reminded every run that a certificate is still fine. `--state-file`
1409
1413
  records each host's status in a small JSON file; `--only-changed` then limits
1410
1414
  the report to targets whose status differs from the previous run (a target
@@ -1513,20 +1517,27 @@ certinspect_policy_ok{target="example.com"} 0
1513
1517
 
1514
1518
  ## Exit codes
1515
1519
 
1516
- Designed for automation (cron, CI, monitoring scripts). In batch mode the
1517
- worst code across all targets is returned.
1518
-
1519
- | Code | Meaning |
1520
- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
1521
- | 0 | Valid certificate |
1522
- | 1 | Runtime error (network, file, parse) |
1523
- | 2 | Command-line usage error |
1524
- | 3 | Expiring within the `--days` threshold |
1525
- | 4 | Expired, not yet valid, or with invalid dates |
1526
- | 5 | Hostname does not match the certificate |
1527
- | 6 | Chain not trusted or revoked (`--verify`) |
1528
- | 7 | Fingerprint does not match `--pin` |
1529
- | 8 | Expected SAN missing (`--expect-san`) |
1520
+ Designed for automation (cron, CI, monitoring scripts). A single number can
1521
+ report only one problem, so when a certificate has several (e.g. expired _and_
1522
+ a weak key), or a batch has several targets, the **most severe** one is
1523
+ returned. The codes are labels, not a scale; severity follows this order, most
1524
+ severe first:
1525
+
1526
+ `6` untrusted/revoked → `7` pin mismatch → `4` expired/not yet valid → `5`
1527
+ hostname mismatch → `1` runtime error (e.g. unreachable host) → `8` SAN
1528
+ missing → `9` policy → `3` expiring → `0` valid.
1529
+
1530
+ | Code | Meaning |
1531
+ | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1532
+ | 0 | Valid certificate |
1533
+ | 1 | Runtime error (network, file, parse) |
1534
+ | 2 | Command-line usage error |
1535
+ | 3 | Expiring within the `--days` threshold |
1536
+ | 4 | Expired, not yet valid, or with invalid dates |
1537
+ | 5 | Hostname does not match the certificate |
1538
+ | 6 | Chain not trusted or revoked (`--verify`) |
1539
+ | 7 | Fingerprint does not match `--pin` |
1540
+ | 8 | Expected SAN missing (`--expect-san`) |
1530
1541
  | 9 | Policy violation (`--not-after-max`/`--cab-forum`, `--min-key-size`, `--fail-weak`, `--require-sct`, `--require-must-staple`, `--require-revocation-check`, `--min-tls-version`) |
1531
1542
 
1532
1543
  Example in a script:
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "certinspect"
3
- version = "2.3.3"
3
+ version = "2.4.0"
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.3.3"
3
+ __version__ = "2.4.0"
@@ -386,8 +386,9 @@ def build_parser() -> argparse.ArgumentParser:
386
386
  metavar="N",
387
387
  dest="min_key_size",
388
388
  help=(
389
- "Fail (exit code 9) when the public key is smaller than N bits "
390
- "(e.g. 2048 for RSA). Opt-in policy check."
389
+ "Fail (exit code 9) when an RSA or DSA public key is smaller than "
390
+ "N bits (e.g. 2048). EC and EdDSA keys are not size-checked here; "
391
+ "--fail-weak flags an EC key below 256 bit. Opt-in policy check."
391
392
  ),
392
393
  )
393
394
  parser.add_argument(
@@ -48,7 +48,7 @@ from certinspect.parser import (
48
48
  POLICY_PROFILES,
49
49
  to_pem,
50
50
  )
51
- from certinspect.exit_codes import EXIT_BY_STATUS, ExitCode
51
+ from certinspect.exit_codes import EXIT_BY_STATUS, RUNTIME_ERROR, ExitCode, most_severe
52
52
  from certinspect.models import CertificateInfo
53
53
  from certinspect.completion import bash_completion_script, zsh_completion_script
54
54
  from certinspect.config import DEFAULT_CONFIG_PATH, load_config
@@ -133,6 +133,17 @@ def _split_target(raw: str, default_port: int) -> tuple[str, int]:
133
133
  return parts.hostname or raw, parts.port or default_port
134
134
 
135
135
 
136
+ def _target_label(host: str, port: int, default_port: int) -> str:
137
+ """Name a host result: the bare host on the default port, else ``host:port``.
138
+
139
+ Keeps the common case unchanged while telling apart several services on the
140
+ same host (output, --state-file keys, Prometheus labels).
141
+ """
142
+ if port == default_port:
143
+ return host
144
+ return f"[{host}]:{port}" if ":" in host else f"{host}:{port}"
145
+
146
+
136
147
  def _connection_kwargs(opts: InspectOptions, *, include_ca: bool = False) -> dict:
137
148
  """Return the TLS connection keyword arguments shared by fetch and verify.
138
149
 
@@ -191,7 +202,8 @@ def _inspect(
191
202
  ``expect_san`` names are not all covered by the certificate's SAN the exit
192
203
  code is 8. The opt-in policy checks (``not_after_max``/``cab_forum``,
193
204
  ``min_key_size``, ``fail_weak``, ``require_sct``, ``require_must_staple``,
194
- ``min_tls_version``) yield exit code 9 when any is violated.
205
+ ``min_tls_version``) yield exit code 9 when any is violated. When several
206
+ checks fail, the most severe code wins (see ``exit_codes.most_severe``).
195
207
  """
196
208
  der, conn = _fetch_source(target, port, opts)
197
209
  cert = load_certificate(der)
@@ -206,9 +218,9 @@ def _inspect(
206
218
  info["hostname_match"] = hostname_matches(info, check_name) if check_name else None
207
219
 
208
220
  info["status"] = certificate_status(info, opts.days, opts.critical_days)
209
- code = EXIT_BY_STATUS[info["status"]]
221
+ codes = [EXIT_BY_STATUS[info["status"]]]
210
222
  if info["hostname_match"] is False:
211
- code = ExitCode.HOSTNAME_MISMATCH
223
+ codes.append(ExitCode.HOSTNAME_MISMATCH)
212
224
 
213
225
  # A --file bundle may carry the whole chain; parse it once when it is needed.
214
226
  file_bundle: list | None = None
@@ -218,8 +230,7 @@ def _inspect(
218
230
  override, chain_certs = _check_chain(
219
231
  info, target, port, cert, conn, opts, file_bundle
220
232
  )
221
- if override is not None:
222
- code = override
233
+ codes.append(override)
223
234
 
224
235
  # The verified chain (when available) is the most accurate source for the
225
236
  # intermediates actually used; fall back to the chain presented by the
@@ -238,14 +249,12 @@ def _inspect(
238
249
  presented = (conn.get("chain") or [cert]) if conn else (file_bundle or [cert])
239
250
  info["chain"] = [chain_summary(c) for c in presented]
240
251
 
241
- for override in (
252
+ codes += [
242
253
  _check_pin(info, opts),
243
254
  _check_expect_san(info, opts),
244
255
  _check_policy(info, opts),
245
- ):
246
- if override is not None:
247
- code = override
248
- return info, code
256
+ ]
257
+ return info, most_severe(code for code in codes if code is not None)
249
258
 
250
259
 
251
260
  def _check_chain(
@@ -325,11 +334,7 @@ def _check_expect_san(info: CertificateInfo, opts: InspectOptions) -> ExitCode |
325
334
 
326
335
 
327
336
  def _check_policy(info: CertificateInfo, opts: InspectOptions) -> ExitCode | None:
328
- """Record the opt-in policy violations; return POLICY when any applies.
329
-
330
- A revoked certificate already fails with UNTRUSTED_OR_REVOKED, so a policy
331
- violation does not override it.
332
- """
337
+ """Record the opt-in policy violations; return POLICY when any applies."""
333
338
  if not (
334
339
  opts.not_after_max is not None
335
340
  or opts.cab_forum
@@ -358,9 +363,7 @@ def _check_policy(info: CertificateInfo, opts: InspectOptions) -> ExitCode | Non
358
363
  if violation is not None:
359
364
  violations.append(violation)
360
365
  info["policy_violations"] = violations
361
- if violations and info.get("revocation_status") != "REVOKED":
362
- return ExitCode.POLICY
363
- return None
366
+ return ExitCode.POLICY if violations else None
364
367
 
365
368
 
366
369
  def _revocation_policy_violation(info: CertificateInfo) -> str | None:
@@ -669,26 +672,27 @@ def main() -> None:
669
672
  work_items += [(False, raw) for raw in host_targets]
670
673
 
671
674
  def _run(item: tuple[bool, str]) -> tuple[str, tuple | None, str | None]:
672
- """Inspect one work item, returning (raw, payload, error).
675
+ """Inspect one work item, returning (name, payload, error).
673
676
 
674
677
  ``item`` is ``(is_file, raw)``: a file path or a host target string.
675
- ``payload`` is ``(label, info, code)`` on success and None on failure,
676
- in which case ``error`` carries the message. Runs in worker threads, so
677
- it must not perform any I/O on shared streams.
678
+ ``name`` labels the item (``host[:port]`` for a host, the path for a
679
+ file). ``payload`` is ``(label, info, code)`` on success and None on
680
+ failure, in which case ``error`` carries the message. Runs in worker
681
+ threads, so it must not perform any I/O on shared streams.
678
682
  """
679
683
  is_file, raw = item
684
+ name = raw
680
685
  try:
681
686
  if is_file:
682
687
  file_opts = replace(opts, file=raw)
683
688
  info, code = _inspect(None, default_port, file_opts)
684
- label = None if single_file else raw
685
- else:
686
- target, port = _split_target(raw, default_port)
687
- info, code = _inspect(target, port, opts)
688
- label = target
689
+ return name, (None if single_file else raw, info, code), None
690
+ target, port = _split_target(raw, default_port)
691
+ name = _target_label(target, port, default_port)
692
+ info, code = _inspect(target, port, opts)
689
693
  except (OSError, ssl.SSLError, ValueError) as err:
690
- return raw, None, str(err)
691
- return raw, (label, info, code), None
694
+ return name, None, str(err)
695
+ return name, (name, info, code), None
692
696
 
693
697
  # Inspect in parallel when asked; ThreadPoolExecutor.map preserves order.
694
698
  workers = max(1, args.concurrency)
@@ -701,13 +705,13 @@ def main() -> None:
701
705
  results: list[tuple[str | None, dict, int]] = []
702
706
  errors: list[tuple[str | None, str]] = []
703
707
  codes: list[int] = []
704
- for raw_target, payload, err in outcomes:
708
+ for name, payload, err in outcomes:
705
709
  if err is not None:
706
710
  if not args.exporter:
707
- label = f"{raw_target}: " if raw_target else ""
711
+ label = f"{name}: " if name else ""
708
712
  print(f"error: {label}{err}", file=sys.stderr)
709
- errors.append((raw_target, err))
710
- codes.append(1)
713
+ errors.append((name, err))
714
+ codes.append(RUNTIME_ERROR)
711
715
  continue
712
716
  results.append(payload)
713
717
  codes.append(payload[2])
@@ -740,7 +744,7 @@ def main() -> None:
740
744
  )
741
745
  if args.exit_zero:
742
746
  sys.exit(0)
743
- sys.exit(override if override is not None else max(codes, default=0))
747
+ sys.exit(override if override is not None else most_severe(codes))
744
748
 
745
749
 
746
750
  if __name__ == "__main__":
@@ -5,6 +5,7 @@ orchestration (cli) and the reporters (formatter) agree on what each number
5
5
  means instead of repeating the literals.
6
6
  """
7
7
 
8
+ from collections.abc import Iterable
8
9
  from enum import IntEnum, StrEnum
9
10
 
10
11
 
@@ -51,3 +52,28 @@ EXIT_BY_STATUS: dict[Status, ExitCode] = {
51
52
  Status.INVALID_DATES: ExitCode.INVALID,
52
53
  Status.NOT_YET_VALID: ExitCode.INVALID,
53
54
  }
55
+
56
+ # Generic runtime error: a target that could not be inspected at all.
57
+ RUNTIME_ERROR = 1
58
+
59
+ # Exit codes from most to least severe. The numbers are labels, not a scale,
60
+ # so when a target (or a batch) has several problems this order picks the one
61
+ # reported: known-bad certificates first, then an unreachable target, then
62
+ # unmet expectations, policy and the expiry warning.
63
+ _SEVERITY_ORDER: tuple[int, ...] = (
64
+ ExitCode.UNTRUSTED_OR_REVOKED,
65
+ ExitCode.PIN_MISMATCH,
66
+ ExitCode.INVALID,
67
+ ExitCode.HOSTNAME_MISMATCH,
68
+ RUNTIME_ERROR,
69
+ ExitCode.SAN_MISMATCH,
70
+ ExitCode.POLICY,
71
+ ExitCode.EXPIRING,
72
+ ExitCode.OK,
73
+ )
74
+ _SEVERITY_RANK = {code: rank for rank, code in enumerate(_SEVERITY_ORDER)}
75
+
76
+
77
+ def most_severe(codes: Iterable[int]) -> int:
78
+ """Return the most severe of ``codes``, or ``ExitCode.OK`` when empty."""
79
+ return min(codes, key=_SEVERITY_RANK.__getitem__, default=ExitCode.OK)