certinspect 2.4.1__tar.gz → 2.4.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 (33) hide show
  1. {certinspect-2.4.1/src/certinspect.egg-info → certinspect-2.4.3}/PKG-INFO +8 -3
  2. {certinspect-2.4.1 → certinspect-2.4.3}/README.md +7 -2
  3. {certinspect-2.4.1 → certinspect-2.4.3}/pyproject.toml +1 -1
  4. {certinspect-2.4.1 → certinspect-2.4.3}/src/certinspect/__init__.py +1 -1
  5. {certinspect-2.4.1 → certinspect-2.4.3}/src/certinspect/cli.py +207 -206
  6. {certinspect-2.4.1 → certinspect-2.4.3}/src/certinspect/exit_codes.py +9 -0
  7. {certinspect-2.4.1 → certinspect-2.4.3}/src/certinspect/fetch.py +76 -48
  8. {certinspect-2.4.1 → certinspect-2.4.3}/src/certinspect/formatter.py +94 -36
  9. certinspect-2.4.3/src/certinspect/httpfetch.py +241 -0
  10. {certinspect-2.4.1 → certinspect-2.4.3}/src/certinspect/models.py +20 -5
  11. {certinspect-2.4.1 → certinspect-2.4.3}/src/certinspect/parser.py +19 -8
  12. certinspect-2.4.3/src/certinspect/render.py +139 -0
  13. {certinspect-2.4.1 → certinspect-2.4.3}/src/certinspect/revocation.py +40 -58
  14. certinspect-2.4.3/src/certinspect/state.py +53 -0
  15. {certinspect-2.4.1 → certinspect-2.4.3/src/certinspect.egg-info}/PKG-INFO +8 -3
  16. {certinspect-2.4.1 → certinspect-2.4.3}/src/certinspect.egg-info/SOURCES.txt +1 -0
  17. {certinspect-2.4.1 → certinspect-2.4.3}/tests/test_fetch.py +107 -0
  18. certinspect-2.4.1/src/certinspect/httpfetch.py +0 -111
  19. certinspect-2.4.1/src/certinspect/render.py +0 -140
  20. {certinspect-2.4.1 → certinspect-2.4.3}/LICENSE +0 -0
  21. {certinspect-2.4.1 → certinspect-2.4.3}/setup.cfg +0 -0
  22. {certinspect-2.4.1 → certinspect-2.4.3}/src/certinspect/args.py +0 -0
  23. {certinspect-2.4.1 → certinspect-2.4.3}/src/certinspect/completion.py +0 -0
  24. {certinspect-2.4.1 → certinspect-2.4.3}/src/certinspect/config.py +0 -0
  25. {certinspect-2.4.1 → certinspect-2.4.3}/src/certinspect/discover.py +0 -0
  26. {certinspect-2.4.1 → certinspect-2.4.3}/src/certinspect.egg-info/dependency_links.txt +0 -0
  27. {certinspect-2.4.1 → certinspect-2.4.3}/src/certinspect.egg-info/entry_points.txt +0 -0
  28. {certinspect-2.4.1 → certinspect-2.4.3}/src/certinspect.egg-info/requires.txt +0 -0
  29. {certinspect-2.4.1 → certinspect-2.4.3}/src/certinspect.egg-info/top_level.txt +0 -0
  30. {certinspect-2.4.1 → certinspect-2.4.3}/tests/test_cli.py +0 -0
  31. {certinspect-2.4.1 → certinspect-2.4.3}/tests/test_discover.py +0 -0
  32. {certinspect-2.4.1 → certinspect-2.4.3}/tests/test_formatter.py +0 -0
  33. {certinspect-2.4.1 → certinspect-2.4.3}/tests/test_parser.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: certinspect
3
- Version: 2.4.1
3
+ Version: 2.4.3
4
4
  Summary: Command-line TLS certificate inspector
5
5
  Author-email: Michele Angrisano <michele.angrisano@gmail.com>
6
6
  License-Expression: MIT
@@ -349,7 +349,9 @@ is treated as `UNAVAILABLE` too, so a replayed answer cannot mask a later
349
349
  revocation. The OCSP/CRL/CA-Issuer URLs come from the certificate, so
350
350
  certinspect refuses to follow one that resolves to a loopback, link-local
