Redflag/docs/4_LOG/December_2025/2025-12-16-Security-Documentation-Incorrect.md

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

# 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

# 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

# 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