Commands Module

The commands module allows executing remote commands on servers from the Bloqd dashboard.

Available Commands

Jail Management

Command	Description	Parameters
jail_enable	Start a jail	jail
jail_disable	Stop a jail	jail

fail2ban Operations

Command	Description	Parameters
fail2ban_reload	Reload fail2ban config	None
list_jails	List active jails	None
list_bans	List banned IPs	jail (optional)

IP Management

Command	Description	Parameters
ip_ban	Ban an IP	ip, jail (default: recidive)
ip_unban	Unban an IP	ip, jail (optional)
ip_unban_all	Unban all IPs	None

Synchronization

Command	Description	Parameters
whitelist_sync	Trigger whitelist sync	None
filter_sync	Sync filter files	filters[]

Configuration

Command	Description	Parameters
config_update	Update jail configuration	add_jails, modify_jails, remove_jails
custom_command	Execute fail2ban-client command	command

Agent Management

Command	Description	Parameters
agent_update	Update agent to latest version	None
agent_uninstall	Uninstall the agent	keep_fail2ban

Advanced Features

Command	Description	Parameters
terminal_start	Start terminal session	session_id
siem_enable	Enable SIEM module	install_lynis
siem_disable	Disable SIEM module	None
siem_run_audit	Run security audit	None
portknock_enable	Enable port knocking	Configuration
portknock_disable	Disable port knocking	None

Configuration

modules:
  commands:
    enabled: true
    poll_interval: 30  # seconds
    allowed_commands:
      - jail_enable
      - jail_disable
      - fail2ban_reload
      - ip_ban
      - ip_unban
      - ip_unban_all
      - whitelist_sync
      - list_bans
      - list_jails
      - agent_update
      - agent_uninstall
      - config_update
      - custom_command
      - filter_sync
      - terminal_start

Setting	Description	Default
enabled	Enable command execution	true
poll_interval	How often to poll for commands (seconds)	30
allowed_commands	List of allowed command types	All commands

How It Works

Polling Mode

1. Agent polls server every poll_interval seconds
2. Server returns pending commands
3. Agent acknowledges receipt
4. Agent executes command
5. Agent reports result

┌─────────────────┐  GET /commands   ┌─────────────────┐
│                 │◄────────────────│                 │
│  Bloqd Server   │                  │ Commands Module │
│                 │────────────────►│                 │
└─────────────────┘  Command list    └─────────────────┘
         ▲                                    │
         │                                    │ Execute
         │                                    ▼
         │                           ┌─────────────────┐
         │        Result             │    fail2ban     │
         └───────────────────────────│   (or other)    │
                                     └─────────────────┘

WebSocket Mode

When WebSocket is enabled, commands are pushed instantly:

1. Dashboard sends command
2. Server pushes to agent via WebSocket
3. Agent executes immediately
4. Result sent back

Command Flow

Dashboard UI
     │
     │ "Unban IP 192.168.1.100"
     ▼
Bloqd Server
     │
     │ Queue command
     ▼
Commands Table
     │
     │ Agent polls / WebSocket push
     ▼
Commands Module
     │
     │ Validate & execute
     ▼
fail2ban-client
     │
     │ Result
     ▼
Commands Module
     │
     │ Report completion
     ▼
Bloqd Server
     │
     │ Update UI
     ▼
Dashboard UI

Security

Command Restrictions

• Only commands in allowed_commands are executed
• Default list covers common operations
• Custom commands restricted to fail2ban-client
• No shell injection allowed

Custom Command Safety

The custom_command handler enforces:

# Must start with fail2ban-client
if not command.startswith("fail2ban-client"):
    return error

# No command chaining
if any(c in command for c in [";", "|", "&", "`", "$("]):
    return error

Valid examples:

• fail2ban-client status
• fail2ban-client set sshd banip 192.168.1.100
• fail2ban-client get sshd actions

Invalid examples:

• rm -rf / - Not fail2ban-client
• fail2ban-client status; cat /etc/passwd - Command chaining

Events

Event	Direction	Description
command_received	Subscribes	WebSocket command received
command_executed	Emits	Command completed
sync_requested	Emits	Triggers whitelist sync

Command Lifecycle

1. Queued: Command created, waiting for agent
2. Acknowledged: Agent received command
3. Completed: Execution finished successfully
4. Failed: Execution failed

Troubleshooting

Commands Not Executing

1. Check agent is running:

   systemctl status bloqd-agent

2. Check poll interval:

   grep poll_interval /etc/bloqd/agent.yaml

3. View pending commands:

   journalctl -u bloqd-agent | grep -i command

4. Verify command is allowed:

   grep allowed_commands /etc/bloqd/agent.yaml

Command Stuck in "Pending"

• Agent may be offline
• Check server connectivity
• Restart agent

Command Failed

1. Check result message in dashboard
2. Common causes:
   • Jail doesn't exist
   • IP already banned/unbanned
   • fail2ban not running
   • Permission denied