emergency-access/README.md

Emergency Access Server

A fail-safe webserver that provides secure access to decryption key parts with mandatory notification system integration. Designed for emergency scenarios where key retrieval must be monitored and logged.

Features

• Fail-safe design: All operations require successful notification delivery
• Dual endpoint system: Emergency key access and health monitoring
• dschep/ntfy integration: Real-time notifications via multiple backends (Pushover, Pushbullet, Slack, etc.)
• Real-time log monitoring: All application logs automatically sent to notification backends
• Configurable security: Random endpoint paths and file locations
• Caddy reverse proxy ready: Runs on localhost for secure proxy setup
• Systemd integration: Automatic startup and service management
• Comprehensive logging: Detailed audit trail of all operations with live notifications

Architecture

The system consists of two main endpoints:

1. Emergency Key Endpoint (/emergency-key-xyz123):

   • Serves the actual decryption key part
   • Sends critical alerts via dschep/ntfy to configured backends
   • Fails closed if notifications cannot be sent

2. Health Check Endpoint (/health-check-abc456):

   • Verifies all system components required for emergency access
   • Tests both health and emergency notification backends
   • Validates file system access for both dummy and key files
   • Ensures complete emergency system readiness
   • Used for regular system verification

Log Monitoring: All application logs (WARNING level and above by default) are automatically sent to the health backends for real-time monitoring and alerting.

The server runs on localhost:1127 by default and is designed to be accessed through a Caddy reverse proxy for security and TLS termination.

Installation

Quick Install

Run the automated installation script as root:

sudo ./install.sh

Manual Installation

1. Install system dependencies:

   # Ubuntu/Debian
   sudo apt-get update
   sudo apt-get install python3 python3-pip python3-venv
   
   # RHEL/CentOS/Fedora (venv is built-in with Python 3.3+)
   sudo dnf install python3 python3-pip
   
   # Verify venv is available
   python3 -m venv --help
   

2. Create service user:

   sudo groupadd --system emergency-access
   sudo useradd --system --gid emergency-access --home-dir /opt/emergency-access \
               --shell /bin/false emergency-access
   

3. Setup directories:

   sudo mkdir -p /opt/emergency-access /etc/emergency-access
   sudo chown emergency-access:emergency-access /opt/emergency-access /etc/emergency-access
   sudo chmod 755 /opt/emergency-access
   sudo chmod 750 /etc/emergency-access
   

4. Install application:

   sudo cp *.py requirements.txt /opt/emergency-access/
   sudo cp config.json /etc/emergency-access/
   sudo chown -R emergency-access:emergency-access /opt/emergency-access
   

5. Setup Python environment:

   sudo -u emergency-access python3 -m venv /opt/emergency-access/venv
   sudo -u emergency-access /opt/emergency-access/venv/bin/pip install -r /opt/emergency-access/requirements.txt
   

6. Install systemd service:

   sudo cp emergency-access.service /etc/systemd/system/
   sudo systemctl daemon-reload
   

Configuration

Main Configuration File

Edit /etc/emergency-access/config.json:

{
  "server": {
    "host": "127.0.0.1",
    "port": 1127
  },
  "routes": {
    "key_route": "/emergency-key-a7f9d2e1",
    "health_route": "/health-check-b8e3f4a2"
  },
  "files": {
    "key_file": "/etc/emergency-access/key-part.txt",
    "dummy_file": "/etc/emergency-access/dummy.txt"
  },
  "notifications": {
    "key_backends": ["matrix_sec", "pushover_emergency"],
    "health_backends": ["matrix_health"],
    "config_path": "/etc/emergency-access/ntfy.yml",
    "key_message": "🚨 EMERGENCY: Decryption key accessed from server",
    "health_message": "✅ Emergency access server health check completed",
    "log_level": "WARNING",
    "send_all_logs": true
  }
}

Configuration Options

Server Settings

• host: Bind address (default: 127.0.0.1 for localhost only)
• port: Listen port (default: 1127)

Route Settings

• key_route: Random path for key access (e.g., /emergency-key-a7f9d2e1)
• health_route: Path for health checks (e.g., /health-check-b8e3f4a2)

File Settings

• key_file: Path to the actual key part file
• dummy_file: Path to dummy content for health checks (health check also validates key file accessibility)

