Skip to content

Security Configuration

Advanced security settings in WireBuddy.

Password Policy

Configure password requirements:

Settings → Security → Password Policy

  • Minimum Length: 8-32 characters
  • Complexity: Require uppercase, lowercase, numbers, special characters
  • Password History: Prevent reuse of last N passwords
  • Expiration: Force password changes every N days (optional)

Session Configuration

Settings → Security → Sessions

Session Timeout

  • 15 minutes: High security environments
  • 30 minutes: Default, balanced security
  • 1 hour: Convenience
  • 4 hours: Maximum allowed

Session Renewal

  • On Activity: Extend session on each request
  • Manual: Require explicit renewal

Concurrent Sessions

  • Allow: Users can have multiple active sessions
  • Deny: Only one session per user

HTTPS Configuration

Force HTTPS

Settings → Security → HTTPS

Enable "Force HTTPS" to redirect all HTTP requests to HTTPS.

Required for:

  • HSTS
  • Secure cookies
  • WebAuthn (passkeys)

SSL/TLS Settings

Reverse Proxy (Recommended):

Configure TLS in your reverse proxy (Caddy, nginx):

# nginx
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
ssl_prefer_server_ciphers on;

Built-in ACME:

See Let's Encrypt Configuration.

HSTS

HTTP Strict Transport Security header:

Strict-Transport-Security: max-age=31536000; includeSubDomains; preload

Enabled automatically when "Force HTTPS" is on.

CSRF Protection

Settings → Security → CSRF

  • Enabled: Double-submit cookie pattern (recommended)
  • SameSite: Lax (default), Strict, or None
  • Origin Validation: Verify Origin/Referer headers

Rate Limiting

Settings → Security → Rate Limiting

Login Rate Limiting

  • Attempts: Maximum failed login attempts (default: 5)
  • Window: Time window in minutes (default: 15)
  • Lockout Duration: Initial lockout (default: 1 minute)
  • Exponential Backoff: Increase lockout on repeated violations

API Rate Limiting

  • Authenticated: Requests per minute (default: 100)
  • Unauthenticated: Requests per minute (default: 10)

See Rate Limiting Guide for details.

IP Whitelisting

Settings → Security → IP Whitelist

Restrict access to specific IP ranges:

# Allow office network
Allow: 203.0.113.0/24

# Allow VPN clients
Allow: 10.8.0.0/24

# Block all others (implicit)

Warning

Ensure you don't lock yourself out. Always test from allowed IP first.

Passkey Configuration

Settings → Security → Passkeys

  • Enable Passkeys: Allow WebAuthn authentication
  • Require User Verification: Fingerprint/PIN on security key
  • Attestation: None (default), Direct, or Indirect
  • Authenticator Attachment: Platform (Touch ID) and/or Cross-platform (security keys)

See Passkeys Guide.

MFA Configuration

Settings → Security → Multi-Factor Authentication

  • Enforce MFA: Require MFA for all admin accounts
  • Grace Period: Days before MFA is required (default: 7)
  • Recovery Codes: Number of backup codes (default: 10)

Audit Logging

Settings → Security → Audit Log

Log security-sensitive events:

  • ✅ Authentication (login/logout)
  • ✅ Failed login attempts
  • ✅ Password changes
  • ✅ MFA enrollment/use
  • ✅ User creation/deletion
  • ✅ Settings changes
  • ✅ Peer/interface modifications

Log Retention

  • 30 days: Minimum recommended
  • 90 days: Compliance requirement (varies)
  • 1 year: Long-term auditing

Export Logs

Export audit logs for external analysis:

Settings → Security → Audit Log → Export

Formats: CSV, JSON, Syslog

Security Headers

WireBuddy automatically sets security headers:

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Referrer-Policy: strict-origin-when-cross-origin
Permissions-Policy: geolocation=(), microphone=(), camera=()
Content-Security-Policy: default-src 'self'; ...

Custom CSP

Settings → Security → Content Security Policy

Add custom CSP directives for third-party integrations.

Trusted Proxies

WireBuddy trusts proxy headers only from explicitly trusted proxy sources.

For the public status page (/status), trusted proxy CIDRs are configured with:

WIREBUDDY_STATUS_TRUSTED_PROXY_CIDRS=127.0.0.1/32,192.168.1.10/32

Notes:

  • Loopback hops are always trusted for /status
  • Private IP ranges are not auto-trusted for /status
  • If a reverse proxy is on a LAN address, add that CIDR explicitly

Secrets Encryption

WireBuddy encrypts sensitive data at rest:

  • Algorithm: Fernet (AES-128-CBC + HMAC-SHA256)
  • Key Derivation: PBKDF2 with WIREBUDDY_SECRET_KEY
  • Per-Row Salt: Unique salt per encrypted field

Encrypted fields:

  • WireGuard private keys
  • TOTP secrets
  • ACME account keys
  • API tokens (SHA-256 hash, not encrypted)

Secret Key Security

Never change WIREBUDDY_SECRET_KEY after deployment. All encrypted data will become unrecoverable.

Database Security

SQLite Security

  • Location: data/wirebuddy.db (inside Docker volume)
  • Permissions: 600 (owner read/write only)
  • Encryption: Not encrypted by default (use dm-crypt for volume encryption)

Backup Encryption

Encrypt backups:

# Backup with GPG encryption
tar cz data/ | gpg -e -r your-key@example.com > backup.tar.gz.gpg

# Restore
gpg -d backup.tar.gz.gpg | tar xz

Container Security

Hardening

# docker-compose.yml
services:
  wirebuddy:
    cap_drop:
      - ALL
    cap_add:
      - NET_ADMIN
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp
      - /run

User Namespace

Run container as non-root:

user: "1000:1000"

Firewall Integration

fail2ban

Automatically ban IPs with failed login attempts:

# /etc/fail2ban/filter.d/wirebuddy.conf
[Definition]
failregex = ^.*Failed login attempt for user .* from <HOST>$
ignoreregex =

# /etc/fail2ban/jail.d/wirebuddy.conf
[wirebuddy]
enabled = true
port = http,https
filter = wirebuddy
logpath = /var/log/wirebuddy/auth.log
maxretry = 5
bantime = 3600

CrowdSec

Integrate with CrowdSec for collaborative security:

# Install CrowdSec bouncer
docker run -d --name crowdsec-bouncer \
  -e CROWDSEC_AGENT_HOST=crowdsec:8080 \
  crowdsecurity/nginx-crowdsec-bouncer

Compliance

GDPR

  • Data Minimization: Only collect necessary data
  • Right to Deletion: Users can request account deletion
  • Export: Users can export their data
  • Consent: Explicit consent for data processing

SOC 2

  • Access Control: Role-based permissions
  • Audit Logging: Comprehensive event logging
  • Encryption: Data encrypted at rest and in transit
  • Monitoring: Real-time security event monitoring

Security Scanning

Vulnerability Scanning

Scan Docker image:

# Trivy
trivy image giiibates/wirebuddy:latest

# Grype
grype giiibates/wirebuddy:latest

Dependency Scanning

Check Python dependencies:

# Safety
safety check -r requirements.txt

# Bandit (static analysis)
bandit -r app/

Next Steps