How It Works

This page explains the core workflows in Bloqd.

Server Registration

When you add a new server, Bloqd:

1. Generates an install token containing:

   • API key for the agent
   • Selected jail configurations
   • Server name and settings

2. User runs the installer on the target server:

   curl -sSL https://bloqd.example.com/api/v1/installer/script/inst_xxx | sudo bash

3. Installer performs setup:

   • Installs dependencies (Python, fail2ban, jq)
   • Downloads and configures the agent
   • Sets up fail2ban with selected jails
   • Creates systemd service
   • Starts the agent

4. Agent registers with server:

   • Sends hostname, OS info, fail2ban version
   • Server marks install token as used
   • Server creates server record in database

Whitelist Synchronization

Bloqd maintains a central whitelist that syncs to all servers.

Adding an Entry

1. User adds IP/CIDR in dashboard
2. Entry stored in whitelist table
3. WebSocket notifies connected clients

Sync Process

Every 5 minutes (configurable), each agent:

1. Fetches whitelist: GET /api/v1/whitelist/plain
2. Compares with local file
3. If different, writes new whitelist
4. Reloads fail2ban: fail2ban-client reload

Whitelist Format

The whitelist is stored as plain text for fail2ban compatibility:

# Bloqd whitelist - do not edit manually
192.168.1.100
10.0.0.0/8
2001:db8::/32

Ban Reporting

When fail2ban bans an IP, Bloqd captures it immediately.

fail2ban Action

Each jail includes the Bloqd action:

[sshd]
enabled = true
action = %(action_)s
         bloqd-report

The action script (/usr/local/bin/bloqd-report) writes to a Unix socket:

echo "$IP|$JAIL|$LOGLINES" | nc -U /var/run/bloqd-agent/report.sock

Agent Processing

The Reporter module:

1. Reads from Unix socket
2. Parses IP, jail name, and log excerpt
3. Adds metadata (hostname, timestamp)
4. Sends to server: POST /api/v1/report

Server Processing

1. Validates the report
2. Checks for duplicates (15-min window)
3. Performs GeoIP lookup
4. Stores in ban_reports table
5. Broadcasts via WebSocket
6. Sends Discord notification (if enabled)
7. Reports to AbuseIPDB (if enabled)

Remote Commands

Bloqd can execute commands on managed servers.

Supported Commands

Command	Description
jail_enable	Enable a fail2ban jail
jail_disable	Disable a fail2ban jail
fail2ban_reload	Reload fail2ban configuration
ip_ban	Manually ban an IP
ip_unban	Unban an IP
ip_unban_all	Unban all IPs in a jail
whitelist_sync	Force whitelist sync
agent_update	Update the agent

Execution Flow

1. User initiates command in dashboard
2. Server queues command in database with "pending" status
3. Agent polls for commands every 30 seconds
4. Agent acknowledges command (status: "acknowledged")
5. Agent executes the command
6. Agent reports result (status: "completed" or "failed")
7. Server broadcasts result via WebSocket

Security

Commands are restricted to a predefined list. The agent never executes arbitrary shell commands unless explicitly allowed in configuration.

Health Monitoring

Agents report server health metrics.

Collected Metrics

Metric	Description
cpu_percent	CPU usage percentage
memory_percent	RAM usage percentage
disk_percent	Disk usage percentage
load_average	1, 5, 15 minute load averages
uptime	Server uptime in seconds
fail2ban_status	Running/stopped
enabled_jails	List of active jails

Reporting Interval

• Heartbeat: Every 60 seconds
• Full metrics: Every 5 minutes
• Health report: Every 15 minutes

Server Status

The dashboard shows server status based on last heartbeat:

Status	Condition
Online	Seen within 90 minutes
Offline	Not seen for 90+ minutes

Real-Time Updates

Bloqd uses WebSocket for instant updates.

Events

Event	Triggered When
ban	New ban reported
server_status	Server comes online/offline
server_jails_updated	Jail list changes
sync_complete	Whitelist sync completes
command_result	Command finishes

Connection

Dashboard connects on page load:

const ws = new WebSocket('wss://bloqd.example.com/ws');
ws.onmessage = (event) => {
  const { type, data } = JSON.parse(event.data);
  // Handle event
};

Integrations

AbuseIPDB

When enabled, Bloqd automatically reports malicious IPs:

1. Ban received from agent
2. Map jail to AbuseIPDB category (e.g., sshd → category 22)
3. Check rate limit (1000/day default)
4. Submit report with IP, category, and comment
5. Store report record to prevent duplicates

Discord

Real-time notifications via webhook:

1. Event occurs (ban, sync, error)
2. Format embed with appropriate color
3. POST to Discord webhook URL
4. Handle rate limits gracefully

Email/SMTP

Daily summary reports and alerts:

1. Scheduler triggers at configured hour
2. Aggregate bans from last 24 hours
3. Generate HTML email
4. Send via configured SMTP server