Notification Settings

• key_backends: List of backend names from /etc/emergency-access/ntfy.yml for key access alerts
• health_backends: List of backend names from /etc/emergency-access/ntfy.yml for health check notifications and all application logs
• config_path: Path to the ntfy configuration file (default: /etc/emergency-access/ntfy.yml)
• key_message: Message sent when key is accessed
• health_message: Message sent for health checks
• log_level: Minimum log level to send to health backends ("INFO", "WARNING", "ERROR")
• send_all_logs: Whether to send application logs to health backends (true/false)

Backend Name Examples

• matrix_sec: Matrix backend for security alerts
• pushover_emergency: Pushover backend for emergency notifications
• slack_critical: Slack backend for critical alerts
• Any backend name configured in /etc/emergency-access/ntfy.yml

Key and Dummy Files

1. Create key file:

   echo "YOUR_ACTUAL_KEY_PART_HERE" | sudo tee /etc/emergency-access/key-part.txt
   sudo chown emergency-access:emergency-access /etc/emergency-access/key-part.txt
   sudo chmod 600 /etc/emergency-access/key-part.txt
   

2. Create dummy file:

   echo "system_healthy" | sudo tee /etc/emergency-access/dummy.txt
   sudo chown emergency-access:emergency-access /etc/emergency-access/dummy.txt
   sudo chmod 644 /etc/emergency-access/dummy.txt
   

dschep/ntfy Backend Setup

The system uses a dedicated ntfy configuration file at /etc/emergency-access/ntfy.yml. Configure your notification backends in this file and reference them by name in the main configuration.

Configuring Notification Backends

1. Edit the dedicated ntfy config (/etc/emergency-access/ntfy.yml):

   backends:
    - matrix_sec
    - matrix_health
    - pushover_emergency
      
   matrix_sec:
    backend: matrix
    url: https://your-matrix-server.com
    roomId: "!emergency-security:your-matrix-server.com"
    userId: "@emergency-bot:your-matrix-server.com"
    password: "your-matrix-bot-password"
      
   matrix_health:
    backend: matrix
    url: https://your-matrix-server.com
    roomId: "!emergency-health:your-matrix-server.com"
    userId: "@emergency-bot:your-matrix-server.com"
    password: "your-matrix-bot-password"
      
   pushover_emergency:
    backend: pushover
    user_key: YOUR_PUSHOVER_USER_KEY
    priority: 2
    retry: 60
    expire: 3600
    sound: siren
   

2. Reference backend names in emergency access config:

   "notifications": {
    "key_backends": ["matrix_sec", "pushover_emergency"],
    "health_backends": ["matrix_health"],
    "config_path": "/etc/emergency-access/ntfy.yml"
   }
   

Adding Additional Backends

Add more backends to /etc/emergency-access/ntfy.yml as needed:

# Additional backends in /etc/emergency-access/ntfy.yml
backends:
  - matrix_sec
  - matrix_health
  - pushover_emergency
  - slack_critical
  - email_emergency

slack_critical:
  backend: slack
  token: YOUR_SLACK_BOT_TOKEN
  recipient: "#emergency-alerts"

email_emergency:
  backend: email
  smtp_server: smtp.gmail.com
  smtp_port: 587
  username: your-email@gmail.com
  password: your-app-password
  to: emergency-team@company.com
  from: emergency-access@company.com

Service Management

Start and Enable Service

# Start the service
sudo systemctl start emergency-access

# Enable automatic startup
sudo systemctl enable emergency-access

# Check status
sudo systemctl status emergency-access

Monitoring and Logs

# View real-time logs
sudo journalctl -u emergency-access -f

# View log file
sudo tail -f /var/log/emergency-access.log

# Check service health (through Caddy proxy)
curl https://your-domain.com/health-check-b8e3f4a2

# Or directly to local service (for testing)
curl http://localhost:1127/health-check-b8e3f4a2

Usage

Emergency Key Access

# Access the key (replace with your actual route)
curl https://your-domain.com/emergency-key-a7f9d2e1

# Expected response:
{
  "success": true,
  "key_part": "YOUR_KEY_PART_HERE",
  "timestamp": 1703123456.789,
  "notified_backends": ["matrix_sec"]
}

