Audit

Goal

Understand and configure AngaraBase’s tamper-evident audit subsystem: chain verification, DML audit policy, and JSON export.

Prerequisites

A running AngaraBase instance with audit enabled (default).
SQL session with SECURITY_ADMIN or SUPERUSER privileges (for configuration changes).
Write-accessible path for the audit log file.

Audit chain concept

AngaraBase maintains an append-only, tamper-evident audit trail:

Every security-relevant event (auth, DDL, DCL, policy changes, break-glass lifecycle) produces an AuditEvent.
Each event contains prev_hash — a SHA-256 hash of the preceding entry, forming a hash chain.
Breaking or modifying any entry invalidates all subsequent hashes, making tampering detectable.
The chain is separate from the transactional data path — audit events are recorded even for rolled-back transactions.

Audit scope

Event category	v0 (baseline)	v1
Auth (success / failure / disconnect)	Yes	Yes
DDL (CREATE / ALTER / DROP)	Yes	Yes
DCL (GRANT / REVOKE)	Yes	Yes
User / role management	Yes	Yes
Security policy changes	Yes	Yes
Break-glass lifecycle	Yes	Yes
DML (SELECT / INSERT / UPDATE / DELETE)	No	Yes (policy-driven)
Key operations	No	Yes

Steps

1) Verify chain integrity

SELECT * FROM angara_audit_verify_chain();

Returns is_valid, first_broken_seq, and details. A healthy chain returns is_valid = true.

2) Query the audit log

SELECT * FROM sys.audit_log
WHERE event_type = 'break_glass_query'
 AND timestamp > now() - INTERVAL '24 hours'
ORDER BY seq DESC
LIMIT 50;

Columns: seq, timestamp, event_type, user_name, auth_method, client_ip, database, session_claims, payload, prev_hash.

3) Configure audit v1 DML policy

DML audit is controlled by three knobs:

export ANGARABASE_AUDIT_DML_MODE=allowlist
export ANGARABASE_AUDIT_DML_ALLOWLIST=public.users,public.payments

Mode	Behaviour
`off`	No DML events recorded (default).
`allowlist`	Record DML only for listed `schema.table` entries — targeted compliance.
`denylist`	Record DML for all tables except those listed — broad coverage with exclusions.

Use ANGARABASE_AUDIT_DML_DENYLIST for the denylist.

Malformed policy or ambiguous object references cause a startup/config-apply rejection (fail-closed).

4) Configure audit log path

export ANGARABASE_AUDIT_LOG_PATH=/var/lib/angarabase/audit/audit.jsonl

The path must be writable. If the path is inaccessible, audit writes fail-closed.

5) Configure JSON export

export ANGARABASE_AUDIT_EXPORT_JSON_ENABLED=1
export ANGARABASE_AUDIT_EXPORT_RATE_LIMIT_RPS=50

Export is bounded and rate-limited. Export failures are reported but never expose secret payload fragments in error text.

6) TDE interaction

When TDE is enabled (ANGARABASE_TDE_ENABLE=1), the audit sink on disk is encrypted transparently:

Key: audit_dek = KDF(master_key, domain="audit-v0", key_id).
sys.audit_log decrypts on read when the correct key is available.
Without the key, audit read/write is impossible (fail-closed).
Encrypted audit data remains encrypted in backups and copied artefacts.

See encryption.md for TDE configuration.

Expected result

angara_audit_verify_chain() returns is_valid = true for an intact chain.
sys.audit_log shows auth, DDL, DCL, policy, and break-glass events.
With DML policy set to allowlist or denylist, matching DML operations appear in the audit log.
TDE-encrypted audit files are unreadable without the master key.

Troubleshooting

angara_audit_verify_chain() returns is_valid = false The chain has been tampered with or corrupted. Note the first_broken_seq and investigate the audit file. The audit subsystem can self-repair by truncating to the last valid entry.
DML events not appearing in audit log Check audit.dml_mode — default is off. Verify that the target table is in the allowlist (or not in the denylist).
Audit write failures after enabling TDE Verify ANGARABASE_TDE_MASTER_KEY_HEX and key validity. Fail-closed behaviour is expected when key material is missing.
Break-glass activation fails with “audit subsystem unavailable” Break-glass requires a healthy audit subsystem. Fix the audit path or key material first.
Need a bug-report artifact? See ../reference/support.md.

AngaraBook