Audit Logging

Field	Value
Document ID	ASCEND-GOV-003
Version	2026.04
Last Updated	April 2026
Author	Ascend Engineering Team
Publisher	OW-KAI Technologies Inc.
Classification	Enterprise Client Documentation
Compliance	SOC 2 CC6.1/CC6.2, PCI-DSS 7.1/8.3, HIPAA 164.312, NIST 800-53 AC-2/SI-4

Reading Time: 10 minutes | Skill Level: Intermediate

Overview

ASCEND provides enterprise-grade immutable audit logging with WORM (Write-Once-Read-Many) design and cryptographic hash-chaining. Every action, decision, and configuration change is logged with tamper-proof integrity.

note

Audit logs use WORM (Write-Once-Read-Many) design with cryptographic hash-chaining. Records cannot be modified or deleted after creation, ensuring tamper-proof compliance evidence.

Architecture

+---------------------------------------------------------------------------------+
|                          IMMUTABLE AUDIT SYSTEM                                  |
+---------------------------------------------------------------------------------+
|                                                                                  |
|   EVENT OCCURS                                                                   |
|        |                                                                         |
|        v                                                                         |
|   +------------------+    +-----------------+    +-------------------+           |
|   | CONTENT HASH     | -> | CHAIN HASH      | -> | SEQUENCE NUMBER   |          |
|   | SHA-256 of event |    | Links to prev   |    | Auto-increment    |          |
|   +------------------+    +-----------------+    +-------------------+           |
|        |                                                                         |
|        v                                                                         |
|   +-------------------------------------------------------------------------+   |
|   |                    IMMUTABLE AUDIT LOG                                   |   |
|   |                                                                          |   |
|   |  Seq: 1001 | Hash: a1b2c3... | Prev: 9f8e7d... | Chain: x7y8z9...      |   |
|   |  Seq: 1002 | Hash: d4e5f6... | Prev: a1b2c3... | Chain: p2q3r4...      |   |
|   |  Seq: 1003 | Hash: g7h8i9... | Prev: d4e5f6... | Chain: m5n6o7...      |   |
|   |                                                                          |   |
|   +-------------------------------------------------------------------------+   |
|                                                                                  |
+---------------------------------------------------------------------------------+

Audit Log Structure

# Source: models_audit.py:14
class ImmutableAuditLog(Base):
    """WORM audit log with hash-chaining."""

    id = Column(UUID, primary_key=True)
    sequence_number = Column(Integer, unique=True)
    organization_id = Column(Integer)  # Multi-tenant isolation

    # Timestamp and source
    timestamp = Column(DateTime)
    source_system = Column(String(100))

    # Event data
    event_type = Column(String(50))    # USER_ACTION, SYSTEM_EVENT, POLICY_VIOLATION
    actor_id = Column(String(100))      # User ID or system identifier
    resource_type = Column(String(50))  # AGENT, TOOL, DATA, POLICY
    resource_id = Column(String(100))
    action = Column(String(100))        # CREATE, READ, UPDATE, DELETE, EXECUTE
    outcome = Column(String(50))        # SUCCESS, FAILURE, PENDING, DENIED

    # Detailed event data
    event_data = Column(JSON)
    risk_level = Column(String(20))     # LOW, MEDIUM, HIGH, CRITICAL
    compliance_tags = Column(JSON)      # SOX, HIPAA, PCI, GDPR

    # Immutability and integrity
    content_hash = Column(String(64))   # SHA-256 of content
    previous_hash = Column(String(64))  # Hash of previous entry
    chain_hash = Column(String(64))     # Combined chain hash

    # Evidence and retention
    evidence_pack_id = Column(UUID)
    retention_until = Column(DateTime)
    legal_hold = Column(Boolean)

Event Types

Event Type	Description	Examples
`USER_ACTION`	User-initiated action	Login, approval, config change
`SYSTEM_EVENT`	System-generated event	Scheduled jobs, auto-approval
`POLICY_VIOLATION`	Policy rule triggered	Blocked action, escalation
`CONFIG_CHANGE`	Configuration modified	Risk weights, thresholds
`SECURITY_EVENT`	Security-related event	Auth failure, anomaly

Creating Audit Logs

REST API

