Audit Trail Design

Event logging, action tracking, agent audit logs, gap analysis, and improvement roadmap

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

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)

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 exists, but no general event evaluation
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