Redflag/docs/2_ARCHITECTURE/SETUP-SECURITY.md

# RedFlag v0.2.x Setup and Key Management Guide

## Overview

Starting with v0.2.x, RedFlag includes comprehensive cryptographic security features that require proper setup of signing keys and security settings. This guide explains the new setup flow and how to manage your signing keys.

## What's New in v0.2.x Setup

### Automatic Key Generation

During the initial setup process, RedFlag now:
1. **Automatically generates Ed25519 key pairs** for signing agent updates and commands
2. **Includes keys in generated configuration** - Both private and public keys are added to `.env`
3. **Initializes default security settings** - All security features enabled with safe defaults
4. **Displays key fingerprint** - Shows first 16 characters of public key for verification

### Configuration Additions

The generated `.env` file now includes:

```bash
# RedFlag Security - Ed25519 Signing Keys
# These keys are used to cryptographically sign agent updates and commands
# BACKUP THE PRIVATE KEY IMMEDIATELY - Store it in a secure location like a password manager
REDFLAG_SIGNING_PRIVATE_KEY=7d8f9e2a1b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e
REDFLAG_SIGNING_PUBLIC_KEY=4f46e57c3aed764ba2981a4b3c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d

# Security Settings
REDFLAG_SECURITY_COMMAND_SIGNING_ENFORCEMENT=strict
REDFLAG_SECURITY_NONCE_TIMEOUT=600
REDFLAG_SECURITY_LOG_LEVEL=warn
```

## Setup Flow Changes

### Step-by-Step Process

**1. Initialize with Bootstrap Config**
```bash
# Copy bootstrap configuration
cp config/.env.bootstrap.example config/.env

# Start services
docker-compose up -d
```

**2. Access Setup UI**
- Visit http://localhost:8080/setup
- Complete the configuration form

**3. Automatic Key Generation**
- Setup automatically generates Ed25519 key pair
- Keys are included in the generated configuration
- Public key fingerprint is displayed

**4. Apply Configuration**
```bash
# Copy the generated configuration to your .env file
echo "[paste generated config]" > config/.env

# Restart services to apply
docker-compose down && docker-compose up -d
```

**5. Verify Security Features**
```bash
# Check logs for security initialization
docker-compose logs server | grep -i "security"

# Expected output:
# [SUCCESS] Database migrations completed
# 🔧 Initializing default security settings...
# [SUCCESS] Default security settings initialized
```

## Key Management

### Understanding Your Keys

RedFlag uses **Ed25519** keys for:
- **Agent Update Signing**: Cryptographically sign agent update packages
- **Command Signing**: Sign commands issued from the server
- **Verification**: Agents verify signatures before executing

**Key Components**:
- **Private Key**: Must be kept secret, used for signing (REDFLAG_SIGNING_PRIVATE_KEY)
- **Public Key**: Can be shared, used for verification (REDFLAG_SIGNING_PUBLIC_KEY)
- **Fingerprint**: First 16 characters of public key, used for identification

### Critical Security Warning

**[WARNING] BACKUP YOUR PRIVATE KEY IMMEDIATELY**

If you lose your private key:
- **Cannot sign new updates** - Agents cannot receive updates
- **Cannot sign commands** - Command execution may fail
- **Cannot verify existing signatures** - Security breaks down
- **ALL AGENTS MUST BE RE-REGISTERED** - Complete reinstall required

**Backup Instructions**:
1. Immediately after setup, copy the private key to a secure location
2. Store in a password manager (e.g., 1Password, Bitwarden)
3. Consider hardware security module (HSM) for production
4. Test restoration procedure periodically

### Viewing Your Keys

**Current Keys**:
```bash
# View public key fingerprint
docker-compose exec server env | grep REDFLAG_SIGNING_PUBLIC_KEY

# View full public key
docker-compose exec server cat /app/keys/ed25519-public.key

# NEVER share your private key
docker-compose exec server cat /app/keys/ed25519-private.key  # Keep secret!
```

**API Endpoint**:
```bash
# Get public key from API (agents use this to verify)
curl http://localhost:8080/api/v1/public-key
```

### Key Rotation (Advanced)

**When to Rotate Keys**:
- Key compromise suspected
- Personnel changes
- Compliance requirements
- Every 12-24 months as best practice

**Rotation Process**:
1. **Generate new key pair**:
   ```bash
   # Development mode: Generate via API
   curl -X POST http://localhost:8080/api/v1/security/keys/rotate \
     -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
     -d '{"grace_period_days": 30}'
   ```

2. **During grace period** (default 30 days):
   - Both old and new keys are valid
   - Agents receive updates signed with new key
   - Old signatures still accepted

3. **Complete rotation**:
   - After grace period, old key is deprecated
   - Only new signatures accepted
   - Old key can be removed from system

### Recovering from Key Loss

**If private key is lost**:
1. **Check for backup**: Look in password manager, key files, backups
2. **If no backup exists**:
   - Must generate new key pair
   - All agents must be re-registered
   - Complete data loss for existing agents
   - This is why backups are critical

**Recovery with backup**:
1. Restore private key from backup to `./keys/ed25519-private.key`
2. Update `REDFLAG_SIGNING_PRIVATE_KEY` in `.env`
3. Restart server: `docker-compose restart server`
4. Verify: `docker-compose logs server | grep "signing"`

## Troubleshooting

### Issue: "Failed to load signing key" in logs

**Cause**: Private key not found or not readable

**Solution**:
```bash
# Check if key exists
ls -la ./keys/

# Check permissions (should be 600)
chmod 600 ./keys/ed25519-private.key

# Verify .env has the key
grep REDFLAG_SIGNING_PRIVATE_KEY config/.env
```

### Issue: "Command signature verification failed"

**Cause**: Key mismatch or signature corruption

**Solution**:
1. Check server logs for detailed error
2. Verify key hasn't changed
3. Check if command was tampered with
4. Re-issue command after verifying key integrity

### Issue: Security settings not applied

**Cause**: Settings not initialized or overridden

**Solution**:
```bash
# Check if default settings exist in database
docker-compose exec postgres psql -U redflag -d redflag -c "SELECT * FROM security_settings;"

# If empty, restart server to re-initialize
docker-compose restart server

# Monitor logs for initialization
docker-compose logs server | grep "security settings"
```

## Production Checklist

- [ ] Private key backed up in secure location
- [ ] Public key fingerprint verified and documented
- [ ] Security settings initialized (check logs)
- [ ] Enforcement mode set to "strict" (not "warning" or "disabled")
- [ ] Signing keys persisted via Docker volume
- [ ] Keys directory excluded from version control (.gitignore)
- [ ] Only authorized personnel have access to private key
- [ ] Key rotation scheduled in calendar
- [ ] Security event logging configured and monitored
- [ ] Incident response plan documented

## Support

For key management issues:
- Check logs: `docker-compose logs server`
- API docs: See SECURITY-SETTINGS.md
- Security guide: See SECURITY.md
- Report issues: https://github.com/Fimeg/RedFlag/issues

**Critical**: If you suspect a key compromise, immediately:
1. Generate new key pair
2. Rotate all agents to new key
3. Investigate scope of compromise
4. Review security event logs