351
351
  (cloud metadata) or otherwise non-routable address, and caps the download
352
- size — private/internal PKI addresses stay reachable.
352
+ size — private/internal PKI addresses stay reachable. It connects to the very
353
+ address it checked, so a DNS answer that changes in between (DNS rebinding)
354
+ cannot send the request elsewhere; through a proxy, the proxy resolves the name.
353
355
 
354
356
  When the responder is down (or the certificate has no OCSP URL at all) the CRL
355
357
  fallback can still catch a revoked certificate; the `via CRL` note shows which
@@ -756,7 +758,10 @@ The report is identical to a plain inspection; only how/where certinspect
756
758
  connects changes. Split the single `--timeout` into `--connect-timeout` and
757
759
  `--read-timeout` to fail fast on dead hosts while still allowing a slow
758
760
  handshake (requests-style), and add `--retries` to ride out transient network
759
- blips instead of reporting a false failure.
761
+ blips instead of reporting a false failure. The read timeout bounds each whole
762
+ server reply (TLS handshake, each STARTTLS reply, the proxy `CONNECT` answer),
763
+ not a single read, so a server sending one byte at a time cannot stall a run;
764
+ OCSP/CRL/CA-Issuer downloads have an overall 60-second limit.
760
765
 
761
766
  ```console
762
767
  $ certinspect example.com --connect-timeout 3 --read-timeout 10 --retries 2
@@ -323,7 +323,9 @@ is treated as `UNAVAILABLE` too, so a replayed answer cannot mask a later
323
323
  revocation. The OCSP/CRL/CA-Issuer URLs come from the certificate, so
324
324
  certinspect refuses to follow one that resolves to a loopback, link-local
325
325
  (cloud metadata) or otherwise non-routable address, and caps the download
326
- size — private/internal PKI addresses stay reachable.
326
+ size — private/internal PKI addresses stay reachable. It connects to the very
327
+ address it checked, so a DNS answer that changes in between (DNS rebinding)
328
+ cannot send the request elsewhere; through a proxy, the proxy resolves the name.
327
329
 
328
330
  When the responder is down (or the certificate has no OCSP URL at all) the CRL
329
331
  fallback can still catch a revoked certificate; the `via CRL` note shows which
@@ -730,7 +732,10 @@ The report is identical to a plain inspection; only how/where certinspect
730
732
  connects changes. Split the single `--timeout` into `--connect-timeout` and
731
733
  `--read-timeout` to fail fast on dead hosts while still allowing a slow
732
734
  handshake (requests-style), and add `--retries` to ride out transient network
733
- blips instead of reporting a false failure.
735
+ blips instead of reporting a false failure. The read timeout bounds each whole
736
+ server reply (TLS handshake, each STARTTLS reply, the proxy `CONNECT` answer),
737
+ not a single read, so a server sending one byte at a time cannot stall a run;
738
+ OCSP/CRL/CA-Issuer downloads have an overall 60-second limit.
734
739
 
735
740
  ```console
