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:

  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:

  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:

  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:

  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:

  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:

  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:

  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:

  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:

  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:

  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

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

   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

# 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

# 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/*