universal-audit-logs 1.0.2

Universal Audit Framework (UAF) — A production-ready, framework-agnostic audit logging SDK for Python.

Universal Audit Framework (UAF) SDK

A production-ready audit logging SDK for Python. Auto-captures WHO did WHAT, WHEN — with zero code in your endpoints.

---

Installation

# With FastAPI middleware + PostgreSQL (most common)
pip install universal-audit-logs[fastapi,postgres]

# Core only (REST transport)
pip install universal-audit-logs

# All transports
pip install universal-audit-logs[all]

---

FastAPI Middleware Setup (Recommended)

from fastapi import FastAPI
from starlette.middleware.sessions import SessionMiddleware
from audit_sdk.middleware.enhanced import (
    EnhancedAuditMiddleware,
    EnhancedAuditConfig,
)
from audit_sdk.transport.simple_database import SimpleAuditTransport

app = FastAPI()

# 1. Configure audit transport (writes to PostgreSQL)
transport = SimpleAuditTransport.for_postgres(
    host="localhost",
    port=5432,
    database="audit_db",
    username="your_user",
    password="your_password",
)

# 2. Add audit middleware
app.add_middleware(
    EnhancedAuditMiddleware,
    transport=transport,
    config=EnhancedAuditConfig(
        capture_request_body=True,
        excluded_paths=frozenset({"/health", "/docs", "/openapi.json"}),
    ),
)

# 3. Add session middleware (for user tracking)
app.add_middleware(SessionMiddleware, secret_key="your-secret-key")

Done. Every endpoint is now automatically audited. No audit.log() calls needed anywhere.

---

User Detection

The middleware auto-detects the logged-in user. Provide a UserProvider:

from audit_sdk.middleware.enhanced import EnhancedAuditMiddleware

class SessionUserProvider:
    async def get_user(self, request) -> dict | None:
        user = request.session.get("current_user")
        if user:
            return {
                "user_id": user["id"],
                "username": user["username"],
                "email": user.get("email", ""),
                "roles": user.get("roles", []),
            }
        return None

app.add_middleware(
    EnhancedAuditMiddleware,
    transport=transport,
    user_provider=SessionUserProvider(),
    config=EnhancedAuditConfig(capture_request_body=True),
)

---

What Gets Captured Automatically

Field	Example
performed_by	Sumanth
action	CREATE, UPDATE, DELETE, LOGIN
action_message	Sumanth created Employee John
functionality	Employee Management
performed_on	Employee #1
performed_at	2025-07-08 10:30:00+00
previous_state	{"salary": 100000}
current_state	{"salary": 120000}
changed_fields	{"salary": {"old": 100000, "new": 120000}}

---

Transport Options

PostgreSQL (recommended)

from audit_sdk.transport.simple_database import SimpleAuditTransport

transport = SimpleAuditTransport.for_postgres(
    host="localhost", port=5432,
    database="audit_db", username="user", password="pass",
)

SQLite

transport = SimpleAuditTransport.for_sqlite(path="./audit.db")

MongoDB

pip install universal-audit-logs[mongodb]

from audit_sdk.transport.mongodb import MongoDBTransport

transport = MongoDBTransport(uri="mongodb://localhost:27017", database="audit_db")

REST (HTTP collector)

from audit_sdk import AuditClient, AuditSettings

settings = AuditSettings(endpoint="https://audit.example.com/api/v1/events")
audit = AuditClient(settings=settings)

---

Audit Log Table (auto-created)

CREATE TABLE audit_log (
    id              VARCHAR(36) PRIMARY KEY,
    performed_by    TEXT NOT NULL,
    action          VARCHAR(100) NOT NULL,
    action_message  TEXT,
    functionality   VARCHAR(200) NOT NULL,
    performed_on    TEXT NOT NULL,
    performed_at    TIMESTAMPTZ NOT NULL,
    previous_state  JSONB,
    current_state   JSONB,
    changed_fields  JSONB,
    http_context    JSONB
);

---

License

MIT - see LICENSE

Copyright (c) 2025 Sumanth