Security Model

Bloqd is designed with security as a priority. This page explains the security measures in place.

Authentication

API Keys

API keys are the primary authentication method for agents and programmatic access.

Key Format:

f2b_[32 random characters]

Security measures:

• Keys are hashed with SHA-256 + salt before storage
• Original key is never stored (only shown once on creation)
• Keys can be scoped to specific servers
• Keys have permission levels (read/write/admin)
• Last-used timestamp tracked for auditing

JWT Tokens

User sessions use JSON Web Tokens:

• Access tokens: Short-lived (15 minutes)
• Refresh tokens: Longer-lived (7 days)
• Tokens are signed with server-specific secrets
• Secrets auto-generated on first run

Multi-Factor Authentication

Users can enable TOTP-based MFA:

• Standard TOTP (Google Authenticator, Authy, etc.)
• QR code for easy setup
• Backup codes for recovery
• Required for admin accounts (recommended)

Authorization

Permission Levels (API Keys)

Level	Capabilities
read	View servers, bans, whitelist, templates
write	All read + report bans, modify whitelist, execute commands
admin	All write + manage API keys, settings, users

Role-Based Access Control (Users)

Users are assigned roles with specific permissions:

Default Roles:

• Admin: Full access to all features
• Operator: Manage servers and bans, no settings access
• Viewer: Read-only access

Granular Permissions:

• servers.view, servers.manage, servers.delete
• bans.view, bans.manage
• whitelist.view, whitelist.manage
• templates.view, templates.manage
• users.view, users.manage
• settings.view, settings.manage

Data Protection

At Rest

• Database: SQLite with file-system permissions
• Passwords: Bcrypt hashed (cost factor 12)
• API keys: SHA-256 hashed with salt
• Sensitive config: Stored in environment variables

In Transit

• All API communication over HTTPS (recommended)
• WebSocket connections encrypted (WSS)
• Agent-server communication via TLS

Sensitive Data Handling

Data Type	Protection
Passwords	Bcrypt hash, never logged
API Keys	SHA-256 hash, shown once
JWT Secrets	Auto-generated, never exposed
IP Addresses	Stored for security purposes
Log excerpts	Truncated to 2000 chars

Input Validation

All input is validated using Zod schemas:

const reportSchema = z.object({
  ip: z.string().refine(isValidIP),
  jail: z.string().min(1).max(100),
  log_excerpt: z.string().max(2000).optional(),
});

Validation includes:

• Type checking
• Length limits
• Format validation (IP addresses, etc.)
• Sanitization of special characters

Rate Limiting

API Rate Limits

Endpoint Type	Limit
Standard endpoints	100 requests/minute
Sensitive endpoints (login, keys)	10 requests/minute
Agent heartbeats	Exempt

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705320600

Protection Against

• Brute force attacks on login
• API key enumeration
• Resource exhaustion

Agent Security

Minimal Permissions

The agent requires root access only for:

• Reading fail2ban logs
• Writing whitelist file
• Reloading fail2ban

Command Restrictions

Remote commands are limited to a predefined set:

allowed_commands:
  - jail_enable
  - jail_disable
  - fail2ban_reload
  - ip_ban
  - ip_unban
  - whitelist_sync

Arbitrary shell commands are not allowed unless explicitly configured.

Communication

• Agent initiates all connections (no inbound ports)
• Connections use HTTPS with certificate validation
• API key sent as Bearer token
• Heartbeats every 60 seconds

Network Security

Recommended Setup

Internet
    │
    ▼
┌─────────────┐
│  Firewall   │  ← Allow only 443 (HTTPS)
└─────────────┘
    │
    ▼
┌─────────────┐
│ Rev. Proxy  │  ← SSL termination, rate limiting
│  (Nginx)    │
└─────────────┘
    │
    ▼
┌─────────────┐
│   Bloqd     │  ← Bind to localhost only
│  (Docker)   │
└─────────────┘

Firewall Rules

Server:

• Allow inbound 443 (HTTPS)
• Allow outbound to Discord, AbuseIPDB, SMTP

Managed servers:

• Allow outbound to Bloqd server
• No inbound ports required

Audit Logging

What's Logged

• User login attempts (success/failure)
• API key usage (last_used timestamp)
• Command execution (who, what, when)
• Configuration changes
• License validation attempts

Log Format

{
  "level": "info",
  "time": "2024-01-15T10:30:00Z",
  "msg": "Command executed",
  "user": "admin",
  "server": "web-01",
  "command": "jail_enable",
  "params": {"jail": "sshd"},
  "result": "success"
}

Security Best Practices

For Administrators

1. Use HTTPS - Always place Bloqd behind a reverse proxy with SSL
2. Enable MFA - Require MFA for all admin accounts
3. Rotate API keys - Regularly rotate agent API keys
4. Limit permissions - Use read-only keys when possible
5. Monitor logs - Review audit logs for suspicious activity
6. Keep updated - Apply Bloqd updates promptly

For Agent Configuration

1. Use dedicated keys - One API key per server
2. Restrict commands - Only enable needed commands
3. Verify SSL - Don't disable certificate validation
4. Firewall rules - Restrict outbound to Bloqd server only

Vulnerability Reporting

If you discover a security vulnerability:

1. Do not disclose publicly
2. Email security@bloqd.io with details
3. Include steps to reproduce
4. Allow reasonable time for fix

We appreciate responsible disclosure and will credit researchers (if desired).