git.stella-ops.org/docs/modules/authority/operations/break-glass-account.md

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

# /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

# 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

# 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

{
  "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

# Use session token for operations
stella --token "${BG_TOKEN}" system status
stella --token "${BG_TOKEN}" service restart authority

Step 4: Extend Session (If Needed)

# Extend session before expiration
stella auth break-glass extend \
  --session bg-session-abc123 \
  --reason "Recovery still in progress"

Step 5: Terminate Session

# 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

{
  "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

# 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

{
  "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

   stella auth break-glass terminate --session ${SESSION_ID} --force
   

2. Contain: Disable break-glass temporarily

   stella config set authority.breakGlass.enabled false --apply
   

3. Investigate: Query audit logs

   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
• Authority Architecture
• Incident Response Playbook