Audit log — privileged actions, retention, export

Every privileged action in FedGrade writes to an append-only audit log. The log is the system of record for compliance reviews and incident response.

What "append-only" means here, precisely: tenant roles have no UPDATE or DELETE path to the table — the write path is insert-only and enforced at the database layer. It does not mean cryptographically tamper-evident. There is no hash chain today (see Integrity below).

What's logged

The audit log captures every action that materially affects access, data, or configuration:

• Authentication. Login success, login failure, MFA challenge, MFA bypass, session expiry, password reset, PIV-CAC card-present (Government tier, roadmap), SSO assertion.
• Authorization. Workspace role change, scope grant on API key, share-link creation, share-link revocation, public/private toggle.
• Data access. Brief export, DOCX export, workspace archive request, share-link claim by external viewer, API request (response code + bytes returned).
• Configuration. Persona create/update/delete, watched-agency add/remove, saved-search create/edit/delete, webhook endpoint configure, signing secret rotation.
• Moderation. Inaccuracy report submitted, claim retracted, claim reinstated, paragraph rewritten.
• Billing. Tier change, seat add, seat remove, payment method update.

Every entry carries exactly these columns: id (UUID), workspace_id, user_id, action, entity_type, entity_id, ip, user_agent, request_id, payload_summary, metadata (JSON), result, and created_at.

Retention by tier

These are the retention commitments attached to each tier. Automated horizon enforcement (scheduled purge of entries past horizon) is on the roadmap; today entries are retained and no automated purge job runs. Any tier-specific archival arrangement is scoped in the contract, not applied automatically by the platform.

Viewing

/audit-log renders a filterable table. Filters: actor, action, resource type, IP, date range. The table is paginated at 100 rows. Self-service export (CSV or JSONL) is a Government-tier capability — on other tiers the log is viewable but the export endpoint declines.

Export to customer-controlled storage — Government (roadmap)

Streaming the audit log to a customer-owned S3 bucket of record — the usual FedRAMP / agency-ATO requirement for "logs of record retained in customer-controlled storage" — is a Government-tier roadmap item, scoped per agency during onboarding. It is not shipped: there is no audit-log streamer in the product today. The shipped Government capability is the self-service CSV/JSONL export above; other tiers view in-app.

Integrity

What exists today: the log is append-only for tenant roles — the write path is insert-only and there is no update or delete path exposed to a workspace. That is the whole of the integrity property we currently provide.

What does not exist: there is no per-entry cryptographic hash chain. Nothing computes a rolling digest over prior rows, and exports carry no per-day hash manifest. A hash chain and out-of-band verifiable export manifests are on the roadmap and will be documented here when they ship — with the migration and the verifier both live, not before.

Do not represent FedGrade's audit log as cryptographically tamper-evident in a security questionnaire. "Append-only, database-enforced" is the accurate phrase.

See Data residency for the storage-layer treatment and Data export for non-audit exports.