curl -X POST "https://pilot.owkai.app/api/audit/log" \
  -H "Authorization: Bearer owkai_..." \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "USER_ACTION",
    "actor_id": "admin@company.com",
    "resource_type": "AGENT",
    "resource_id": "finance-bot-001",
    "action": "UPDATE",
    "event_data": {
      "field_changed": "auto_approve_below",
      "old_value": 30,
      "new_value": 25
    },
    "risk_level": "MEDIUM",
    "compliance_tags": ["SOX", "CONFIG_MANAGEMENT"]
  }'

Response:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "sequence_number": 10045,
  "timestamp": "2025-12-15T10:30:00Z",
  "content_hash": "a1b2c3d4e5f6g7h8i9j0...",
  "status": "created"
}

SDK Integration

from ascend import AscendClient

client = AscendClient(api_key="owkai_...")

# Automatic audit logging with actions
result = client.evaluate_action(
    action_type="database.delete",
    resource="customers.inactive"
)

# Audit log created automatically with:
# - Action details
# - Risk assessment
# - Policy matches
# - Decision outcome

Retrieving Audit Logs

List Logs

curl "https://pilot.owkai.app/api/audit/logs?limit=100&offset=0" \
  -H "Authorization: Bearer owkai_..."

Response:

{
  "total": 10045,
  "limit": 100,
  "offset": 0,
  "logs": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "sequence_number": 10045,
      "timestamp": "2025-12-15T10:30:00Z",
      "event_type": "USER_ACTION",
      "actor_id": "admin@company.com",
      "resource_type": "AGENT",
      "action": "UPDATE",
      "risk_level": "MEDIUM"
    }
  ]
}

Filter by Date Range

curl "https://pilot.owkai.app/api/audit/logs?\
start_date=2025-12-01T00:00:00Z&\
end_date=2025-12-15T23:59:59Z" \
  -H "Authorization: Bearer owkai_..."

Filter by Event Type

curl "https://pilot.owkai.app/api/audit/logs?event_type=POLICY_VIOLATION" \
  -H "Authorization: Bearer owkai_..."

Chain Integrity Verification

Verify Integrity

curl -X POST "https://pilot.owkai.app/api/audit/verify-integrity" \
  -H "Authorization: Bearer owkai_..."

Response:

{
  "id": "b2c3d4e5-f6g7-8901-bcde-f12345678901",
  "check_time": "2025-12-15T10:35:00Z",
  "status": "VALID",
  "total_records": 10045,
  "check_duration_ms": 2450,
  "records_per_second": 4100
}

Integrity Check Statuses

Status	Description	Action Required
`VALID`	All hashes verified	None
`BROKEN`	Chain hash mismatch	Investigate break point
`TAMPERED`	Content hash invalid	Security incident

Export Formats

CSV Export

curl "https://pilot.owkai.app/api/audit/export/csv?\
start_date=2025-12-01T00:00:00Z&\
end_date=2025-12-15T23:59:59Z" \
  -H "Authorization: Bearer owkai_..." \
  -o audit_logs.csv

CSV Format:

Sequence Number,Timestamp,Event Type,Actor ID,Resource Type,Resource ID,Action,Risk Level,Compliance Tags,Content Hash,Chain Hash,Retention Until,Legal Hold,IP Address
10045,2025-12-15T10:30:00Z,USER_ACTION,admin@company.com,AGENT,finance-bot-001,UPDATE,MEDIUM,"SOX,CONFIG_MANAGEMENT",a1b2c3d4...,x7y8z9...,2032-12-15T10:30:00Z,No,192.168.1.100

PDF Export

curl "https://pilot.owkai.app/api/audit/export/pdf?\
start_date=2025-12-01T00:00:00Z&\
end_date=2025-12-15T23:59:59Z" \
  -H "Authorization: Bearer owkai_..." \
  -o audit_report.pdf

PDF includes:

Report metadata and generation info
Hash chain integrity status
Compliance framework badges
Formatted audit log table
Digital signature notice

Retention Policies

Compliance-Based Retention

# Source: services/immutable_audit_service.py:173
RETENTION_PERIODS = {
    'SOX': 2555,      # 7 years
    'HIPAA': 2190,    # 6 years
    'PCI': 365,       # 1 year
    'GDPR': 2190,     # 6 years
    'CCPA': 1095,     # 3 years
    'FERPA': 1825,    # 5 years
}

Automatic Retention

When compliance tags are set, retention is automatically calculated:

