certmonitor 0.1.0__py3-none-any.whl

certmonitor/__init__.py

@@ -0,0 +1,3 @@
+from certmonitor.core import CertMonitor
+
+__all__ = ["CertMonitor"]

certmonitor/cipher_algorithms.py

@@ -0,0 +1,135 @@
+# cipher_algorithms.py
+
+from functools import lru_cache
+import re
+
+"""
+This module defines:
+- Patterns for parsing cipher suites into their components.
+- Centrally managed allowed TLS versions and cipher suites.
+- Functions to update these allowed lists at runtime.
+
+By using allowed lists, the validator fails if the target negotiates
+a version or cipher suite not present in these lists.
+
+Users and maintainers can:
+1. View current algorithms using `list_algorithms()`.
+2. Update cipher parsing patterns using `update_algorithms()`.
+3. Update allowed TLS versions and cipher suites using `update_allowed_lists()`.
+
+Default values are based on commonly accepted industry standards.
+"""
+
+ALL_ALGORITHMS = {
+    "encryption": {
+        "AES": r"AES",
+        "CHACHA20": r"CHACHA20",
+        "3DES": r"3DES|DES-EDE3",
+        "CAMELLIA": r"CAMELLIA",
+        "ARIA": r"ARIA",
+        "SEED": r"SEED",
+        "SM4": r"SM4",
+        "IDEA": r"IDEA",
+        "RC4": r"RC4",
+    },
+    "key_exchange": {
+        "ECDHE": r"ECDHE|EECDH",
+        "DHE": r"DHE|EDH",
+        "ECDH": r"ECDH",
+        "DH": r"DH",
+        "RSA": r"RSA",
+        "PSK": r"PSK",
+        "SRP": r"SRP",
+        "GOST": r"GOST",
+        "ECCPWD": r"ECCPWD",
+        "SM2": r"SM2",
+    },
+    "mac": {
+        "SHA384": r"SHA384",
+        "SHA256": r"SHA256",
+        "SHA224": r"SHA224",
+        "SHA": r"SHA1?",  # Matches 'SHA' or 'SHA1'
+        "MD5": r"MD5",
+        "POLY1305": r"POLY1305",
+        "AEAD": r"GCM|CCM|OCB",
+        "GOST": r"GOST28147|GOST34\.11",
+        "SM3": r"SM3",
+    },
+}
+
+# Compile all regex patterns
+for category in ALL_ALGORITHMS.values():
+    for alg, pattern in category.items():
+        category[alg] = re.compile(pattern)
+
+
+@lru_cache(maxsize=128)
+def parse_cipher_suite(cipher_suite):
+    """
+    Parse a cipher suite string to identify encryption, key exchange, and MAC algorithms.
+    """
+    result = {"encryption": "Unknown", "key_exchange": "Unknown", "mac": "Unknown"}
+
+    for category, algorithms in ALL_ALGORITHMS.items():
+        for alg, pattern in algorithms.items():
+            if pattern.search(cipher_suite):
+                result[category] = alg
+                break
+
+    return result
+
+
+def list_algorithms():
+    """
+    List all known algorithms by category.
+    """
+    alg_list = {}
+    for category, alg_dict in ALL_ALGORITHMS.items():
+        alg_list[category] = list(alg_dict.keys())
+    return alg_list
+
+
+def update_algorithms(custom_algorithms):
+    """
+    Update the ALL_ALGORITHMS dictionary with user-provided custom algorithms.
+    """
+    global ALL_ALGORITHMS
+
+    for category, algs in custom_algorithms.items():
+        if category not in ALL_ALGORITHMS:
+            ALL_ALGORITHMS[category] = {}
+        for alg_name, pattern in algs.items():
+            ALL_ALGORITHMS[category][alg_name] = re.compile(pattern)
+
+    parse_cipher_suite.cache_clear()
+
+
+# Default allowed lists for TLS versions and cipher suites.
+# If a negotiated version or cipher is not in these sets, validation fails.
+ALLOWED_TLS_VERSIONS = {"TLSv1.2", "TLSv1.3"}
+
+ALLOWED_CIPHER_SUITES = {
+    # Following industry guidelines (e.g., Mozilla's "Intermediate" TLS configuration)
+    "ECDHE-ECDSA-AES128-GCM-SHA256",
+    "ECDHE-RSA-AES128-GCM-SHA256",
+    "ECDHE-ECDSA-CHACHA20-POLY1305",
+    "ECDHE-RSA-CHACHA20-POLY1305",
+    "ECDHE-ECDSA-AES256-GCM-SHA384",
+    "ECDHE-RSA-AES256-GCM-SHA384",
+}
+
+
+def update_allowed_lists(custom_tls_versions=None, custom_ciphers=None):
+    """
+    Update the sets of allowed TLS versions and cipher suites.
+
+    Args:
+        custom_tls_versions (set): A set of allowed TLS versions. E.g., {"TLSv1.2", "TLSv1.3"}
+        custom_ciphers (set): A set of allowed cipher suites. E.g., {"ECDHE-RSA-AES128-GCM-SHA256"}
+    """
+    global ALLOWED_TLS_VERSIONS, ALLOWED_CIPHER_SUITES
+    if custom_tls_versions is not None:
+        ALLOWED_TLS_VERSIONS = custom_tls_versions
+
+    if custom_ciphers is not None:
+        ALLOWED_CIPHER_SUITES = custom_ciphers

