Skip to content

Audit Logs

CertusOrdo provides immutable, hash-chained audit logs for compliance and accountability.

Why Audit Logs Matter

For regulated industries, comprehensive audit trails aren't optional—they're required:

Regulation Requirement
SOC 2 Complete audit trail of all access
HIPAA 6-year retention of access logs
SEC 17a-4 Tamper-evident record keeping
GDPR Accountability and traceability

How It Works

Every action in CertusOrdo creates an audit log entry with:

┌────────────────────────────────────────────────────────┐
│                    AUDIT LOG ENTRY                      │
├────────────────────────────────────────────────────────┤
│  sequence_number: 12345                                │
│  timestamp: 2025-01-16T14:30:00Z                       │
│  event_type: transaction.started                       │
│  organization_id: uuid                                 │
│  agent_id: uuid                                        │
│  metadata: {...}                                       │
│  previous_hash: abc123...                              │
│  entry_hash: def456...  ◄── SHA256 of this entry      │
└────────────────────────────────────────────────────────┘
                          │
                          ▼
┌────────────────────────────────────────────────────────┐
│  sequence_number: 12346                                │
│  previous_hash: def456... ◄── Links to previous       │
│  entry_hash: ghi789...                                 │
└────────────────────────────────────────────────────────┘

Hash Chain Integrity

Each entry contains the hash of the previous entry, creating an unbreakable chain. If anyone modifies a historical entry, the chain breaks and tampering is detected.

Event Types

Event Type Description
org.created Organization created
agent.created New agent registered
agent.revoked Agent revoked
auth.token_issued JWT token generated
auth.token_revoked Token revoked
session.started Session created
session.ended Session completed
txn.started Transaction began
txn.committed Transaction completed
txn.rolled_back Transaction rolled back

Querying Audit Logs

List All Entries

from certusrodo import CertusOrdoClient

client = CertusOrdoClient(api_key="aa_your_api_key")

# Get recent audit entries
entries = client.audit.list()

for entry in entries:
    print(f"{entry.timestamp}: {entry.event_type}")

Filter by Event Type

# Only transaction events
txn_events = client.audit.list(event_type="txn.started")

# Only rollback events
rollbacks = client.audit.list(event_type="txn.rolled_back")

Filter by Agent

# All activity for a specific agent
agent_activity = client.audit.list(agent_id="agent-uuid")

Filter by Time Range

from datetime import datetime, timedelta

# Last 24 hours
yesterday = datetime.now() - timedelta(days=1)
recent = client.audit.list(after=yesterday)

# Specific date range
start = datetime(2025, 1, 1)
end = datetime(2025, 1, 31)
january = client.audit.list(after=start, before=end)

Pagination

# First page
page1 = client.audit.list(limit=100)

# Next page using cursor
page2 = client.audit.list(limit=100, cursor=page1.next_cursor)

Verifying Chain Integrity

# Verify the entire audit chain
verification = client.audit.verify()

print(f"Chain valid: {verification.is_valid}")
print(f"Entries checked: {verification.entries_checked}")
print(f"First entry: {verification.first_sequence}")
print(f"Last entry: {verification.last_sequence}")

if not verification.is_valid:
    print(f"Broken at: {verification.break_point}")

Tamper Detection

If anyone modifies historical entries, verify() returns is_valid: False and identifies where the chain was broken.

Audit Entry Details

# Get full details of an entry
entry = client.audit.get(entry_id)

print(f"Sequence: {entry.sequence_number}")
print(f"Event: {entry.event_type}")
print(f"Timestamp: {entry.timestamp}")
print(f"Agent: {entry.agent_id}")
print(f"Metadata: {entry.metadata}")
print(f"Hash: {entry.entry_hash}")
print(f"Previous Hash: {entry.previous_hash}")

Metadata Examples

Agent Created: 

{
  "agent_name": "payment-processor",
  "scopes": ["payments:read", "payments:write"]
}

Transaction Started: 

{
  "transaction_id": "txn-uuid",
  "action_type": "transfer_funds",
  "session_id": "session-uuid"
}

Transaction Rolled Back: 

{
  "transaction_id": "txn-uuid",
  "reason": "Destination account frozen",
  "rollback_confidence": "guaranteed"
}

Compliance Reports

Generate Compliance Export

# Export audit log for compliance review
from datetime import datetime

report = client.audit.export(
    start_date=datetime(2025, 1, 1),
    end_date=datetime(2025, 3, 31),
    format="csv"  # or "json"
)

# Save to file
with open("q1_audit_report.csv", "w") as f:
    f.write(report)

SOC 2 Report Format

# SOC 2 specific export
soc2_report = client.audit.export(
    start_date=audit_period_start,
    end_date=audit_period_end,
    format="json",
    include_hashes=True,
    include_verification=True
)

Retention Policy

Plan Retention Period
Starter 30 days
Growth 1 year
Enterprise 7+ years (configurable)

Best Practices

1. Regular Verification

# Weekly integrity check
def weekly_audit_check():
    verification = client.audit.verify()

    if not verification.is_valid:
        alert_security_team(
            f"Audit chain broken at {verification.break_point}"
        )

2. Archive Before Retention Expires

# Export before data ages out
def monthly_archive():
    last_month = get_last_month_range()

    export = client.audit.export(
        start_date=last_month.start,
        end_date=last_month.end,
        format="json"
    )

    save_to_long_term_storage(export)

3. Monitor Critical Events

# Alert on rollbacks
def monitor_rollbacks():
    recent_rollbacks = client.audit.list(
        event_type="txn.rolled_back",
        after=datetime.now() - timedelta(hours=1)
    )

    if len(recent_rollbacks) > 10:
        alert("High rollback rate detected")

Next Steps