# Break-Glass Account Operations This document describes the break-glass emergency access mechanism for Stella Ops Authority when normal authentication is unavailable. ## Overview Break-glass accounts provide emergency administrative access when: - PostgreSQL database is unavailable - Identity provider (IdP) is unreachable - Network partition isolates Authority service - Disaster recovery scenarios ## Security Model ### Activation Requirements | Requirement | Description | |-------------|-------------| | Reason code | Mandatory selection from approved list | | Reason details | Free-text justification (logged) | | Time limit | Maximum 15 minutes per session | | Extensions | Maximum 2 extensions with re-authentication | | Alert dispatch | Immediate notification to security team | ### Approved Reason Codes | Code | Description | Use Case | |------|-------------|----------| | `emergency-incident` | Active security incident | Security team responding to breach | | `database-outage` | PostgreSQL unavailable | DBA performing recovery | | `security-event` | Proactive security response | Patching critical vulnerability | | `scheduled-maintenance` | Planned maintenance window | Pre-approved maintenance | | `disaster-recovery` | DR scenario activation | DR team executing runbook | ## Configuration ### Local Policy File ```yaml # /etc/stellaops/authority/local-policy.yaml schemaVersion: "1.0.0" lastUpdated: "2026-01-15T12:00:00Z" breakGlass: enabled: true accounts: - id: "break-glass-admin" name: "Emergency Administrator" passwordHash: "$argon2id$v=19$m=65536,t=3,p=4$..." roles: ["admin"] permissions: - "authority:*" - "platform:admin" - "orch:operate" sessionTimeoutMinutes: 15 maxExtensions: 2 requireReasonCode: true allowedReasonCodes: - "emergency-incident" - "database-outage" - "security-event" - "scheduled-maintenance" - "disaster-recovery" - id: "break-glass-readonly" name: "Emergency Read-Only" passwordHash: "$argon2id$v=19$m=65536,t=3,p=4$..." roles: ["auditor"] permissions: - "audit:read" - "obs:incident" sessionTimeoutMinutes: 30 maxExtensions: 1 requireReasonCode: true allowedReasonCodes: - "emergency-incident" - "security-event" alerting: onActivation: true channels: - type: "email" recipients: ["security@company.com", "oncall@company.com"] - type: "slack" webhook: "${SLACK_SECURITY_WEBHOOK}" - type: "pagerduty" serviceKey: "${PAGERDUTY_SERVICE_KEY}" ``` ### Password Generation ```bash # Generate Argon2id hash for break-glass password # Use a strong, unique password stored securely offline # Option 1: Using argon2 CLI echo -n "StrongBreakGlassPassword123!" | argon2 "$(openssl rand -hex 16)" -id -t 3 -m 16 -p 4 -e # Option 2: Using Python python3 << 'EOF' from argon2 import PasswordHasher ph = PasswordHasher(time_cost=3, memory_cost=65536, parallelism=4) hash = ph.hash("StrongBreakGlassPassword123!") print(hash) EOF ``` ### Secure Storage Break-glass credentials should be: 1. Stored in a physical safe (not digital-only) 2. Split between multiple custodians (M-of-N) 3. Sealed with tamper-evident packaging 4. Inventoried and audited quarterly ## Activation Procedure ### Step 1: Initiate Break-Glass ```bash # Via CLI stella auth break-glass \ --account break-glass-admin \ --reason emergency-incident \ --details "PostgreSQL cluster unreachable, DBA on-call" # Via API curl -X POST https://authority.company.com/auth/break-glass \ -H "Content-Type: application/json" \ -d '{ "accountId": "break-glass-admin", "password": "StrongBreakGlassPassword123!", "reasonCode": "emergency-incident", "reasonDetails": "PostgreSQL cluster unreachable, DBA on-call" }' ``` ### Step 2: Receive Session Token ```json { "sessionId": "bg-session-abc123", "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...", "expiresAt": "2026-01-15T12:49:56Z", "permissions": ["authority:*", "platform:admin", "orch:operate"], "extensionsRemaining": 2 } ``` ### Step 3: Perform Emergency Operations ```bash # Use session token for operations stella --token "${BG_TOKEN}" system status stella --token "${BG_TOKEN}" service restart authority ``` ### Step 4: Extend Session (If Needed) ```bash # Extend session before expiration stella auth break-glass extend \ --session bg-session-abc123 \ --reason "Recovery still in progress" ``` ### Step 5: Terminate Session ```bash # Always explicitly terminate when done stella auth break-glass terminate \ --session bg-session-abc123 \ --resolution "Database recovered, normal auth restored" ``` ## Audit Trail ### Event Types | Event | Description | Severity | |-------|-------------|----------| | `break_glass.activated` | Session started | WARNING | | `break_glass.extended` | Session extended | WARNING | | `break_glass.terminated` | Session ended | INFO | | `break_glass.expired` | Session timed out | WARNING | | `break_glass.action` | Action performed | INFO | | `break_glass.denied` | Access denied | ERROR | ### Sample Audit Entry ```json { "eventType": "authority.break_glass.activated", "timestamp": "2026-01-15T12:34:56.789Z", "severity": "warning", "session": { "id": "bg-session-abc123", "accountId": "break-glass-admin", "reasonCode": "database-outage", "reasonDetails": "PostgreSQL cluster unreachable, DBA on-call" }, "client": { "ip": "10.0.0.5", "userAgent": "StellaOps-CLI/2027.Q1" }, "timing": { "activatedAt": "2026-01-15T12:34:56Z", "expiresAt": "2026-01-15T12:49:56Z", "extensionsRemaining": 2 } } ``` ### Audit Query ```bash # Query break-glass audit events stella audit query \ --type "break_glass.*" \ --since "2026-01-01" \ --format json # Generate break-glass usage report stella audit report break-glass \ --period monthly \ --output break-glass-report.pdf ``` ## Alert Configuration ### Email Template ``` Subject: [ALERT] Break-Glass Access Activated - ${REASON_CODE} A break-glass account has been activated: Account: ${ACCOUNT_ID} Reason: ${REASON_CODE} Details: ${REASON_DETAILS} Session ID: ${SESSION_ID} Activated: ${ACTIVATED_AT} Expires: ${EXPIRES_AT} Client IP: ${CLIENT_IP} This session will automatically expire in 15 minutes. If this activation was not authorized, take immediate action: 1. Terminate the session: stella auth break-glass terminate --session ${SESSION_ID} 2. Investigate the access attempt 3. Contact Security Operations ``` ### Slack Alert ```json { "blocks": [ { "type": "header", "text": { "type": "plain_text", "text": "Break-Glass Access Activated" } }, { "type": "section", "fields": [ {"type": "mrkdwn", "text": "*Account:*\n${ACCOUNT_ID}"}, {"type": "mrkdwn", "text": "*Reason:*\n${REASON_CODE}"}, {"type": "mrkdwn", "text": "*Session:*\n${SESSION_ID}"}, {"type": "mrkdwn", "text": "*Expires:*\n${EXPIRES_AT}"} ] } ] } ``` ## Testing ### Quarterly Drill Conduct quarterly break-glass activation drills: 1. Schedule maintenance window 2. Simulate database outage 3. Activate break-glass account 4. Perform test operations 5. Verify audit trail 6. Terminate session 7. Document drill results ### Test Checklist - [ ] Break-glass activation successful - [ ] Alerts dispatched correctly - [ ] Session timeout enforced - [ ] Extension mechanism works - [ ] Audit events captured - [ ] Session termination works - [ ] Post-drill report generated ## Incident Response ### On Unauthorized Break-Glass Activation 1. **Immediate**: Terminate session ```bash stella auth break-glass terminate --session ${SESSION_ID} --force ``` 2. **Contain**: Disable break-glass temporarily ```bash stella config set authority.breakGlass.enabled false --apply ``` 3. **Investigate**: Query audit logs ```bash stella audit query --type "break_glass.*" --session ${SESSION_ID} ``` 4. **Remediate**: Rotate credentials if compromised 5. **Report**: File incident report per security policy ## Related Documentation - [Local RBAC Fallback](../local-rbac-fallback.md) - [Authority Architecture](../architecture.md) - [Incident Response Playbook](../../security/incident-response.md)