certinspect 2.3.1__tar.gz → 2.3.3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. {certinspect-2.3.1/src/certinspect.egg-info → certinspect-2.3.3}/PKG-INFO +1 -1
  2. {certinspect-2.3.1 → certinspect-2.3.3}/pyproject.toml +1 -1
  3. {certinspect-2.3.1 → certinspect-2.3.3}/src/certinspect/__init__.py +1 -1
  4. {certinspect-2.3.1 → certinspect-2.3.3}/src/certinspect/args.py +2 -2
  5. {certinspect-2.3.1 → certinspect-2.3.3}/src/certinspect/cli.py +9 -9
  6. {certinspect-2.3.1 → certinspect-2.3.3}/src/certinspect/config.py +2 -2
  7. {certinspect-2.3.1 → certinspect-2.3.3}/src/certinspect/discover.py +2 -2
  8. certinspect-2.3.3/src/certinspect/exit_codes.py +53 -0
  9. {certinspect-2.3.1 → certinspect-2.3.3}/src/certinspect/fetch.py +2 -318
  10. {certinspect-2.3.1 → certinspect-2.3.3}/src/certinspect/formatter.py +7 -6
  11. certinspect-2.3.3/src/certinspect/httpfetch.py +84 -0
  12. {certinspect-2.3.1 → certinspect-2.3.3}/src/certinspect/parser.py +8 -7
  13. {certinspect-2.3.1 → certinspect-2.3.3}/src/certinspect/render.py +3 -3
  14. certinspect-2.3.3/src/certinspect/revocation.py +257 -0
  15. {certinspect-2.3.1 → certinspect-2.3.3/src/certinspect.egg-info}/PKG-INFO +1 -1
  16. {certinspect-2.3.1 → certinspect-2.3.3}/src/certinspect.egg-info/SOURCES.txt +2 -0
  17. {certinspect-2.3.1 → certinspect-2.3.3}/tests/test_cli.py +1 -1
  18. {certinspect-2.3.1 → certinspect-2.3.3}/tests/test_discover.py +5 -5
  19. {certinspect-2.3.1 → certinspect-2.3.3}/tests/test_fetch.py +49 -49
  20. certinspect-2.3.1/src/certinspect/exit_codes.py +0 -37
  21. {certinspect-2.3.1 → certinspect-2.3.3}/LICENSE +0 -0
  22. {certinspect-2.3.1 → certinspect-2.3.3}/README.md +0 -0
  23. {certinspect-2.3.1 → certinspect-2.3.3}/setup.cfg +0 -0
  24. {certinspect-2.3.1 → certinspect-2.3.3}/src/certinspect/completion.py +0 -0
  25. {certinspect-2.3.1 → certinspect-2.3.3}/src/certinspect/models.py +0 -0
  26. {certinspect-2.3.1 → certinspect-2.3.3}/src/certinspect.egg-info/dependency_links.txt +0 -0
  27. {certinspect-2.3.1 → certinspect-2.3.3}/src/certinspect.egg-info/entry_points.txt +0 -0
  28. {certinspect-2.3.1 → certinspect-2.3.3}/src/certinspect.egg-info/requires.txt +0 -0
  29. {certinspect-2.3.1 → certinspect-2.3.3}/src/certinspect.egg-info/top_level.txt +0 -0
  30. {certinspect-2.3.1 → certinspect-2.3.3}/tests/test_formatter.py +0 -0
  31. {certinspect-2.3.1 → certinspect-2.3.3}/tests/test_parser.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: certinspect
3
- Version: 2.3.1
3
+ Version: 2.3.3
4
4
  Summary: Command-line TLS certificate inspector
5
5
  Author-email: Michele Angrisano <michele.angrisano@gmail.com>
6
6
  License-Expression: MIT
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "certinspect"
3
- version = "2.3.1"
3
+ version = "2.3.3"
4
4
  description = "Command-line TLS certificate inspector"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.12"
@@ -1,3 +1,3 @@
1
1
  """certinspect — command-line TLS certificate inspector."""
2
2
 
