nitlsconfig 1.0.0__py3-none-any.whl

nitlsconfig/__init__.py

@@ -0,0 +1,99 @@
+"""Python package to read settings from nitlsconfig and build NI gRPC Device channels from them.
+
+The gRPC names below are resolved lazily: importing this package never imports
+grpcio, so a caller that only reads NI TLS configuration does not pay for a
+binary dependency it will not use. See the project README for install options.
+"""
+
+from importlib.metadata import version
+from importlib.util import find_spec
+from typing import TYPE_CHECKING, Any
+
+from nitlsconfig.audit import audit_session_connect
+from nitlsconfig.cli import (
+    CertificateLocation,
+    ClientCertMode,
+    ClientConfig,
+    ClientServerMode,
+    LocationScheme,
+    ServerCertMode,
+    ServerClientMode,
+    ServerConfig,
+    TrustedCertificateData,
+    KnownServerData,
+)
+from nitlsconfig.errors import (
+    CommandFailedError,
+    CommandTimeoutError,
+    ExecutableNotFoundError,
+    InvalidOutputError,
+    NitlsconfigCliError,
+    NitlsconfigError,
+    TlsConfigurationError,
+    get_tls_connection_error_elaboration,
+)
+
+if TYPE_CHECKING:
+    # Imported eagerly for type checkers and editors, which do not run __getattr__.
+    from nitlsconfig.grpc_channel import (
+        RetryPolicy,
+        create_grpc_device_channel,
+    )
+
+__version__ = version("nitlsconfig")
+
+# Names re-exported from nitlsconfig.grpc_channel, which requires grpcio.
+# A plain list literal, because pyright only tracks __all__ through a small set
+# of literal forms; anything computed makes it give up on the export list.
+_GRPC_EXPORTS = [
+    "RetryPolicy",
+    "create_grpc_device_channel",
+]
+
+__all__ = [
+    "__version__",
+    "audit_session_connect",
+    "CertificateLocation",
+    "ClientCertMode",
+    "ClientConfig",
+    "ClientServerMode",
+    "LocationScheme",
+    "ServerCertMode",
+    "ServerClientMode",
+    "ServerConfig",
+    "NitlsconfigError",
+    "NitlsconfigCliError",
+    "ExecutableNotFoundError",
+    "CommandFailedError",
+    "CommandTimeoutError",
+    "InvalidOutputError",
+    "TlsConfigurationError",
+    "TrustedCertificateData",
+    "KnownServerData",
+    "get_tls_connection_error_elaboration",
+]
+
+# The gRPC names are public API, but only on an install that can supply them.
+# Listing them unconditionally would make `from nitlsconfig import *` raise
+# ImportError without the grpc extra, since star-import resolves every name in
+# __all__. find_spec only locates grpcio; it does not import it, so the lazy
+# __getattr__ below still decides when grpcio is actually loaded.
+if find_spec("grpc") is not None:
+    # pyright only tracks __all__ through inline literals, so it cannot follow
+    # this and warns that the export list may be incomplete. The TYPE_CHECKING
+    # block above already declares these names for static consumers.
+    __all__ += _GRPC_EXPORTS  # pyright: ignore[reportUnsupportedDunderAll]
+
+
+def __getattr__(name: str) -> Any:
+    """Resolve gRPC exports on first use, so importing this package does not need grpcio."""
+    if name in _GRPC_EXPORTS:
+        try:
+            from nitlsconfig import grpc_channel
+        except ImportError as exc:  # pragma: no cover - requires an install without the extra
+            raise ImportError(
+                f"nitlsconfig.{name} requires grpcio, which is not installed. "
+                "Install it with: pip install nitlsconfig[grpc]"
+            ) from exc
+        return getattr(grpc_channel, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

nitlsconfig/_service.py

@@ -0,0 +1,12 @@
+"""The NI TLS services this package builds transports for.
+
+Only the NI gRPC Device Server is supported today. Anything else can still be
+read through :class:`~nitlsconfig.cli.ClientConfig`, but has no channel factory.
+"""
+
+from __future__ import annotations
+
+# The NI TLS registered service name for the NI gRPC Device Server: the file stem of
+# ni-grpc-device.client.caps.yml, the Event Log source, and the record tag are all this
+# one name, so records can be tied back to the configuration they describe.
+SERVICE_NAME = "ni-grpc-device"

nitlsconfig/audit.py

@@ -0,0 +1,279 @@
+"""Audit logging for NI TLS client transports.
+
+Records the security posture of transports this package creates, and the outcome of a
+driver's gRPC session initialize RPC, to the platform audit log: the Windows Event Log
+on Windows, syslog on Linux.
+
+Transport posture is recorded by the channel factory. The session connect outcome
+cannot be, because a gRPC channel connects lazily, so the driver API layer that issues
+the initialize RPC calls :func:`audit_session_connect` itself.
+"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+import sys
+import threading
+from enum import Enum
+from typing import Any
+
+from nitlsconfig._service import SERVICE_NAME
+from nitlsconfig.channel_tag import get_channel_target
+
+# A record is emitted only for something that attests to the security posture of a
+# connection that actually existed. Configuration errors are not audited, because no
+# channel is created and nothing is transmitted; TlsConfigurationError carries that
+# detail to the caller directly. We also do not record *which* server we authenticated,
+# for example its certificate subject: gRPC's Python client API takes certificates as
+# input only, offering no handshake callback and no way to read the server's certificate
+# afterward.
+#
+# Auditing covers the NI gRPC Device Server only, so the service name is fixed
+# package-wide rather than accepted from callers. Should another service ever need audit
+# records, this module grows a service parameter again at that point.
+#
+# Records report what this package observed, assuming the hosting process is not hostile.
+# Nothing here can defend against code in the same process, which can call the standard
+# library logger directly. Untrusted *values* reaching a record are bounded and escaped
+# below, because those do cross a trust boundary.
+
+_ROLE = "Client"
+# This source uses mscoree.dll as its EventMessageFile. Event ID 1000 selects its
+# generic literal-message template, which renders the complete first insertion
+# string as the event description. Other IDs can produce Event Viewer's
+# "message was not found in the message table" fallback instead.
+_WINDOWS_EVENT_ID = 1000
+
+# Match spdlog's Windows Event Log categories, which use its level enum values:
+# trace=0, debug=1, info=2, warn=3, err=4, critical=5.
+_WINDOWS_EVENT_CATEGORIES = {
+    logging.DEBUG: 1,
+    logging.INFO: 2,
+    logging.WARNING: 3,
+    logging.ERROR: 4,
+    logging.CRITICAL: 5,
+}
+
+
+class _TransportSecurity(Enum):
+    """Security posture of a created transport."""
+
+    Unencrypted = "unencrypted"
+    ServerAuthenticatedTls = "server_authenticated_tls"
+    MutualTls = "mutual_tls"
+
+
+# Whether the audit logger has had its logging handler attached. The lock guards
+# the check-then-set below: without it, threads creating channels can each attach
+# a logging handler and double every record.
+_logging_handler_lock = threading.Lock()
+_logging_handler_attached = False
+
+_MAX_FIELD_LENGTH = 256
+
+# The quote is here because messages wrap every field in single quotes; without it
+# a value can close the quote and append text that reads as part of our message.
+_ESCAPES = {"\\": "\\\\", "'": "\\'", "\r": "\\r", "\n": "\\n"}
+
+
+class _WindowsEventLogHandler(logging.Handler):
+    """Write to a pre-registered Windows Event Log source."""
+
+    def __init__(self, source_name: str) -> None:
+        super().__init__()
+        self._source_name = source_name
+        self._event_log: Any = importlib.import_module("win32evtlog")
+        self._user_sid = self._get_current_user_sid()
+        self._event_types = {
+            logging.DEBUG: self._event_log.EVENTLOG_INFORMATION_TYPE,
+            logging.INFO: self._event_log.EVENTLOG_INFORMATION_TYPE,
+            logging.WARNING: self._event_log.EVENTLOG_WARNING_TYPE,
+            logging.ERROR: self._event_log.EVENTLOG_ERROR_TYPE,
+            logging.CRITICAL: self._event_log.EVENTLOG_ERROR_TYPE,
+        }
+
+    @staticmethod
+    def _get_current_user_sid() -> Any:
+        """Return the current process token's user SID, or None if unavailable."""
+        try:
+            win32api = importlib.import_module("win32api")
+            win32con = importlib.import_module("win32con")
+            win32security = importlib.import_module("win32security")
+            token = win32security.OpenProcessToken(
+                win32api.GetCurrentProcess(), win32con.TOKEN_QUERY
+            )
+            try:
+                user_sid, _ = win32security.GetTokenInformation(token, win32security.TokenUser)
+                return user_sid
+            finally:
+                token.Close()
+        except Exception:
+            # A missing SID must not prevent the audit event itself from being recorded.
+            return None
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """Emit one record without creating or changing Event Log registry keys."""
+        event_source = None
+        try:
+            event_source = self._event_log.RegisterEventSource(None, self._source_name)
+            event_type = self._event_types.get(record.levelno, self._event_log.EVENTLOG_ERROR_TYPE)
+            event_category = _WINDOWS_EVENT_CATEGORIES.get(
+                record.levelno,
+                4,  # Unknown/custom Python levels default to spdlog's error category.
+            )
+            self._event_log.ReportEvent(
+                event_source,
+                event_type,
+                event_category,
+                _WINDOWS_EVENT_ID,
+                self._user_sid,
+                [self.format(record)],
+                None,
+            )
+        finally:
+            if event_source is not None:
+                self._event_log.DeregisterEventSource(event_source)
+
+
+def _audit_field(value: object) -> str:
+    """Return a bounded audit field with record-breaking characters escaped.
+
+    Escaping runs before the bound, so the returned length is the real limit;
+    escaping afterwards could double it.
+
+    Remaining C0 controls and DEL become hex escapes: ESC would otherwise emit
+    terminal control sequences when a syslog file is read, and NUL can truncate
+    the record as it crosses into the platform logging API.
+    """
+    escaped = "".join(
+        _ESCAPES[ch] if ch in _ESCAPES else (ch if " " <= ch != "\x7f" else f"\\x{ord(ch):02x}")
+        for ch in str(value)
+    )
+    if len(escaped) <= _MAX_FIELD_LENGTH:
+        return escaped
+
+    truncated = escaped[: _MAX_FIELD_LENGTH - 3]
+    # Cutting mid-escape would leave a trailing backslash that escapes the quote
+    # the message puts after this field.
+    if (len(truncated) - len(truncated.rstrip("\\"))) % 2:
+        truncated = truncated[:-1]
+    return truncated + "..."
+
+
+def _make_logging_handler() -> logging.Handler:
+    """Create the platform audit logging handler.
+
+    Windows uses the Windows Event Log and Linux uses syslog. Audit logging is
+    intentionally disabled on every other platform.
+
+    Falls back to a null logging handler when the platform log is unreachable.
+    That keeps audit records out of stderr, which ``logging`` would otherwise
+    fall back to for a logger that has no logging handler of its own.
+    """
+    try:
+        # "win32" is the value on every Windows build, 64-bit included; there is no "win64".
+        if sys.platform == "win32":
+            return _WindowsEventLogHandler(SERVICE_NAME)
+
+        if sys.platform.startswith("linux"):
+            from logging.handlers import SysLogHandler
+
+            return SysLogHandler(address="/dev/log", facility=SysLogHandler.LOG_DAEMON)
+
+        return logging.NullHandler()
+    except Exception:
+        # The platform logging handler failed, not `logging` itself; this diagnostic
+        # goes to the host application's ordinary logger, never to the audit channel.
+        logging.getLogger(__name__).warning(
+            "NI TLS audit logging is unavailable on this system; audit events "
+            "will not be recorded.",
+            exc_info=True,
+        )
+        return logging.NullHandler()
+
+
+def _get_audit_logger() -> logging.Logger:
+    """Return the audit logger, attaching its logging handler on first use.
+
+    Tracks setup ourselves rather than inspecting ``logger.handlers``, since
+    anything else in the process may attach logging handlers to the same logger
+    and would otherwise make an unconfigured logger look ready.
+    """
+    global _logging_handler_attached
+
+    logger = logging.getLogger(f"nitlsconfig.audit.{SERVICE_NAME}.{_ROLE}")
+
+    with _logging_handler_lock:
+        if not _logging_handler_attached:
+            logger.setLevel(logging.INFO)
+            # Audit records belong in the platform audit log, not in whatever
+            # logging the host application has configured on the root logger.
+            logger.propagate = False
+
+            handler = _make_logging_handler()
+            # Record pattern: [<service>][<role>] <message>
+            handler.setFormatter(logging.Formatter(f"[{SERVICE_NAME}][{_ROLE}] %(message)s"))
+            logger.addHandler(handler)
+            _logging_handler_attached = True
+
+    return logger
+
+
+def _audit_transport_posture(peer_host: str, security: _TransportSecurity) -> None:
+    """Record the security posture of a client transport.
+
+    Never raises: auditing must not disrupt transport creation.
+    """
+    try:
+        peer_host = _audit_field(peer_host)
+        message = f"Client transport for service '{SERVICE_NAME}'"
+        if peer_host:
+            message += f" to '{peer_host}'"
+
+        if security is _TransportSecurity.Unencrypted:
+            message += " is unencrypted (TLS disabled)."
+        elif security is _TransportSecurity.ServerAuthenticatedTls:
+            message += " uses one-way TLS. Not presenting a client certificate."
+        else:
+            message += " uses mutual TLS. Presenting a client certificate."
+
+        logger = _get_audit_logger()
+        # Mutual TLS is the secure baseline; weaker postures are auditable warnings.
+        if security is _TransportSecurity.MutualTls:
+            logger.info(message)
+        else:
+            logger.warning(message)
+    except Exception:
+        logging.getLogger(__name__).debug("Unable to record transport audit event.", exc_info=True)
+
+
+def audit_session_connect(driver_name: str, channel: object, connected: bool) -> None:
+    """Record the outcome of a driver's gRPC session initialize RPC. Never raises.
+
+    Call this from the API layer once the initialize RPC returns, passing the
+    driver's logging name (``NI-DCPower``, and so on).
+
+    Channels this package did not create are ignored, so drivers can call this
+    unconditionally. A caller who built their own channel never went through
+    NI TLS, so there is no transport posture record to pair the outcome with and
+    nothing to attest to.
+    """
+    try:
+        target = get_channel_target(channel)
+        if not target:
+            return
+
+        driver_name = _audit_field(driver_name)
+        target = _audit_field(target)
+
+        outcome = "connected" if connected else "failed to connect"
+        message = f"{driver_name} gRPC session {outcome} on hostname '{target}'"
+
+        logger = _get_audit_logger()
+        if connected:
+            logger.info(message)
+        else:
+            logger.error(message)
+    except Exception:
+        logging.getLogger(__name__).debug("Unable to record session audit event.", exc_info=True)

nitlsconfig/channel_tag.py

@@ -0,0 +1,39 @@
+"""Marks NI gRPC Device channels this package created.
+
+A caller holding only a channel cannot tell whether NI TLS had any part in
+building it, so the channel factory tags what it creates. Two features read the
+tag: audit records name the address, and connection-error elaboration speaks only
+for channels we built.
+
+The tag is advisory, not a security control. It says where a channel came from,
+never that a connection is trustworthy.
+"""
+
+from __future__ import annotations
+
+import logging
+
+_TARGET_ATTR = "_nitls_channel_target"
+
+
+def tag_channel_target(channel: object, target: str) -> None:
+    """Record on a channel the ``host:port`` it was created for. Never raises."""
+    try:
+        setattr(channel, _TARGET_ATTR, target)
+    except Exception:
+        logging.getLogger(__name__).debug(
+            "Unable to tag channel; it will go unaudited and will not elaborate on "
+            "connection errors.",
+            exc_info=True,
+        )
+
+
+def get_channel_target(channel: object) -> str:
+    """Return the ``host:port`` a channel was created for, or empty if we did not create it."""
+    target = getattr(channel, _TARGET_ATTR, "")
+    return target if isinstance(target, str) else ""
+
+
+def is_nitls_channel(channel: object) -> bool:
+    """Return whether this package created the channel."""
+    return bool(get_channel_target(channel))