Audit Trail Design

Status: DRAFT Owner: Engineering Last Review: 2026-02-21 Applicable Standards: SOC 2 (CC4.1, CC4.2, CC7.2, CC7.3) / GDPR (Art. 30) / SEC (recordkeeping)

1. Purpose

This document describes the audit trail mechanisms in the Equa platform — how user actions, system events, and AI agent operations are recorded, stored, and surfaced. It identifies gaps in the current implementation and recommends improvements to meet SOC 2, GDPR, and SEC recordkeeping requirements.

2. Scope

Component	In Scope	Notes
equa-server	Yes	Actions table, EventLogs table, activity module
equa-server (agent)	Yes	Agent audit logger with sensitive field sanitization
equa-web	Partial	Dashboard display of organization activity
PostgreSQL	Yes	Audit data storage
Comet-Bridge	Yes	Browser automation audit (session-scoped and run-oriented streams); local-runtime audit surface, not server-side

For the full technical architecture, see Event and Activity Model.

3. Current Implementation

The platform uses a dual audit system: structured Actions for high-level user operations and flexible EventLogs for detailed event records.

3.1 Actions Table

Source: equa-server/modules/persistence/src/schema.ts (Actions entity)

Column	Type	Purpose
`hash`	Hash (PK)	Content-addressable identifier (extends `HashedTable`)
`organization`	UUID (nullable)	Organization context (nullable for user-level actions)
`type`	UUID	Action type identifier (links to action type definitions)
`user`	UUID	User who performed the action
`created`	Date	Timestamp (`@CreateDateColumn`)
`format`	smallint	Schema version number (default: 1)

Key characteristics:

Content-addressable: The hash-based primary key means identical actions produce the same hash, providing implicit deduplication
Immutable by design intent: The HashedTable base class uses the hash as the primary key, making updates semantically incorrect (a modified record would have a different hash). However, DELETE operations are not prevented at the database level
No payload field: The Actions table stores only the action type UUID — detailed context must be correlated from other sources

3.2 EventLogs Table

Source: equa-server/modules/persistence/src/schema.ts (EventLogs entity)

Column	Type	Purpose
`id`	UUID (PK)	Unique event identifier
`type`	string	Event type (e.g., `"login"`, `"share_transfer"`, `"document_upload"`)
`user`	UUID (nullable)	User who triggered the event
`organization`	UUID (nullable)	Organization context
`data`	JSON	Arbitrary event payload (flexible schema)
`created`	Date	Timestamp
`modified`	Date	Last modification timestamp

Key characteristics:

Flexible schema: The data JSON field can store any structured payload, making it adaptable to new event types without schema migrations
Mutable: Both created and modified timestamps exist, and the record can be updated or deleted
Semi-queryable: JSON payloads can be queried via PostgreSQL JSON operators, but there are no dedicated indexes on the data field

3.3 Activity Flow

3.4 Activity API Endpoints

Source: equa-server/modules/api/src/endpoints/activity-endpoints.ts

Method	Path	Permission	Purpose
`POST`	`/organization/:organization/action`	`canViewOrganization`	Create an action record
`GET`	`/organization/:organization/action`	`canViewOrganization`	Retrieve actions for an organization

4. Agent Audit Logger

Source: equa-server/modules/agent/src/security/guardrails.ts The AI agent (Equanaut) has a dedicated audit logger that records all tool executions with enhanced detail.

4.1 Logged Fields

Field	Description
Tool name	Which tool was invoked
Arguments	Input parameters (sanitized — see 4.2)
Result	`success`, `failed`, or `cancelled`
User	User who initiated the agent session
Organization	Target organization
Conversation ID	Links to the agent conversation context
Execution time	Duration in milliseconds

4.2 Sensitive Field Sanitization

Before logging tool arguments, the audit logger redacts values for fields matching these patterns:

Pattern	Example Fields Redacted
`password`	User passwords, temporary passwords
`token`	OAuth tokens, API keys
`secret`	2FA secrets, client secrets
`apiKey`	Provider API keys
`credential`	Stored credentials

Sanitized fields are replaced with [REDACTED] in the log output.

4.3 Agent Rate Limit Logging

The guardrails system also logs rate limit events:

Event	Trigger
Tool call rate exceeded	More than 30 tool calls per minute (configurable)
Write rate exceeded	More than 10 write operations per minute (configurable)
Destructive rate exceeded	More than 5 destructive operations per hour (configurable)

