Agent Overview

The Bloqd agent is a Python-based security agent that runs on your managed servers. It connects your fail2ban instances to the central Bloqd dashboard.

Features

• Whitelist Synchronization: Automatically sync whitelist from central server
• Ban Reporting: Report fail2ban bans to central server in real-time
• System Metrics: Collect and report CPU, memory, disk, and load metrics
• Health Monitoring: Perform health checks and report status
• Remote Commands: Execute commands from central server (ban/unban, reload, etc.)
• WebSocket: Real-time bidirectional communication with server

Requirements

• Python 3.10+
• Linux (Debian/Ubuntu, RHEL/Rocky/CentOS, Fedora)
• fail2ban installed
• Root access (required for fail2ban interaction)

Architecture

bloqd_agent/
├── agent.py              # Main agent class
├── config.py             # Configuration management
├── main.py               # Entry point & CLI
├── core/
│   ├── api_client.py     # REST API client
│   ├── websocket_client.py  # WebSocket client
│   ├── event_bus.py      # Internal event system
│   ├── scheduler.py      # Task scheduling
│   └── module_loader.py  # Dynamic module loading
├── modules/
│   ├── base.py           # Base module class
│   ├── sync.py           # Whitelist sync
│   ├── reporter.py       # Ban reporting
│   ├── metrics.py        # System metrics
│   ├── health.py         # Health checks
│   ├── commands.py       # Remote commands
│   ├── terminal.py       # Terminal sessions
│   ├── siem.py           # Security auditing (Pro)
│   └── portknock.py      # Port knocking (Pro)
└── utils/
    └── fail2ban.py       # Fail2ban client

Communication Flow

┌──────────────────┐          ┌──────────────────┐
│                  │  HTTPS   │                  │
│   Bloqd Server   │◄────────►│   Bloqd Agent    │
│                  │          │                  │
└──────────────────┘          └──────────────────┘
        │                              │
        │                              │
        ▼                              ▼
┌──────────────────┐          ┌──────────────────┐
│                  │          │                  │
│    Dashboard     │          │    fail2ban      │
│                  │          │                  │
└──────────────────┘          └──────────────────┘

Data Flow

1. Registration: Agent registers with server on startup
2. Heartbeat: Regular metrics and status updates
3. Whitelist Sync: Download whitelist from server
4. Ban Reporting: Report bans via Unix socket → API
5. Commands: Poll or receive commands via WebSocket
6. Health Checks: Report system and service health

Modules

The agent uses a modular architecture. Each module can be enabled/disabled independently.

Module	Purpose	Interval
sync	Whitelist synchronization	5 minutes
reporter	Ban event reporting	Event-driven
metrics	System metrics collection	5 minutes
health	Health checks	30 minutes
commands	Remote command execution	30 seconds
terminal	Interactive terminal	On-demand
siem	Security auditing	1 hour
portknock	Port knocking	1 minute

File Locations

File	Path
Agent binary	/usr/local/bin/bloqd-agent
Configuration	/etc/bloqd/agent.yaml
Virtual environment	/opt/bloqd-agent/venv/
Logs	/var/log/bloqd/agent.log
PID file	/var/run/bloqd-agent/agent.pid
Report socket	/var/run/bloqd-agent/report.sock
Whitelist	/etc/fail2ban/bloqd-whitelist.txt

Systemd Service

The agent runs as a systemd service:

# Check status
systemctl status bloqd-agent

# View logs
journalctl -u bloqd-agent -f

# Restart
systemctl restart bloqd-agent

# Stop
systemctl stop bloqd-agent

Security Considerations

• Configuration file has restricted permissions (0600)
• API key stored securely in config
• Commands validated before execution
• Custom commands restricted to fail2ban-client
• No command chaining or shell injection allowed