Audit Logs

An audit log (also called an audit trail) is a chronological record of system activities. According to Sumo Logic, audit logs "provide a detailed record of events and changes within a system, enabling organizations to track user actions, system changes, and access to sensitive data."

Why audit logs matter

Accountability

Audit logs answer the question "who did what, when?" This is essential for holding users and administrators accountable for their actions. If data is deleted or modified, the audit log shows exactly who made the change.

Security

Audit logs help detect and investigate security incidents. For example, if an attacker gains unauthorized access, the logs reveal which resources they accessed and what actions they performed. This information is critical for incident response and forensics.

Compliance

Many regulations (GDPR, HIPAA, SOC 2, PCI DSS) require organizations to maintain audit logs. These logs must be tamper-evident, retained for a specified period, and available for inspection by auditors.

Debugging

When something goes wrong in production, audit logs provide a detailed timeline of events leading up to the failure. This makes it much easier to diagnose and fix issues.

What ContractSpec logs

ContractSpec automatically logs every significant operation, including:

  • API calls – Every invocation of a capability, including inputs, outputs, and the user who made the call.
  • Policy decisions – Every decision made by the Policy Decision Point, including the rule that matched and the reason for the decision.
  • Data access – Every query to a data view, including which fields were accessed and whether any were redacted.
  • Workflow execution – Every step in a workflow, including retries, compensations, and failures.
  • Administrative actions – Spec deployments, configuration changes, user role assignments, and other privileged operations.
  • Authentication events – Login attempts, password resets, and session expirations.

Audit log format

Each audit log entry is a structured JSON object containing:

{
  "timestamp": "2025-11-13T14:32:15.123Z",
  "eventId": "evt_abc123",
  "eventType": "capability.invoked",
  "actor": {
    "userId": "user_xyz789",
    "role": "admin",
    "ipAddress": "203.0.113.42"
  },
  "resource": {
    "type": "capability",
    "id": "transferFunds",
    "version": "1.2.0"
  },
  "action": "execute",
  "result": "success",
  "metadata": {
    "inputs": {
      "recipient": "user_def456",
      "amount": 100.00
    },
    "outputs": {
      "transactionId": "txn_ghi789",
      "timestamp": "2025-11-13T14:32:15.456Z"
    }
  },
  "policyDecision": {
    "decision": "PERMIT",
    "ruleId": "allow-admin-transfers",
    "reason": "User has admin role"
  }
}

Storage and retention

Audit logs are stored in a tamper-evident append-only log. Once written, entries cannot be modified or deleted. This ensures the integrity of the audit trail.

ContractSpec supports multiple storage backends:

  • Local file system – For development and testing.
  • Cloud object storage – S3, GCS, or Azure Blob Storage for production.
  • SIEM integration – Forward logs to Splunk, Datadog, or other security information and event management systems.

You can configure retention policies to automatically archive or delete old logs after a specified period (e.g., 7 years for GDPR compliance).

Querying audit logs

ContractSpec provides a query API for searching audit logs. You can filter by:

  • Time range
  • Event type
  • Actor (user ID, role, IP address)
  • Resource (capability, data view, workflow)
  • Result (success, failure, denied)

Example query: "Show all failed login attempts from IP address 203.0.113.42 in the last 24 hours."

Best practices

  • Review logs regularly – Set up alerts for suspicious activity (e.g., repeated failed login attempts, unauthorized access attempts).
  • Protect log access – Only authorized personnel should be able to view audit logs. Use role-based access control to restrict access.
  • Retain logs long enough – Check your compliance requirements and configure retention policies accordingly.
  • Test log integrity – Periodically verify that logs have not been tampered with by checking cryptographic signatures.
Previous: Policy Decision PointsNext: Migrations