lokryn-compliance-log-schema

Protocol Buffers schema for compliance-grade audit logging. Built for SOC2, HIPAA, and PCI environments. Works everywhere, optimized for AI/agent systems.

The Problem

There's no standard for compliance-grade audit logging. Everyone rolls their own. When you need to prove what happened, when, and why—especially with AI agents making autonomous decisions—you're stuck stitching together ad-hoc logs that weren't designed for auditors.

The Solution

A single, opinionated schema that covers:

• Traditional audit events (login, file access, config changes)
• AI/agent-specific events (tool calls, model inference, autonomous decisions)
• Sensitivity classification for data handling policies
• Outcome tracking for success/failure analysis

One format. Drop-in ready for any logging system. Built for compliance teams to actually use.

Installation

Python (PyPI)

pip install lokryn-compliance-log

Buf (For generating other languages)

Add to your buf.yaml:

deps:
  - buf.build/lokryn/compliance-log-schema

Then run:

buf mod update
buf generate

Schema Overview

EventType

What happened.

AI/Agent Events

Severity

How important is this event. Follows RFC 5424 syslog levels.

Outcome

Did it work?

Sensitivity

How sensitive is the data involved?

LogEntry Message

The core message structure:

message LogEntry {
  EventType event_type   = 1;
  Outcome outcome        = 2;
  Severity severity      = 3;
  string actor_id        = 4;   // Who did it (user, service, agent)
  string component       = 5;   // What system component
  string environment     = 6;   // prod, staging, dev
  string resource        = 7;   // What was accessed/modified
  string message         = 8;   // Human-readable description
  bytes payload          = 9;   // Structured data (JSON/CBOR)
  repeated string policy_tags = 10;  // Compliance tags (PCI, HIPAA, etc.)
  Sensitivity sensitivity = 11;
}

Usage Examples

Python

from lokryn_compliance_log import (
    LogEntry,
    EVENT_TOOL_INVOCATION,
    OUTCOME_SUCCESS,
    SEVERITY_INFO,
    SENSITIVITY_CONFIDENTIAL,
)

# Log an MCP tool call
log = LogEntry(
    event_type=EVENT_TOOL_INVOCATION,
    outcome=OUTCOME_SUCCESS,
    severity=SEVERITY_INFO,
    actor_id="agent-001",
    component="mcp-client",
    environment="production",
    resource="tools/database_query",
    message="Executed database query tool",
    payload=b'{"query": "SELECT * FROM users", "rows_returned": 42}',
    policy_tags=["SOC2", "data-access"],
    sensitivity=SENSITIVITY_CONFIDENTIAL,
)

# Serialize
data = log.SerializeToString()

Logging a Guardrail Check

from lokryn_compliance_log import (
    LogEntry,
    EVENT_GUARDRAIL_CHECK,
    OUTCOME_FAILURE_DENIED,
    SEVERITY_WARNING,
    SENSITIVITY_HIGHLY_RESTRICTED,
)

log = LogEntry(
    event_type=EVENT_GUARDRAIL_CHECK,
    outcome=OUTCOME_FAILURE_DENIED,
    severity=SEVERITY_WARNING,
    actor_id="agent-001",
    component="safety-filter",
    environment="production",
    resource="guardrails/pii-detection",
    message="PII detected in agent output, blocked",
    payload=b'{"rule": "ssn-pattern", "action": "block"}',
    policy_tags=["PII", "HIPAA"],
    sensitivity=SENSITIVITY_HIGHLY_RESTRICTED,
)

Logging an Agent Decision

from lokryn_compliance_log import (
    LogEntry,
    EVENT_AGENT_DECISION,
    OUTCOME_SUCCESS,
    SEVERITY_INFO,
    SENSITIVITY_INTERNAL,
)

log = LogEntry(
    event_type=EVENT_AGENT_DECISION,
    outcome=OUTCOME_SUCCESS,
    severity=SEVERITY_INFO,
    actor_id="agent-001",
    component="decision-engine",
    environment="production",
    resource="workflows/customer-support",
    message="Agent chose to escalate to human",
    payload=b'{"options": ["respond", "escalate", "defer"], "selected": "escalate", "confidence": 0.92}',
    policy_tags=["audit-trail"],
    sensitivity=SENSITIVITY_INTERNAL,
)

Why This Schema?

For Compliance Teams

• Maps directly to SOC2, HIPAA, PCI audit requirements
• Sensitivity levels match data classification policies
• Policy tags let you filter by compliance framework
• Outcome tracking shows attempted vs. successful actions

For AI/Agent Systems

• First-class support for tool calls, model inference, and autonomous decisions
• Tracks delegation chains (agent → sub-agent → tool)
• Guardrail events create audit trail for safety checks
• Context access events show what information agents used

For Developers

• Single schema, multiple languages (Python, Go, TypeScript, etc.)
• Protobuf means type safety and compact serialization
• Drop-in ready for any logging backend
• Works with Field Notes or your own system

Ecosystem

This schema is the foundation for:

• lokryn-mcp - MCP client wrapper that auto-generates compliant logs
• Field Notes - Tamper-evident audit logging with sub-second queries

License

Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ https://www.apache.org/licenses/LICENSE-2.0.txt

Contributing

Issues and PRs welcome. For significant changes, open an issue first to discuss.

About Lokryn

Blue collar data tools for SMBs. Compliance-ready. No bloat. Fair pricing.

lokryn.com