Refactor auditor to use pluggable storage backend, add AuditorLogStorageInterface and GPG‑based GPGAuditorLogStorage implementation, and update import path accordingly.

Author: Paweł Kędzia

llm_router_api/core/auditor.py

@@ -0,0 +1,81 @@
+"""
+Module providing a simple auditing mechanism for request logs.
+
+The :class:`AnyRequestAuditor` class accepts a standard :class:`logging.Logger`
+instance and forwards audit entries to a storage backend defined by
+``DEFAULT_AUDITOR_STORAGE_CLASS``.  The default implementation stores logs
+using GPG encryption via :class:`GPGAuditorLogStorage`.
+
+Typical usage::
+
+    logger = logging.getLogger(__name__)
+    auditor = AnyRequestAuditor(logger)
+    auditor.add_log({"audit_type": "request", "data": {...}})
+
+"""
+
+import logging
+
+from llm_router_api.core.auditor.log_storage.pgp import GPGAuditorLogStorage
+
+DEFAULT_AUDITOR_STORAGE_CLASS = GPGAuditorLogStorage
+
+
+class AnyRequestAuditor:
+    """Auditor for arbitrary request logs.
+
+    Parameters
+    ----------
+    logger : logging.Logger
+        Logger used to emit audit notifications. The logger should be
+        configured by the consuming application.
+
+    Attributes
+    ----------
+    logger : logging.Logger
+        The logger instance provided at construction.
+    _auditor_storage : GPGAuditorLogStorage
+        Instance of the storage backend used to persist audit logs.
+    """
+
+    def __init__(self, logger: logging.Logger) -> None:
+        """
+        Create a new :class:`AnyRequestAuditor`.
+
+        Parameters
+        ----------
+        logger : logging.Logger
+            The logger that will receive audit warnings.
+        """
+        self.logger = logger
+        self._auditor_storage = DEFAULT_AUDITOR_STORAGE_CLASS()
+
+    def add_log(self, log):
+        """
+        Record an audit log entry.
+
+        The ``log`` argument may be any JSON‑serialisable object – a ``dict``,
+        a list of ``dict`` objects, or any other structure that can be
+        serialized by the underlying storage implementation.
+
+        The function extracts the ``audit_type`` field from the log, emits a
+        warning‑level message via the configured logger, and delegates the
+        actual persistence to ``_auditor_storage.store_log``.
+
+        Parameters
+        ----------
+        log : dict or list
+            The audit record(s) to store. Must contain an ``"audit_type"``
+            key when ``log`` is a mapping.
+
+        Raises
+        ------
+        KeyError
+            If ``log`` is a mapping and does not contain the required
+            ``"audit_type"`` key.
+        """
+        audit_type = log["audit_type"]
+        self.logger.warning(
+            f"[AUDIT] ************ Added {audit_type} audit log! ************ "
+        )
+        self._auditor_storage.store_log(audit_log=log, audit_type=audit_type)

llm_router_api/core/auditor/__init__.py

@@ -0,0 +1,46 @@
+"""
+Abstract definition for audit‑log storage back‑ends.
+
+Any concrete implementation must inherit from
+:class:`AuditorLogStorageInterface` and provide a :meth:`store_log`
+method that persists the supplied audit record.  This contract allows
+different storage strategies (e.g., encrypted files, databases,
+cloud buckets) to be swapped transparently in the auditing subsystem.
+"""
+
+import abc
+
+
+class AuditorLogStorageInterface(abc.ABC):
+    """
+    Base class for audit‑log storage implementations.
+
+    Sub‑classes are required to implement :meth:`store_log`, which
+    receives a log entry and its associated ``audit_type``.  The
+    interface is deliberately minimal to keep storage back‑ends
+    lightweight and interchangeable.
+    """
+
+    @abc.abstractmethod
+    def store_log(self, audit_log, audit_type: str):
+        """
+        Persist an audit log entry.
+
+        Parameters
+        ----------
+        audit_log : Any
+            The audit record to store.  It can be any JSON‑serialisable
+            object (e.g., ``dict``, ``list``) depending on the concrete
+            storage implementation.
+
+        audit_type : str
+            A string categorising the log entry (e.g., ``"request"``,
+            ``"error"``).  Implementations may use this value to route
+            logs to different locations or apply specific handling.
+
+        Raises
+        ------
+        NotImplementedError
+            If a subclass does not provide an implementation.
+        """
+        raise NotImplementedError

llm_router_api/core/auditor/auditor.py