{
  "compliance_tags": ["SOX", "HIPAA"],
  "retention_until": "2032-12-15T10:30:00Z"
}

The longest applicable retention period is used (SOX: 7 years in this case).

Health Check

curl "https://pilot.owkai.app/api/audit/health" \
  -H "Authorization: Bearer owkai_..."

Response:

{
  "status": "healthy",
  "audit_system": "operational",
  "timestamp": "2025-12-15T10:45:00Z",
  "features": ["immutable_logs", "hash_chaining", "evidence_packs"]
}

SDK Integration

The SDK exposes audit-log reads directly; write-side custom audit events and chain integrity verification are available via the REST API. A higher-level client.audit.* namespace accessor is planned (see SDK-NAMESPACE-FEATURE — tracked for 2.5).

Query Audit Logs (SDK)

# Source: ascend/client.py
from ascend import AscendClient
from datetime import datetime, timedelta, timezone

client = AscendClient(api_key="owkai_...")

# Read recent audit events
logs = client.query_audit_log(
    start_time=datetime.now(timezone.utc) - timedelta(hours=24),
    end_time=datetime.now(timezone.utc),
    limit=100,
)

for entry in logs.entries:
    print(f"{entry.timestamp} — {entry.action} by {entry.actor_id}")

Log a Custom Event (REST API)

Custom audit events are posted directly against the governance endpoint. The SDK reuses your existing API key for authentication.

curl -X POST "https://pilot.owkai.app/audit/logs" \
  -H "Authorization: Bearer $ASCEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "USER_ACTION",
    "actor_id": "user@company.com",
    "resource_type": "DATA",
    "resource_id": "customers.export",
    "action": "EXPORT",
    "event_data": {"records_exported": 1500, "format": "csv"},
    "risk_level": "MEDIUM",
    "compliance_tags": ["GDPR", "DATA_EXPORT"]
  }'

Verify Chain Integrity (REST API)

curl -X GET "https://pilot.owkai.app/audit/logs/verify-chain" \
  -H "Authorization: Bearer $ASCEND_API_KEY"

Best Practices

1. Use Meaningful Event Types

# Good - specific event type
{"event_type": "POLICY_VIOLATION"}

# Bad - generic type
{"event_type": "EVENT"}

2. Include Compliance Tags

# Tag events for compliance frameworks
{
    "compliance_tags": ["SOX", "PCI-DSS", "AUDIT"]
}

3. Regular Integrity Verification

# Run daily integrity checks
schedule.every().day.at("02:00").do(
    client.audit.verify_integrity
)

4. Export for Long-Term Archival

# Monthly compliance export
client.audit.export_pdf(
    start_date=month_start,
    end_date=month_end,
    filename=f"audit_{month}.pdf"
)

Next Steps

Compliance — Compliance export features
Analytics — Audit analytics and trends
Risk Assessment — Risk scoring configuration

Document Version: 2026.04 | Last Updated: April 2026

Overview​

Architecture​

Audit Log Structure​

Event Types​

Creating Audit Logs​

REST API​

SDK Integration​

Retrieving Audit Logs​

List Logs​

Filter by Date Range​

Filter by Event Type​

Chain Integrity Verification​

Verify Integrity​

Integrity Check Statuses​

Export Formats​

CSV Export​

PDF Export​

Retention Policies​

Compliance-Based Retention​

Automatic Retention​

Health Check​

SDK Integration​

Query Audit Logs (SDK)​

Log a Custom Event (REST API)​

Verify Chain Integrity (REST API)​

Best Practices​

1. Use Meaningful Event Types​

2. Include Compliance Tags​

3. Regular Integrity Verification​

4. Export for Long-Term Archival​

Next Steps​

Overview

Architecture

Audit Log Structure

Event Types

Creating Audit Logs

REST API

SDK Integration

Retrieving Audit Logs

List Logs

Filter by Date Range

Filter by Event Type

Chain Integrity Verification

Verify Integrity

Integrity Check Statuses

Export Formats

CSV Export

PDF Export

Retention Policies

Compliance-Based Retention

Automatic Retention

Health Check

SDK Integration

Query Audit Logs (SDK)

Log a Custom Event (REST API)

Verify Chain Integrity (REST API)

Best Practices

1. Use Meaningful Event Types

2. Include Compliance Tags

3. Regular Integrity Verification

4. Export for Long-Term Archival

Next Steps