old sprints work, new sprints for exposing functionality via cli, improve code_of_conduct and other agents instructions
This commit is contained in:
master
330
docs/modules/authority/operations/break-glass-account.md
Normal file
330
docs/modules/authority/operations/break-glass-account.md
Normal file
@@ -0,0 +1,330 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user