certinspect 0.1.0__tar.gz

certinspect-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michele Angrisano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

certinspect-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: certinspect
+Version: 0.1.0
+Summary: Ispettore di certificati TLS da riga di comando
+Author: Michele Angrisano
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mangrisano/certinspect
+Project-URL: Repository, https://github.com/mangrisano/certinspect
+Project-URL: Issues, https://github.com/mangrisano/certinspect/issues
+Keywords: tls,ssl,certificate,x509,cli
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=42.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Dynamic: license-file
+
+# certinspect
+
+Ispettore di certificati TLS da riga di comando.
+
+Dato uno o più domini (o un file `.pem`/`.der`), mostra validità, giorni alla
+scadenza, soggetto, issuer, SAN, algoritmo di firma, dimensione della chiave,
+fingerprint SHA-256, flag CA, self-signed, eventuali debolezze crittografiche e
+la corrispondenza dell'hostname.
+
+## Requisiti
+
+- Python >= 3.14
+
+## Installazione (sviluppo)
+
+```bash
+python3.14 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+pip install -e ".[dev]"
+```
+
+## Uso
+
+```bash
+# Ispeziona un host
+certinspect example.com
+
+# Più host in una volta (modalità batch)
+certinspect example.com github.com api.example.com
+
+# Porta personalizzata
+certinspect example.com --port 8443
+
+# Output JSON (sempre una lista di oggetti)
+certinspect example.com --json
+
+# Ispeziona un certificato locale
+certinspect --file ./certificato.pem
+
+# Soglia di avviso scadenza personalizzata (default: 30 giorni)
+certinspect example.com --days 14
+
+# Salva il certificato scaricato in formato PEM
+certinspect example.com --export ./scaricato.pem
+```
+
+## Opzioni
+
+| Opzione         | Descrizione                                                    |
+| --------------- | -------------------------------------------------------------- |
+| `target...`     | Uno o più domini da ispezionare. Ometti quando usi `--file`.   |
+| `--file PATH`   | Ispeziona un certificato locale (PEM o DER) invece di un host. |
+| `--port N`      | Porta TCP a cui connettersi (default: 443).                    |
+| `--json`        | Stampa il risultato come JSON invece del testo leggibile.      |
+| `--days N`      | Avvisa se il certificato scade entro N giorni (default: 30).   |
+| `--export PATH` | Salva il certificato ispezionato come file PEM in PATH.        |
+
+## Exit code
+
+Pensati per l'automazione (cron, CI, script di monitoraggio). In modalità batch
+viene restituito il caso peggiore tra tutti i target.
+
+| Code | Significato                                  |
+| ---- | -------------------------------------------- |
+| 0    | Certificato valido                           |
+| 1    | Errore di runtime (rete, file, parsing)      |
+| 2    | Errore negli argomenti della riga di comando |
+| 3    | In scadenza entro la soglia `--days`         |
+| 4    | Scaduto o con date non valide                |
+| 5    | L'hostname non corrisponde al certificato    |
+
+Esempio in uno script:
+
+```bash
+certinspect tuosito.it --days 21
+case $? in
+  0) ;;                                          # tutto ok
+  3) echo "In scadenza" | mail -s "Avviso" tu@mail.it ;;
+  4) echo "Scaduto"     | mail -s "Urgente" tu@mail.it ;;
+  5) echo "Host errato" | mail -s "Urgente" tu@mail.it ;;
+  *) echo "Check fallito" ;;
+esac
+```
+
+## Sviluppo
+
+```bash
+# Test
+pytest
+
+# Lint e formattazione (Ruff)
+ruff check src tests
+ruff format src tests
+```

certinspect-0.1.0/README.md