736
741
  $ certinspect example.com --connect-timeout 3 --read-timeout 10 --retries 2
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "certinspect"
3
- version = "2.4.1"
3
+ version = "2.4.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.4.1"
3
+ __version__ = "2.4.3"
@@ -8,10 +8,7 @@ with a status code reflecting the worst certificate state found.
8
8
  """
9
9
 
10
10
  import argparse
11
- import csv
12
11
  import functools
13
- import io
14
- import json
15
12
  import sys
16
13
  import ssl
17
14
  from concurrent.futures import ThreadPoolExecutor
@@ -48,11 +45,19 @@ from certinspect.parser import (
48
45
  POLICY_PROFILES,
49
46
  to_pem,
50
47
  )
51
- from certinspect.exit_codes import EXIT_BY_STATUS, RUNTIME_ERROR, ExitCode, most_severe
52
- from certinspect.models import CertificateInfo
48
+ from certinspect.exit_codes import (
49
+ EXIT_BY_STATUS,
50
+ RUNTIME_ERROR,
51
+ ExitCode,
52
+ RevocationStatus,
53
+ most_severe,
54
+ )
55
+ from certinspect.models import CertificateInfo, InspectionResult
56
+ from certinspect.formatter import format_ct_inventory
53
57
  from certinspect.completion import bash_completion_script, zsh_completion_script
54
58
  from certinspect.config import DEFAULT_CONFIG_PATH, load_config
55
- from certinspect.render import load_state, render, save_state
59
+ from certinspect.render import OutputOptions, render
60
+ from certinspect.state import update_state
56
61
 
57
62
 
58
63
  @dataclass(frozen=True)
@@ -120,6 +125,28 @@ class InspectOptions:
120
125
  """Read/handshake timeout, defaulting to ``timeout`` when unset."""
121
126
  return self.read_timeout if self.read_timeout is not None else self.timeout
122
127
 
128
+ @property
129
+ def policy_requested(self) -> bool:
130
+ """True when at least one opt-in policy check (exit code 9) is enabled."""
131
+ # Identity checks: a numeric limit of 0 still counts as enabled (0 == False).
132
+ return any(
133
+ (value := getattr(self, name)) is not None and value is not False
134
+ for name in _POLICY_OPTIONS
135
+ )
136
+
137
+
138
+ # The InspectOptions fields that enable an opt-in policy check.
139
+ _POLICY_OPTIONS = (
140
+ "not_after_max",
141
+ "cab_forum",
142
+ "min_key_size",
143
+ "fail_weak",
144
+ "require_sct",
145
+ "require_must_staple",
146
+ "require_revocation_check",
147
+ "min_tls_version",
148
+ )
149
+
123
150
 
124
151
  def _split_target(raw: str, default_port: int) -> tuple[str, int]:
125
152
  """Normalize a target into ``(host, port)``.
