Skip to main content

​
Overview

SecurAtlas maintains audit trails across multiple subsystems. These trails support compliance requirements for change tracking, access reviews, and incident investigation.
Audit data is append-only by design. Records in audit tables are never updated or deleted under normal operation.

​
Audit Sources

Billing Events

Stripe webhook events and subscription lifecycle changes

Evidence Validations

Evidence review decisions with reviewer, timestamp, and comments

Platform Integrity Log

System-level events: migrations, cron results, admin actions

Timestamp Tracking

created_at, updated_at, and created_by on all records

​
billing_events

Captures all Stripe webhook events for billing audit compliance: 
billing_events (
  id              uuid PRIMARY KEY,
  tenant_id       uuid REFERENCES tenants,
  event_type      text,          -- 'checkout.session.completed', 'invoice.paid', etc.
  stripe_event_id text UNIQUE,   -- Idempotency key
  payload         jsonb,         -- Full Stripe event payload
  processed_at    timestamptz,
  created_at      timestamptz DEFAULT now()
)
Key events tracked:
Event TypeDescription
checkout.session.completedNew subscription created
customer.subscription.updatedPlan change or renewal
customer.subscription.deletedSubscription cancelled
invoice.payment_failedPayment failure
invoice.paidSuccessful payment
The stripe_event_id unique constraint ensures idempotent processing. Duplicate webhook deliveries from Stripe are silently ignored.

​
evidence_validations

Records every evidence review decision, forming the core compliance audit trail: 
evidence_validations (
  id                uuid PRIMARY KEY,
  evidence_item_id  uuid REFERENCES tenant_evidence_items,
  reviewer_id       uuid REFERENCES auth.users,
  status            text,        -- 'accepted', 'rejected'
  comments          text,        -- Reviewer notes
  reviewed_at       timestamptz,
  created_at        timestamptz DEFAULT now()
)

​
Evidence Review Workflow as Audit Trail

The evidence validation workflow creates a complete audit chain:
1

Evidence uploaded

tenant_evidence_items record created with created_by and created_at.
2

Evidence linked to controls

control_evidence_links records created, establishing the compliance mapping.
3

Submitted for review

Evidence status changes to under_review. The updated_at timestamp captures when.
4

Review decision

An evidence_validations record captures who reviewed, when, the decision, and any comments.
5

Maturity recalculated

If accepted, the control maturity sync trigger fires and updates tenant_controls.updated_at.
This chain answers the key audit questions: Who uploaded evidence, what controls it maps to, who reviewed it, when was it reviewed, and what was the decision.

​
platform_integrity_log

Captures system-level events for operational auditing: 
platform_integrity_log (
  id          uuid PRIMARY KEY,
  event_type  text,          -- 'migration_applied', 'cron_executed', 'admin_action'
  actor       text,          -- 'system', 'cron', or user ID
  details     jsonb,         -- Event-specific metadata
  created_at  timestamptz DEFAULT now()
)
Example events:
Event TypeActorDetails
migration_appliedsystem{"version": "20250401092000", "name": "sync_control_maturity"}
cron_executedcron{"job": "nightly_risk_recompute", "tenants_processed": 42}
admin_actionuser-uuid{"action": "disable_tenant", "tenant_id": "..."}
integration_syncsystem{"connection_id": "...", "entities": 150, "findings": 3}

​
Timestamp Tracking

All tenant-scoped tables include standard audit columns: 
created_at    timestamptz DEFAULT now(),
updated_at    timestamptz DEFAULT now(),
created_by    uuid REFERENCES auth.users
An automatic trigger updates updated_at on any row modification: 
CREATE OR REPLACE FUNCTION fn_update_timestamp()
RETURNS TRIGGER AS $$
BEGIN
  NEW.updated_at = now();
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

-- Applied to all tables with updated_at
CREATE TRIGGER set_updated_at
  BEFORE UPDATE ON tenant_controls
  FOR EACH ROW EXECUTE FUNCTION fn_update_timestamp();

​
Querying Audit Data

​
Recent evidence reviews for a tenant

SELECT
  ev.reviewed_at,
  p.display_name AS reviewer,
  ev.status,
  ev.comments,
  tei.title AS evidence_title
FROM evidence_validations ev
JOIN profiles p ON p.id = ev.reviewer_id
JOIN tenant_evidence_items tei ON tei.id = ev.evidence_item_id
WHERE tei.tenant_id = 'tenant-uuid'
ORDER BY ev.reviewed_at DESC
LIMIT 20;

​
Billing event history

SELECT event_type, processed_at, payload->>'amount_total' AS amount
FROM billing_events
WHERE tenant_id = 'tenant-uuid'
ORDER BY created_at DESC;
For compliance audits, export audit data using the Supabase SQL Editor or build a dedicated admin report page. The evidence_validations table is the most critical for SOC 2 and ISO 27001 evidence of review controls.