certmonitor/config.py

@@ -0,0 +1,14 @@
+# config.py
+
+import os
+
+# Default validators if not set in environment
+DEFAULT_VALIDATORS = ["expiration", "hostname", "root_certificate"]
+
+# Read from environment variable, fall back to default if not set
+ENABLED_VALIDATORS = (
+    os.environ.get("ENABLED_VALIDATORS", "").split(",") or DEFAULT_VALIDATORS
+)
+
+# Remove any empty strings that might result from splitting
+ENABLED_VALIDATORS = [v.strip() for v in ENABLED_VALIDATORS if v.strip()]

certmonitor/core.py

@@ -0,0 +1,438 @@
+# core.py
+
+import ipaddress
+import logging
+import os
+import socket
+import ssl
+import tempfile
+from typing import Any, Dict, Optional
+
+import certinfo
+
+from certmonitor import config
+from certmonitor.cipher_algorithms import parse_cipher_suite
+from certmonitor.error_handlers import ErrorHandler
+from certmonitor.protocol_handlers.ssh_handler import SSHHandler
+from certmonitor.protocol_handlers.ssl_handler import SSLHandler
+from certmonitor.validators import VALIDATORS
+
+
+class CertMonitor:
+    """Class for monitoring and retrieving certificate details from a given host."""
+
+    def __init__(
+        self,
+        host: str,
+        port: int = 443,
+        enabled_validators: list = config.DEFAULT_VALIDATORS,
+    ):
+        """Initialize the CertMonitor with the specified host and port."""
+        self.host = host
+        self.port = port
+        self.is_ip = self._is_ip_address(host)
+        self.der = None
+        self.pem = None
+        self.cert_info = None
+        self.validators = VALIDATORS
+        self.enabled_validators = enabled_validators or config.ENABLED_VALIDATORS
+        self.error_handler = ErrorHandler()
+        self.handler = None
+        self.protocol = None
+        self.connected = False
+
+    def __enter__(self):
+        """Enter the runtime context related to this object."""
+        self.connect()
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        """Exit the runtime context related to this object."""
+        self.close()
+
+    def connect(self) -> Optional[Dict[str, Any]]:
+        """Establishes a connection to the host if not already connected."""
+        if self.connected:
+            logging.debug("Already connected, skipping connection attempt")
+            return None
+
+        self.protocol = self.detect_protocol()
+        if isinstance(self.protocol, dict) and "error" in self.protocol:
+            return self.protocol
+
+        if self.protocol == "ssl":
+            self.handler = SSLHandler(self.host, self.port, self.error_handler)
+        elif self.protocol == "ssh":
+            self.handler = SSHHandler(self.host, self.port, self.error_handler)
+        else:
+            return self.error_handler.handle_error(
+                "ProtocolError",
+                f"Unsupported protocol: {self.protocol}",
+                self.host,
+                self.port,
+            )
+
+        connection_result = self.handler.connect()
+        if connection_result is not None:  # This means there was an error
+            return connection_result
+
+        self.connected = True
+        logging.debug(f"Successfully connected to {self.host}:{self.port}")
+        return None
+
+    def close(self):
+        """Close the connection and reset the handler."""
+        if self.handler:
+            self.handler.close()
+        self.handler = None
+
+    def detect_protocol(self):
+        """Detect the protocol used by the host."""
+        try:
+            with socket.create_connection((self.host, self.port), timeout=10) as sock:
+                sock.setblocking(False)
+                try:
+                    data = sock.recv(4, socket.MSG_PEEK)
+                    if data.startswith(b"SSH-"):
+                        return "ssh"
+                    elif data[0] in [22, 128, 160]:  # Common first bytes for SSL/TLS
+                        return "ssl"
+                    else:
+                        return self.error_handler.handle_error(
+                            "ProtocolDetectionError",
+                            f"Unable to determine protocol. First bytes: {data.hex()}",
+                            self.host,
+                            self.port,
+                        )
+                except socket.error:
+                    # If no data is received, assume it's SSL
+                    return "ssl"
+                finally:
+                    sock.setblocking(True)
+        except Exception as e:
+            return self.error_handler.handle_error(
+                "ConnectionError", str(e), self.host, self.port
+            )
+
+    def _ensure_connection(self):
+        """Ensures that a valid connection is established."""
+        if not self.connected:
+            connect_result = self.connect()
+            if connect_result is not None:  # This means there was an error
+                raise ConnectionError(
+                    f"Failed to establish connection: {connect_result}"
+                )
+        else:
+            try:
+                self.handler.check_connection()
+            except ConnectionError:
+                logging.warning("Connection lost, attempting to reconnect")
+                self.connected = False
+                connect_result = self.connect()
+                if connect_result is not None:  # This means there was an error
+                    raise ConnectionError(
+                        f"Failed to re-establish connection: {connect_result}"
+                    )
+
+    def _is_ip_address(self, host: str) -> bool:
+        """Check if the provided host is an IP address."""
+        try:
+            ipaddress.ip_address(host)
+            return True
+        except ValueError:
+            return False
+
+    def _fetch_raw_cert(self) -> Dict[str, Any]:
+        """Fetches the raw certificate from the connected host."""
+        self._ensure_connection()
+        cert_data = self.handler.fetch_raw_cert()
+
+        if isinstance(cert_data, dict) and "error" in cert_data:
+            return cert_data
+
+        cert_info = cert_data["cert_info"]
+        self.der = cert_data["der"]
+        self.pem = cert_data["pem"]
+        self.public_key_info = {}
+
+        if not cert_info:
+            # If getpeercert() returns an empty dict, we'll parse the cert ourselves
+            cert_data["cert_info"] = self._parse_pem_cert(self.pem)
+
+        if self.der:
+            try:
+                # parse_public_key_info expects DER bytes and returns e.g.
+                # {"algorithm": "rsaEncryption", "size": 2048, "curve": None}
+                pubkey = certinfo.parse_public_key_info(self.der)
+                cert_data["public_key_info"] = pubkey
+                self.public_key_info = pubkey
+            except Exception as e:
+                logging.error(f"Unable to parse public key info: {e}")
+                # If you want, store a partial or error object here instead
+                cert_data["public_key_info"] = {
+                    "error": f"Failed to parse public key info: {e}"
+                }
+        else:
+            # If there's no DER, we can't parse the public key
+            cert_data["public_key_info"] = {"error": "DER bytes not available"}
+
+        self.cert_data = cert_data
+        return cert_data
+
+    def _fetch_raw_cipher(self) -> tuple:
+        """Fetch the raw cipher information."""
+        self._ensure_connection()
+        if self.protocol != "ssl":
+            return self.error_handler.handle_error(
+                "ProtocolError",
+                "Cipher information is only available for SSL/TLS connections",
+                self.host,
+                self.port,
+            )
+        return self.handler.fetch_raw_cipher()
+
+    def _parse_pem_cert(self, pem_cert: str) -> dict:
+        """Parse a PEM formatted certificate to extract relevant details."""
+        with tempfile.NamedTemporaryFile(delete=False, mode="w") as temp_file:
+            temp_file.write(pem_cert)
+            temp_file.flush()
+            temp_file_path = temp_file.name
+
+        try:
+            cert_details = ssl._ssl._test_decode_cert(temp_file_path)
+        finally:
+            os.remove(temp_file_path)
+
+        return cert_details
+
+    def _to_structured_dict(self, data) -> dict:
+        """Convert the certificate data into a structured dictionary format.
+
+        Args:
+            data (dict): The certificate data.
+
+        Returns:
+            dict: A dictionary containing the structured certificate data.
+        """
+
+        def _handle_duplicate_keys(data):
+            result = {}
+            for key, value in data:
+                if key in result:
+                    if not isinstance(result[key], list):
+                        result[key] = [result[key]]
+                    result[key].append(self._to_structured_dict(value))
+                else:
+                    result[key] = self._to_structured_dict(value)
+            return result
+
+        if isinstance(data, (tuple, list)):
+            if all(isinstance(item, tuple) and len(item) == 2 for item in data):
+                return _handle_duplicate_keys(data)
+            return [self._to_structured_dict(item) for item in data]
+        elif isinstance(data, dict):
+            result = {}
+            for key, value in data.items():
+                if key in ["subject", "issuer"]:
+                    result[key] = _handle_duplicate_keys(
+                        [item for sublist in value for item in sublist]
+                    )
+                else:
+                    result[key] = self._to_structured_dict(value)
+            return result
+        else:
+            return data
+
+    def get_cert_info(self) -> Dict[str, Any]:
+        """Retrieves and structures the certificate details."""
+        if not self.cert_info:
+            try:
+                self._ensure_connection()
+                cert = self._fetch_raw_cert()
+
+                if isinstance(cert, dict) and "error" in cert:
+                    logging.error(f"Error in fetching raw certificate: {cert}")
+                    return cert
+
+                self.cert_data["cert_info"] = self._to_structured_dict(
+                    cert["cert_info"]
+                )
+                self.cert_info = self.cert_data["cert_info"]
+                logging.debug("Certificate info retrieved and structured")
+            except Exception as e:
+                logging.exception("Error while getting certificate info")
+                return self.error_handler.handle_error(
+                    "UnknownError", str(e), self.host, self.port
+                )
+
+        return self.cert_info
+
+    def get_raw_der(self) -> bytes:
+        """Return the raw DER format of the certificate."""
+        if self.protocol != "ssl":
+            return self.error_handler.handle_error(
+                "ProtocolError",
+                "DER format is only available for SSL/TLS connections",
+                self.host,
+                self.port,
+            )
+
+        self._ensure_connection()
+
+        if self.der is None:
+            cert_data = self.handler.fetch_raw_cert()
+            self.der = cert_data.get("der")
+
+        return self.der
+
+    def get_raw_pem(self) -> str:
+        """Return the raw PEM format of the certificate."""
+        if self.protocol != "ssl":
+            return self.error_handler.handle_error(
+                "ProtocolError",
+                "PEM format is only available for SSL/TLS connections",
+                self.host,
+                self.port,
+            )
+
+        self._ensure_connection()
+
+        if self.pem is None:
+            cert_data = self.handler.fetch_raw_cert()
+            self.pem = cert_data.get("pem")
+
+        return self.pem
+
+    def get_cipher_info(self) -> dict:
+        """Retrieve and structure the cipher information of the SSL/TLS connection."""
+        raw_cipher = self._fetch_raw_cipher()
+
+        # Check if raw_cipher is an error response
+        if isinstance(raw_cipher, dict) and "error" in raw_cipher:
+            return raw_cipher
+
+        # If raw_cipher is not an error, it should be a tuple of 3 elements
+        if not isinstance(raw_cipher, tuple) or len(raw_cipher) != 3:
+            return self.error_handler.handle_error(
+                "CipherInfoError", "Unexpected cipher info format", self.host, self.port
+            )
+
+        cipher_suite, protocol_version, key_bit_length = raw_cipher
+        parsed_cipher = parse_cipher_suite(cipher_suite)
+
+        result = {
+            "cipher_suite": {
+                "name": cipher_suite,
+                "encryption_algorithm": parsed_cipher["encryption"],
+                "message_authentication_code": parsed_cipher["mac"],
+            },
+            "protocol_version": protocol_version,
+            "key_bit_length": key_bit_length,
+        }
+
+        if protocol_version == "TLSv1.3":
+            result["cipher_suite"]["key_exchange_algorithm"] = (
+                "Not applicable (TLS 1.3 uses ephemeral key exchange by default)"
+            )
+        else:
+            result["cipher_suite"]["key_exchange_algorithm"] = parsed_cipher[
+                "key_exchange"
+            ]
+
+        return result
+
+    def validate(self, validator_args=None) -> dict:
+        """
+        Validates the target host by running all enabled validators.
+
+        This method:
+        1. Checks if all requested validators are implemented.
+        2. Separates validators into cert-based and cipher-based groups.
+        3. Fetches cert_info and cipher_info as needed.
+        4. Runs each validator with the appropriate arguments.
+        5. Returns a dictionary of validation results.
+
+        Args:
+            validator_args (dict, optional): Additional arguments for specific validators.
+                Example:
+                {
+                    "subject_alt_names": ["example.com", "test.com"]
+                }
+
+        Returns:
+            dict: A dictionary keyed by validator name, each value being the result of that validator.
+
+        Example:
+            results = monitor.validate()
+            print(results["expiration"])      # Output for expiration validator
+            print(results["weak_cipher"])     # Output for weak cipher validator
+        """
+        results = {}
+
+        # Check for unknown validators
+        for requested_validator in self.enabled_validators:
+            if requested_validator not in self.validators:
+                results[requested_validator] = {
+                    "is_valid": False,
+                    "reason": f"Validator '{requested_validator}' is not implemented.",
+                }
+
+        cert_validators = [
+            validator
+            for name, validator in self.validators.items()
+            if name in self.enabled_validators
+            and getattr(validator, "validator_type", "cert") == "cert"
+            and name not in results  # exclude already marked unknown validators
+        ]
+
+        cipher_validators = [
+            validator
+            for name, validator in self.validators.items()
+            if name in self.enabled_validators
+            and getattr(validator, "validator_type", "cert") == "cipher"
+            and name not in results
+        ]
+
+        # Certificate-based validations
+        if cert_validators:
+            cert_data = getattr(self, "cert_data", None)
+            if not cert_data or (isinstance(cert_data, dict) and "error" in cert_data):
+                error_reason = (
+                    cert_data["error"]
+                    if isinstance(cert_data, dict) and "error" in cert_data
+                    else "Certificate data is missing due to a connection or retrieval error."
+                )
+                for validator in cert_validators:
+                    results[validator.name] = {
+                        "is_valid": False,
+                        "reason": f"Certificate-based validation could not be performed: {error_reason}",
+                    }
+            else:
+                for validator in cert_validators:
+                    args = [cert_data, self.host, self.port]
+                    # Pass additional arguments if any
+                    if validator_args and validator.name in validator_args:
+                        if validator.name == "subject_alt_names":
+                            args.append(validator_args[validator.name])
+                        else:
+                            args.extend(validator_args[validator.name])
+
+                    results[validator.name] = validator.validate(*args)
+
+        # Cipher-based validations
+        if cipher_validators:
+            cipher_info = self.get_cipher_info()
+            if isinstance(cipher_info, dict) and "error" in cipher_info:
+                logging.error(
+                    "Skipping cipher-based validations due to cipher info retrieval error."
+                )
+            else:
+                for validator in cipher_validators:
+                    args = [cipher_info, self.host, self.port]
+                    # Pass additional arguments if any
+                    if validator_args and validator.name in validator_args:
+                        args.extend(validator_args[validator.name])
+
+                    results[validator.name] = validator.validate(*args)
+
+        return results