Health Check

# Regular health monitoring
curl https://your-domain.com/health-check-b8e3f4a2

# Expected response (all systems operational):
{
  "status": "ok",
  "timestamp": 1703123456.789,
  "health_backends_notified": ["matrix_health"],
  "key_backends_tested": ["matrix_sec", "pushover_emergency"],
  "dummy_content_length": 14,
  "key_file_accessible": true,
  "emergency_system_ready": true
}

# Error response (when components fail):
{
  "status": "error",
  "message": "System components failed",
  "details": ["key notifications failed", "key file access failed: Permission denied"],
  "health_notifications": true,
  "key_notifications": false,
  "dummy_file_access": true,
  "key_file_access": false
}

Security Considerations

Caddy Reverse Proxy Setup

1. Basic Caddyfile configuration:

   emergency.yourdomain.com {
      tls your-email@example.com
      reverse_proxy localhost:1127
          
      header {
          X-Content-Type-Options nosniff
          X-Frame-Options DENY
      }
          
      rate_limit {
          zone emergency {
              key {remote_host}
              events 10
              window 1m
          }
      }
   }
   

2. Path-based routing:

   yourdomain.com {
      handle /emergency/* {
          uri strip_prefix /emergency
          reverse_proxy localhost:1127
      }
   }
   

3. IP-restricted access:

   :443 {
      @allowed_ips remote_ip 192.168.0.0/16
      handle @allowed_ips {
          reverse_proxy localhost:1127
      }
      handle {
          respond "Access Denied" 403
      }
   }
   

Network Security

The service binds only to localhost (127.0.0.1:1127) and is accessed through your existing Caddy reverse proxy. No additional firewall configuration is required.

File Permissions

• Key file: 600 (owner read-only)
• Config file: 640 (owner read/write, group read)
• Application files: 644 (standard read permissions)

Monitoring

1. Set up regular health checks:

   # Cron job for health monitoring through Caddy
   */5 * * * * curl -s https://yourdomain.com/health-check-b8e3f4a2 > /dev/null
      
   # Or direct to service for internal monitoring
   */5 * * * * curl -s http://localhost:1127/health-check-b8e3f4a2 > /dev/null
   

2. Monitor notification delivery:

   • Configure notification backends (Pushover, Pushbullet, etc.)
   • Set up monitoring of notification delivery in your backends
   • Monitor log files for errors
   • All application logs are automatically sent to health backends for real-time monitoring

Troubleshooting

Common Issues

1. Service won't start:

   sudo journalctl -u emergency-access -n 50
   sudo systemctl status emergency-access
   

2. Notification failures:

   # Test dschep/ntfy installation and configuration
   ntfy -c /etc/emergency-access/ntfy.yml send "test message"
      
   # Check ntfy configuration
   cat /etc/emergency-access/ntfy.yml
      
   # Test specific backend
   ntfy -c /etc/emergency-access/ntfy.yml -b matrix_sec send "test message"
   

3. File permission errors:

   sudo chown -R emergency-access:emergency-access /opt/emergency-access
   sudo chown emergency-access:emergency-access /etc/emergency-access/*
   

Configuration Validation

Test your setup before deployment:

# Validate configuration
sudo -u emergency-access /opt/emergency-access/venv/bin/python /opt/emergency-access/main.py --validate

# Test notifications manually with your backend
ntfy -c /etc/emergency-access/ntfy.yml -b matrix_sec send "Test notification"
ntfy -c /etc/emergency-access/ntfy.yml -b pushover_emergency send "Test emergency notification"

Development

Running in Development Mode

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run with development config
EMERGENCY_CONFIG=config.json python main.py

Testing

# Test key endpoint (direct to service)
curl http://localhost:1127/emergency-key-xyz123

# Test health endpoint (direct to service)
curl http://localhost:1127/health-check

# Test through Caddy proxy
curl https://yourdomain.com/emergency-key-xyz123
curl https://yourdomain.com/health-check

License

This project is designed for emergency access scenarios. Use responsibly and ensure proper security measures are in place.

Support

For issues and questions:

1. Check the logs: /var/log/emergency-access.log
2. Verify configuration: /etc/emergency-access/config.json
3. Test notification systems independently
4. Monitor service status: systemctl status emergency-access