certinspect 2.4.0__tar.gz → 2.4.2__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 (32) hide show
  1. {certinspect-2.4.0/src/certinspect.egg-info → certinspect-2.4.2}/PKG-INFO +68 -31
  2. {certinspect-2.4.0 → certinspect-2.4.2}/README.md +67 -30
  3. {certinspect-2.4.0 → certinspect-2.4.2}/pyproject.toml +1 -1
  4. {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect/__init__.py +1 -1
  5. {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect/args.py +8 -3
  6. {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect/cli.py +209 -202
  7. {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect/exit_codes.py +9 -0
  8. {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect/fetch.py +17 -31
  9. {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect/formatter.py +112 -47
  10. {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect/models.py +20 -5
  11. {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect/parser.py +23 -12
  12. certinspect-2.4.2/src/certinspect/render.py +139 -0
  13. {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect/revocation.py +40 -58
  14. certinspect-2.4.2/src/certinspect/state.py +53 -0
  15. {certinspect-2.4.0 → certinspect-2.4.2/src/certinspect.egg-info}/PKG-INFO +68 -31
  16. {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect.egg-info/SOURCES.txt +1 -0
  17. {certinspect-2.4.0 → certinspect-2.4.2}/tests/test_cli.py +115 -0
  18. {certinspect-2.4.0 → certinspect-2.4.2}/tests/test_formatter.py +77 -0
  19. certinspect-2.4.0/src/certinspect/render.py +0 -140
  20. {certinspect-2.4.0 → certinspect-2.4.2}/LICENSE +0 -0
  21. {certinspect-2.4.0 → certinspect-2.4.2}/setup.cfg +0 -0
  22. {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect/completion.py +0 -0
  23. {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect/config.py +0 -0
  24. {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect/discover.py +0 -0
  25. {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect/httpfetch.py +0 -0
  26. {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect.egg-info/dependency_links.txt +0 -0
  27. {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect.egg-info/entry_points.txt +0 -0
  28. {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect.egg-info/requires.txt +0 -0
  29. {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect.egg-info/top_level.txt +0 -0
  30. {certinspect-2.4.0 → certinspect-2.4.2}/tests/test_discover.py +0 -0
  31. {certinspect-2.4.0 → certinspect-2.4.2}/tests/test_fetch.py +0 -0
  32. {certinspect-2.4.0 → certinspect-2.4.2}/tests/test_parser.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: certinspect
3
- Version: 2.4.0
3
+ Version: 2.4.2
4
4
  Summary: Command-line TLS certificate inspector
5
5
  Author-email: Michele Angrisano <michele.angrisano@gmail.com>
6
6
  License-Expression: MIT
@@ -488,11 +488,11 @@ certinspect internal.example.lan --verify --cafile ./internal-ca.pem
488
488
 
489
489
  ### Catch a revoked certificate
490
490
 
491
- `--verify` queries OCSP and falls back to the CRL; a revoked leaf fails with
492
- exit `6`:
491
+ Verification is on by default: it queries OCSP and falls back to the CRL, and a
492
+ revoked leaf fails with exit `6`:
493
493
 
494
494
  ```bash
495
- certinspect revoked.example.com --verify
495
+ certinspect revoked.example.com
496
496
  ```
497
497
 
498
498
  ### Spot an expired intermediate before it breaks the chain
@@ -659,7 +659,7 @@ certinspect example.com --export ./example.com.pem
659
659
  | `--summary` | Print a one-line tally (valid/expiring/expired/errors) to stderr; counts every target before filtering. |
660
660
  | `--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. |
661
661
  | `--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. |
662
- | `--export PATH` | Save the inspected certificate as a PEM file at PATH. |
662
+ | `--export PATH` | Save the inspected certificate as a PEM file at PATH. Single target only. |
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. |
@@ -707,6 +707,10 @@ SAN:
707
707
  ```
708
708
 
709
709
  Passing several hosts prints one `=== host ===` block per target (batch mode).
710
+ A target on a non-default port is labelled `host:port` (e.g.
711
+ `=== example.com:8443 ===`) there and in every other output, the
712
+ `--state-file` and the Prometheus `target` label, so several services on the
713
+ same host stay apart.
710
714
 
711
715
  ### `--file PATH` — inspect a local certificate
712
716
 
@@ -816,6 +820,10 @@ The `status` field mirrors the human report's `Status` line (`VALID`,
816
820
  honors `--days` / `--critical-days`, so a JSON consumer gets the verdict
817
821
  without re-deriving it from the dates.
818
822
 
823
+ `key.type` is the key family (`RSA`, `EC`, `DSA`, `Ed25519` or `Ed448`).
824
+ EdDSA keys have a fixed size, so for them `key.size` is `null` (`n/a` in the
825
+ text report).
826
+
819
827
  Need the pre-2.0 flat array (no envelope, dates via `str()`, integer serial)?
820
828
  Pass `--schema 1`:
821
829
 
@@ -892,6 +900,19 @@ $ certinspect --file ./bundle.pem --verify
892
900
  Chain trusted: True
893
901
  ```
894
902
 
903
+ For a host, revocation is checked over OCSP first, falling back to the CRL. An
904
+ answer only counts when it is authentic: the OCSP response must be about this
905
+ certificate and signed by its issuer (or by a responder the issuer delegated
906
+ with the OCSP Signing EKU); the CRL must be signed by the issuer, name it and
907
+ cover this kind of certificate. The issuer itself, taken from the verified
908
+ chain or downloaded from the certificate's AIA URL, must have signed the leaf.
909
+ Anything else is reported as `UNAVAILABLE` — a browser-like soft-fail that
910
+ leaves the exit code alone; add
911
+ [`--require-revocation-check`](#--require-revocation-check) to make it fail.
912
+ The OCSP, CRL and issuer URLs come from the certificate, so certinspect
913
+ refuses to fetch loopback, link-local (cloud metadata) or other internal
914
+ addresses — also after an HTTP redirect — and caps each response at 16 MB.
915
+
895
916
  ### `--chain`
896
917
 
897
918
  ```console
@@ -1172,13 +1193,13 @@ you had passed the flags yourself.
1172
1193
 
1173
1194
  Each stricter tier is a superset of the one below it:
1174
1195
 
1175
- | Check (flag) | `lenient` | `standard` | `strict` |
1176
- | --------------------------------------------- | :-------: | :--------: | :---------: |
1177
- | Minimum TLS version (`--min-tls-version`) | TLSv1.2 | TLSv1.2 | **TLSv1.3** |
1178
- | Fail on weak crypto (`--fail-weak`) | yes | yes | yes |
1179
- | Minimum key size (`--min-key-size`) | — | 2048 bit | 2048 bit |
1180
- | Require CT SCTs (`--require-sct`) | — | — | yes |
1181
- | CA/Browser Forum validity cap (`--cab-forum`) | — | — | yes |
1196
+ | Check (flag) | `lenient` | `standard` | `strict` |
1197
+ | --------------------------------------------- | :-------: | :----------------: | :----------------: |
1198
+ | Minimum TLS version (`--min-tls-version`) | TLSv1.2 | TLSv1.2 | **TLSv1.3** |
1199
+ | Fail on weak crypto (`--fail-weak`) | yes | yes | yes |
1200
+ | Minimum key size (`--min-key-size`) | — | 2048 bit (RSA/DSA) | 2048 bit (RSA/DSA) |
1201
+ | Require CT SCTs (`--require-sct`) | — | — | yes |
1202
+ | CA/Browser Forum validity cap (`--cab-forum`) | — | — | yes |
1182
1203
 
1183
1204
  Precedence and edge cases a sysadmin should know:
1184
1205
 
@@ -1287,7 +1308,9 @@ summary: 1 valid · 0 expiring · 0 expired · 1 error (2 targets)
1287
1308
  Print only the fields you ask for, one tab-separated line per target, so you
1288
1309
  can pull values straight into a script without a JSON tool. Repeat `--field`
1289
1310
  for several columns; the pseudo-field `target` is the inspected host and list
1290
- fields (like `san`) are comma-joined.
1311
+ fields (like `san`) are comma-joined. Any key of the `--json --schema 1`
1312
+ output is a valid name (e.g. `issuer`, `key_type`, `key_size`,
1313
+ `revocation_status`).
1291
1314
 
1292
1315
  ```console
1293
1316
  $ certinspect example.com github.com --field target --field days_to_expire --field status
@@ -1316,7 +1339,9 @@ $ echo $?
1316
1339
 
1317
1340
  ### `--export PATH`
1318
1341
 
1319
- Save the fetched certificate as PEM and still print the report.
1342
+ Save the fetched certificate as PEM and still print the report. It takes a
1343
+ single target; with several (hosts, `--file`s or a `--discover` result) the
1344
+ command stops with a usage error rather than overwriting the same file.
1320
1345
 
1321
1346
  ```console
1322
1347
  $ certinspect example.com --export ./fetched.pem
@@ -1393,7 +1418,7 @@ Machine-readable monitoring output (full examples in
1393
1418
 
1394
1419
  ```console
1395
1420
  $ certinspect example.com --exporter nagios
1396
- OK: example.com certificate VALID (64 days to expiry) | days=64;30;0
1421
+ OK: example.com certificate VALID (64 days to expiry) | days=64;30:;0:
1397
1422
  ```
1398
1423
 
1399
1424
  ### `--version`
@@ -1450,7 +1475,10 @@ Status: EXPIRING
1450
1475
  ```
1451
1476
 
1452
1477
  The state file is always brought up to date, whether or not `--only-changed`
1453
- is given, so the next run has a fresh baseline to compare against.
1478
+ is given, so the next run has a fresh baseline to compare against. A target
1479
+ that cannot be reached keeps its last known status, so a transient outage is
1480
+ reported as an error on that run (exit code 1) but not as a change once the
1481
+ host is back; a target removed from the list is dropped from the file.
1454
1482
 
1455
1483
  ### `--print-completion {bash,zsh}`
1456
1484
 
@@ -1485,10 +1513,15 @@ host is CRITICAL:
1485
1513
 
1486
1514
  ```console
1487
1515
  $ certinspect example.com expired.example.com --exporter nagios
1488
- OK: example.com certificate VALID (217 days to expiry) | days=217;30;0
1489
- CRITICAL: expired.example.com certificate EXPIRED (-3 days to expiry) | days=-3;30;0
1516
+ OK: example.com certificate VALID (217 days to expiry) | days=217;30:;0:
1517
+ CRITICAL: expired.example.com certificate EXPIRED (-3 days to expiry) | days=-3;30:;0:
1490
1518
  ```
1491
1519
 
1520
+ The perfdata thresholds use the `N:` range form, "alert below N": `30:` is the
1521
+ `--days` warning, `0:` the critical one (expired), or `--critical-days` when set
1522
+ (`days=12;30:;7:`), so graphers colour each series exactly as the plugin rates
1523
+ it.
1524
+
1492
1525
  `prometheus` emits textfile-collector metrics (`certinspect_up`,
1493
1526
  `certinspect_cert_expiry_days`, `certinspect_cert_valid`), keeping the normal
1494
1527
  worst-status exit code:
@@ -1508,7 +1541,7 @@ certinspect_cert_valid{target="example.com"} 1
1508
1541
 
1509
1542
  Three further gauges appear only for the targets whose check actually ran, so a
1510
1543
  scrape never carries a misleading `0` for a check that was not requested:
1511
- `certinspect_hostname_match` (host targets), and — with `--verify` —
1544
+ `certinspect_hostname_match` (host targets), and — unless `--no-verify` —
1512
1545
  `certinspect_chain_trusted` and `certinspect_cert_revoked` (the latter only when
1513
1546
  OCSP/CRL returns a definitive answer). This lets you alert directly on chain,
1514
1547
  hostname and revocation problems without parsing text:
@@ -1553,18 +1586,22 @@ severe first:
1553
1586
  hostname mismatch → `1` runtime error (e.g. unreachable host) → `8` SAN
1554
1587
  missing → `9` policy → `3` expiring → `0` valid.
1555
1588
 
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`) |
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`) |
1589
+ Two options replace these codes: `--exporter nagios` exits with the plugin
1590
+ convention (`0` OK, `1` WARNING, `2` CRITICAL) and `--exit-zero` always exits
1591
+ `0`.
1592
+
1593
+ | Code | Meaning |
1594
+ | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1595
+ | 0 | Valid certificate |
1596
+ | 1 | Runtime error (network, file, parse) |
1597
+ | 2 | Command-line usage error |
1598
+ | 3 | Expiring within the `--days` threshold |
1599
+ | 4 | Expired, not yet valid, with invalid dates, or expiring within `--critical-days` |
1600
+ | 5 | Hostname does not match the certificate |
1601
+ | 6 | Chain not trusted or certificate revoked (verification is on by default; `--no-verify` skips it) |
1602
+ | 7 | Fingerprint does not match `--pin` |
1603
+ | 8 | Expected SAN missing (`--expect-san`) |
1604
+ | 9 | Policy violation (`--profile`, `--not-after-max`/`--cab-forum`, `--min-key-size`, `--fail-weak`, `--require-sct`, `--require-must-staple`, `--require-revocation-check`, `--min-tls-version`), or an unexpected issuer with `--discover-only --expect-issuer` |
1568
1605
 
1569
1606
  Example in a script:
1570
1607
 
@@ -462,11 +462,11 @@ certinspect internal.example.lan --verify --cafile ./internal-ca.pem
462
462
 
463
463
  ### Catch a revoked certificate
464
464
 
465
- `--verify` queries OCSP and falls back to the CRL; a revoked leaf fails with
466
- exit `6`:
465
+ Verification is on by default: it queries OCSP and falls back to the CRL, and a
466
+ revoked leaf fails with exit `6`:
467
467
 
468
468
  ```bash
469
- certinspect revoked.example.com --verify
469
+ certinspect revoked.example.com
470
470
  ```
471
471
 
472
472
  ### Spot an expired intermediate before it breaks the chain
@@ -633,7 +633,7 @@ certinspect example.com --export ./example.com.pem
633
633
  | `--summary` | Print a one-line tally (valid/expiring/expired/errors) to stderr; counts every target before filtering. |
634
634
  | `--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. |
635
635
  | `--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. |
636
- | `--export PATH` | Save the inspected certificate as a PEM file at PATH. |
636
+ | `--export PATH` | Save the inspected certificate as a PEM file at PATH. Single target only. |
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. |
@@ -681,6 +681,10 @@ SAN:
681
681
  ```
682
682
 
683
683
  Passing several hosts prints one `=== host ===` block per target (batch mode).
684
+ A target on a non-default port is labelled `host:port` (e.g.
685
+ `=== example.com:8443 ===`) there and in every other output, the
686
+ `--state-file` and the Prometheus `target` label, so several services on the
687
+ same host stay apart.
684
688
 
685
689
  ### `--file PATH` — inspect a local certificate
686
690
 
@@ -790,6 +794,10 @@ The `status` field mirrors the human report's `Status` line (`VALID`,
790
794
  honors `--days` / `--critical-days`, so a JSON consumer gets the verdict
791
795
  without re-deriving it from the dates.
792
796
 
797
+ `key.type` is the key family (`RSA`, `EC`, `DSA`, `Ed25519` or `Ed448`).
798
+ EdDSA keys have a fixed size, so for them `key.size` is `null` (`n/a` in the
799
+ text report).
800
+
793
801
  Need the pre-2.0 flat array (no envelope, dates via `str()`, integer serial)?
794
802
  Pass `--schema 1`:
795
803
 
@@ -866,6 +874,19 @@ $ certinspect --file ./bundle.pem --verify
866
874
  Chain trusted: True
867
875
  ```
868
876
 
877
+ For a host, revocation is checked over OCSP first, falling back to the CRL. An
878
+ answer only counts when it is authentic: the OCSP response must be about this
879
+ certificate and signed by its issuer (or by a responder the issuer delegated
880
+ with the OCSP Signing EKU); the CRL must be signed by the issuer, name it and
881
+ cover this kind of certificate. The issuer itself, taken from the verified
882
+ chain or downloaded from the certificate's AIA URL, must have signed the leaf.
883
+ Anything else is reported as `UNAVAILABLE` — a browser-like soft-fail that
884
+ leaves the exit code alone; add
885
+ [`--require-revocation-check`](#--require-revocation-check) to make it fail.
886
+ The OCSP, CRL and issuer URLs come from the certificate, so certinspect
887
+ refuses to fetch loopback, link-local (cloud metadata) or other internal
888
+ addresses — also after an HTTP redirect — and caps each response at 16 MB.
889
+
869
890
  ### `--chain`
870
891
 
871
892
  ```console
@@ -1146,13 +1167,13 @@ you had passed the flags yourself.
1146
1167
 
1147
1168
  Each stricter tier is a superset of the one below it:
1148
1169
 
1149
- | Check (flag) | `lenient` | `standard` | `strict` |
1150
- | --------------------------------------------- | :-------: | :--------: | :---------: |
1151
- | Minimum TLS version (`--min-tls-version`) | TLSv1.2 | TLSv1.2 | **TLSv1.3** |
1152
- | Fail on weak crypto (`--fail-weak`) | yes | yes | yes |
1153
- | Minimum key size (`--min-key-size`) | — | 2048 bit | 2048 bit |
1154
- | Require CT SCTs (`--require-sct`) | — | — | yes |
1155
- | CA/Browser Forum validity cap (`--cab-forum`) | — | — | yes |
1170
+ | Check (flag) | `lenient` | `standard` | `strict` |
1171
+ | --------------------------------------------- | :-------: | :----------------: | :----------------: |
1172
+ | Minimum TLS version (`--min-tls-version`) | TLSv1.2 | TLSv1.2 | **TLSv1.3** |
1173
+ | Fail on weak crypto (`--fail-weak`) | yes | yes | yes |
1174
+ | Minimum key size (`--min-key-size`) | — | 2048 bit (RSA/DSA) | 2048 bit (RSA/DSA) |
1175
+ | Require CT SCTs (`--require-sct`) | — | — | yes |
1176
+ | CA/Browser Forum validity cap (`--cab-forum`) | — | — | yes |
1156
1177
 
1157
1178
  Precedence and edge cases a sysadmin should know:
1158
1179
 
@@ -1261,7 +1282,9 @@ summary: 1 valid · 0 expiring · 0 expired · 1 error (2 targets)
1261
1282
  Print only the fields you ask for, one tab-separated line per target, so you
1262
1283
  can pull values straight into a script without a JSON tool. Repeat `--field`
1263
1284
  for several columns; the pseudo-field `target` is the inspected host and list
1264
- fields (like `san`) are comma-joined.
1285
+ fields (like `san`) are comma-joined. Any key of the `--json --schema 1`
1286
+ output is a valid name (e.g. `issuer`, `key_type`, `key_size`,
1287
+ `revocation_status`).
1265
1288
 
1266
1289
  ```console
1267
1290
  $ certinspect example.com github.com --field target --field days_to_expire --field status
@@ -1290,7 +1313,9 @@ $ echo $?
1290
1313
 
1291
1314
  ### `--export PATH`
1292
1315
 
1293
- Save the fetched certificate as PEM and still print the report.
1316
+ Save the fetched certificate as PEM and still print the report. It takes a
1317
+ single target; with several (hosts, `--file`s or a `--discover` result) the
1318
+ command stops with a usage error rather than overwriting the same file.
1294
1319
 
1295
1320
  ```console
1296
1321
  $ certinspect example.com --export ./fetched.pem
@@ -1367,7 +1392,7 @@ Machine-readable monitoring output (full examples in
1367
1392
 
1368
1393
  ```console
1369
1394
  $ certinspect example.com --exporter nagios
1370
- OK: example.com certificate VALID (64 days to expiry) | days=64;30;0
1395
+ OK: example.com certificate VALID (64 days to expiry) | days=64;30:;0:
1371
1396
  ```
1372
1397
 
1373
1398
  ### `--version`
@@ -1424,7 +1449,10 @@ Status: EXPIRING
1424
1449
  ```
1425
1450
 
1426
1451
  The state file is always brought up to date, whether or not `--only-changed`
1427
- is given, so the next run has a fresh baseline to compare against.
1452
+ is given, so the next run has a fresh baseline to compare against. A target
1453
+ that cannot be reached keeps its last known status, so a transient outage is
1454
+ reported as an error on that run (exit code 1) but not as a change once the
1455
+ host is back; a target removed from the list is dropped from the file.
1428
1456
 
1429
1457
  ### `--print-completion {bash,zsh}`
1430
1458
 
@@ -1459,10 +1487,15 @@ host is CRITICAL:
1459
1487
 
1460
1488
  ```console
1461
1489
  $ certinspect example.com expired.example.com --exporter nagios
1462
- OK: example.com certificate VALID (217 days to expiry) | days=217;30;0
1463
- CRITICAL: expired.example.com certificate EXPIRED (-3 days to expiry) | days=-3;30;0
1490
+ OK: example.com certificate VALID (217 days to expiry) | days=217;30:;0:
1491
+ CRITICAL: expired.example.com certificate EXPIRED (-3 days to expiry) | days=-3;30:;0:
1464
1492
  ```
1465
1493
 
1494
+ The perfdata thresholds use the `N:` range form, "alert below N": `30:` is the
1495
+ `--days` warning, `0:` the critical one (expired), or `--critical-days` when set
1496
+ (`days=12;30:;7:`), so graphers colour each series exactly as the plugin rates
1497
+ it.
1498
+
1466
1499
  `prometheus` emits textfile-collector metrics (`certinspect_up`,
1467
1500
  `certinspect_cert_expiry_days`, `certinspect_cert_valid`), keeping the normal
1468
1501
  worst-status exit code:
@@ -1482,7 +1515,7 @@ certinspect_cert_valid{target="example.com"} 1
1482
1515
 
1483
1516
  Three further gauges appear only for the targets whose check actually ran, so a
1484
1517
  scrape never carries a misleading `0` for a check that was not requested:
1485
- `certinspect_hostname_match` (host targets), and — with `--verify` —
1518
+ `certinspect_hostname_match` (host targets), and — unless `--no-verify` —
1486
1519
  `certinspect_chain_trusted` and `certinspect_cert_revoked` (the latter only when
1487
1520
  OCSP/CRL returns a definitive answer). This lets you alert directly on chain,
1488
1521
  hostname and revocation problems without parsing text:
@@ -1527,18 +1560,22 @@ severe first:
1527
1560
  hostname mismatch → `1` runtime error (e.g. unreachable host) → `8` SAN
1528
1561
  missing → `9` policy → `3` expiring → `0` valid.
1529
1562
 
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`) |
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`) |
1563
+ Two options replace these codes: `--exporter nagios` exits with the plugin
1564
+ convention (`0` OK, `1` WARNING, `2` CRITICAL) and `--exit-zero` always exits
1565
+ `0`.
1566
+
1567
+ | Code | Meaning |
1568
+ | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1569
+ | 0 | Valid certificate |
1570
+ | 1 | Runtime error (network, file, parse) |
1571
+ | 2 | Command-line usage error |
1572
+ | 3 | Expiring within the `--days` threshold |
1573
+ | 4 | Expired, not yet valid, with invalid dates, or expiring within `--critical-days` |
1574
+ | 5 | Hostname does not match the certificate |
1575
+ | 6 | Chain not trusted or certificate revoked (verification is on by default; `--no-verify` skips it) |
1576
+ | 7 | Fingerprint does not match `--pin` |
1577
+ | 8 | Expected SAN missing (`--expect-san`) |
1578
+ | 9 | Policy violation (`--profile`, `--not-after-max`/`--cab-forum`, `--min-key-size`, `--fail-weak`, `--require-sct`, `--require-must-staple`, `--require-revocation-check`, `--min-tls-version`), or an unexpected issuer with `--discover-only --expect-issuer` |
1542
1579
 
1543
1580
  Example in a script:
1544
1581
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "certinspect"
3
- version = "2.4.0"
3
+ version = "2.4.2"
4
4
  description = "Command-line TLS certificate inspector"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.12"
@@ -1,3 +1,3 @@
1
1
  """certinspect — command-line TLS certificate inspector."""
2
2
 
3
- __version__ = "2.4.0"
3
+ __version__ = "2.4.2"
@@ -346,7 +346,8 @@ def build_parser() -> argparse.ArgumentParser:
346
346
  "Apply a named bundle of the opt-in policy checks (exit code 9) in "
347
347
  "one go. Intensity ladder, not an official standard: 'lenient' = "
348
348
  "TLS >= 1.2 and fail on weak crypto; 'standard' adds a 2048-bit "
349
- "minimum key; 'strict' = TLS >= 1.3, 2048-bit key, weak-crypto "
349
+ "minimum RSA/DSA key; 'strict' = TLS >= 1.3, 2048-bit RSA/DSA key, "
350
+ "weak-crypto "
350
351
  "failure, required Certificate Transparency SCTs and the CA/Browser "
351
352
  "Forum validity cap. Any explicit flag overrides the profile; the "
352
353
  "TLS-version part applies to host targets only. Passing a profile "
@@ -444,7 +445,10 @@ def build_parser() -> argparse.ArgumentParser:
444
445
  parser.add_argument(
445
446
  "--export",
446
447
  metavar="PATH",
447
- help="Save the inspected certificate as a PEM file at PATH.",
448
+ help=(
449
+ "Save the inspected certificate as a PEM file at PATH. Needs a "
450
+ "single target (host or --file)."
451
+ ),
448
452
  )
449
453
  parser.add_argument(
450
454
  "--starttls",
@@ -524,7 +528,8 @@ def build_parser() -> argparse.ArgumentParser:
524
528
  "compare against the previous run. Combine with --only-changed to "
525
529
  "show only the targets whose status changed; without it, the file "
526
530
  "is simply kept up to date for the next run. Host targets only; a "
527
- "target seen for the first time counts as changed."
531
+ "target seen for the first time counts as changed, and one that "
532
+ "cannot be reached keeps its last known status."
528
533
  ),
529
534
  )
530
535
  parser.add_argument(