certinspect 2.3.2__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.
- {certinspect-2.3.2/src/certinspect.egg-info → certinspect-2.4.0}/PKG-INFO +42 -31
- {certinspect-2.3.2 → certinspect-2.4.0}/README.md +41 -30
- {certinspect-2.3.2 → certinspect-2.4.0}/pyproject.toml +1 -1
- {certinspect-2.3.2 → certinspect-2.4.0}/src/certinspect/__init__.py +1 -1
- {certinspect-2.3.2 → certinspect-2.4.0}/src/certinspect/args.py +5 -4
- {certinspect-2.3.2 → certinspect-2.4.0}/src/certinspect/cli.py +47 -43
- {certinspect-2.3.2 → certinspect-2.4.0}/src/certinspect/config.py +2 -2
- {certinspect-2.3.2 → certinspect-2.4.0}/src/certinspect/discover.py +2 -2
- {certinspect-2.3.2 → certinspect-2.4.0}/src/certinspect/exit_codes.py +26 -0
- {certinspect-2.3.2 → certinspect-2.4.0}/src/certinspect/fetch.py +40 -8
- {certinspect-2.3.2 → certinspect-2.4.0}/src/certinspect/formatter.py +10 -1
- {certinspect-2.3.2 → certinspect-2.4.0}/src/certinspect/httpfetch.py +34 -7
- {certinspect-2.3.2 → certinspect-2.4.0}/src/certinspect/models.py +2 -1
- {certinspect-2.3.2 → certinspect-2.4.0}/src/certinspect/parser.py +36 -8
- {certinspect-2.3.2 → certinspect-2.4.0}/src/certinspect/render.py +3 -3
- certinspect-2.4.0/src/certinspect/revocation.py +445 -0
- {certinspect-2.3.2 → certinspect-2.4.0/src/certinspect.egg-info}/PKG-INFO +42 -31
- {certinspect-2.3.2 → certinspect-2.4.0}/tests/test_cli.py +168 -5
- {certinspect-2.3.2 → certinspect-2.4.0}/tests/test_discover.py +5 -5
- {certinspect-2.3.2 → certinspect-2.4.0}/tests/test_fetch.py +617 -16
- {certinspect-2.3.2 → certinspect-2.4.0}/tests/test_formatter.py +10 -0
- {certinspect-2.3.2 → certinspect-2.4.0}/tests/test_parser.py +33 -0
- certinspect-2.3.2/src/certinspect/revocation.py +0 -257
- {certinspect-2.3.2 → certinspect-2.4.0}/LICENSE +0 -0
- {certinspect-2.3.2 → certinspect-2.4.0}/setup.cfg +0 -0
- {certinspect-2.3.2 → certinspect-2.4.0}/src/certinspect/completion.py +0 -0
- {certinspect-2.3.2 → certinspect-2.4.0}/src/certinspect.egg-info/SOURCES.txt +0 -0
- {certinspect-2.3.2 → certinspect-2.4.0}/src/certinspect.egg-info/dependency_links.txt +0 -0
- {certinspect-2.3.2 → certinspect-2.4.0}/src/certinspect.egg-info/entry_points.txt +0 -0
- {certinspect-2.3.2 → certinspect-2.4.0}/src/certinspect.egg-info/requires.txt +0 -0
- {certinspect-2.3.2 → certinspect-2.4.0}/src/certinspect.egg-info/top_level.txt +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: certinspect
|
|
3
|
-
Version: 2.
|
|
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
|
|
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
|
|
1051
|
-
any RSA key below 2048 bit.
|
|
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
|
|
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).
|
|
1543
|
-
|
|
1544
|
-
|
|
1545
|
-
|
|
1546
|
-
|
|
1547
|
-
|
|
1548
|
-
|
|
1549
|
-
|
|
1550
|
-
|
|
1551
|
-
|
|
1552
|
-
|
|
|
1553
|
-
|
|
|
1554
|
-
|
|
|
1555
|
-
|
|
|
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
|
|
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
|
|
1025
|
-
any RSA key below 2048 bit.
|
|
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
|
|
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).
|
|
1517
|
-
|
|
1518
|
-
|
|
1519
|
-
|
|
1520
|
-
|
|
1521
|
-
|
|
1522
|
-
|
|
1523
|
-
|
|
1524
|
-
|
|
1525
|
-
|
|
1526
|
-
|
|
|
1527
|
-
|
|
|
1528
|
-
|
|
|
1529
|
-
|
|
|
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:
|
|
@@ -8,7 +8,7 @@ run logic; the completion and --config machinery introspect this parser.
|
|
|
8
8
|
import argparse
|
|
9
9
|
|
|
10
10
|
from certinspect import __version__
|
|
11
|
-
from certinspect.config import
|
|
11
|
+
from certinspect.config import DEFAULT_CONFIG_PATH
|
|
12
12
|
from certinspect.fetch import STARTTLS_PORTS
|
|
13
13
|
from certinspect.parser import POLICY_PROFILES
|
|
14
14
|
|
|
@@ -31,7 +31,7 @@ def build_parser() -> argparse.ArgumentParser:
|
|
|
31
31
|
f"TOML file of default option values (keys use the argparse "
|
|
32
32
|
f"destination name, e.g. 'days = 14' or 'verify = false'); an "
|
|
33
33
|
f"explicit command-line flag always overrides it. Without "
|
|
34
|
-
f"--config, {
|
|
34
|
+
f"--config, {DEFAULT_CONFIG_PATH} is loaded automatically if it "
|
|
35
35
|
"exists."
|
|
36
36
|
),
|
|
37
37
|
)
|
|
@@ -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
|
|
390
|
-
"(e.g. 2048
|
|
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,11 +48,11 @@ 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
|
-
from certinspect.config import
|
|
55
|
-
from certinspect.render import
|
|
54
|
+
from certinspect.config import DEFAULT_CONFIG_PATH, load_config
|
|
55
|
+
from certinspect.render import load_state, render, save_state
|
|
56
56
|
|
|
57
57
|
|
|
58
58
|
@dataclass(frozen=True)
|
|
@@ -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
|
-
|
|
221
|
+
codes = [EXIT_BY_STATUS[info["status"]]]
|
|
210
222
|
if info["hostname_match"] is False:
|
|
211
|
-
|
|
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
|
-
|
|
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
|
-
|
|
252
|
+
codes += [
|
|
242
253
|
_check_pin(info, opts),
|
|
243
254
|
_check_expect_san(info, opts),
|
|
244
255
|
_check_policy(info, opts),
|
|
245
|
-
|
|
246
|
-
|
|
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
|
|
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:
|
|
@@ -588,13 +591,13 @@ def main() -> None:
|
|
|
588
591
|
if not Path(pre_args.config).is_file():
|
|
589
592
|
parser.error(f"--config file not found: {pre_args.config}")
|
|
590
593
|
config_path: Path | None = Path(pre_args.config)
|
|
591
|
-
elif
|
|
592
|
-
config_path =
|
|
594
|
+
elif DEFAULT_CONFIG_PATH.is_file():
|
|
595
|
+
config_path = DEFAULT_CONFIG_PATH
|
|
593
596
|
else:
|
|
594
597
|
config_path = None
|
|
595
598
|
if config_path is not None:
|
|
596
599
|
try:
|
|
597
|
-
parser.set_defaults(**
|
|
600
|
+
parser.set_defaults(**load_config(str(config_path), parser))
|
|
598
601
|
except ValueError as err:
|
|
599
602
|
parser.error(str(err))
|
|
600
603
|
|
|
@@ -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 (
|
|
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
|
-
``
|
|
676
|
-
|
|
677
|
-
|
|
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
|
-
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
|
|
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
|
|
691
|
-
return
|
|
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,27 +705,27 @@ 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
|
|
708
|
+
for name, payload, err in outcomes:
|
|
705
709
|
if err is not None:
|
|
706
710
|
if not args.exporter:
|
|
707
|
-
label = f"{
|
|
711
|
+
label = f"{name}: " if name else ""
|
|
708
712
|
print(f"error: {label}{err}", file=sys.stderr)
|
|
709
|
-
errors.append((
|
|
710
|
-
codes.append(
|
|
713
|
+
errors.append((name, err))
|
|
714
|
+
codes.append(RUNTIME_ERROR)
|
|
711
715
|
continue
|
|
712
716
|
results.append(payload)
|
|
713
717
|
codes.append(payload[2])
|
|
714
718
|
|
|
715
719
|
changed_targets: set[str] | None = None
|
|
716
720
|
if args.state_file:
|
|
717
|
-
previous_state =
|
|
721
|
+
previous_state = load_state(args.state_file)
|
|
718
722
|
current_state = {t: info["status"] for t, info, _ in results if t is not None}
|
|
719
723
|
changed_targets = {
|
|
720
724
|
t for t, status in current_state.items() if previous_state.get(t) != status
|
|
721
725
|
}
|
|
722
|
-
|
|
726
|
+
save_state(args.state_file, current_state)
|
|
723
727
|
|
|
724
|
-
override =
|
|
728
|
+
override = render(
|
|
725
729
|
results,
|
|
726
730
|
as_json=args.json,
|
|
727
731
|
days=args.days,
|
|
@@ -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
|
|
747
|
+
sys.exit(override if override is not None else most_severe(codes))
|
|
744
748
|
|
|
745
749
|
|
|
746
750
|
if __name__ == "__main__":
|