3
- __version__ = "2.3.1"
3
+ __version__ = "2.3.3"
@@ -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 _DEFAULT_CONFIG_PATH
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, {_DEFAULT_CONFIG_PATH} is loaded automatically if it "
34
+ f"--config, {DEFAULT_CONFIG_PATH} is loaded automatically if it "
35
35
  "exists."
36
36
  ),
37
37
  )
@@ -26,12 +26,12 @@ from certinspect.discover import (
26
26
  )
27
27
  from certinspect.fetch import (
28
28
  STARTTLS_PORTS,
29
- check_revocation,
30
29
  get_server_cert,
31
30
  retry_network,
32
31
  verify_chain,
33
32
  verify_chain_offline,
34
33
  )
34
+ from certinspect.revocation import check_revocation
35
35
  from certinspect.parser import (
36
36
  load_certificate,
37
37
  load_certificates,
@@ -51,8 +51,8 @@ from certinspect.parser import (
51
51
  from certinspect.exit_codes import EXIT_BY_STATUS, ExitCode
52
52
  from certinspect.models import CertificateInfo
53
53
  from certinspect.completion import bash_completion_script, zsh_completion_script
54
- from certinspect.config import _DEFAULT_CONFIG_PATH, _load_config
55
- from certinspect.render import _load_state, _render, _save_state
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)
@@ -588,13 +588,13 @@ def main() -> None:
588
588
  if not Path(pre_args.config).is_file():
589
589
  parser.error(f"--config file not found: {pre_args.config}")
590
590
  config_path: Path | None = Path(pre_args.config)
591
- elif _DEFAULT_CONFIG_PATH.is_file():
592
- config_path = _DEFAULT_CONFIG_PATH
591
+ elif DEFAULT_CONFIG_PATH.is_file():
592
+ config_path = DEFAULT_CONFIG_PATH
593
593
  else:
594
594
  config_path = None
595
595
  if config_path is not None:
596
596
  try:
597
- parser.set_defaults(**_load_config(str(config_path), parser))
597
+ parser.set_defaults(**load_config(str(config_path), parser))
598
598
  except ValueError as err:
599
599
  parser.error(str(err))
600
600
 
@@ -714,14 +714,14 @@ def main() -> None:
714
714
 
715
715
  changed_targets: set[str] | None = None
716
716
  if args.state_file:
717
- previous_state = _load_state(args.state_file)
717
+ previous_state = load_state(args.state_file)
718
718
  current_state = {t: info["status"] for t, info, _ in results if t is not None}
719
719
  changed_targets = {
720
720
  t for t, status in current_state.items() if previous_state.get(t) != status
721
721
  }
722
- _save_state(args.state_file, current_state)
722
+ save_state(args.state_file, current_state)
723
723
 
724
- override = _render(
724
+ override = render(
725
725
  results,
726
726
  as_json=args.json,
727
727
  days=args.days,
@@ -10,7 +10,7 @@ import tomllib
10
10
  from pathlib import Path
11
11
 
12
12
  # Default location for --config, checked only when the flag is not given.
13
- _DEFAULT_CONFIG_PATH = Path.home() / ".config" / "certinspect" / "config.toml"
13
+ DEFAULT_CONFIG_PATH = Path.home() / ".config" / "certinspect" / "config.toml"
14
14
 
15
15
  # Destination groups the parser makes mutually exclusive: a --config file
16
16
  # setting more than one member of a group would silently defeat argparse's own
@@ -23,7 +23,7 @@ _CONFIG_EXCLUSIVE_GROUPS = (
23
23
  )
24
24
 
25
25
 
26
- def _load_config(path: str, parser: argparse.ArgumentParser) -> dict:
26
+ def load_config(path: str, parser: argparse.ArgumentParser) -> dict:
27
27
  """Load a --config TOML file and return it as a dest -> value mapping.
28
28
 
29
29
  Every key must be a known argparse destination (checked against ``parser``
@@ -14,7 +14,7 @@ import json
14
14
  from dataclasses import dataclass
15
15
  from urllib.parse import urlencode
16
16
 
17
- from certinspect.fetch import _http
17
+ from certinspect.httpfetch import fetch
18
18
 
19
19
  # crt.sh search front end. The `%` in the query is a SQL LIKE wildcard matching
20
20
  # any subdomain label; `output=json` asks for machine-readable results.
@@ -69,7 +69,7 @@ def _fetch_records(domain: str, timeout: float) -> list[dict]:
69
69
  Raises ValueError when the response is not the expected JSON array.
70
70
  """
71
71
  query = urlencode({"q": f"%.{domain}", "output": "json"})
72
- body = _http(f"{_CRT_SH_URL}?{query}", timeout=timeout)
72
+ body = fetch(f"{_CRT_SH_URL}?{query}", timeout=timeout)
73
73
  try:
74
74
  records = json.loads(body)
75
75
  except json.JSONDecodeError as err:
@@ -0,0 +1,53 @@
1
+ """Process exit codes and the status-to-code mapping.
2
+
3
+ Single source of truth for the exit codes certinspect returns, so the
4
+ orchestration (cli) and the reporters (formatter) agree on what each number
5
+ means instead of repeating the literals.
6
+ """
7
+
8
+ from enum import IntEnum, StrEnum
9
+
10
+
11
+ class ExitCode(IntEnum):
12
+ """Exit code reflecting the worst certificate state found.
13
+
14
+ Kept distinct from argparse's usage error (2) and the generic runtime
15
+ error (1), which are not certificate states and stay plain integers.
16
+ """
17
+
18
+ OK = 0
19
+ EXPIRING = 3
20
+ INVALID = 4 # expired, critical, not-yet-valid or invalid dates
21
+ HOSTNAME_MISMATCH = 5
22
+ UNTRUSTED_OR_REVOKED = 6
23
+ PIN_MISMATCH = 7
24
+ SAN_MISMATCH = 8
25
+ POLICY = 9
26
+
27
+
28
+ class Status(StrEnum):
29
+ """Certificate validity status returned by ``certificate_status``.
30
+
31
+ A ``StrEnum`` so each member still *is* its plain string ("EXPIRED", ...),
32
+ keeping the JSON output and every existing string comparison unchanged
33
+ while giving one authoritative definition of the status set.
34
+ """
35
+
36
+ VALID = "VALID"
37
+ EXPIRING = "EXPIRING"
38
+ CRITICAL = "CRITICAL"
39
+ EXPIRED = "EXPIRED"
40
+ NOT_YET_VALID = "NOT YET VALID"
41
+ INVALID_DATES = "INVALID DATES"
42
+
43
+
44
+ # Validity status mapped to its exit code; the four non-valid date states all
45
+ # share ExitCode.INVALID.
46
+ EXIT_BY_STATUS: dict[Status, ExitCode] = {
47
+ Status.VALID: ExitCode.OK,
48
+ Status.EXPIRING: ExitCode.EXPIRING,
49
+ Status.CRITICAL: ExitCode.INVALID,
50
+ Status.EXPIRED: ExitCode.INVALID,
51
+ Status.INVALID_DATES: ExitCode.INVALID,
52
+ Status.NOT_YET_VALID: ExitCode.INVALID,
53
+ }
@@ -10,78 +10,22 @@ connection failing. Validity is computed later in parser.py.
10
10
  """
11
11
 
12
12
  import base64
13
- import ipaddress
14
13
  import socket
15
14
  import ssl
16
15
  import time
17
16
  import urllib.request
18
17
  import warnings
19
- from datetime import datetime, timedelta, timezone
20
18
  from urllib.parse import urlsplit
21
19
 
22
20
  from cryptography import x509
23
- from cryptography.hazmat.primitives import hashes, serialization
24
- from cryptography.x509 import ocsp, verification
25
- from cryptography.x509.oid import AuthorityInformationAccessOID, ExtensionOID, NameOID
21
+ from cryptography.x509 import verification
22
+ from cryptography.x509.oid import NameOID
26
23
 
27
24
 
28
25
  # Standard plaintext ports for the STARTTLS-capable protocols, used as the
29
26
  # default port when --port is left unset.
30
27
  STARTTLS_PORTS = {"smtp": 587, "imap": 143, "pop3": 110, "ftp": 21}
31
28
 
32
- # Cap the size of any certificate-supplied HTTP response (OCSP/CRL/CA-Issuer)
33
- # so a malicious certificate cannot point us at an unbounded download and
34
- # exhaust memory. Real-world CRLs stay comfortably below this.
35
- _MAX_HTTP_RESPONSE_BYTES = 16 * 1024 * 1024
36
-
37
- # Clock-skew tolerance when judging whether an OCSP response is still fresh.
38
- _OCSP_CLOCK_SKEW = timedelta(minutes=5)
39
-
40
-
41
- def _is_blocked_fetch_address(
42
- ip: ipaddress.IPv4Address | ipaddress.IPv6Address,
43
- ) -> bool:
44
- """Return True for addresses a certificate-supplied URL must not reach.
45
-
46
- Loopback, link-local (which covers the cloud metadata endpoint
47
- ``169.254.169.254``), unspecified, multicast and reserved ranges are
48
- refused. Private RFC1918 ranges are deliberately allowed so revocation
49
- still works behind an internal PKI.
50
- """
51
- return (
52
- ip.is_loopback
53
- or ip.is_link_local
54
- or ip.is_unspecified
55
- or ip.is_multicast
56
- or ip.is_reserved
57
- )
58
-
59
-
60
- def _guard_fetch_host(url: str) -> None:
61
- """Refuse to fetch a certificate-supplied URL pointing at an internal host.
62
-
63
- OCSP, CRL and CA-Issuer URLs come from the inspected certificate, i.e. from
64
- untrusted input; following them blindly would turn certinspect into an SSRF
65
- primitive able to reach the cloud metadata service or a port on localhost.
66
- The host is resolved and every returned address checked. The guard is
67
- best-effort (the HTTP client resolves DNS again, so a rebinding attacker
68
- could still race it) but closes the obvious vectors. Raises ValueError when
69
- the target is not allowed, which the callers already treat as a soft-fail.
70
- """
71
- host = urlsplit(url).hostname
72
- if not host:
73
- raise ValueError(f"URL has no host: {url}")
74
- try:
75
- infos = socket.getaddrinfo(host, None, proto=socket.IPPROTO_TCP)
76
- except OSError as err:
77
- raise ValueError(f"could not resolve {host}: {err}") from err
78
- for info in infos:
79
- ip = ipaddress.ip_address(info[4][0])
80
- if _is_blocked_fetch_address(ip):
81
- raise ValueError(
82
- f"refusing to fetch {url}: {ip} is a non-routable or internal address"
83
- )
84
-
85
29
 
86
30
  def _read_connect_response(sock: socket.socket) -> bytes:
87
31
  """Read an HTTP CONNECT response up to the end of its header block."""
@@ -494,263 +438,3 @@ def verify_chain_offline(
494
438
  except verification.VerificationError as err:
495
439
  return False, str(err), []
496
440
  return True, None, list(verified)
497
-
498
-
499
- def _aia_urls(cert: x509.Certificate) -> tuple[list[str], list[str]]:
500
- """Return (ocsp_urls, ca_issuer_urls) from the certificate's AIA extension.
501
-
502
- Both lists are empty when the Authority Information Access extension is
503
- absent.
504
- """
505
- try:
506
- aia = cert.extensions.get_extension_for_oid(
507
- ExtensionOID.AUTHORITY_INFORMATION_ACCESS
508
- ).value
509
- except x509.ExtensionNotFound:
510
- return [], []
511
-
512
- ocsp_urls: list[str] = []
513
- issuer_urls: list[str] = []
514
- for desc in aia:
515
- location = desc.access_location.value
516
- if desc.access_method == AuthorityInformationAccessOID.OCSP:
517
- ocsp_urls.append(location)
518
- elif desc.access_method == AuthorityInformationAccessOID.CA_ISSUERS:
519
- issuer_urls.append(location)
520
- return ocsp_urls, issuer_urls
521
-
522
-
523
- def _http(url: str, *, data: bytes | None = None, timeout: float) -> bytes:
524
- """Perform a minimal HTTP(S) GET/POST and return the response body.
525
-
526
- Only ``http`` and ``https`` URLs are accepted; the URLs come from the
527
- certificate's own AIA/CRL extensions, i.e. from untrusted input, so the
528
- target host is screened against internal/non-routable addresses and the
529
- response size is capped. A POST is used when ``data`` is given.
530
- """
531
- if not url.lower().startswith(("http://", "https://")):
532
- raise ValueError(f"unsupported URL scheme: {url}")
533
- _guard_fetch_host(url)
534
- headers = {"Content-Type": "application/ocsp-request"} if data else {}
535
- request = urllib.request.Request(url, data=data, headers=headers)
536
- with urllib.request.urlopen(request, timeout=timeout) as response: # noqa: S310
537
- body = response.read(_MAX_HTTP_RESPONSE_BYTES + 1)
538
- if len(body) > _MAX_HTTP_RESPONSE_BYTES:
539
- raise ValueError(
540
- f"response from {url} exceeds the {_MAX_HTTP_RESPONSE_BYTES}-byte limit"
541
- )
542
- return body
543
-
544
-
545
- def _fetch_issuer(cert: x509.Certificate, timeout: float) -> x509.Certificate | None:
546
- """Download the issuer certificate via the AIA "CA Issuers" URL.
547
-
548
- Return None when no usable issuer can be retrieved.
549
- """
550
- _, issuer_urls = _aia_urls(cert)
551
- for url in issuer_urls:
552
- try:
553
- return x509.load_der_x509_certificate(_http(url, timeout=timeout))
554
- except (OSError, ValueError):
555
- continue
556
- return None
557
-
558
-
559
- def _crl_urls(cert: x509.Certificate) -> list[str]:
560
- """Return the HTTP(S) CRL distribution-point URLs from the certificate.
561
-
562
- Only ``http``/``https`` distribution points are returned (LDAP and other
563
- schemes are skipped). The list is empty when the CRLDistributionPoints
564
- extension is absent or carries no usable URL.
565
- """
566
- try:
567
- dps = cert.extensions.get_extension_for_oid(
568
- ExtensionOID.CRL_DISTRIBUTION_POINTS
569
- ).value
570
- except x509.ExtensionNotFound:
571
- return []
572
-
573
- urls: list[str] = []
574
- for dp in dps:
575
- for name in dp.full_name or []:
576
- value = getattr(name, "value", None)
577
- if isinstance(value, str) and value.lower().startswith(
578
- ("http://", "https://")
579
- ):
580
- urls.append(value)
581
- return urls
582
-
583
-
584
- def _ocsp_response_stale(response: ocsp.OCSPResponse) -> str | None:
585
- """Return a reason when the OCSP response is outside its validity window.
586
-
587
- A response whose ``nextUpdate`` is already in the past (or whose
588
- ``thisUpdate`` lies in the future) may be a replayed or stale answer and
589
- must not back a trusted GOOD verdict; a small clock-skew tolerance is
590
- allowed. Missing timestamps or parse errors return None ("cannot tell"),
591
- preserving the browser-like soft-fail behaviour.
592
- """
593
- now = datetime.now(timezone.utc)
594
- try:
595
- this_update = response.this_update_utc
596
- next_update = response.next_update_utc
597
- except (ValueError, AttributeError):
598
- return None
599
- if this_update is not None and this_update - _OCSP_CLOCK_SKEW > now:
600
- return f"OCSP response not yet valid (thisUpdate {this_update})"
601
- if next_update is not None and next_update + _OCSP_CLOCK_SKEW < now:
602
- return f"OCSP response is stale (nextUpdate {next_update})"
603
- return None
604
-
605
-
606
- def _check_ocsp(
607
- cert: x509.Certificate,
608
- issuer: x509.Certificate | None,
609
- timeout: float,
610
- ) -> tuple[str, str | None]:
611
- """Check revocation via OCSP. See ``check_revocation`` for the status set."""
612
- ocsp_urls, _ = _aia_urls(cert)
613
- if not ocsp_urls:
614
- return "UNAVAILABLE", "no OCSP responder in AIA extension"
615
- if issuer is None:
616
- return "UNAVAILABLE", "issuer certificate could not be retrieved"
617
-
618
- # OCSP CertID conventionally uses SHA-1 for the issuer name/key hashes;
619
- # many responders reject other digests.
620
- builder = ocsp.OCSPRequestBuilder().add_certificate(cert, issuer, hashes.SHA1())
621
- der_request = builder.build().public_bytes(serialization.Encoding.DER)
622
-
623
- try:
624
- raw = _http(ocsp_urls[0], data=der_request, timeout=timeout)
625
- except (OSError, ValueError) as err:
626
- return "UNAVAILABLE", f"OCSP request failed: {err}"
627
-
628
- # Parsing must soft-fail too: some responders (e.g. DigiCert/GitHub) return
629
- # a BasicOCSPResponse whose signatureAlgorithm the strict ASN.1 parser
630
- # rejects with a ValueError. A malformed response must not abort the whole
631
- # inspection — degrade to UNAVAILABLE and let the CRL fallback take over.
632
- try:
633
- response = ocsp.load_der_ocsp_response(raw)
634
- if response.response_status != ocsp.OCSPResponseStatus.SUCCESSFUL:
635
- return (
636
- "UNAVAILABLE",
637
- f"OCSP response status: {response.response_status.name}",
638
- )
639
- status = response.certificate_status
640
- except ValueError as err:
641
- return "UNAVAILABLE", f"OCSP response could not be parsed: {err}"
642
-
643
- if status == ocsp.OCSPCertStatus.GOOD:
644
- stale = _ocsp_response_stale(response)
645
- if stale is not None:
646
- return "UNAVAILABLE", stale
647
- return "GOOD", None
648
- if status == ocsp.OCSPCertStatus.REVOKED:
649
- when = getattr(response, "revocation_time_utc", None)
650
- return "REVOKED", f"revoked at {when}" if when else "revoked"
651
- return "UNKNOWN", "responder does not know this certificate"
652
-
653
-
654
- def _load_crl(raw: bytes) -> x509.CertificateRevocationList | None:
655
- """Parse a CRL from DER or PEM bytes, or return None when neither works."""
656
- try:
657
- return x509.load_der_x509_crl(raw)
658
- except ValueError:
659
- try:
660
- return x509.load_pem_x509_crl(raw)
661
- except ValueError:
662
- return None
663
-
664
-
665
- def _crl_stale(crl: x509.CertificateRevocationList) -> str | None:
666
- """Return a reason when a CRL is outside its validity window."""
667
- now = datetime.now(timezone.utc)
668
- try:
669
- last_update = crl.last_update_utc
670
- next_update = crl.next_update_utc
671
- except (ValueError, AttributeError):
672
- return None
673
- if last_update is not None and last_update - _OCSP_CLOCK_SKEW > now:
674
- return f"CRL is not yet valid (lastUpdate {last_update})"
675
- if next_update is not None and next_update + _OCSP_CLOCK_SKEW < now:
676
- return f"CRL is stale (nextUpdate {next_update})"
677
- return None
678
-
679
-
680
- def _check_crl(
681
- cert: x509.Certificate,
682
- issuer: x509.Certificate | None,
683
- timeout: float,
684
- ) -> tuple[str, str | None]:
685
- """Check revocation via the certificate's CRL distribution points.
686
-
687
- Download each CRL in turn and look up the certificate's serial number.
688
- When ``issuer`` is known the CRL signature is verified and a CRL that
689
- fails the check is skipped. The first CRL that yields a verdict wins;
690
- otherwise the status is ``"UNAVAILABLE"`` (soft-fail).
691
- """
692
- urls = _crl_urls(cert)
693
- if not urls:
694
- return "UNAVAILABLE", "no CRL distribution point in extension"
695
-
696
- for url in urls:
697
- try:
698
- raw = _http(url, timeout=timeout)
699
- except (OSError, ValueError):
700
- continue
701
- crl = _load_crl(raw)
702
- if crl is None:
703
- continue
704
- if issuer is not None and not crl.is_signature_valid(issuer.public_key()):
705
- continue
706
-
707
- revoked = crl.get_revoked_certificate_by_serial_number(cert.serial_number)
708
- if revoked is not None:
709
- when = getattr(revoked, "revocation_date_utc", None)
710
- detail = f"revoked at {when}" if when else "revoked"
711
- return "REVOKED", f"{detail} (via CRL)"
712
- stale = _crl_stale(crl)
713
- if stale is not None:
714
- return "UNAVAILABLE", stale
715
- return "GOOD", "via CRL"
716
-
717
- return "UNAVAILABLE", "CRL could not be retrieved"
718
-
719
-
720
- def check_revocation(
721
- cert: x509.Certificate,
722
- timeout: float = 5.0,
723
- issuer: x509.Certificate | None = None,
724
- ) -> tuple[str, str | None]:
725
- """Check the certificate's revocation status via OCSP, then CRL.
726
-
727
- Return ``(status, detail)`` where status is one of:
728
-
729
- * ``"GOOD"`` — the certificate is confirmed valid.
730
- * ``"REVOKED"`` — the certificate is confirmed revoked.
731
- * ``"UNKNOWN"`` — the OCSP responder does not know this certificate.
732
- * ``"UNAVAILABLE"`` — neither OCSP nor CRL gave an answer (soft-fail,
733
- like a browser).
734
-
735
- OCSP is tried first. When it soft-fails (no responder, issuer unavailable,
736
- network or responder error) the certificate's CRL distribution points are
737
- queried as a fallback. ``detail`` carries extra context (e.g. the
738
- revocation time, or which source answered) when useful.
739
-
740
- When ``issuer`` is provided (e.g. from the verified TLS chain) it is used
741
- directly; otherwise the issuer is downloaded via the AIA "CA Issuers" URL.
742
- """
743
- if issuer is None:
744
- issuer = _fetch_issuer(cert, timeout)
745
-
746
- status, detail = _check_ocsp(cert, issuer, timeout)
747
- if status != "UNAVAILABLE":
748
- return status, detail
749
-
750
- crl_status, crl_detail = _check_crl(cert, issuer, timeout)
751
- if crl_status != "UNAVAILABLE":
752
- return crl_status, crl_detail
753
-
754
- # Both soft-failed: report the OCSP reason, which is usually the more
755
- # informative of the two.
756
- return status, detail
@@ -9,7 +9,7 @@ import csv
9
9
  import io
10
10
  import json
11
11
 
12
- from certinspect.exit_codes import ExitCode
12
+ from certinspect.exit_codes import ExitCode, Status
13
13
  from certinspect.models import CertificateInfo
14
14
  from certinspect.parser import certificate_status
15
15
 
@@ -104,10 +104,10 @@ def format_human(
104
104
  if not info["pin_match"]:
105
105
  lines.append("WARNING: fingerprint does not match the expected pin")
106
106
 
107
- if status == "CRITICAL":
107
+ if status == Status.CRITICAL:
108
108
  lines.append("")
109
109
  lines.append(f"CRITICAL: certificate expires in {days} days")
110
- elif status == "NOT YET VALID":
110
+ elif status == Status.NOT_YET_VALID:
111
111
  lines.append("")
112
112
  lines.append(
113
113
  f"WARNING: certificate is not valid until {info['not_valid_before']}"
@@ -369,9 +369,9 @@ def format_summary(
369
369
  status = info.get("status") or certificate_status(
370
370
  info, warn_days, critical_days
371
371
  )
372
- if status == "CRITICAL":
372
+ if status == Status.CRITICAL:
373
373
  counts["critical"] += 1
374
- elif status == "NOT YET VALID":
374
+ elif status == Status.NOT_YET_VALID:
375
375
  counts["not-yet-valid"] += 1
376
376
  else:
377
377
  counts["expired"] += 1
@@ -496,7 +496,8 @@ def format_prometheus(
496
496
  days = info["days_to_expire"]
497
497
  is_valid = (
498
498
  0
499
- if certificate_status(info, warn_days) in ("EXPIRED", "INVALID DATES")
499
+ if certificate_status(info, warn_days)
500
+ in (Status.EXPIRED, Status.INVALID_DATES)
500
501
  else 1
501
502
  )
502
503
  up.append(f'certinspect_up{{target="{label}"}} 1')
@@ -0,0 +1,84 @@
1
+ """SSRF-guarded HTTP GET/POST for certificate- and CT-log-supplied URLs.
2
+
3
+ OCSP, CRL, CA-Issuer and Certificate Transparency URLs all come from untrusted
4
+ input, so this small client screens the target host against internal or
5
+ non-routable addresses and caps the response size. Shared by the revocation
6
+ checks and the CT-log discovery.
7
+ """
8
+
9
+ import ipaddress
10
+ import socket
11
+ import urllib.request
12
+ from urllib.parse import urlsplit
13
+
14
+ # Cap the size of any certificate-supplied HTTP response (OCSP/CRL/CA-Issuer)
15
+ # so a malicious certificate cannot point us at an unbounded download and
16
+ # exhaust memory. Real-world CRLs stay comfortably below this.
17
+ _MAX_HTTP_RESPONSE_BYTES = 16 * 1024 * 1024
18
+
19
+
20
+ def _is_blocked_fetch_address(
21
+ ip: ipaddress.IPv4Address | ipaddress.IPv6Address,
22
+ ) -> bool:
23
+ """Return True for addresses a certificate-supplied URL must not reach.
24
+
25
+ Loopback, link-local (which covers the cloud metadata endpoint
26
+ ``169.254.169.254``), unspecified, multicast and reserved ranges are
27
+ refused. Private RFC1918 ranges are deliberately allowed so revocation
28
+ still works behind an internal PKI.
29
+ """
30
+ return (
31
+ ip.is_loopback
32
+ or ip.is_link_local
33
+ or ip.is_unspecified
34
+ or ip.is_multicast
35
+ or ip.is_reserved
36
+ )
37
+
38
+
39
+ def _guard_fetch_host(url: str) -> None:
40
+ """Refuse to fetch a certificate-supplied URL pointing at an internal host.
41
+
42
+ OCSP, CRL and CA-Issuer URLs come from the inspected certificate, i.e. from
43
+ untrusted input; following them blindly would turn certinspect into an SSRF
44
+ primitive able to reach the cloud metadata service or a port on localhost.
45
+ The host is resolved and every returned address checked. The guard is
46
+ best-effort (the HTTP client resolves DNS again, so a rebinding attacker
47
+ could still race it) but closes the obvious vectors. Raises ValueError when
48
+ the target is not allowed, which the callers already treat as a soft-fail.
49
+ """
50
+ host = urlsplit(url).hostname
51
+ if not host:
52
+ raise ValueError(f"URL has no host: {url}")
53
+ try:
54
+ infos = socket.getaddrinfo(host, None, proto=socket.IPPROTO_TCP)
55
+ except OSError as err:
56
+ raise ValueError(f"could not resolve {host}: {err}") from err
57
+ for info in infos:
58
+ ip = ipaddress.ip_address(info[4][0])
59
+ if _is_blocked_fetch_address(ip):
60
+ raise ValueError(
61
+ f"refusing to fetch {url}: {ip} is a non-routable or internal address"
62
+ )
63
+
64
+
65
+ def fetch(url: str, *, data: bytes | None = None, timeout: float) -> bytes:
66
+ """Perform a minimal HTTP(S) GET/POST and return the response body.
67
+
68
+ Only ``http`` and ``https`` URLs are accepted; the URLs come from the
69
+ certificate's own AIA/CRL extensions, i.e. from untrusted input, so the
70
+ target host is screened against internal/non-routable addresses and the
71
+ response size is capped. A POST is used when ``data`` is given.
72
+ """
73
+ if not url.lower().startswith(("http://", "https://")):
74
+ raise ValueError(f"unsupported URL scheme: {url}")
75
+ _guard_fetch_host(url)
76
+ headers = {"Content-Type": "application/ocsp-request"} if data else {}
77
+ request = urllib.request.Request(url, data=data, headers=headers)
78
+ with urllib.request.urlopen(request, timeout=timeout) as response: # noqa: S310
79
+ body = response.read(_MAX_HTTP_RESPONSE_BYTES + 1)
80
+ if len(body) > _MAX_HTTP_RESPONSE_BYTES:
81
+ raise ValueError(
82
+ f"response from {url} exceeds the {_MAX_HTTP_RESPONSE_BYTES}-byte limit"
83
+ )
84
+ return body