Audit Logging Skill

Generate comprehensive, tamper-evident audit trails for all AI agent activities to support compliance, debugging, and continuous improvement.

Purpose

This skill ensures that all AI agent activities are logged in a structured, queryable format that supports compliance audits, incident investigation, and process improvement. It creates an immutable record of all decisions and actions.

When to Use

• Always (audit logging should be automatic)
• Especially during compliance-sensitive operations
• For debugging agent behavior issues
• During security incident investigation
• For performance analysis and optimization

Audit Log Structure

Standard Log Entry Format

{
  "id": "uuid-v4",
  "timestamp": "2026-01-02T00:30:00.000Z",
  "sequence": 12345,
  "session_id": "9ddd8c22-28cb-4b1e-9174-676bbece6de6",
  "event_type": "task.completed",
  "severity": "info",
  "agent": {
    "name": "testing-specialist",
    "version": "1.0.0",
    "instance_id": "agent-001"
  },
  "task": {
    "id": "E.1.1",
    "description": "Full signup → payment → activation E2E test",
    "track": "E",
    "plan": "PILOT-PARALLEL-EXECUTION-PLAN.md"
  },
  "action": {
    "type": "file_write",
    "target": "backend/tests/e2e/test_signup_activation_flow.py",
    "result": "success",
    "metrics": {
      "lines_written": 450,
      "bytes_written": 18432,
      "duration_ms": 1250
    }
  },
  "context": {
    "sources": ["PILOT-PARALLEL-EXECUTION-PLAN.md", "SESSION-LOG-2026-01-01.md"],
    "tokens_used": 4500,
    "model": "claude-opus-4-5-20251101"
  },
  "hash": "sha256:a7f3b2c...",
  "previous_hash": "sha256:9e8d7c6..."
}

Event Types

Event Type	Description	Severity
session.start	New session begins	info
session.end	Session terminates	info
task.registered	Task created	info
task.started	Task execution begins	info
task.completed	Task execution succeeds	info
task.failed	Task execution fails	error
agent.selected	Agent chosen for task	info
agent.invoked	Agent execution starts	info
file.created	New file written	info
file.modified	Existing file changed	info
decision.made	Significant decision point	info
error.occurred	Error encountered	error
quality.gate_passed	Quality check passed	info
quality.gate_failed	Quality check failed	warning

Severity Levels

Level	Usage	Retention
debug	Detailed tracing	7 days
info	Normal operations	90 days
warning	Potential issues	1 year
error	Failures	2 years
critical	System failures	Permanent

Implementation Patterns

Pattern 1: Structured Logging

import json
import hashlib
from datetime import datetime, timezone
from uuid import uuid4

class AuditLogger:
    def __init__(self, session_id: str):
        self.session_id = session_id
        self.sequence = 0
        self.previous_hash = "genesis"

    def log(self, event_type: str, data: dict, severity: str = "info") -> dict:
        """Create tamper-evident audit log entry."""
        self.sequence += 1

        entry = {
            "id": str(uuid4()),
            "timestamp": datetime.now(timezone.utc).isoformat(),
            "sequence": self.sequence,
            "session_id": self.session_id,
            "event_type": event_type,
            "severity": severity,
            "data": data,
            "previous_hash": self.previous_hash
        }

        # Calculate hash for tamper evidence
        entry_json = json.dumps(entry, sort_keys=True)
        entry["hash"] = hashlib.sha256(entry_json.encode()).hexdigest()
        self.previous_hash = entry["hash"]

        # Persist entry
        self._persist(entry)

        return entry

    def _persist(self, entry: dict):
        """Persist audit log entry."""
        # Append to session log
        with open(f"audit-log-{self.session_id}.jsonl", "a") as f:
            f.write(json.dumps(entry) + "\n")

Pattern 2: Event Correlation

