audit-framework-jsonl 0.1.0__py3-none-any.whl

audit_framework_jsonl/__init__.py

@@ -0,0 +1,18 @@
+"""audit-framework-jsonl — append-only JSONL file sink for audit-framework.
+
+The reference :class:`~audit_framework.core.ports.ExternalSink` implementation:
+copy ``sink.py`` as the template for your own sink (Splunk HEC, Elasticsearch,
+syslog, …).
+"""
+
+from audit_framework_jsonl.plugin import register
+from audit_framework_jsonl.sink import JsonlFileSink
+
+import importlib.metadata as _md
+
+try:
+    __version__ = _md.version("audit-framework-jsonl")
+except _md.PackageNotFoundError:  # running from source without an install
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["JsonlFileSink", "register", "__version__"]

audit_framework_jsonl/plugin.py

@@ -0,0 +1,20 @@
+"""Plugin registration for the JSONL file sink.
+
+The core never imports this module directly; it is reached either via the
+``audit_framework.plugins`` entry point declared in ``pyproject.toml`` (picked
+up by :meth:`PluginRegistry.discover_entrypoints`) or by an explicit module
+path passed to :meth:`PluginRegistry.load_from_config`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from audit_framework_jsonl.sink import JsonlFileSink
+
+__all__ = ["register"]
+
+
+def register(registry: Any) -> None:
+    """Register :class:`JsonlFileSink` as the ``file_jsonl`` external sink."""
+    registry.register("external_sink", "file_jsonl", JsonlFileSink)

audit_framework_jsonl/sink.py

@@ -0,0 +1,135 @@
+"""JsonlFileSink — an append-only JSON-Lines :class:`ExternalSink`.
+
+This is the **reference sink implementation** for the audit-framework plugin
+system: the simplest possible adapter, written so a customer can copy it as the
+template for their own sink (Splunk HEC, Elasticsearch, syslog, …). The recipe
+every sink follows:
+
+1.  Expose a stable :pyattr:`sink_name` (matched against ``AuditPolicy.sinks``).
+2.  Implement ``async emit(event, context)`` — forward one event, best-effort.
+3.  Implement ``async health_check()`` — report whether the downstream is usable.
+4.  Register the class in a ``register(registry)`` function (see ``plugin.py``).
+
+This sink appends one compact JSON object per line to a file. Writes are
+serialised with an :class:`asyncio.Lock` and offloaded with
+:func:`asyncio.to_thread`, so concurrent ``emit`` calls neither interleave nor
+block the event loop. Optional rotation is supported by date (one file per UTC
+day) and/or by size (roll the current file aside once it would exceed a byte
+threshold).
+
+Only the standard library is used here; the ``audit_framework`` import is for
+type hints and is part of this plugin's declared dependency.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Callable, Optional
+
+from audit_framework.core.models import AuditEvent, PipelineContext
+
+__all__ = ["JsonlFileSink"]
+
+
+def _utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class JsonlFileSink:
+    """Appends each audit event as one JSON line to a file.
+
+    Parameters
+    ----------
+    path:
+        Destination file (its parent directories are created on demand).
+    name:
+        The :pyattr:`sink_name` used for per-policy sink filtering.
+    daily:
+        When True, write to a date-stamped file ``<stem>-YYYY-MM-DD<suffix>``
+        so each UTC day gets its own file.
+    max_bytes:
+        When set, roll the current file aside (``<stem>.<timestamp><suffix>``)
+        before a write that would push it past this size. Composes with
+        ``daily``.
+    clock:
+        Injectable time source (returns an aware :class:`datetime`); used for
+        rotation stamps. Defaults to ``datetime.now(timezone.utc)``.
+    """
+
+    def __init__(
+        self,
+        path: str | os.PathLike[str],
+        *,
+        name: str = "file_jsonl",
+        daily: bool = False,
+        max_bytes: Optional[int] = None,
+        clock: Callable[[], datetime] = _utc_now,
+    ) -> None:
+        self._base = Path(path)
+        self._name = name
+        self._daily = daily
+        self._max_bytes = max_bytes
+        self._clock = clock
+        self._lock = asyncio.Lock()
+
+    @property
+    def sink_name(self) -> str:
+        """Stable identifier matched against ``AuditPolicy.sinks``."""
+        return self._name
+
+    async def emit(self, event: AuditEvent, context: PipelineContext) -> None:
+        """Append ``event`` (as one JSON line) to the current target file.
+
+        Best-effort and serialised: a raised OSError propagates so the
+        ``SinkFanOutMiddleware`` can record the failure, but it never corrupts a
+        concurrent write (the lock guarantees one writer at a time).
+        """
+        line = json.dumps(
+            event.to_dict(), separators=(",", ":"), ensure_ascii=False, default=str
+        )
+        async with self._lock:
+            await asyncio.to_thread(self._write, line)
+
+    async def health_check(self) -> bool:
+        """Return True if the target directory exists (or can be) and is writable."""
+        return await asyncio.to_thread(self._check_writable)
+
+    # ----------------------------------------------------------------- #
+    # Blocking helpers (run inside asyncio.to_thread)                    #
+    # ----------------------------------------------------------------- #
+    def _write(self, line: str) -> None:
+        path = self._target_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        if self._max_bytes is not None and path.exists():
+            projected = path.stat().st_size + len(line.encode("utf-8")) + 1
+            if projected > self._max_bytes:
+                self._rollover(path)
+        with path.open("a", encoding="utf-8") as fh:
+            fh.write(line + "\n")
+
+    def _check_writable(self) -> bool:
+        try:
+            parent = self._base.parent
+            parent.mkdir(parents=True, exist_ok=True)
+            return os.access(parent, os.W_OK)
+        except OSError:
+            return False
+
+    def _target_path(self) -> Path:
+        if not self._daily:
+            return self._base
+        stamp = self._clock().strftime("%Y-%m-%d")
+        return self._base.with_name(f"{self._base.stem}-{stamp}{self._base.suffix}")
+
+    def _rollover(self, path: Path) -> None:
+        stamp = self._clock().strftime("%Y%m%dT%H%M%S")
+        target = path.with_name(f"{path.stem}.{stamp}{path.suffix}")
+        suffix = 0
+        while target.exists():  # never clobber an existing rolled file
+            suffix += 1
+            target = path.with_name(f"{path.stem}.{stamp}.{suffix}{path.suffix}")
+        path.rename(target)

