Redflag/docs/4_LOG/October_2025/Development-Documentation/CONFIGURATION.md

# RedFlag Configuration Guide

Configuration follows this priority order (highest to lowest):
1. **CLI Flags** (overrides everything)
2. **Environment Variables**
3. **Configuration File**
4. **Default Values**

---

## Agent Configuration

### CLI Flags

```bash
./redflag-agent \
  --server https://redflag.example.com:8080 \
  --token rf-tok-abc123 \
  --proxy-http http://proxy.company.com:8080 \
  --proxy-https https://proxy.company.com:8080 \
  --log-level debug \
  --organization "my-homelab" \
  --tags "production,webserver" \
  --name "web-server-01" \
  --insecure-tls
```

**Available Flags:**
- `--server` - Server URL (required for registration)
- `--token` - Registration token (required for first run)
- `--proxy-http` - HTTP proxy URL
- `--proxy-https` - HTTPS proxy URL
- `--log-level` - Logging level (debug, info, warn, error)
- `--organization` - Organization name
- `--tags` - Comma-separated tags
- `--name` - Display name for agent
- `--insecure-tls` - Skip TLS certificate validation (dev only)
- `--register` - Force registration mode
- `-install-service` - Install as Windows service
- `-start-service` - Start Windows service
- `-stop-service` - Stop Windows service
- `-remove-service` - Remove Windows service

### Environment Variables

```bash
export REDFLAG_SERVER_URL="https://redflag.example.com"
export REDFLAG_REGISTRATION_TOKEN="rf-tok-abc123"
export REDFLAG_HTTP_PROXY="http://proxy.company.com:8080"
export REDFLAG_HTTPS_PROXY="https://proxy.company.com:8080"
export REDFLAG_NO_PROXY="localhost,127.0.0.1"
export REDFLAG_LOG_LEVEL="info"
export REDFLAG_ORGANIZATION="my-homelab"
export REDFLAG_TAGS="production,webserver"
export REDFLAG_DISPLAY_NAME="web-server-01"
```

### Configuration File

**Linux:** `/etc/redflag/config.json`
**Windows:** `C:\ProgramData\RedFlag\config.json`

Auto-generated on registration:
```json
{
  "server_url": "https://redflag.example.com",
  "agent_id": "uuid",
  "token": "jwt-access-token",
  "refresh_token": "long-lived-refresh-token",
  "check_in_interval": 300,
  "proxy": {
    "enabled": true,
    "http": "http://proxy.company.com:8080",
    "https": "https://proxy.company.com:8080",
    "no_proxy": "localhost,127.0.0.1"
  },
  "network": {
    "timeout": "30s",
    "retry_count": 3,
    "retry_delay": "5s"
  },
  "logging": {
    "level": "info",
    "max_size": 100,
    "max_backups": 3
  },
  "tags": ["production", "webserver"],
  "organization": "my-homelab",
  "display_name": "web-server-01"
}
```

---

## Server Configuration

### Environment Variables (.env)

```bash
# Server Settings
REDFLAG_SERVER_HOST=0.0.0.0
REDFLAG_SERVER_PORT=8080

# Database Settings
REDFLAG_DB_HOST=postgres
REDFLAG_DB_PORT=5432
REDFLAG_DB_NAME=redflag
REDFLAG_DB_USER=redflag
REDFLAG_DB_PASSWORD=your-secure-password

# Security
REDFLAG_JWT_SECRET=your-jwt-secret
REDFLAG_ADMIN_USERNAME=admin
REDFLAG_ADMIN_PASSWORD=your-admin-password

# Agent Settings
REDFLAG_CHECK_IN_INTERVAL=300
REDFLAG_OFFLINE_THRESHOLD=600

# Rate Limiting
REDFLAG_RATE_LIMIT_ENABLED=true
```

### Server CLI Flags

```bash
./redflag-server \
  --setup \
  --migrate \
  --host 0.0.0.0 \
  --port 8080
```

**Available Flags:**
- `--setup` - Run interactive setup wizard
- `--migrate` - Run database migrations
- `--host` - Server bind address (default: 0.0.0.0)
- `--port` - Server port (default: 8080)

---

## Docker Compose Configuration

```yaml
version: '3.8'
services:
  aggregator-server:
    build: ./aggregator-server
    ports:
      - "8080:8080"
    environment:
      - REDFLAG_SERVER_HOST=0.0.0.0
      - REDFLAG_SERVER_PORT=8080
      - REDFLAG_DB_HOST=postgres
      - REDFLAG_DB_PORT=5432
      - REDFLAG_DB_NAME=redflag
      - REDFLAG_DB_USER=redflag
      - REDFLAG_DB_PASSWORD=secure-password
    depends_on:
      - postgres
    volumes:
      - ./server-config:/etc/redflag
      - ./logs:/app/logs

  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: redflag
      POSTGRES_USER: redflag
      POSTGRES_PASSWORD: secure-password
    volumes:
      - postgres-data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

volumes:
  postgres-data:
```

---

## Proxy Configuration

RedFlag supports HTTP, HTTPS, and SOCKS5 proxies for agents in restricted networks.

### Example: Corporate Proxy
```bash
./redflag-agent \
  --server https://redflag.example.com:8080 \
  --token rf-tok-abc123 \
  --proxy-http http://proxy.corp.com:8080 \
  --proxy-https https://proxy.corp.com:8080
```

### Example: SSH Tunnel
```bash
# Set up SSH tunnel
ssh -D 1080 -f -C -q -N user@jumphost

# Configure agent to use SOCKS5
export REDFLAG_HTTP_PROXY="socks5://localhost:1080"
export REDFLAG_HTTPS_PROXY="socks5://localhost:1080"
./redflag-agent
```

---

## Security Hardening

### Production Checklist
- [ ] Change default admin password
- [ ] Use strong JWT secret (32+ characters)
- [ ] Enable TLS/HTTPS
- [ ] Configure rate limiting
- [ ] Use firewall rules
- [ ] Disable `--insecure-tls` flag
- [ ] Regular token rotation
- [ ] Monitor audit logs

### Minimal Agent Privileges (Linux)

The installer creates a `redflag-agent` user with limited sudo access:

```bash
# /etc/sudoers.d/redflag-agent
redflag-agent ALL=(ALL) NOPASSWD: /usr/bin/apt-get update
redflag-agent ALL=(ALL) NOPASSWD: /usr/bin/apt-get upgrade *
redflag-agent ALL=(ALL) NOPASSWD: /usr/bin/dnf check-update
redflag-agent ALL=(ALL) NOPASSWD: /usr/bin/dnf upgrade *
```

---

## Logging

### Agent Logs
**Linux:** `/var/log/redflag-agent/`
**Windows:** `C:\ProgramData\RedFlag\logs\`

### Server Logs
**Docker:** `docker-compose logs -f aggregator-server`
**Systemd:** `journalctl -u redflag-server -f`

### Log Levels
- `debug` - Verbose debugging info
- `info` - General operational messages (default)
- `warn` - Warning messages
- `error` - Error messages only