certmonitor/error_handlers.py

@@ -0,0 +1,28 @@
+# error_handlers.py
+
+
+class ErrorHandler:
+    """
+    Class for handling errors in a flexible manner.
+    """
+
+    @staticmethod
+    def handle_error(error_type: str, message: str, host: str, port: int) -> dict:
+        """
+        Handles errors encountered during certificate retrieval.
+
+        Args:
+            error_type (str): The type of error.
+            message (str): The error message.
+            host (str): The host where the error occurred.
+            port (int): The port where the error occurred.
+
+        Returns:
+            dict: A dictionary containing the error details.
+        """
+        return {
+            "error": error_type,
+            "message": message,
+            "host": host,
+            "port": port,
+        }

certmonitor/protocol_handlers/base.py

@@ -0,0 +1,24 @@
+# protocol_handlers/base.py
+
+from abc import ABC, abstractmethod
+
+
+class BaseProtocolHandler(ABC):
+    def __init__(self, host, port, error_handler):
+        self.host = host
+        self.port = port
+        self.socket = None
+        self.secure_socket = None
+        self.error_handler = error_handler
+
+    @abstractmethod
+    def connect(self):
+        pass
+
+    @abstractmethod
+    def fetch_raw_cert(self):
+        pass
+
+    @abstractmethod
+    def close(self):
+        pass

