secubox-openwrt/package/secubox/CROWDSEC-OPENWRT-24.md

CrowdSec Integration for OpenWrt 24.10+ (SecuBox)

Overview

This documentation covers the complete CrowdSec security solution integration for OpenWrt 24.10+ with fw4/nftables support. The integration consists of two packages:

1. secubox-crowdsec-setup: Automated installation script
2. luci-app-secubox-crowdsec: LuCI web interface dashboard

Requirements

Hardware

• Minimum 256MB RAM
• Minimum 50MB available flash storage
• ARM64, ARMv7, x86_64, or MIPS architecture

Software

• OpenWrt 24.10 or later
• fw4 with nftables (default in OpenWrt 24.10+)
• Internet connectivity for initial setup

Quick Installation

Method 1: Using the Setup Script

# Install dependencies
opkg update
opkg install secubox-crowdsec-setup

# Run the automated setup
secubox-crowdsec-setup --install

Method 2: Manual Installation

# Update package lists
opkg update

# Install required packages
opkg install crowdsec crowdsec-firewall-bouncer syslog-ng

# Install LuCI dashboard (optional)
opkg install luci-app-secubox-crowdsec

Architecture

                    +-----------------------+
                    |    OpenWrt System     |
                    +-----------------------+
                             |
              +--------------+--------------+
              |                             |
      +-------v-------+           +---------v---------+
      |   syslog-ng  |           |   logread -f      |
      | (UDP 5140)    |           |   (fallback)      |
      +-------+-------+           +---------+---------+
              |                             |
              +-------------+---------------+
                            |
                    +-------v-------+
                    |   CrowdSec    |
                    | (LAPI :8080)  |
                    +-------+-------+
                            |
              +-------------+-------------+
              |                           |
      +-------v-------+          +--------v--------+
      |  Local CAPI   |          |   CrowdSec      |
      |  (blocklists) |          |   Hub (parsers, |
      +---------------+          |   scenarios)    |
                                 +-----------------+
                                          |
                            +-------------v-------------+
                            | crowdsec-firewall-bouncer |
                            |    (nftables mode)        |
                            +-------------+-------------+
                                          |
                                 +--------v--------+
                                 |  nftables fw4   |
                                 |  (crowdsec/     |
                                 |   crowdsec6)    |
                                 +-----------------+

Components

1. syslog-ng Configuration

Located at /etc/syslog-ng/syslog-ng.conf, this configuration:

• Captures all system logs via Unix socket
• Forwards logs to CrowdSec via UDP port 5140
• Writes local copies to /tmp/log/ for debugging

Key sources monitored:

• System logs (/dev/log)
• Kernel messages (/proc/kmsg)
• Authentication logs (SSH, login attempts)

2. CrowdSec Engine

Configuration directory: /etc/crowdsec/

Main components:

• config.yaml: Main configuration file
• acquis.d/: Acquisition configuration files
• parsers/: Log parsing rules
• scenarios/: Attack detection scenarios
• hub/: Downloaded hub content

Data storage: /srv/crowdsec/data/

3. Firewall Bouncer

Configuration: /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml

Creates nftables tables:

• ip crowdsec: IPv4 blocking
• ip6 crowdsec6: IPv6 blocking

4. LuCI Dashboard

Accessible via: Services > CrowdSec

Features:

• Dashboard with service status
• Active decisions (bans) management
• Security alerts viewer
• Collections management
• Settings configuration

UCI Configuration

The UCI configuration file /etc/config/crowdsec contains:

config crowdsec 'crowdsec'
    option enabled '1'
    option data_dir '/srv/crowdsec/data'
    option db_path '/srv/crowdsec/data/crowdsec.db'

config acquisition 'acquisition'
    option syslog_enabled '1'
    option firewall_enabled '1'
    option ssh_enabled '1'
    option http_enabled '0'

config hub 'hub'
    option auto_install '1'
    option collections 'crowdsecurity/linux crowdsecurity/sshd crowdsecurity/iptables'
    option update_interval '7'

config bouncer 'bouncer'
    option enabled '1'
    option ipv4 '1'
    option ipv6 '1'
    option deny_action 'drop'
    option deny_log '1'
    option update_frequency '10s'

Default Collections

The following collections are installed by default:

Collection	Description
crowdsecurity/linux	Linux system security
crowdsecurity/sshd	SSH brute-force protection
crowdsecurity/iptables	Firewall logs parsing
crowdsecurity/http-cve	HTTP CVE exploits

Command Reference

Service Management

# CrowdSec service
/etc/init.d/crowdsec start|stop|restart|enable|disable

# Firewall bouncer
/etc/init.d/crowdsec-firewall-bouncer start|stop|restart|enable|disable

# Syslog-ng
/etc/init.d/syslog-ng start|stop|restart|enable|disable

cscli Commands

# View status
cscli lapi status
cscli capi status

# Decision management
cscli decisions list
cscli decisions add --ip <IP> --duration 24h --reason "Manual ban"
cscli decisions delete --ip <IP>

# Alert management
cscli alerts list
cscli alerts list --since 24h

# Collection management
cscli collections list
cscli collections install crowdsecurity/nginx
cscli collections remove crowdsecurity/nginx

# Hub management
cscli hub update
cscli hub upgrade

# Bouncer management
cscli bouncers list

# Metrics
cscli metrics

nftables Commands

# List CrowdSec tables
nft list tables | grep crowdsec

# Show blocked IPs (IPv4)
nft list set ip crowdsec crowdsec-blacklists

# Show blocked IPs (IPv6)
nft list set ip6 crowdsec6 crowdsec6-blacklists

Troubleshooting

CrowdSec not starting

# Check logs
logread | grep crowdsec
cat /var/log/crowdsec.log

# Verify configuration
cscli config show

LAPI unavailable

# Check if CrowdSec is running
pgrep crowdsec

# Repair machine registration
cscli machines add localhost --auto --force
/etc/init.d/crowdsec restart

Bouncer not blocking

# Check bouncer status
pgrep -f crowdsec-firewall-bouncer

# Verify nftables tables
nft list tables

# Check bouncer API key
cat /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml | grep api_key

syslog-ng issues

# Check if running
pgrep syslog-ng

# Test configuration
syslog-ng -s

# Check UDP listener
netstat -uln | grep 5140

No alerts being generated

# Check acquisition
cscli metrics show acquisition

# Test log parsing
echo "Failed password for root from 192.168.1.100 port 22222 ssh2" | \
  cscli parsers inspect crowdsecurity/sshd-logs

Uninstallation

# Using setup script
secubox-crowdsec-setup --uninstall

# Manual removal
/etc/init.d/crowdsec-firewall-bouncer stop
/etc/init.d/crowdsec stop
/etc/init.d/syslog-ng stop

opkg remove luci-app-secubox-crowdsec
opkg remove crowdsec-firewall-bouncer
opkg remove crowdsec
opkg remove syslog-ng

# Clean nftables
nft delete table ip crowdsec
nft delete table ip6 crowdsec6

# Re-enable logd
/etc/init.d/log enable
/etc/init.d/log start

Security Considerations

Whitelist Local Networks

The default configuration includes a whitelist for RFC1918 private networks:

• 10.0.0.0/8
• 172.16.0.0/12
• 192.168.0.0/16
• 127.0.0.0/8

This prevents accidental blocking of local management access.

Bouncer API Key

The bouncer API key is automatically generated during setup and stored in:

• /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml
• UCI config: crowdsec.bouncer.api_key

Log Retention

Logs in /tmp/log/ are stored in tmpfs and cleared on reboot. For persistent logging, configure syslog-ng to write to overlay storage.

Performance Optimization

For resource-constrained devices:

1. Reduce update frequency:

   uci set crowdsec.bouncer.update_frequency='30s'
   uci commit crowdsec
   

2. Disable IPv6 if not used:

   uci set crowdsec.bouncer.ipv6='0'
   uci commit crowdsec
   

3. Limit collections: Only install collections relevant to your setup.

Integration with SecuBox

This CrowdSec integration is part of the SecuBox security suite for OpenWrt. It works alongside other SecuBox components:

• SecuBox Firewall
• SecuBox VPN
• SecuBox DNS filtering
• SecuBox Monitoring

License

MIT License - Copyright (C) 2025 CyberMind.fr

Support

• GitHub Issues: https://github.com/secubox/secubox-openwrt
• Documentation: https://docs.secubox.io
• CrowdSec Docs: https://docs.crowdsec.net