Add docs and project files - force for Culurien
This commit is contained in:
Fimeg
388
docs/2_ARCHITECTURE/SECURITY-SETTINGS.md
Normal file
388
docs/2_ARCHITECTURE/SECURITY-SETTINGS.md
Normal file
@@ -0,0 +1,388 @@
|
||||
# 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/*`
|
||||
Reference in New Issue
Block a user