@@ -227,10 +254,10 @@ def _inspect(
227
254
  if opts.file and (opts.verify or opts.chain):
228
255
  file_bundle = load_certificates(der)
229
256
 
230
- override, chain_certs = _check_chain(
231
- info, target, port, cert, conn, opts, file_bundle
232
- )
257
+ override, chain_certs = _check_chain(info, target, port, conn, opts, file_bundle)
233
258
  codes.append(override)
259
+ if opts.verify and target:
260
+ codes.append(_check_revocation(info, cert, chain_certs, opts))
234
261
 
235
262
  # The verified chain (when available) is the most accurate source for the
236
263
  # intermediates actually used; fall back to the chain presented by the
@@ -261,59 +288,61 @@ def _check_chain(
261
288
  info: CertificateInfo,
262
289
  target: str | None,
263
290
  port: int,
264
- cert,
265
291
  conn: dict | None,
266
292
  opts: InspectOptions,
267
293
  file_bundle: list | None,
268
294
  ) -> tuple[ExitCode | None, list]:
269
- """Verify the chain (and, for hosts, revocation) and record the outcome.
295
+ """Verify the chain and record the outcome on ``info``.
270
296
 
271
- Sets the ``chain_trusted``/``chain_error``/``chain_diagnosis`` keys, and
272
- for host targets ``revocation_status``/``revocation_detail``, on ``info``.
273
- Returns the exit-code override (UNTRUSTED_OR_REVOKED when the chain is
274
- untrusted or the certificate is revoked, else None) and the chain to use
275
- for expiry warnings.
297
+ A --file bundle is verified offline, a host over a verified handshake.
298
+ Sets ``chain_trusted``/``chain_error`` and, when it fails,
299
+ ``chain_diagnosis``. Returns UNTRUSTED_OR_REVOKED when the chain is not
300
+ trusted (else None) and the verified chain, leaf first ([] when
301
+ unavailable).
276
302
  """
277
- if opts.verify and opts.file:
303
+ if not opts.verify:
304
+ return None, []
305
+ if opts.file:
278
306
  trusted, reason, verified = verify_chain_offline(
279
307
  file_bundle, cafile=opts.cafile, capath=opts.capath
280
308
  )
281
- info["chain_trusted"] = trusted
282
- info["chain_error"] = reason
283
- override = None
284
- if not trusted:
285
- override = ExitCode.UNTRUSTED_OR_REVOKED
286
- diagnosis = diagnose_chain(file_bundle)
287
- if diagnosis:
288
- info["chain_diagnosis"] = diagnosis
289
- return override, verified or file_bundle
290
- if opts.verify and target:
309
+ presented = file_bundle
310
+ elif target:
291
311
  verify_kwargs = _connection_kwargs(opts, include_ca=True)
292
312
  timeouts = (opts.effective_connect_timeout, opts.effective_read_timeout)
293
313
  trusted, reason, verified = retry_network(
294
314
  lambda: verify_chain(target, port, timeouts, **verify_kwargs),
295
315
  opts.retries,
296
316
  )
297
- info["chain_trusted"] = trusted
298
- info["chain_error"] = reason
299
- override = None
300
- if not trusted:
301
- override = ExitCode.UNTRUSTED_OR_REVOKED
302
- presented = conn.get("chain") if conn else None
303
- if presented:
304
- diagnosis = diagnose_chain(presented)
305
- if diagnosis:
306
- info["chain_diagnosis"] = diagnosis
307
-
308
- # Prefer the issuer from the verified chain; fall back to AIA download.
309
- issuer = verified[1] if len(verified) > 1 else None
310
- revocation, detail = check_revocation(cert, opts.timeout, issuer=issuer)
311
- info["revocation_status"] = revocation
312
- info["revocation_detail"] = detail
313
- if revocation == "REVOKED":
314
- override = ExitCode.UNTRUSTED_OR_REVOKED
315
- return override, verified
316
- return None, []
317
+ presented = conn.get("chain") if conn else None
318
+ else:
319
+ return None, []
320
+
321
+ info["chain_trusted"] = trusted
322
+ info["chain_error"] = reason
323
+ if trusted:
324
+ return None, verified
325
+ diagnosis = diagnose_chain(presented) if presented else None
326
+ if diagnosis:
327
+ info["chain_diagnosis"] = diagnosis
328
+ return ExitCode.UNTRUSTED_OR_REVOKED, verified
329
+
330
+
331
+ def _check_revocation(
332
+ info: CertificateInfo, cert, verified: list, opts: InspectOptions
333
+ ) -> ExitCode | None:
334
+ """Query OCSP/CRL and record ``revocation_status``/``revocation_detail``.
335
+
336
+ Returns UNTRUSTED_OR_REVOKED when the certificate is revoked, else None.
337
+ """
338
+ # Prefer the issuer from the verified chain; fall back to AIA download.
339
+ issuer = verified[1] if len(verified) > 1 else None
340
+ status, detail = check_revocation(cert, opts.timeout, issuer=issuer)
341
+ info["revocation_status"] = status
342
+ info["revocation_detail"] = detail
343
+ if status == RevocationStatus.REVOKED:
344
+ return ExitCode.UNTRUSTED_OR_REVOKED
345
+ return None
317
346
 
318
347
 
319
348
  def _check_pin(info: CertificateInfo, opts: InspectOptions) -> ExitCode | None:
@@ -335,16 +364,7 @@ def _check_expect_san(info: CertificateInfo, opts: InspectOptions) -> ExitCode |
335
364
 
336
365
  def _check_policy(info: CertificateInfo, opts: InspectOptions) -> ExitCode | None:
337
366
  """Record the opt-in policy violations; return POLICY when any applies."""
338
- if not (
339
- opts.not_after_max is not None
340
- or opts.cab_forum
341
- or opts.min_key_size is not None
342
- or opts.fail_weak
343
- or opts.require_sct
344
- or opts.require_must_staple
345
- or opts.require_revocation_check
346
- or opts.min_tls_version is not None
347
- ):
367
+ if not opts.policy_requested:
348
368
  return None
349
369
  not_after_max = opts.not_after_max
350
370
  if opts.cab_forum:
@@ -369,7 +389,7 @@ def _check_policy(info: CertificateInfo, opts: InspectOptions) -> ExitCode | Non
369
389
  def _revocation_policy_violation(info: CertificateInfo) -> str | None:
370
390
  """Return a policy violation when revocation was not proven GOOD."""
371
391
  status = info.get("revocation_status")
372
- if status == "GOOD":
392
+ if status == RevocationStatus.GOOD:
373
393
  return None
374
394
  detail = info.get("revocation_detail")
375
395
  if detail:
@@ -429,18 +449,40 @@ def _discover_one(
429
449
  return domain, None, str(err)
430
450
 
431
451
 
432
- def _discover_all(domains: list[str], timeout: float, workers: int, fetch) -> list:
433
- """Run ``fetch(domain, timeout)`` for every domain, in parallel when asked.
452
+ def _map(call, items: list, workers: int) -> list:
453
+ """Return ``[call(item) for item in items]``, in threads when ``workers`` > 1.
434
454
 
435
- Returns the ``(domain, result, error)`` outcomes in ``domains`` order
436
- regardless of concurrency, so callers can report them deterministically.
455
+ ThreadPoolExecutor.map keeps the input order, so the output is
456
+ deterministic regardless of concurrency.
437
457
  """
438
- call = functools.partial(_discover_one, timeout=timeout, fetch=fetch)
439
458
  workers = max(1, workers)
440
- if workers > 1 and len(domains) > 1:
459
+ if workers > 1 and len(items) > 1:
441
460
  with ThreadPoolExecutor(max_workers=workers) as pool:
442
- return list(pool.map(call, domains))
443
- return [call(domain) for domain in domains]
461
+ return list(pool.map(call, items))
462
+ return [call(item) for item in items]
463
+
464
+
465
+ def _discover(
466
+ domains: list[str], timeout: float, workers: int, fetch, noun: str
467
+ ) -> list[tuple[str, list]]:
468
+ """Run ``fetch(domain, timeout)`` for every domain and report it on stderr.
469
+
470
+ ``noun`` names what ``fetch`` returns ("hostname", "certificate") in the
471
+ per-domain message. The first failed domain aborts with exit code 1, like
472
+ an unreadable --input. Returns ``(domain, result)`` pairs in input order.
473
+ """
474
+ call = functools.partial(_discover_one, timeout=timeout, fetch=fetch)
475
+ found = []
476
+ for domain, result, err in _map(call, domains, workers):
477
+ if err is not None:
478
+ print(f"error: discovery for {domain}: {err}", file=sys.stderr)
479
+ sys.exit(1)
480
+ if result:
481
+ print(f"discovered {len(result)} {noun}(s) for {domain}", file=sys.stderr)
482
+ else:
483
+ print(f"warning: no certificates found for {domain}", file=sys.stderr)
484
+ found.append((domain, result))
485
+ return found
444
486
 
445
487
 
446
488
  def _issuer_is_expected(issuer: str, expected: list[str]) -> bool:
@@ -453,31 +495,25 @@ def _issuer_is_expected(issuer: str, expected: list[str]) -> bool:
453
495
  return any(token.lower() in lowered for token in expected)
454
496
 
455
497
 
456
- def _run_discover_only(args: argparse.Namespace) -> None:
457
- """List the CT inventory for the --discover domains and exit.
498
+ def _run_discover_only(args: argparse.Namespace) -> ExitCode:
499
+ """Print the CT inventory for the --discover domains, return the exit code.
458
500
 
459
501
  Prints one certificate per line (expiry, issuer, hostnames), soonest expiry
460
502
  first, so the whole Certificate Transparency picture — dead hosts and
461
503
  unexpected issuers included — is visible without a live handshake. With
462
- --expect-issuer, certificates from any other CA are flagged and the exit
463
- code becomes 9; with --json the inventory is emitted as a JSON array.
504
+ --expect-issuer, certificates from any other CA are flagged and the result
505
+ is POLICY; with --json/--csv the inventory uses that format.
464
506
  """
465
507
  expected = args.expect_issuer or []
466
508
  rows: list[tuple[str, DiscoveredCert, bool]] = []
467
- outcomes = _discover_all(
468
- args.discover, args.discover_timeout, args.concurrency, discover_certificates
509
+ inventory = _discover(
510
+ args.discover,
511
+ args.discover_timeout,
512
+ args.concurrency,
513
+ discover_certificates,
514
+ "certificate",
469
515
  )
470
- for domain, certs, err in outcomes:
471
- if err is not None:
472
- print(f"error: discovery for {domain}: {err}", file=sys.stderr)
473
- sys.exit(1)
474
- if certs:
475
- print(
476
- f"discovered {len(certs)} certificate(s) for {domain}",
477
- file=sys.stderr,
478
- )
479
- else:
480
- print(f"warning: no certificates found for {domain}", file=sys.stderr)
516
+ for domain, certs in inventory:
481
517
  for cert in certs:
482
518
  unexpected = bool(expected) and not _issuer_is_expected(
483
519
  cert.issuer, expected
@@ -486,53 +522,22 @@ def _run_discover_only(args: argparse.Namespace) -> None:
486
522
 
487
523
  unexpected_count = sum(1 for _, _, unexpected in rows if unexpected)
488
524
 
489
- if args.json:
490
- payload = []
491
- for domain, cert, unexpected in rows:
492
- record = {
493
- "domain": domain,
494
- "hostnames": list(cert.hostnames),
495
- "issuer": cert.issuer,
496
- "not_before": cert.not_before,
497
- "not_after": cert.not_after,
498
- }
499
- if expected:
500
- record["unexpected_issuer"] = unexpected
501
- payload.append(record)
502
- print(json.dumps(payload, indent=2, default=str, ensure_ascii=False))
503
- elif args.csv:
504
- buffer = io.StringIO()
505
- writer = csv.writer(buffer, delimiter=args.csv_delimiter, lineterminator="\n")
506
- header = ["domain", "hostnames", "issuer", "not_before", "not_after"]
507
- if expected:
508
- header.append("unexpected_issuer")
509
- writer.writerow(header)
510
- for domain, cert, unexpected in rows:
511
- record = [
512
- domain,
513
- " ".join(cert.hostnames),
514
- cert.issuer,
515
- cert.not_before,
516
- cert.not_after,
517
- ]
518
- if expected:
519
- record.append("yes" if unexpected else "no")
520
- writer.writerow(record)
521
- print(buffer.getvalue(), end="")
522
- else:
523
- for _, cert, unexpected in rows:
524
- line = f"{cert.not_after}\t{cert.issuer}\t{', '.join(cert.hostnames)}"
525
- print(f"{line}\tUNEXPECTED" if unexpected else line)
525
+ text = format_ct_inventory(
526
+ rows,
527
+ as_json=args.json,
528
+ as_csv=args.csv,
529
+ delimiter=args.csv_delimiter,
530
+ flag_issuer=bool(expected),
531
+ )
532
+ print(text, end="")
526
533
 
527
- if expected and unexpected_count:
534
+ if unexpected_count:
528
535
  print(
529
536
  f"warning: {unexpected_count} certificate(s) from an unexpected issuer",
530
537
  file=sys.stderr,
531
538
  )
532
-
533
- if args.exit_zero:
534
- sys.exit(0)
535
- sys.exit(9 if unexpected_count else 0)
539
+ return ExitCode.POLICY
540
+ return ExitCode.OK
536
541
 
537
542
 
538
543
  def _validate_args(args: argparse.Namespace, parser: argparse.ArgumentParser) -> None:
@@ -578,10 +583,8 @@ def _validate_args(args: argparse.Namespace, parser: argparse.ArgumentParser) ->
578
583
  parser.error("--state-file applies to host targets, not --file.")
579
584
 
580
585
 
581
- def main() -> None:
582
- """CLI entry point."""
583
- parser = build_parser()
584
-
586
+ def _parse_args(parser: argparse.ArgumentParser) -> argparse.Namespace:
587
+ """Parse the command line on top of the defaults from the config file."""
585
588
  # --config must be resolved before the real parse: its values become the
586
589
  # argparse defaults, which an explicit command-line flag still overrides.
587
590
  config_pre_parser = argparse.ArgumentParser(add_help=False)
@@ -600,25 +603,24 @@ def main() -> None:
600
603
  parser.set_defaults(**load_config(str(config_path), parser))
601
604
  except ValueError as err:
602
605
  parser.error(str(err))
606
+ return parser.parse_args()
603
607
 
604
- args = parser.parse_args()
605
608
 
606
- if args.print_completion:
607
- script = (
608
- bash_completion_script(parser)
609
- if args.print_completion == "bash"
610
- else zsh_completion_script(parser)
611
- )
612
- print(script, end="")
613
- sys.exit(0)
609
+ def _completion_script(parser: argparse.ArgumentParser, shell: str) -> str:
610
+ """Return the completion script for ``shell`` ('bash' or 'zsh')."""
611
+ if shell == "bash":
612
+ return bash_completion_script(parser)
613
+ return zsh_completion_script(parser)
614
614
 
615
- _apply_profile(args)
616
615
 
617
- _validate_args(args, parser)
618
-
619
- if args.discover_only:
620
- _run_discover_only(args)
616
+ def _collect_targets(
617
+ args: argparse.Namespace, parser: argparse.ArgumentParser
618
+ ) -> tuple[list[str], list[str]]:
619
+ """Return ``(host_targets, file_targets)``, --input and --discover included.
621
620
 
621
+ Rejects an empty or inconsistent target set via ``parser.error``; an
622
+ unreadable --input file aborts with exit code 1.
623
+ """
622
624
  extra_targets = []
623
625
  if args.input:
624
626
  # An unreadable --input file (missing, no permission) is a runtime error
@@ -631,20 +633,13 @@ def main() -> None:
631
633
  sys.exit(1)
632
634
  discovered_targets: list[str] = []
633
635
  if args.discover:
634
- outcomes = _discover_all(
635
- args.discover, args.discover_timeout, args.concurrency, discover_hostnames
636
- )
637
- for domain, found, err in outcomes:
638
- if err is not None:
639
- print(f"error: discovery for {domain}: {err}", file=sys.stderr)
640
- sys.exit(1)
641
- if found:
642
- print(
643
- f"discovered {len(found)} hostname(s) for {domain}",
644
- file=sys.stderr,
645
- )
646
- else:
647
- print(f"warning: no certificates found for {domain}", file=sys.stderr)
636
+ for _, found in _discover(
637
+ args.discover,
638
+ args.discover_timeout,
639
+ args.concurrency,
640
+ discover_hostnames,
641
+ "hostname",
642
+ ):
648
643
  discovered_targets.extend(found)
649
644
 
650
645
  host_targets = [*args.target, *extra_targets, *discovered_targets]
@@ -658,13 +653,25 @@ def main() -> None:
658
653
  parser.error("--file '-' (standard input) may be given at most once.")
659
654
  if args.export and len(host_targets) + len(file_targets) > 1:
660
655
  parser.error("--export saves a single certificate; give one target.")
656
+ return host_targets, file_targets
661
657
 
662
- # With STARTTLS, fall back to the protocol's standard port unless the user
663
- # passed --port explicitly (i.e. it differs from the 443 default).
664
- default_port = args.port
665
- if args.starttls and default_port == 443:
666
- default_port = STARTTLS_PORTS[args.starttls]
667
658
 
659
+ def _default_port(args: argparse.Namespace) -> int:
660
+ """Return --port, or the STARTTLS protocol's port when --port was not given."""
661
+ if args.starttls and args.port == 443:
662
+ return STARTTLS_PORTS[args.starttls]
663
+ return args.port
664
+
665
+
666
+ def _inspect_all(
667
+ args: argparse.Namespace, host_targets: list[str], file_targets: list[str]
668
+ ) -> tuple[list[InspectionResult], list[tuple[str | None, str]], list[int]]:
669
+ """Inspect every target, returning ``(results, errors, codes)``.
670
+
671
+ Failures are reported on stderr (unless an exporter is selected) and
672
+ counted as RUNTIME_ERROR; ``codes`` holds one exit code per target.
673
+ """
674
+ default_port = _default_port(args)
668
675
  opts = InspectOptions.from_args(args)
669
676
 
670
677
  # A single --file source keeps the old unlabelled output; with several
@@ -673,14 +680,14 @@ def main() -> None:
673
680
  work_items: list[tuple[bool, str]] = [(True, path) for path in file_targets]
674
681
  work_items += [(False, raw) for raw in host_targets]
675
682
 
676
- def _run(item: tuple[bool, str]) -> tuple[str, tuple | None, str | None]:
677
- """Inspect one work item, returning (name, payload, error).
683
+ def _run(item: tuple[bool, str]) -> tuple[str, InspectionResult | None, str | None]:
684
+ """Inspect one work item, returning (name, result, error).
678
685
 
679
686
  ``item`` is ``(is_file, raw)``: a file path or a host target string.
680
687
  ``name`` labels the item (``host[:port]`` for a host, the path for a
681
- file). ``payload`` is ``(label, info, code)`` on success and None on
682
- failure, in which case ``error`` carries the message. Runs in worker
683
- threads, so it must not perform any I/O on shared streams.
688
+ file). ``result`` is None on failure, in which case ``error`` carries
689
+ the message. Runs in worker threads, so it must not perform any I/O on
690
+ shared streams.
684
691
  """
685
692
  is_file, raw = item
686
693
  name = raw
@@ -688,26 +695,19 @@ def main() -> None:
688
695
  if is_file:
689
696
  file_opts = replace(opts, file=raw)
690
697
  info, code = _inspect(None, default_port, file_opts)
691
- return name, (None if single_file else raw, info, code), None
698
+ label = None if single_file else raw
699
+ return name, InspectionResult(label, info, code), None
692
700
  target, port = _split_target(raw, default_port)
693
701
  name = _target_label(target, port, default_port)
694
702
  info, code = _inspect(target, port, opts)
695
703
  except (OSError, ssl.SSLError, ValueError) as err:
696
704
  return name, None, str(err)
697
- return name, (name, info, code), None
705
+ return name, InspectionResult(name, info, code), None
698
706
 
699
- # Inspect in parallel when asked; ThreadPoolExecutor.map preserves order.
700
- workers = max(1, args.concurrency)
701
- if workers > 1 and len(work_items) > 1:
702
- with ThreadPoolExecutor(max_workers=workers) as pool:
703
- outcomes = list(pool.map(_run, work_items))
704
- else:
705
- outcomes = [_run(item) for item in work_items]
706
-
707
- results: list[tuple[str | None, dict, int]] = []
707
+ results: list[InspectionResult] = []
708
708
  errors: list[tuple[str | None, str]] = []
709
709
  codes: list[int] = []
710
- for name, payload, err in outcomes:
710
+ for name, result, err in _map(_run, work_items, args.concurrency):
711
711
  if err is not None:
712
712
  if not args.exporter:
713
713
  label = f"{name}: " if name else ""
@@ -715,38 +715,39 @@ def main() -> None:
715
715
  errors.append((name, err))
716
716
  codes.append(RUNTIME_ERROR)
717
717
  continue
718
- results.append(payload)
719
- codes.append(payload[2])
718
+ results.append(result)
719
+ codes.append(result.code)
720
+ return results, errors, codes
721
+
722
+
723
+ def main() -> None:
724
+ """CLI entry point."""
725
+ parser = build_parser()
726
+ args = _parse_args(parser)
720
727
 
721
- changed_targets: set[str] | None = None
728
+ if args.print_completion:
729
+ print(_completion_script(parser, args.print_completion), end="")
730
+ sys.exit(0)
731
+
732
+ _apply_profile(args)
733
+ _validate_args(args, parser)
734
+
735
+ if args.discover_only:
736
+ code = _run_discover_only(args)
737
+ sys.exit(0 if args.exit_zero else code)
738
+
739
+ host_targets, file_targets = _collect_targets(args, parser)
740
+ results, errors, codes = _inspect_all(args, host_targets, file_targets)
741
+
742
+ changed_targets = None
722
743
  if args.state_file:
723
- previous_state = load_state(args.state_file)
724
- current_state = {t: info["status"] for t, info, _ in results if t is not None}
725
- changed_targets = {
726
- t for t, status in current_state.items() if previous_state.get(t) != status
727
- }
728
- # A target that failed this run keeps its last known status, so a
729
- # transient outage is not reported as a change once it recovers.
730
- failed = {name for name, _ in errors}
731
- kept = {t: s for t, s in previous_state.items() if t in failed}
732
- save_state(args.state_file, {**kept, **current_state})
744
+ changed_targets = update_state(args.state_file, results, errors)
733
745
 
734
746
  override = render(
735
747
  results,
736
- as_json=args.json,
737
- days=args.days,
738
- quiet=args.quiet,
739
- as_csv=args.csv,
740
- csv_delimiter=args.csv_delimiter,
741
- critical_days=args.critical_days,
742
- max_days=args.max_days,
743
- sort=args.sort,
744
- summary=args.summary,
745
- exporter=args.exporter,
746
- fields=args.field,
747
- schema=args.schema,
748
- errors=errors,
749
- changed_targets=changed_targets if args.only_changed else None,
748
+ errors,
749
+ OutputOptions.from_args(args),
750
+ changed_targets if args.only_changed else None,
750
751
  )
751
752
  if args.exit_zero:
752
753
  sys.exit(0)