4.4 Browser Automation Audit (Comet-Bridge)

Source: Comet-Bridge/scripts/browser-audit.mjs, Comet-Bridge/scripts/audit-logger.mjs Comet-Bridge, the browser automation layer used by Equanaut for web-based tasks, maintains its own audit trail independently of the server-side audit system. This is a local-runtime audit surface that records all browser automation sessions and lifecycle events.

Lifecycle Event Types

The browser automation audit captures five lifecycle event types:

Event Type	File Pattern	Trigger
`lifecycle_start`	`lifecycle-start-{runId}-{timestamp}.json`	Run enters `running` state
`lifecycle_update`	`lifecycle-update-{runId}-{timestamp}.json`	Metadata or status update on a running run
`lifecycle_complete`	`lifecycle-complete-{runId}-{timestamp}.json`	Run finishes successfully (`completed` state)
`lifecycle_abort`	`lifecycle-abort-{runId}-{timestamp}.json`	Run intentionally stopped (`aborted` state) — e.g., user cancel or timeout
`lifecycle_fail`	`lifecycle-fail-{runId}-{timestamp}.json`	Run ends with an error (`failed` state)

Each event file contains the full lifecycle envelope (task-thread ID, run ID, status, timestamps, route, agent ID, and failure reason where applicable).

PII Masking Rules

Browser automation sessions may capture screenshots and action logs that contain sensitive content. The following masking rules apply:

Content Type	Masking Behaviour
Credential input fields (passwords, tokens)	Input values are never recorded; field interactions are logged as `[REDACTED]`
Screenshot capture	Configurable via `COMET_AUDIT_SCREENSHOTS`; disabled by default in production
URL parameters	Query parameters matching `token`, `key`, `secret`, `password` patterns are redacted from action logs

Dual-Stream Architecture

Lifecycle events are written to two parallel audit streams simultaneously:

Stream	Writer	Output Location
Session-scoped	`browser-audit.mjs` (`BrowserAuditSession`)	`~/equabot/audit/browser-sessions/{sessionId}/lifecycle.jsonl` + `metadata.json`
Run-oriented	`audit-logger.mjs` (`logLifecycleEvent()`)	`{COMET_OUTPUT_BASE}/audit/{runId}.jsonl`

The runId field cross-links both streams, enabling complete reconstruction of a browser automation run from either the session directory or the run JSONL.

5. Frontend Display

Source: equa-web/src/modules/organization-dashboard/ The organization dashboard displays recent actions for the active organization, providing visibility into team activity. This is a read-only view that queries the activity API endpoints.

6. Audit Trail Gaps

6.1 Mutability

Both actions and event_logs tables allow UPDATE and DELETE operations at the database level. While the HashedTable pattern for Actions discourages updates (the hash would change), there is no technical enforcement preventing deletion of audit records.Risk: An attacker with database access could delete or modify audit records to cover their tracks.

6.2 No Before/After State Tracking

Neither audit system captures the state of an entity before and after a change. For example, when a shareholding is modified, the log records that a change occurred and who made it, but not what the previous values were.Risk: Forensic investigation of unauthorized changes requires correlating multiple data sources and cannot definitively reconstruct the state at a given point in time.

6.3 No Comprehensive Coverage

Not all state-changing operations in the platform trigger audit log entries. The audit system is opt-in — each endpoint must explicitly call the activity module to create records.Risk: Some operations may not be captured, creating blind spots in the audit trail.

6.4 No Log Export or Compliance Reporting

There is no mechanism to export audit logs in a standardized format (e.g., CSV, SIEM-compatible JSON) or to generate compliance reports from the audit data.Risk: Manual effort required for audit preparation and regulatory reporting.

6.5 No External Log Shipping

Audit logs are stored only in the application database. There is no log shipping to external, append-only storage (e.g., AWS CloudWatch, Datadog, Splunk).Risk: If the database is compromised, all audit data is compromised.

6.6 No Real-Time Alerting

There is no real-time monitoring or alerting on audit events. Suspicious patterns (e.g., bulk data access, privilege escalation, off-hours activity) are not detected automatically.Risk: Security incidents may go undetected until manual review.

7. Recommended Improvements

7.1 Priority 1: Immutable Audit Storage