@@ -0,0 +1,115 @@
+"""
+Implementation of an audit‑log storage backend that encrypts logs using GPG.
+
+The :class:`GPGAuditorLogStorage` class conforms to the
+:class:`~llm_router_api.core.auditor.log_storage.log_storage_interface.AuditorLogStorageInterface`
+protocol.  It writes each log entry to a timestamped file inside
+``logs/auditor`` and encrypts the JSON payload with a public GPG key
+located in ``resources/keys``.  This ensures that audit data is stored
+at rest in a confidential, tamper‑evident format.
+
+Typical workflow
+----------------
+1. An instance of :class:`GPGAuditorLogStorage` is created – the public
+   key is imported automatically.
+2. The :meth:`store_log` method is called with a serialisable ``audit_log``
+   and an ``audit_type`` string.
+3. The log is JSON‑encoded, encrypted with the imported key, and written to
+   ``logs/auditor/<audit_type>__<timestamp>.audit``.
+"""
+
+import json
+import gnupg
+
+from pathlib import Path
+from datetime import datetime
+
+from llm_router_api.core.auditor.log_storage.log_storage_interface import (
+    AuditorLogStorageInterface,
+)
+
+
+class GPGAuditorLogStorage(AuditorLogStorageInterface):
+    """
+    GPG‑backed storage for audit logs.
+
+    The storage writes each log entry to a file under ``DEFAULT_AUDITOR_OUT_DIR``
+    and encrypts the content with the public key found at
+    ``AUDITOR_PUB_KEY_FILE``.  The key is imported once during initialisation.
+
+    Attributes
+    ----------
+    _gpg : gnupg.GPG
+        Configured GPG instance pointing at ``AUDITOR_PUB_KEY_DIR``.
+    _import_result : gnupg.ImportResult
+        Result of importing the public key; contains the fingerprint(s) used
+        for encryption.
+    """
+
+    # Base output directory for the auditor
+    DEFAULT_AUDITOR_OUT_DIR = Path("logs/auditor")
+    DEFAULT_AUDITOR_OUT_DIR.mkdir(parents=True, exist_ok=True)
+
+    AUDITOR_PUB_KEY_DIR = Path("resources/keys")
+    AUDITOR_PUB_KEY_FILE = AUDITOR_PUB_KEY_DIR / Path("llm-router-auditor-pub.asc")
+
+    def __init__(self):
+        """
+        Create a new GPG‑based audit log storage instance.
+
+        The constructor loads the public key from ``AUDITOR_PUB_KEY_FILE``.
+        If the key cannot be imported, a :class:`RuntimeError` is raised.
+
+        Raises
+        ------
+        RuntimeError
+            If the public key file is missing or contains no importable keys.
+        """
+
+        self._import_result = None
+        self._gpg = gnupg.GPG(gnupghome=str(self.AUDITOR_PUB_KEY_DIR))
+        self._gpg.encoding = "utf-8"
+
+        with self.AUDITOR_PUB_KEY_FILE.open("r", encoding="utf-8") as f:
+            self._import_result = self._gpg.import_keys(f.read())
+            if not self._import_result.count:
+                raise RuntimeError(
+                    f"Failed to import public key from {self.AUDITOR_PUB_KEY_FILE}"
+                )
+
+    def store_log(self, audit_log, audit_type: str):
+        """
+        Encrypt and persist an audit log entry.
+
+        Parameters
+        ----------
+        audit_log : Any
+            JSON‑serialisable object representing the audit record.
+        audit_type : str
+            Category of the log (e.g., ``"request"``, ``"error"``).  The value
+            is incorporated into the output filename.
+
+        The method creates a filename of the form
+        ``<audit_type>__<YYYYMMDD_HHMMSS.microseconds>.audit`` inside
+        ``DEFAULT_AUDITOR_OUT_DIR``.  The log is JSON‑encoded with indentation
+        for readability, encrypted using the previously imported public key,
+        and written in ASCII‑armored format.
+
+        Raises
+        ------
+        Exception
+            Propagates any exception raised by the underlying GPG encryption
+            or file I/O operations.
+        """
+        date_str = datetime.now().strftime("%Y%m%d_%H%M%S.%f")
+        out_file_name = f"{audit_type}__{date_str}.audit"
+        out_file_path = self.DEFAULT_AUDITOR_OUT_DIR / out_file_name
+        with open(out_file_path, "wt") as f:
+            audit_str = json.dumps(audit_log, indent=2, ensure_ascii=False)
+            encrypted_data = self._gpg.encrypt(
+                audit_str,
+                recipients=self._import_result.fingerprints,
+                always_trust=True,
+                armor=True,
+            )
+            f.write(str(encrypted_data))

llm_router_api/core/auditor/log_storage/__init__.py

@@ -52,7 +52,7 @@
     GUARDRAIL_WITH_AUDIT_RESPONSE,
 )
 
-from llm_router_api.core.auditor import AnyRequestAuditor
+from llm_router_api.core.auditor.auditor import AnyRequestAuditor
 from llm_router_api.core.api_types.openai import OPENAI_ACCEPTABLE_PARAMS
 from llm_router_api.core.api_types.dispatcher import ApiTypesDispatcher, API_TYPES
 from llm_router_api.endpoints.httprequest import HttpRequestExecutor