class CorrelatedAuditLogger(AuditLogger):
    def __init__(self, session_id: str):
        super().__init__(session_id)
        self.correlation_ids = {}

    def start_operation(self, operation_id: str, task_id: str) -> str:
        """Start a correlated operation."""
        correlation_id = str(uuid4())
        self.correlation_ids[operation_id] = correlation_id

        self.log("operation.started", {
            "operation_id": operation_id,
            "task_id": task_id,
            "correlation_id": correlation_id
        })

        return correlation_id

    def log_correlated(self, operation_id: str, event_type: str, data: dict):
        """Log event with correlation ID."""
        correlation_id = self.correlation_ids.get(operation_id)
        data["correlation_id"] = correlation_id
        return self.log(event_type, data)

    def end_operation(self, operation_id: str, result: str):
        """End a correlated operation."""
        correlation_id = self.correlation_ids.pop(operation_id, None)

        self.log("operation.completed", {
            "operation_id": operation_id,
            "correlation_id": correlation_id,
            "result": result
        })

Pattern 3: Compliance Export

def export_audit_trail(session_id: str, format: str = "json") -> str:
    """Export audit trail in compliance-friendly format."""

    with open(f"audit-log-{session_id}.jsonl", "r") as f:
        entries = [json.loads(line) for line in f]

    if format == "json":
        return json.dumps({
            "audit_trail": entries,
            "metadata": {
                "session_id": session_id,
                "entry_count": len(entries),
                "exported_at": datetime.now(timezone.utc).isoformat(),
                "integrity_verified": verify_chain_integrity(entries)
            }
        }, indent=2)

    elif format == "csv":
        # CSV export for spreadsheet analysis
        return export_as_csv(entries)

    elif format == "markdown":
        # Human-readable markdown report
        return export_as_markdown(entries)

Audit Log Destinations

Local File (Default)

context-storage/audit-logs/
├── session-{id}.jsonl        # Session-specific log
├── daily-2026-01-02.jsonl    # Daily aggregate
└── archive/                  # Compressed archives

Cloud Storage (Production)

# Sync to GCS
gsutil rsync -r context-storage/audit-logs/ \
    gs://coditect-cloud-infra-audit-logs/

SIEM Integration

def send_to_siem(entry: dict):
    """Send audit entry to SIEM system."""
    # Example: Send to Splunk HEC
    requests.post(
        "https://siem.example.com/services/collector",
        headers={"Authorization": f"Splunk {SIEM_TOKEN}"},
        json={"event": entry}
    )

Query Patterns

Find All Actions for Task

# Using jq
cat audit-log-*.jsonl | jq 'select(.task.id == "E.1.1")'

Find All Errors

cat audit-log-*.jsonl | jq 'select(.severity == "error")'

Timeline of Session

cat audit-log-*.jsonl | jq -r '[.timestamp, .event_type, .data.description] | @tsv' | sort

Verify Chain Integrity

def verify_chain_integrity(entries: list) -> bool:
    """Verify audit log chain has not been tampered with."""
    for i, entry in enumerate(entries):
        if i == 0:
            continue

        # Recalculate hash
        entry_copy = entry.copy()
        stored_hash = entry_copy.pop("hash")
        expected_previous = entries[i-1]["hash"]

        if entry_copy["previous_hash"] != expected_previous:
            return False

        calculated_hash = hashlib.sha256(
            json.dumps(entry_copy, sort_keys=True).encode()
        ).hexdigest()

        if calculated_hash != stored_hash:
            return False

    return True

Compliance Mappings

Requirement	Audit Log Support
SOC 2 - CC7.2	All system activities logged
ISO 27001 - A.12.4	Event logging enabled
GDPR - Art. 30	Processing activities recorded
HIPAA - 164.312(b)	Audit controls implemented

Anti-Patterns to Avoid

Anti-Pattern	Problem	Solution
Mutable logs	Tampering possible	Hash chain verification
Missing timestamps	Can't sequence events	Always include ISO timestamp
Unstructured logs	Hard to query	Use JSON format
No retention policy	Storage bloat	Implement tiered retention
Sensitive data in logs	Privacy violation	Redact PII, encrypt at rest

Related Components

