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.
- {certinspect-2.4.0/src/certinspect.egg-info → certinspect-2.4.2}/PKG-INFO +68 -31
- {certinspect-2.4.0 → certinspect-2.4.2}/README.md +67 -30
- {certinspect-2.4.0 → certinspect-2.4.2}/pyproject.toml +1 -1
- {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect/__init__.py +1 -1
- {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect/args.py +8 -3
- {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect/cli.py +209 -202
- {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect/exit_codes.py +9 -0
- {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect/fetch.py +17 -31
- {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect/formatter.py +112 -47
- {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect/models.py +20 -5
- {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect/parser.py +23 -12
- certinspect-2.4.2/src/certinspect/render.py +139 -0
- {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect/revocation.py +40 -58
- certinspect-2.4.2/src/certinspect/state.py +53 -0
- {certinspect-2.4.0 → certinspect-2.4.2/src/certinspect.egg-info}/PKG-INFO +68 -31
- {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect.egg-info/SOURCES.txt +1 -0
- {certinspect-2.4.0 → certinspect-2.4.2}/tests/test_cli.py +115 -0
- {certinspect-2.4.0 → certinspect-2.4.2}/tests/test_formatter.py +77 -0
- certinspect-2.4.0/src/certinspect/render.py +0 -140
- {certinspect-2.4.0 → certinspect-2.4.2}/LICENSE +0 -0
- {certinspect-2.4.0 → certinspect-2.4.2}/setup.cfg +0 -0
- {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect/completion.py +0 -0
- {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect/config.py +0 -0
- {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect/discover.py +0 -0
- {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect/httpfetch.py +0 -0
- {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect.egg-info/dependency_links.txt +0 -0
- {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect.egg-info/entry_points.txt +0 -0
- {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect.egg-info/requires.txt +0 -0
- {certinspect-2.4.0 → certinspect-2.4.2}/src/certinspect.egg-info/top_level.txt +0 -0
- {certinspect-2.4.0 → certinspect-2.4.2}/tests/test_discover.py +0 -0
- {certinspect-2.4.0 → certinspect-2.4.2}/tests/test_fetch.py +0 -0
- {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.
|
|
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
|
-
|
|
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
|
|
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` |
|
|
1176
|
-
| --------------------------------------------- | :-------: |
|
|
1177
|
-
| Minimum TLS version (`--min-tls-version`) | TLSv1.2 |
|
|
1178
|
-
| Fail on weak crypto (`--fail-weak`) | yes |
|
|
1179
|
-
| Minimum key size (`--min-key-size`) | — |
|
|
1180
|
-
| Require CT SCTs (`--require-sct`) | — |
|
|
1181
|
-
| CA/Browser Forum validity cap (`--cab-forum`) | — |
|
|
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
|
|
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
|
|
1489
|
-
CRITICAL: expired.example.com certificate EXPIRED (-3 days to expiry) | days=-3;30
|
|
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 —
|
|
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
|
-
|
|
1557
|
-
|
|
1558
|
-
|
|
1559
|
-
|
|
1560
|
-
|
|
|
1561
|
-
|
|
|
1562
|
-
|
|
|
1563
|
-
|
|
|
1564
|
-
|
|
|
1565
|
-
|
|
|
1566
|
-
|
|
|
1567
|
-
|
|
|
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
|
-
|
|
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
|
|
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` |
|
|
1150
|
-
| --------------------------------------------- | :-------: |
|
|
1151
|
-
| Minimum TLS version (`--min-tls-version`) | TLSv1.2 |
|
|
1152
|
-
| Fail on weak crypto (`--fail-weak`) | yes |
|
|
1153
|
-
| Minimum key size (`--min-key-size`) | — |
|
|
1154
|
-
| Require CT SCTs (`--require-sct`) | — |
|
|
1155
|
-
| CA/Browser Forum validity cap (`--cab-forum`) | — |
|
|
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
|
|
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
|
|
1463
|
-
CRITICAL: expired.example.com certificate EXPIRED (-3 days to expiry) | days=-3;30
|
|
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 —
|
|
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
|
-
|
|
1531
|
-
|
|
1532
|
-
|
|
1533
|
-
|
|
1534
|
-
|
|
|
1535
|
-
|
|
|
1536
|
-
|
|
|
1537
|
-
|
|
|
1538
|
-
|
|
|
1539
|
-
|
|
|
1540
|
-
|
|
|
1541
|
-
|
|
|
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
|
|
|
@@ -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,
|
|
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=
|
|
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(
|