@@ -0,0 +1,95 @@
+# certinspect
+
+Ispettore di certificati TLS da riga di comando.
+
+Dato uno o più domini (o un file `.pem`/`.der`), mostra validità, giorni alla
+scadenza, soggetto, issuer, SAN, algoritmo di firma, dimensione della chiave,
+fingerprint SHA-256, flag CA, self-signed, eventuali debolezze crittografiche e
+la corrispondenza dell'hostname.
+
+## Requisiti
+
+- Python >= 3.14
+
+## Installazione (sviluppo)
+
+```bash
+python3.14 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+pip install -e ".[dev]"
+```
+
+## Uso
+
+```bash
+# Ispeziona un host
+certinspect example.com
+
+# Più host in una volta (modalità batch)
+certinspect example.com github.com api.example.com
+
+# Porta personalizzata
+certinspect example.com --port 8443
+
+# Output JSON (sempre una lista di oggetti)
+certinspect example.com --json
+
+# Ispeziona un certificato locale
+certinspect --file ./certificato.pem
+
+# Soglia di avviso scadenza personalizzata (default: 30 giorni)
+certinspect example.com --days 14
+
+# Salva il certificato scaricato in formato PEM
+certinspect example.com --export ./scaricato.pem
+```
+
+## Opzioni
+
+| Opzione         | Descrizione                                                    |
+| --------------- | -------------------------------------------------------------- |
+| `target...`     | Uno o più domini da ispezionare. Ometti quando usi `--file`.   |
+| `--file PATH`   | Ispeziona un certificato locale (PEM o DER) invece di un host. |
+| `--port N`      | Porta TCP a cui connettersi (default: 443).                    |
+| `--json`        | Stampa il risultato come JSON invece del testo leggibile.      |
+| `--days N`      | Avvisa se il certificato scade entro N giorni (default: 30).   |
+| `--export PATH` | Salva il certificato ispezionato come file PEM in PATH.        |
+
+## Exit code
+
+Pensati per l'automazione (cron, CI, script di monitoraggio). In modalità batch
+viene restituito il caso peggiore tra tutti i target.
+
+| Code | Significato                                  |
+| ---- | -------------------------------------------- |
+| 0    | Certificato valido                           |
+| 1    | Errore di runtime (rete, file, parsing)      |
+| 2    | Errore negli argomenti della riga di comando |
+| 3    | In scadenza entro la soglia `--days`         |
+| 4    | Scaduto o con date non valide                |
+| 5    | L'hostname non corrisponde al certificato    |
+
+Esempio in uno script:
+
+```bash
+certinspect tuosito.it --days 21
+case $? in
+  0) ;;                                          # tutto ok
+  3) echo "In scadenza" | mail -s "Avviso" tu@mail.it ;;
+  4) echo "Scaduto"     | mail -s "Urgente" tu@mail.it ;;
+  5) echo "Host errato" | mail -s "Urgente" tu@mail.it ;;
+  *) echo "Check fallito" ;;
+esac
+```
+
+## Sviluppo
+
+```bash
+# Test
+pytest
+
+# Lint e formattazione (Ruff)
+ruff check src tests
+ruff format src tests
+```

