Break-glass

Goal

Understand and use controlled privilege escalation (break-glass) to temporarily bypass RLS policies with full auditability.

Prerequisites

• SQL session with a user who has been granted the BREAK_GLASS capability.
• A healthy audit subsystem (break-glass cannot activate if audit is unavailable).

What is break-glass?

Break-glass is AngaraBase’s mechanism for controlled, time-limited, fully audited bypass of row-level security policies. It exists because SUPERUSER alone does not bypass RLS — this is a deliberate design choice.

Key properties:

• Activation requires a mandatory reason and a mandatory TTL.
• Every query executed during break-glass generates a dedicated break_glass_query audit entry.
• There is no “silent” bypass — the audit chain always records break-glass activity.
• This is a first-in-class database feature: neither PostgreSQL nor MS SQL Server have a built-in break-glass mechanism with TTL + reason + mandatory audit.

Steps

1) Grant the break-glass capability

A SECURITY_ADMIN grants the BREAK_GLASS role to a user or role:

GRANT BREAK_GLASS TO dba_team;

2) Activate break-glass

The user who has been granted BREAK_GLASS activates it with a reason and duration:

SET BREAK_GLASS REASON='INCIDENT-789: data corruption investigation' TTL='2h';

Duration format: '15m', '2h', '1d' etc. Maximum TTL is controlled by the server configuration (see below).

3) Check status

SELECT * FROM angara_break_glass_status();

Returns: is_active, reason, expires_at, activated_at.

4) Work under break-glass

While break-glass is active, RLS policies are bypassed. Every query in this session generates an audit entry with event_type = 'break_glass_query', including the full (sanitized) SQL text.

5) Deactivate (manual or automatic)

RESET BREAK_GLASS;

If not deactivated manually, break-glass auto-expires when the TTL elapses. After expiry, RLS applies again immediately.

6) Revoke the capability

REVOKE BREAK_GLASS FROM dba_team;

Configuration

Also exposed as security.break_glass_max_ttl in sys.settings.

Audit trail

All break-glass lifecycle events are recorded:

Invariants

1. Audit must be healthy. If the audit subsystem is down or corrupted, break-glass activation fails (fail-closed).
2. TTL is mandatory. SET BREAK_GLASS without TTL → error.
3. Reason is mandatory. SET BREAK_GLASS without REASON → error.
4. Max TTL is server-enforced. Exceeding security.break_glass_max_ttl → 22023 invalid_parameter_value.
5. No refresh. A client cannot extend the TTL — deactivate and re-activate with a new reason/TTL instead.
6. SUPERUSER ≠ RLS bypass. Only BREAK_GLASS bypasses RLS.

Expected result

• SET BREAK_GLASS with valid reason and TTL activates bypass; angara_break_glass_status() confirms.
• All queries during break-glass appear in sys.audit_log with event_type = 'break_glass_query'.
• After TTL expiry or RESET BREAK_GLASS, RLS enforcement resumes.
• Invalid TTL returns 22023; missing reason or TTL returns an error.

Troubleshooting

• 22023 invalid_parameter_value on SET BREAK_GLASS The TTL exceeds security.break_glass_max_ttl or is in an invalid format. Check the max TTL setting and use a supported duration format ('15m', '2h', '1d').
• 42501 insufficient_privilege on SET BREAK_GLASS The current user has not been granted BREAK_GLASS. A SECURITY_ADMIN must run GRANT BREAK_GLASS TO <user>.
• Break-glass activation fails with “audit unavailable” The audit subsystem must be healthy. Check ANGARABASE_AUDIT_LOG_PATH and audit key material if TDE is enabled.
• Break-glass expired unexpectedly TTL is server-enforced and cannot be refreshed. Deactivate and re-activate with a new reason and TTL.
• Need a bug-report artifact? See ../reference/support.md.

Links

• Security model overview: overview.md
• Authorization (RLS policies): authorization.md
• Audit: audit.md
• Known issues: ../reference/known-issues.md