• Commands: /audit-trail, /quality-gate
• Skills: process-transparency, task-accountability
• Hooks: task-completion, session-handoff
• Agents: audit-trail-manager

Success Output

When successful, this skill MUST output:

✅ SKILL COMPLETE: audit-logging

Completed:
- [x] Audit logger initialized with tamper-evident hash chain
- [x] All critical events logged (task start/complete, file writes, decisions)
- [x] Event correlation IDs assigned for multi-step operations
- [x] Audit log integrity verified (hash chain valid)
- [x] Compliance export generated (JSON/CSV/Markdown)
- [x] Query patterns tested and documented

Outputs:
- context-storage/audit-logs/session-{id}.jsonl (primary log)
- context-storage/audit-logs/daily-{date}.jsonl (daily aggregate)
- Audit trail export (compliance-ready format)
- Query documentation and examples
- Integrity verification report (100% chain valid)

Completion Checklist

Before marking this skill as complete, verify:

• Audit logger captures all required event types
• Hash chain verification passes (no tampering detected)
• Event timestamps in UTC ISO 8601 format
• Correlation IDs link related operations correctly
• Severity levels assigned appropriately
• No sensitive data (PII, secrets) logged in plaintext
• Log retention policy configured and documented
• Query patterns return expected results
• Compliance export includes all required fields
• Log files have correct permissions (read-only after write)

Failure Indicators

This skill has FAILED if:

• ❌ Events missing from audit log
• ❌ Hash chain verification fails (tampering detected)
• ❌ Timestamps inconsistent or in wrong timezone
• ❌ Correlation IDs missing or incorrect
• ❌ Sensitive data logged in plaintext
• ❌ Log files have incorrect permissions
• ❌ Query patterns return incomplete results
• ❌ Compliance export missing required fields
• ❌ Log rotation/retention not implemented
• ❌ JSONL files have syntax errors (invalid JSON)

When NOT to Use

Do NOT use this skill when:

• Non-compliance contexts - If no regulatory requirements, simpler logging sufficient
• Prototype/development only - Audit overhead not needed for throwaway code
• Performance-critical paths - Synchronous audit logging adds latency
• Offline-only systems - Tamper evidence requires network time sync
• Public data only - If no sensitive operations, standard logging adequate
• Short-lived processes - Audit trail overhead not justified for quick scripts
• Non-agent activities - Human actions may use different audit systems

Alternative approaches:

• Use standard application logging (log4j, winston) for development
• Use APM tools (DataDog, New Relic) for performance monitoring
• Use SIEM systems directly for security-focused logging

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Mutable log files	Tampering possible	Implement hash chain, write-once semantics
Missing timestamps	Can't sequence events	Always include UTC ISO timestamp
Unstructured logs	Hard to query, parse	Use structured JSON format
No retention policy	Storage bloat, compliance gaps	Define and enforce retention (90d/1y/2y/permanent)
Logging PII plaintext	Privacy violation, GDPR breach	Redact PII, encrypt at rest
Synchronous logging	Blocks execution, adds latency	Use async logging with buffering
Generic event types	Can't filter meaningfully	Use specific types (task.started, file.modified)
No correlation IDs	Can't trace multi-step operations	Assign correlation IDs for workflows
Log to single file	File grows unbounded	Implement daily rotation
Skipping severity	All events treated equally	Use debug/info/warning/error/critical

Principles

This skill embodies these CODITECT principles:

• #5 Eliminate Ambiguity - Structured logs with explicit event types
• #6 Clear, Understandable, Explainable - Every decision and action logged
• #8 No Assumptions - Verify log integrity, don't assume tamper-free
• #9 Observability First - Complete audit trail from start
• #11 Security by Design - Tamper-evident, encrypted, access-controlled
• #15 Standards Compliance - SOC 2, ISO 27001, GDPR, HIPAA support
• #17 Accountability - Every action traceable to agent and session

Full Principles: CODITECT-STANDARD-AUTOMATION.md

---

Skill Version: 1.0.0 Created: 2026-01-02 Author: CODITECT Process Refinement