# RedFlag Security Architecture v0.2.x

## Overview
RedFlag implements defense-in-depth security with multiple layers of protection focused on command integrity, update security, and agent authentication.

## What IS Secured

### 1. Update Integrity (v0.2.x)
- **How**: Update packages cryptographically signed with Ed25519
- **Nonce verification**: UUID + timestamp signed by server, 5-minute freshness window
- **Verification**: Agents verify both signature and checksum before installation
- **Threat mitigated**: Malicious update packages, replay attacks
- **Status**: Implemented Implemented and enforced

### 2. Machine Binding (v0.1.22+)
- **How**: Persistent machine ID validation on every request
- **Binding components**: machine-id, CPU info, system UUID, memory configuration
- **Verification**: Server validates X-Machine-ID header matches database
- **Threat mitigated**: Agent impersonation, config file copying between machines
- **Status**: Implemented Implemented and enforced

### 3. Authentication & Authorization
- **Registration tokens**: One-time use with configurable seat limits
- **JWT access tokens**: 24-hour expiry, HttpOnly cookies
- **Refresh tokens**: 90-day sliding window
- **Threat mitigated**: Unauthorized access, token replay
- **Status**: Implemented Implemented and enforced

### 4. Version Enforcement
- **Minimum version**: v0.1.22 required for security features
- **Downgrade protection**: Explicit version comparison prevents downgrade attacks
- **Update security**: Signed update packages with rollback protection
- **Status**: Implemented Implemented and enforced

## What is NOT Secured

### 1. Command Signing
- Commands are NOT currently signed (only updates are signed)
- Server-to-agent communication relies on TLS and JWT authentication
- Recommendation: Enable command signing in future versions

### 2. Network Traffic
- TLS encrypts transport but endpoints are not authenticated beyond JWT
- Use TLS 1.3+ with proper certificate validation
- Consider mutual TLS in highly sensitive environments

### 3. Private Key Storage
- Private key stored in environment variable (REDFLAG_SIGNING_PRIVATE_KEY)
- Current rotation: Manual process
- Recommendations: Use HSM or secrets management system

## Threat Model

### Protected Against
- Implemented Update tampering in transit
- Implemented Malicious update packages
- Implemented Agent impersonation via config copying
- Implemented Update replay attacks (via nonces)
- Implemented Registration token abuse (seat limits)
- Implemented Version downgrade attacks

### NOT Protected Against
- ❌ MITM on first certificate contact (standard TLS TOFU)
- ❌ Private key compromise (environment variable exposure)
- ❌ Physical access to agent machine
- ❌ Supply chain attacks (compromised build process)
- ❌ Command tampering (commands are not signed)

## Configuration

### Required Environment Variables
```bash
# Ed25519 signing for updates
REDFLAG_SIGNING_PRIVATE_KEY=<ed25519-private-key-hex>

# Database and authentication
REDFLAG_DB_PASSWORD=<secure-password>
REDFLAG_ADMIN_PASSWORD=<secure-admin-password>
REDFLAG_JWT_SECRET=<cryptographically-secure-secret>
```

### Optional Security Settings
```bash
# Agent version enforcement
MIN_AGENT_VERSION=0.1.22

# Server security
REDFLAG_TLS_ENABLED=true
REDFLAG_SERVER_HOST=0.0.0.0
REDFLAG_SERVER_PORT=8443

# Token limits
REDFLAG_MAX_TOKENS=100
REDFLAG_MAX_SEATS=50
```

### Web UI Settings
Security settings are accessible via Dashboard → Settings → Security:
- Nonce timeout configuration
- Update signing enforcement
- Machine binding settings
- Security event logging

## Key Management

### Generating Keys
```bash
# Generate Ed25519 key pair for update signing
go run scripts/generate-keypair.go
```

### Key Format
- Private key: 64 hex characters (32 bytes)
- Public key: 64 hex characters (32 bytes)
- Algorithm: Ed25519
- Fingerprint: First 8 bytes of public key (displayed in UI)

### Key Rotation
Current implementation requires manual rotation:
1. Generate new key pair
2. Update REDFLAG_SIGNING_PRIVATE_KEY environment variable
3. Restart server
4. Re-issue any pending updates

## Security Best Practices

### Production Deployment
1. **Always set REDFLAG_SIGNING_PRIVATE_KEY** in production
2. **Use strong secrets** for JWT and admin passwords
3. **Enable TLS 1.3+** for all connections
4. **Set MIN_AGENT_VERSION** to enforce security features
5. **Monitor security events** in dashboard

### Agent Security
1. **Run agents as non-root** where possible
2. **Secure agent configuration files** ( chmod 600 )
3. **Use firewall rules** to restrict access to server
4. **Regular updates** to latest agent version

### Server Security
1. **Use environment variables** for secrets, not config files
2. **Enable database SSL** connections
3. **Implement backup encryption**
4. **Regular credential rotation** (quarterly recommended)

## Incident Response

### If Update Verification Fails
1. Check agent logs for specific error
2. Verify server public key in agent cache
3. Check network connectivity to server
4. Validate update creation process

### If Machine Binding Fails
1. Verify agent hasn't been moved to new hardware
2. Check `/etc/machine-id` (Linux) or equivalent
3. Re-register agent with new token if legitimate change
4. Investigate potential config file copying

### If Private Key is Compromised
1. Immediately generate new Ed25519 key pair
2. Update REDFLAG_SIGNING_PRIVATE_KEY
3. Restart server
4. Rotate any cached public keys on agents
5. Review audit logs for unauthorized updates

## Audit Trail

All security-critical operations are logged:
- Update installations (success/failure)
- Machine ID validations
- Registration token usage
- Authentication failures
- Version enforcement actions

Log locations:
- **Server**: Standard application logs
- **Agent**: Local agent logs
- **Dashboard**: Security → Events

## Compliance Considerations

RedFlag security features support compliance requirements for:
- **SOC 2 Type II**: Change management, access controls, encryption
- **ISO 27001**: Cryptographic controls, system integrity
- **NIST CSF**: Protect, Detect, Respond functions

Note: Consult your compliance team for specific implementation requirements and additional controls needed.

## Security Monitoring

### Key Metrics to Monitor
- Failed update verifications
- Machine ID mismatches
- Authentication failure rates
- Agent version compliance
- Unusual configuration changes

### Dashboard Monitoring
Access via Dashboard → Security:
- Real-time security status
- Event timeline
- Agent compliance metrics
- Key fingerprint verification

## Version History
- **v0.2.x**: Ed25519 update signing with nonce protection
- **v0.1.23**: Enhanced machine binding enforcement
- **v0.1.22**: Initial machine ID binding implementation
- **v0.1.x**: Basic JWT authentication and registration tokens

## Known Limitations

1. **Command signing**: Not implemented - relies on TLS for command integrity
2. **Key rotation**: Manual process only
3. **Multi-tenancy**: No tenant isolation at cryptographic level
4. **Supply chain**: No binary attestation or reproducible builds

## Security Contacts

For security-related questions or vulnerability reports:
- Email: security@redflag.local
- Dashboard: Security → Report Incident
- Documentation: `/docs/SECURITY-HARDENING.md`

---

*This document describes the ACTUAL security features implemented in v0.2.x. For deployment guidance, see SECURITY-HARDENING.md*