Audit Log Explorer

Every API write in Cognethics A7 is recorded in an immutable, SHA-256 hash-chained audit trail. Tenants can query it, export it, and verify the chain themselves to prove no entry has been modified, deleted, or back-dated.

Compliance-grade hash chain across all events

Both the operational and governance audit logs are backed by the same compliance-grade hash chain. Each row carries:

• A monotonically increasing sequence_number within its tenant
• A previous_hash linking it to the prior row's entry_hash
• An entry_hash computed across every immutable field of the row plus previous_hash

If anyone — including a database administrator — alters, deletes, or back-dates a row, the chain breaks at that point and the next call to verify-chain flags the first offending entry.

Two audit ledgers, one chain primitive

1. Operational Audit Log (SystemAuditLog)

Records every CRUD operation across the platform.

Properties:

• Immutable: Application-level save() guard + PostgreSQL trigger reject every UPDATE except the single one-time entry-hash seal; every DELETE is blocked.
• Tenant-scoped: Mandatory tenant foreign key; organization filtering available.
• Hash-chained: SHA-256 chain, per-tenant. Verifiable via POST /api/audit/verify-chain/.
• Indexed: Efficient queries by timestamp, user, action, entity, category, sequence number.
• Self-auditing: Exports are themselves logged via log_data_export.
• CSV-exportable: Up to 10,000 rows per export; full query syntax supported.

Fields captured:

• action (create, read, update, delete, export, access, system)
• category (auth, crud, access, export, system)
• entity_type & entity_id (what was changed)
• changes (JSON diff of before/after)
• user_id, session_id (JWT jti), ip_address, user_agent
• request_method, request_path, response_status
• timestamp (UTC)
• previous_hash, entry_hash, sequence_number (chain)

Use case: Compliance review, DSAR requests, operational debugging, data lineage, chain-of-custody proofs.

2. Governance Audit Ledger (GovernanceAuditEntry)

Records policy decisions, delegations, escalations, and state transitions — with the same hash chain primitive, additionally bound to distributed-tracing identifiers.

Properties:

• Hash-chained: SHA-256 chain with previous_hash + entry_hash (append-only ledger).
• OTEL-bound: Includes trace_id + span_id in the hash for distributed-trace correlation.
• Immutable: Append-only; no modifications or deletions allowed.
• Verifiable: Call verify_chain() to prove no entry was tampered with.

Fields captured:

• governance action (policy evaluation, delegation approval, escalation, state change)
• actor & target personas
• decision outcome
• hash chain (previous, current, verifiable)
• trace IDs (distributed tracing)
• timestamp

Use case: Compliance audits (SOC 2, HIPAA), governance verification, delegation audit trail, cross-system correlation.

How to Query

REST API

List audit log entries:

curl -H "Authorization: Bearer <token>" \
  "https://<tenant>.cognethics.com/api/audit/?action=create&entity_type=invoice&date_from=2026-05-01&date_to=2026-05-21&page=1&page_size=50"

Export as CSV:

curl -H "Authorization: Bearer <token>" \
  "https://<tenant>.cognethics.com/api/audit/export/?action=update&date_from=2026-05-01&date_to=2026-05-21" \
  > audit_export.csv

Verify the hash chain

Both ledgers expose a verifier. The operational ledger's verifier runs across the caller's whole tenant slice (or a sequence range you specify).

Verify the operational ledger:

curl -X POST -H "Authorization: Bearer <token>" \
  "https://<tenant>.cognethics.com/api/audit/verify-chain/" \
  -H "Content-Type: application/json" \
  -d '{}'

Optional body fields:

• organization_id — restrict to one organization within the tenant
• sequence_from — start at this sequence number (default: 1)
• sequence_to — stop at this sequence number (default: latest)

Response:

{
  "is_valid": true,
  "total_entries": 218010,
  "first_invalid_entry_id": null,
  "error_details": null,
  "sequence_from": 1,
  "sequence_to": 218010,
  "tenant_id": "8a2e8037-96f9-47d1-aef3-3f9c42d48fd0",
  "verified_at": "2026-05-21T20:12:25.165646+00:00"
}

If any row has been altered — even at the database layer with the immutability trigger bypassed — the response identifies the first offending entry:

{
  "is_valid": false,
  "total_entries": 218010,
  "first_invalid_entry_id": "0e97604e-3887-46c3-a3d6-6b3236d59968",
  "error_details": "Entry 218009 entry_hash mismatch (possible tampering). Expected: 4df9cb7f515bf398..., Got: d148f12ea2707b21..."
}

Verify the governance ledger:

curl -X GET -H "Authorization: Bearer <token>" \
  "https://<tenant>.cognethics.com/api/agents/governance-audit/verify_chain/?governed_agent=<id>"

MCP (Programmatic)

Call from any agent with the admin.view_audit_logs permission:

from cognethics.mcp.client import PrismClient

client = PrismClient(token="...")
response = client.call(
    app="core",
    entity="audit_log",
    operation="list",
    filters={
        "action": "create",
        "entity_type": "invoice",
        "date_from": "2026-05-01",
        "date_to": "2026-05-21"
    },
    page=1,
    page_size=50
)

for entry in response["results"]:
    print(f"{entry['timestamp']} | {entry['action']} | {entry['entity_type']} | {entry['user_id']}")

Filters & Fields

Available filters:

• action (create, read, update, delete, export, access, system)
• category (auth, crud, access, export, system)
• entity_type (any entity on the platform)
• entity_id (specific record)
• user_id (audit entries by specific user)
• date_from, date_to (ISO 8601)

Sortable fields:

• timestamp (default: descending)
• action, category, entity_type, user_id, sequence_number

Compliance Notes

• SOC 2 / HIPAA: Immutability + per-tenant hash-chain integrity meet audit logging requirements (CC6.1, HIPAA 45 CFR 164.312(b)).
• Self-audit: Every export is logged, creating a verifiable record of "who accessed what and when."
• Defense in depth: Three independent layers reject tampering — Django ImmutableAuditModel blocks at the application layer, a PostgreSQL BEFORE UPDATE OR DELETE trigger rejects mutations at the database layer, and the SHA-256 chain detects after-the-fact rewrites if either of the first two is bypassed.
• Retention: Audit entries are retained per your organizational policy.

Examples

DSAR (Data Subject Access Request)

Find all operations on a specific customer's record:

curl -H "Authorization: Bearer <token>" \
  "https://tenant.cognethics.com/api/audit/?entity_type=Contact&entity_id=contact-uuid&date_from=2025-01-01"

Incident Investigation

Find all changes to a sensitive field in the last 7 days:

curl -H "Authorization: Bearer <token>" \
  "https://tenant.cognethics.com/api/audit/?action=update&entity_type=PaymentRecord&date_from=2026-05-14&date_to=2026-05-21" \
  | jq '.results[] | select(.changes.amount_usd != null)'

Chain verification (compliance review)

Run a periodic chain check across a tenant's whole audit history:

curl -X POST -H "Authorization: Bearer <token>" \
  "https://tenant.cognethics.com/api/audit/verify-chain/" \
  -d '{}'

Or verify a specific range — useful when the chain is long and you want to anchor evidence to a previously-signed sequence number:

curl -X POST -H "Authorization: Bearer <token>" \
  "https://tenant.cognethics.com/api/audit/verify-chain/" \
  -d '{"sequence_from": 1, "sequence_to": 100000}'

Tenant Permissions

By default, the audit log is accessible to users with the admin.view_audit_logs permission (typically security officers, compliance teams, and system admins). Your organization may assign this permission to compliance roles as needed.

Questions?

For questions about the audit log or your compliance posture, contact our Security & Compliance team through the form below.