Audit Logging

Field	Value
Document ID	ASCEND-GOV-003
Version	1.0.0
Last Updated	December 19, 2025
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.

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).

Evidence Packs

Create Evidence Pack

curl -X POST "https://pilot.owkai.app/api/audit/evidence-packs" \
  -H "Authorization: Bearer owkai_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Q4 2025 Compliance Audit",
    "description": "Quarterly SOX compliance audit evidence",
    "start_time": "2025-10-01T00:00:00Z",
    "end_time": "2025-12-31T23:59:59Z",
    "actor_ids": ["admin@company.com", "auditor@company.com"],
    "resource_types": ["AGENT", "POLICY"]
  }'

Response:

{
  "id": "c3d4e5f6-g7h8-9012-cdef-123456789012",
  "title": "Q4 2025 Compliance Audit",
  "status": "ACTIVE",
  "manifest_hash": "d4e5f6g7h8i9j0k1l2m3...",
  "compliance_frameworks": ["SOX"],
  "created_at": "2025-12-15T10:40:00Z"
}

Evidence Pack Features

# Source: models_audit.py:95
class EvidencePack(Base):
    """Signed evidence packages for legal and compliance use."""

    id = Column(UUID, primary_key=True)
    title = Column(String(200))
    description = Column(Text)
    case_number = Column(String(100))       # Legal case reference
    investigation_id = Column(String(100))  # Internal investigation

    # Time range and scope
    start_time = Column(DateTime)
    end_time = Column(DateTime)
    actor_ids = Column(JSON)
    resource_types = Column(JSON)

    # Cryptographic integrity
    manifest_hash = Column(String(64))
    signature = Column(LargeBinary)
    certificate_info = Column(JSON)

    # Status and access
    status = Column(String(20))  # ACTIVE, SEALED, ARCHIVED
    legal_hold = Column(Boolean)
    retention_policy = Column(String(50))

Legal Hold

Apply Legal Hold

curl -X PUT "https://pilot.owkai.app/api/audit/logs/10045/legal-hold" \
  -H "Authorization: Bearer owkai_..." \
  -H "Content-Type: application/json" \
  -d '{
    "legal_hold": true,
    "reason": "Litigation hold - Case #2025-001"
  }'

Legal hold prevents:

Automatic deletion after retention period
Manual deletion
Evidence pack archival

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

Log Custom Events

from ascend import AscendClient

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

# Log custom audit event
audit_log = client.audit.log_event(
    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",
        "destination": "s3://exports/customer-data.csv"
    },
    risk_level="MEDIUM",
    compliance_tags=["GDPR", "DATA_EXPORT"]
)

print(f"Audit log created: {audit_log.id}")
print(f"Sequence: {audit_log.sequence_number}")

Verify Chain Integrity

# Verify entire chain
result = client.audit.verify_integrity()

if result.status == "VALID":
    print(f"Chain verified: {result.total_records} records")
else:
    print(f"Chain issue: {result.status}")
    for break_point in result.broken_chains:
        print(f"  Break at sequence {break_point['sequence']}")

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: 1.0.0 | Last Updated: December 2025

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​

Evidence Packs​

Create Evidence Pack​

Evidence Pack Features​

Legal Hold​

Apply Legal Hold​

Health Check​

SDK Integration​

Log Custom Events​

Verify Chain Integrity​

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

Evidence Packs

Create Evidence Pack

Evidence Pack Features

Legal Hold

Apply Legal Hold

Health Check

SDK Integration

Log Custom Events

Verify Chain Integrity

Best Practices

1. Use Meaningful Event Types

2. Include Compliance Tags

3. Regular Integrity Verification

4. Export for Long-Term Archival

Next Steps