emergency-access

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):

   • Serves dummy content to verify system functionality
   • Sends health status to monitoring backends
   • 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
   sudo dnf install python3 python3-pip python3-venv
   

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"],
    "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

Notification Settings

• key_backends: List of backend names from your global ntfy config for key access alerts
• health_backends: List of backend names from your global ntfy config for health check notifications and all application logs
• 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 your global ~/.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 your existing global ntfy configuration. Simply reference your configured backend names in the emergency access configuration.

Using Your Existing Backends

1. Check your global ntfy config (typically ~/.ntfy.yml):

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

2. Reference backend names in emergency access config:

   "notifications": {
    "key_backends": ["matrix_sec", "pushover_emergency"],
    "health_backends": ["matrix_sec"]
   }
   

Adding New Backends

If you need additional backends for emergency access, add them to your global ntfy config:

# Add to your ~/.ntfy.yml
backends:
  - matrix_sec
  - pushover_emergency
  - slack_critical

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

Then reference them in the emergency access configuration.

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:
{
  "status": "ok",
  "timestamp": 1703123456.789,
  "notified_backends": ["matrix_sec"],
  "dummy_content_length": 14
}

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 send "test message"
      
   # Check global ntfy configuration
   cat ~/.ntfy.yml
      
   # Test specific backend
   ntfy -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 -b matrix_sec send "Test notification"
ntfy -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