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

# RedFlag Security Settings Configuration Guide

## Overview

This guide provides comprehensive configuration options for RedFlag security settings, including environment variables, UI settings, validation rules, and the impact of each configuration change.

## Environment Variables

### Core Security Settings

#### REDFLAG_SIGNING_PRIVATE_KEY
- **Type**: Required (for update signing)
- **Format**: 64-character hex string (Ed25519 private key)
- **Default**: None
- **Impact**:
  - Required to sign update packages
  - Without this, updates will be rejected by agents
  - Agents store the public key for verification
- **Example**:
  ```bash
  REDFLAG_SIGNING_PRIVATE_KEY=abcd1234567890abcd1234567890abcd1234567890abcd1234567890abcd1234
  ```

#### MIN_AGENT_VERSION
- **Type**: Optional
- **Format**: Semantic version string (e.g., "0.1.22")
- **Default**: "0.1.22"
- **Impact**:
  - Agents below this version are blocked
  - Prevents downgrade attacks
  - Forces security feature adoption
- **Recommendation**: Set to minimum version with required security features
- **Example**:
  ```bash
  MIN_AGENT_VERSION=0.1.22
  ```

### Authentication Settings

#### REDFLAG_JWT_SECRET
- **Type**: Required
- **Format**: Cryptographically secure random string
- **Default**: Generated during setup
- **Impact**:
  - Signs all JWT tokens
  - Compromise invalidates all sessions
  - Rotation requires user re-authentication
- **Example**:
  ```bash
  REDFLAG_JWT_SECRET=$(openssl rand -hex 32)
  ```

#### REDFLAG_ADMIN_PASSWORD
- **Type**: Required
- **Format**: Strong password string
- **Default**: Set during setup
- **Impact**:
  - Web UI administrator access
  - Should use strong password policy
  - Rotate regularly in production
- **Example**:
  ```bash
  REDFLAG_ADMIN_PASSWORD=SecurePass123!@#
  ```

### Registration Settings

#### REDFLAG_MAX_TOKENS
- **Type**: Optional
- **Format**: Integer
- **Default**: 100
- **Impact**:
  - Maximum active registration tokens
  - Prevents token exhaustion attacks
  - High values may increase attack surface
- **Example**:
  ```bash
  REDFLAG_MAX_TOKENS=50
  ```

#### REDFLAG_MAX_SEATS
- **Type**: Optional
- **Format**: Integer
- **Default**: 50
- **Impact**:
  - Maximum agents per registration token
  - Controls license/seat usage
  - Prevents unauthorized agent registration
- **Example**:
  ```bash
  REDFLAG_MAX_SEATS=25
  ```

#### REDFLAG_TOKEN_EXPIRY
- **Type**: Optional
- **Format**: Duration string (e.g., "24h", "7d")
- **Default**: "24h"
- **Impact**:
  - Registration token validity period
  - Shorter values improve security
  - Very short values may inconvenience users
- **Example**:
  ```bash
  REDFLAG_TOKEN_EXPIRY=48h
  ```

### TLS/Network Settings

#### REDFLAG_TLS_ENABLED
- **Type**: Optional
- **Format**: Boolean ("true"/"false")
- **Default**: "false"
- **Impact**:
  - Enables HTTPS connections
  - Required for production deployments
  - Requires valid certificates
- **Example**:
  ```bash
  REDFLAG_TLS_ENABLED=true
  ```

#### REDFLAG_TLS_CERT_FILE
- **Type**: Required if TLS enabled
- **Format**: File path
- **Default**: None
- **Impact**:
  - SSL/TLS certificate file location
  - Must be valid for the server hostname
  - Expired certificates prevent connections
- **Example**:
  ```bash
  REDFLAG_TLS_CERT_FILE=/etc/ssl/certs/redflag.crt
  ```

#### REDFLAG_TLS_KEY_FILE
- **Type**: Required if TLS enabled
- **Format**: File path
- **Default**: None
- **Impact**:
  - Private key for TLS certificate
  - Must match certificate
  - File permissions should be restricted (600)
- **Example**:
  ```bash
  REDFLAG_TLS_KEY_FILE=/etc/ssl/private/redflag.key
  ```

## Web UI Security Settings

Access via: Dashboard → Settings → Security

### Machine Binding Settings

#### Enforcement Mode
- **Options**:
  - `strict` (default) - Reject all mismatches
  - `warn` - Log mismatches but allow
  - `disabled` - No verification (not recommended)
- **Impact**:
  - Prevents agent impersonation attacks
  - Requires agent v0.1.22+
  - Disabled mode removes security protection

#### Version Enforcement
- **Options**:
  - `enforced` - Block old agents
  - `warn` - Allow with warnings
  - `disabled` - Allow all (not recommended)
- **Impact**:
  - Ensures security feature adoption
  - May cause agent upgrade requirements
  - Disabled allows vulnerable agents

### Update Security Settings

#### Automatic Signing
- **Options**: Enabled/Disabled
- **Default**: Enabled (if key configured)
- **Impact**:
  - Signs all update packages
  - Required for agent verification
  - Disabled requires manual signing

#### Nonce Timeout
- **Range**: 1-60 minutes
- **Default**: 5 minutes
- **Impact**:
  - Prevents replay attacks
  - Too short may cause clock sync issues
  - Too long increases replay window