Improvement	Implementation
Append-only audit table	Create a new `audit_log` table with database-level `REVOKE DELETE, UPDATE` on the application role
Structured payloads	Include `entity_type`, `entity_id`, `action`, `before_state` (JSON), `after_state` (JSON), `ip_address`, `user_agent`
Trigger-based capture	Use PostgreSQL triggers on critical tables (users, shareholdings, members, roles) to auto-capture before/after states

7.2 Priority 2: External Log Shipping

Improvement	Implementation
Ship to cloud logging	Configure PostgreSQL logical replication or application-level shipping to AWS CloudWatch Logs or a SIEM
Separate retention	External logs retained for 7+ years (SEC requirement) independently of the application database
Tamper evidence	External storage provides an independent copy that cannot be altered by application-level access

7.3 Priority 3: Comprehensive Coverage

Improvement	Implementation
Middleware-level logging	Add Express middleware that automatically logs all state-changing requests (POST, PUT, PATCH, DELETE)
Opt-out instead of opt-in	Default to logging all mutations; require explicit exclusion for non-sensitive operations
Include request metadata	Log IP address, user agent, request ID for correlation

7.4 Priority 4: Monitoring and Alerting

Improvement	Implementation
Anomaly detection	Alert on: bulk data access (>100 records/min), off-hours admin operations, repeated auth failures, privilege escalation
SIEM integration	Forward structured audit events to a SIEM platform for centralized monitoring
Dashboard	Build an audit dashboard showing event volume, unusual patterns, and compliance metrics

7.5 Priority 5: Export and Reporting

Improvement	Implementation
Audit export API	New endpoint to export audit logs as CSV or JSON with date range and entity filters
Compliance reports	Pre-built report templates for SOC 2 auditors (access reviews, change logs, incident timelines)
GDPR Art. 30 report	Automated Records of Processing Activities report generation

8. What Should Be Audited

For SOC 2 and SEC compliance, the following events should be captured in the audit trail:

Category	Events
Authentication	Login success/failure, logout, password change, 2FA enable/disable, magic link generation
Authorization	Role assignment/removal, permission changes, member addition/removal
Equity Operations	Share issuance, transfer, cancellation, option grant, exercise, vesting events
Document Operations	Upload, download, delete, rename, data room access grant/revoke
Financial Operations	Payment creation, billing changes, subscription modifications
Organization Management	Create, update, delete organization, settings changes
Admin Operations	Site admin actions, user enable/disable, global role assignments
Agent Operations	Tool calls (already logged), confirmation requests, rate limit events

9. Regulatory References

Standard	Requirement	Current Status
SOC 2 CC4.1	Design and implement monitoring activities	Gap — no real-time monitoring or alerting
SOC 2 CC4.2	Evaluate and communicate deficiencies in a timely manner	Gap — no automated deficiency detection
SOC 2 CC7.2	Monitor system components for anomalies	Gap — only health check exists
SOC 2 CC7.3	Evaluate security events to determine incidents	Partial — agent audit logger and Comet-Bridge browser automation audit exist; no general event evaluation or real-time incident correlation
GDPR Art. 30	Records of processing activities	Partial — EventLogs capture some processing, but not comprehensive
SEC 17a-4	Recordkeeping for financial records	Gap — audit logs are mutable and not exported

10. Revision History

Date	Version	Author	Changes
2026-02-21	0.1	Agent (Phase 5 Session A)	Initial draft from code analysis

​Audit Trail Design

​1. Purpose

​2. Scope

​3. Current Implementation

​3.1 Actions Table

​3.2 EventLogs Table

​3.3 Activity Flow

​3.4 Activity API Endpoints

​4. Agent Audit Logger

​4.1 Logged Fields

​4.2 Sensitive Field Sanitization

​4.3 Agent Rate Limit Logging

​4.4 Browser Automation Audit (Comet-Bridge)

​Lifecycle Event Types

​PII Masking Rules

​Dual-Stream Architecture

​5. Frontend Display

​6. Audit Trail Gaps

​6.1 Mutability

​6.2 No Before/After State Tracking

​6.3 No Comprehensive Coverage

​6.4 No Log Export or Compliance Reporting

​6.5 No External Log Shipping

​6.6 No Real-Time Alerting

​7. Recommended Improvements

​7.1 Priority 1: Immutable Audit Storage

​7.2 Priority 2: External Log Shipping

​7.3 Priority 3: Comprehensive Coverage

​7.4 Priority 4: Monitoring and Alerting

​7.5 Priority 5: Export and Reporting

​8. What Should Be Audited

​9. Regulatory References

​10. Revision History