audit_framework_jsonl-0.1.0.dist-info/METADATA

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: audit-framework-jsonl
+Version: 0.1.0
+Summary: Append-only JSONL file ExternalSink for audit-framework — the reference sink plugin.
+Project-URL: Homepage, https://github.com/vanmarkic/audit-logger
+Project-URL: Repository, https://github.com/vanmarkic/audit-logger
+License-Expression: MIT
+Keywords: audit,audit-log,jsonl,plugin,siem,sink
+Requires-Python: >=3.11
+Requires-Dist: audit-framework<0.2,>=0.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# audit-framework-jsonl
+
+An append-only **JSON-Lines file sink** for
+[`audit-framework`](../audit-framework) — and the **reference implementation**
+every other `ExternalSink` (Splunk HEC, Elasticsearch, syslog, …) can be copied
+from.
+
+It implements the `ExternalSink` port: one compact JSON object per line,
+appended to a file. Writes are serialised and offloaded off the event loop, with
+optional rotation by date and/or size.
+
+## Install
+
+```bash
+pip install audit-framework-jsonl
+```
+
+## Use
+
+```python
+from audit_framework_jsonl.sink import JsonlFileSink
+from audit_framework.core.middlewares.sink_fanout import SinkFanOutMiddleware
+
+sink = JsonlFileSink("/var/log/audit/audit.jsonl", daily=True, max_bytes=50_000_000)
+pipeline.use(SinkFanOutMiddleware([sink]))   # fan events out to this sink
+```
+
+Or wire it by configuration through the registry — it advertises itself under
+the `audit_framework.plugins` entry point as the `file_jsonl` external sink:
+
+```python
+registry.discover_entrypoints()                 # finds file_jsonl
+SinkClass = registry.get("external_sink", "file_jsonl")
+sink = SinkClass("/var/log/audit/audit.jsonl")
+```
+
+Each emitted line is `event.to_dict()` serialised compactly, e.g.:
+
+```json
+{"actor_id":"alice","action":"DELETE","resource_type":"contract","resource_id":"c-42",...}
+```
+
+### Options
+
+| Param | Effect |
+|---|---|
+| `name` | The `sink_name` used for per-policy sink filtering (default `"file_jsonl"`). |
+| `daily` | Write to a date-stamped file `audit-YYYY-MM-DD.jsonl` (one per UTC day). |
+| `max_bytes` | Roll the current file aside (`audit.<timestamp>.jsonl`) before it exceeds this size. Composes with `daily`. |
+| `clock` | Injectable time source for rotation stamps (testing). |
+
+## Writing your own sink
+
+`sink.py` is deliberately tiny — copy it and change four things:
+
+1. a stable `sink_name` (matched against `AuditPolicy.sinks`),
+2. `async emit(event, context)` — forward `event.to_dict()` to your platform (best-effort; raise on permanent failure so the pipeline records it),
+3. `async health_check()` — report reachability,
+4. a `register(registry)` that calls `registry.register("external_sink", "<name>", YourSink)` (+ an `audit_framework.plugins` entry point in `pyproject.toml`).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest        # 9 stdlib-only tests (tmp files; no infrastructure)
+```
+
+## License
+
+MIT

audit_framework_jsonl-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+audit_framework_jsonl/__init__.py,sha256=WGJYvRCkbIduq_J9EoK-NdCgBbpd1ingyLzTAYps0NY,620
+audit_framework_jsonl/plugin.py,sha256=NictSLREHWUCswa4hjTHFtck3zi6_-_CHoCM3P2y_hY,662
+audit_framework_jsonl/sink.py,sha256=wnuXm4HVKkB_oX_GqHqoXWFf7qVmaKOFtbsILynjMa0,5175
+audit_framework_jsonl-0.1.0.dist-info/METADATA,sha256=otv8QdTsRnxOPhT-BQ7GB8572NbyRXlwvIoPenApV90,2925
+audit_framework_jsonl-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+audit_framework_jsonl-0.1.0.dist-info/entry_points.txt,sha256=NKdDnahYuY9Hcl4awH4ANCxV6IUKfpZxGAuOToKpi9M,77
+audit_framework_jsonl-0.1.0.dist-info/RECORD,,

audit_framework_jsonl-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

audit_framework_jsonl-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[audit_framework.plugins]
+file_jsonl = audit_framework_jsonl.plugin:register