certmonitor/protocol_handlers/ssh_handler.py

@@ -0,0 +1,51 @@
+# protocol_handlers/ssh_handler.py
+
+import re
+import socket
+
+from .base import BaseProtocolHandler
+
+
+class SSHHandler(BaseProtocolHandler):
+    def connect(self):
+        try:
+            self.socket = socket.create_connection((self.host, self.port), timeout=10)
+        except socket.error as e:
+            return self.error_handler.handle_error(
+                "SocketError", str(e), self.host, self.port
+            )
+        except Exception as e:
+            return self.error_handler.handle_error(
+                "UnknownError", str(e), self.host, self.port
+            )
+
+    def fetch_raw_cert(self):
+        try:
+            ssh_banner = self.socket.recv(1024).decode("ascii", errors="ignore").strip()
+            match = re.match(r"^SSH-(\d+\.\d+)-(.*)$", ssh_banner)
+            if match:
+                return {
+                    "protocol": "ssh",
+                    "ssh_version_string": ssh_banner,
+                    "protocol_version": match.group(1),
+                    "software_version": match.group(2),
+                }
+            else:
+                return self.error_handler.handle_error(
+                    "SSHError", "Invalid SSH banner", self.host, self.port
+                )
+        except Exception as e:
+            return self.error_handler.handle_error(
+                "SSHError", str(e), self.host, self.port
+            )
+
+    def close(self):
+        if self.socket:
+            self.socket.close()
+
+    def check_connection(self):
+        try:
+            self.socket.getpeername()
+            return True
+        except socket.error:
+            return False