certinspect-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "certinspect"
+version = "0.1.0"
+description = "Ispettore di certificati TLS da riga di comando"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Michele Angrisano" }]
+keywords = ["tls", "ssl", "certificate", "x509", "cli"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Environment :: Console",
+    "Topic :: Security :: Cryptography",
+]
+dependencies = [
+    "cryptography>=42.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "ruff>=0.4.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/mangrisano/certinspect"
+Repository = "https://github.com/mangrisano/certinspect"
+Issues = "https://github.com/mangrisano/certinspect/issues"
+
+[project.scripts]
+certinspect = "certinspect.cli:main"
+
+[build-system]
+requires = ["setuptools>=77.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]

certinspect-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

certinspect-0.1.0/src/certinspect/__init__.py

@@ -0,0 +1,3 @@
+"""certinspect — Ispettore di certificati TLS da riga di comando."""
+
+__version__ = "0.1.0"

certinspect-0.1.0/src/certinspect/cli.py

@@ -0,0 +1,169 @@
+"""
+cli.py — Command-line entry point.
+
+Wire together fetch -> parser -> formatter, reading the CLI arguments.
+
+It fetches a certificate from one or more hosts (or reads a local file),
+analyzes it, prints the result as human-readable text or JSON, and exits
+with a status code reflecting the worst certificate state found.
+"""
+
+import argparse
+import json
+import sys
+import ssl
+from certinspect.fetch import get_server_cert_der
+from certinspect.parser import (
+    load_certificate,
+    analyze,
+    certificate_status,
+    hostname_matches,
+    to_pem,
+)
+from certinspect.formatter import format_human
+
+# Exit codes reflecting the certificate status, kept distinct from
+# argparse's usage error (2) and the generic runtime error (1).
+EXIT_BY_STATUS = {
+    "VALID": 0,
+    "EXPIRING": 3,
+    "EXPIRED": 4,
+    "INVALID DATES": 4,
+}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build and return the ArgumentParser."""
+
+    parser = argparse.ArgumentParser(
+        prog="certinspect",
+        description="Inspect a TLS certificate from a host or a local file.",
+    )
+    parser.add_argument(
+        "target",
+        nargs="*",
+        help=(
+            "One or more domain names to inspect (e.g. example.com). "
+            "Omit when using --file."
+        ),
+    )
+    parser.add_argument(
+        "--file",
+        help=(
+            "Path to a local certificate file (PEM or DER) to inspect "
+            "instead of a host."
+        ),
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=443,
+        help="TCP port to connect to (default: 443).",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output the result as JSON instead of human-readable text.",
+    )
+    parser.add_argument(
+        "--days",
+        type=int,
+        default=30,
+        help=("Warn if the certificate expires within this many days (default: 30)."),
+    )
+    parser.add_argument(
+        "--export",
+        metavar="PATH",
+        help="Save the inspected certificate as a PEM file at PATH.",
+    )
+
+    return parser
+
+
+def _fetch_bytes(target: str | None, port: int, file: str | None) -> bytes:
+    """Return the raw certificate bytes for a single source (file or host)."""
+    if file:
+        with open(file, "rb") as f:
+            return f.read()
+    return get_server_cert_der(target, port)
+
+
+def _inspect(
+    target: str | None,
+    *,
+    port: int,
+    file: str | None,
+    days: int,
+    export: str | None,
+) -> tuple[dict, int]:
+    """Inspect one source and return its (info, exit_code).
+
+    The hostname match (and its exit code 5) only applies to host targets;
+    with --file it is left as None.
+    """
+    cert = load_certificate(_fetch_bytes(target, port, file))
+    info = analyze(cert)
+    if export:
+        with open(export, "wb") as f:
+            f.write(to_pem(cert))
+    info["hostname_match"] = hostname_matches(info, target) if target else None
+
+    code = EXIT_BY_STATUS[certificate_status(info, days)]
+    if info["hostname_match"] is False:
+        code = 5
+    return info, code
+
+
+def _render(
+    results: list[tuple[str | None, dict]], *, as_json: bool, days: int
+) -> None:
+    """Print the collected results as JSON (always a list) or human text."""
+    if as_json:
+        print(json.dumps([info for _, info in results], indent=2, default=str))
+        return
+
+    blocks = []
+    for target, info in results:
+        text = format_human(info, warn_days=days)
+        blocks.append(f"=== {target} ===\n{text}" if target else text)
+    if blocks:
+        print("\n\n".join(blocks))
+
+
+def main() -> None:
+    """CLI entry point."""
+
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if not args.target and not args.file:
+        parser.error("There is no target or no file to inspect.")
+
+    # A single --file source has no host; otherwise iterate over the targets.
+    targets: list[str | None] = [None] if args.file else list(args.target)
+
+    results: list[tuple[str | None, dict]] = []
+    codes: list[int] = []
+    for target in targets:
+        try:
+            info, code = _inspect(
+                target,
+                port=args.port,
+                file=args.file,
+                days=args.days,
+                export=args.export,
+            )
+        except (OSError, ssl.SSLError, ValueError) as err:
+            label = f"{target}: " if target else ""
+            print(f"error: {label}{err}", file=sys.stderr)
+            codes.append(1)
+            continue
+        results.append((target, info))
+        codes.append(code)
+
+    _render(results, as_json=args.json, days=args.days)
+    sys.exit(max(codes, default=0))
+
+
+if __name__ == "__main__":
+    main()

certinspect-0.1.0/src/certinspect/fetch.py

@@ -0,0 +1,24 @@
+"""
+fetch.py — Retrieving the certificate from the TLS server.
+
+Connect to a host:port over TLS and obtain the server certificate in DER
+format (bytes), ready to be parsed in parser.py.
+
+Hostname checking and verification are disabled on purpose: this tool must
+be able to inspect expired or self-signed certificates without the
+connection failing. Validity is computed later in parser.py.
+"""
+
+import socket
+import ssl
+
+
+def get_server_cert_der(host: str, port: int = 443, timeout: float = 5.0) -> bytes:
+    """Return the server certificate in DER format (bytes)."""
+
+    context = ssl.create_default_context()
+    context.check_hostname = False
+    context.verify_mode = ssl.CERT_NONE
+    with socket.create_connection((host, port), timeout=timeout) as sock:
+        with context.wrap_socket(sock, server_hostname=host) as ssock:
+            return ssock.getpeercert(binary_form=True)

certinspect-0.1.0/src/certinspect/formatter.py

@@ -0,0 +1,81 @@
+"""
+formatter.py — Presentation of the results to the user.
+
+MODULE GOAL
+-----------
+Take the dict produced by parser.analyze() and produce human-readable output
+(text) or machine-readable output (JSON).
+
+GUIDED STEPS (write them yourself):
+1. format_human(info: dict) -> str
+   - Print the fields in a tidy, readable way.
+   - Highlight the status: VALID / EXPIRED / NOT YET VALID.
+   - Show a WARNING if the days to expiry are < 30.
+2. format_json(info: dict) -> str
+   - Serialize with json.dumps(info, default=str, indent=2).
+   - Note: dates are not serializable by default → use default=str
+     or convert them to ISO 8601 in parser.analyze().
+
+Hint: keep color/emoji logic optional and simple.
+Do not put analysis logic here: this module only PRESENTS the data.
+"""
+
+import json
+
+from certinspect.parser import certificate_status
+
+LABEL_WIDTH = 16
+
+
+def format_human(info: dict, warn_days: int = 30) -> str:
+    """Return a human-readable text representation."""
+    days = info["days_to_expire"]
+    status = certificate_status(info, warn_days)
+
+    def row(label: str, value: object) -> str:
+        return f"{label + ':':<{LABEL_WIDTH}}{value}"
+
+    lines = [
+        row("Subject", info["subject"]),
+        row("Status", status),
+        "",
+        row("Issuer", info["issuer"]),
+        row("Valid from", info["not_valid_before"]),
+        row("Valid until", info["not_valid_after"]),
+        row("Days to expiry", days),
+        "",
+        row("Serial number", info["serial_number"]),
+        row("Signature", info["signature_algorithm"]),
+        row("Key size", f"{info['key_size']} bit"),
+        row("Fingerprint", info["fingerprint_sha256"]),
+        row("CA", info["is_ca"]),
+        row("Self-Signed", info["self_signed"]),
+    ]
+
+    if info["weak"]:
+        lines.append("")
+        for reason in info["weak"]:
+            lines.append(f"WARNING: {reason}")
+
+    if info.get("hostname_match") is not None:
+        lines.append(row("Hostname match", info["hostname_match"]))
+
+    if 0 <= days < warn_days:
+        lines.append("")
+        lines.append(f"WARNING: certificate expires in {days} days")
+
+    san = info["san"]
+    lines.append("")
+    if san:
+        lines.append("SAN:")
+        lines.extend(f"  - {name}" for name in san)
+    else:
+        lines.append(row("SAN", "(none)"))
+
+    return "\n".join(lines)
+
+
+def format_json(info: dict) -> str:
+    """Return a JSON representation."""
+
+    return json.dumps(info, indent=2, default=str)

certinspect-0.1.0/src/certinspect/parser.py

@@ -0,0 +1,123 @@
+"""X.509 certificate parsing and analysis.
+
+Turns certificate bytes (DER or PEM) into a dictionary of fields ready to be
+formatted for the user.
+"""
+
+from datetime import datetime, timezone
+from cryptography import x509
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import dsa, ec, rsa
+
+
+class CertificateLoadError(ValueError): ...
+
+
+def to_pem(cert: x509.Certificate) -> bytes:
+    return cert.public_bytes(serialization.Encoding.PEM)
+
+
+def _name_matches(pattern: str, hostname: str) -> bool:
+    pattern = pattern.lower()
+    hostname = hostname.lower()
+    if pattern.startswith("*."):
+        head, _, tail = hostname.partition(".")
+        return bool(head) and tail == pattern[2:]
+
+    return pattern == hostname
+
+
+def hostname_matches(info: dict, hostname: str) -> bool:
+    """Return True if hostname is covered by the certificate's SAN names."""
+
+    return any(_name_matches(name, hostname) for name in info["san"])
+
+
+def format_fingerprint(cert: x509.Certificate) -> str:
+    return ":".join(f"{b:02X}" for b in cert.fingerprint(hashes.SHA256()))
+
+
+def _weak_key(public_key) -> str | None:
+    """Return a warning if the key is below safe size for its type.
+
+    RSA/DSA need >= 2048 bit; EC needs >= 256 bit. Other key types
+    (e.g. Ed25519) are always considered strong.
+    """
+    if isinstance(public_key, ec.EllipticCurvePublicKey):
+        if public_key.key_size < 256:
+            return f"Weak EC key ({public_key.key_size} bit)"
+    elif isinstance(public_key, (rsa.RSAPublicKey, dsa.DSAPublicKey)):
+        if public_key.key_size < 2048:
+            return f"Weak key ({public_key.key_size} bit)"
+    return None
+
+
+def load_certificate(data: bytes) -> x509.Certificate:
+    """Load a certificate from DER or PEM bytes."""
+
+    if not data:
+        raise CertificateLoadError("There is no certificate to load.")
+    try:
+        return x509.load_der_x509_certificate(data)
+    except ValueError:
+        return x509.load_pem_x509_certificate(data)
+
+
+def analyze(cert: x509.Certificate) -> dict:
+    """Extract the relevant information from the certificate as a dict."""
+
+    now = datetime.now(timezone.utc)
+    days_to_expire = (cert.not_valid_after_utc - now).days
+    try:
+        ext = cert.extensions.get_extension_for_class(x509.SubjectAlternativeName)
+        san = ext.value.get_values_for_type(x509.DNSName)
+    except x509.ExtensionNotFound:
+        san = []
+
+    try:
+        ext = cert.extensions.get_extension_for_class(x509.BasicConstraints)
+        is_ca = ext.value.ca
+    except x509.ExtensionNotFound:
+        is_ca = False
+
+    weak = []
+    reason = _weak_key(cert.public_key())
+    if reason:
+        weak.append(reason)
+    sig = cert.signature_algorithm_oid._name.lower()
+    if "sha1" in sig or "md5" in sig:
+        weak.append(f"Weak signature ({cert.signature_algorithm_oid._name})")
+
+    return {
+        "subject": cert.subject.rfc4514_string(),
+        "issuer": cert.issuer.rfc4514_string(),
+        "not_valid_before": cert.not_valid_before_utc,
+        "not_valid_after": cert.not_valid_after_utc,
+        "serial_number": cert.serial_number,
+        "signature_algorithm": cert.signature_algorithm_oid._name,
+        "days_to_expire": days_to_expire,
+        "key_size": cert.public_key().key_size,
+        "san": san,
+        "fingerprint_sha256": format_fingerprint(cert),
+        "is_ca": is_ca,
+        "self_signed": cert.subject == cert.issuer,
+        "weak": weak,
+    }
+
+
+def certificate_status(info: dict, warn_days: int = 30) -> str:
+    """Return the validity status derived from the analyzed data.
+
+    One of: 'INVALID DATES', 'EXPIRED', 'EXPIRING', 'VALID'.
+    'EXPIRING' means the certificate is still valid but expires within
+    ``warn_days`` days.
+    """
+
+    if info["not_valid_before"] > info["not_valid_after"]:
+        return "INVALID DATES"
+    days = info["days_to_expire"]
+    if days < 0:
+        return "EXPIRED"
+    if days < warn_days:
+        return "EXPIRING"
+    return "VALID"