#### Signature Algorithm
- **Options**: Ed25519 only
- **Future**: May support RSA, ECDSA
- **Note**: Ed25519 provides best security/performance

### Logging Settings

#### Security Log Level
- **Options**:
  - `error` - Critical failures only
  - `warn` (default) - Security events and failures
  - `info` - All security operations
  - `debug` - Detailed debugging info
- **Impact**:
  - Log volume and storage requirements
  - Incident response visibility
  - Performance impact minimal

#### Log Retention
- **Range**: 1-365 days
- **Default**: 30 days
- **Impact**:
  - Disk space usage
  - Audit trail availability
  - Compliance requirements

### Alerting Settings

#### Failed Authentication Alerts
- **Threshold**: 5-100 failures
- **Window**: 1-60 minutes
- **Action**: Email/Webhook/Disabled
- **Default**: 10 failures in 5 minutes

#### Machine Binding Violations
- **Alert on**: First violation only / All violations
- **Grace period**: 0-60 minutes
- **Action**: Block/Warning/Disabled

## Configuration Validation Rules

### Ed25519 Key Validation
```go
// Key must be 64 hex characters (32 bytes)
if len(keyHex) != 64 {
    return error("Invalid key length: expected 64 chars")
}

// Must be valid hex
if !isValidHex(keyHex) {
    return error("Invalid hex format")
}

// Must generate valid Ed25519 key pair
privateKey, err := hex.DecodeString(keyHex)
if err != nil {
    return error("Invalid hex encoding")
}

if len(privateKey) != ed25519.PrivateKeySize {
    return error("Invalid Ed25519 key size")
}
```

### Version Format Validation
```
Required format: X.Y.Z where X,Y,Z are integers
Examples: 0.1.22, 1.0.0, 2.3.4
Invalid: v0.1.22, 0.1, 0.1.22-beta
```

### JWT Secret Requirements
- Minimum length: 32 characters
- Recommended: 64+ characters
- Must not be the default value
- Should use cryptographically secure random generation

## Impact of Settings Changes

### High Impact (Requires Restart)
- REDFLAG_SIGNING_PRIVATE_KEY
- REDFLAG_TLS_ENABLED
- REDFLAG_TLS_CERT_FILE
- REDFLAG_TLS_KEY_FILE
- REDFLAG_JWT_SECRET

### Medium Impact (Affects New Sessions)
- REDFLAG_MAX_TOKENS
- REDFLAG_MAX_SEATS
- REDFLAG_TOKEN_EXPIRY
- MIN_AGENT_VERSION

### Low Impact (Real-time Updates)
- Web UI security settings
- Log levels and retention
- Alert thresholds

## Migration Paths

### Enabling Update Signing (v0.1.x to v0.2.x)
1. Generate Ed25519 key pair:
   ```bash
   go run scripts/generate-keypair.go
   ```
2. Set REDFLAG_SIGNING_PRIVATE_KEY
3. Restart server
4. Existing agents will fetch public key on next check-in
5. All new updates will be signed

### Enforcing Machine Binding
1. Set MIN_AGENT_VERSION=0.1.22
2. Existing agents < v0.1.22 will be blocked
3. Agents must re-register to bind to machine
4. Monitor for binding violations during transition

### Upgrading Agents Securely
1. Use signed update packages
2. Verify public key distribution
3. Monitor update success rates
4. Have rollback plan ready

## Troubleshooting

### Common Issues

#### Update Verification Fails
```
Error: "signature verification failed"
Solution:
1. Check REDFLAG_SIGNING_PRIVATE_KEY is set
2. Verify agent has correct public key
3. Check if key was recently rotated
```

#### Machine ID Mismatch
```
Error: "machine ID mismatch"
Solution:
1. Verify agent wasn't moved to new hardware
2. Check /etc/machine-id (Linux)
3. Re-register if legitimate hardware change
```

#### Version Enforcement Blocking
```
Error: "agent version too old"
Solution:
1. Update MIN_AGENT_VERSION appropriately
2. Upgrade agents to minimum version
3. Use temporary override if needed
```

### Verification Commands

#### Check Key Configuration
```bash
# Verify server has signing key
curl -k https://server:8080/api/v1/security/signing-status

# Should return:
{
  "status": "available",
  "public_key_fingerprint": "abcd1234",
  "algorithm": "ed25519"
}
```

#### Test Agent Registration
```bash
# Create test token
curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://server:8080/api/v1/registration-tokens

# Verify limits applied
```

## Security Checklist

Before going to production:

- [ ] Generate and set REDFLAG_SIGNING_PRIVATE_KEY
- [ ] Configure TLS with valid certificates
- [ ] Set strong REDFLAG_JWT_SECRET
- [ ] Configure MIN_AGENT_VERSION appropriately
- [ ] Set reasonable REDFLAG_MAX_TOKENS and REDFLAG_MAX_SEATS
- [ ] Enable security logging
- [ ] Configure alerting thresholds
- [ ] Test update signing and verification
- [ ] Verify machine binding enforcement
- [ ] Document key rotation procedures

## References

- Main security documentation: `/docs/SECURITY.md`
- Hardening guide: `/docs/SECURITY-HARDENING.md`
- Key generation script: `/scripts/generate-keypair.go`
- Security API endpoints: `/api/v1/security/*`