A CrowdSec remediation component (bouncer) for MikroTik RouterOS that automatically manages firewall rules and address lists via the RouterOS API.

• Zero manual router configuration — auto-creates and auto-removes firewall filter/raw rules on start/stop
• Individual IP management — adds on ban, removes on unban (no bulk re-upload, no duplicates)
• State reconciliation — on start/restart, syncs CrowdSec decisions with MikroTik state (adds missing, removes stale)
• High-performance sync — connection pool, script-based bulk add, in-memory cache (~1,500 IPs in ~9 s, ~25,000 IPs in ~2 min 50 s)
• Graceful shutdown — removes firewall rules on stop (address list entries expire via MikroTik timeout)
• IPv4 + IPv6 — independently toggleable
• Input + Output blocking — output blocking optional with configurable interface/interface-list
• Decision filtering — sync only local decisions or include CrowdSec community blocklists (CAPI)
• Observable — Prometheus metrics (/metrics), structured logging, health endpoint (/health), LAPI usage metrics (active decisions, dropped traffic)
• Multiple deployment options — Docker, systemd, or standalone binary

Existing MikroTik bouncers have significant limitations that this project addresses:

• CrowdSec 1.5+ with LAPI accessible from the bouncer host
• MikroTik RouterOS 7.x with API enabled (port 8728 or 8729 for TLS)
• A dedicated RouterOS API user (see Router Setup)

1sudo cscli bouncers add cs-routeros-bouncer

Save the API key shown in the output.

Connect to your MikroTik router and create a dedicated user:

1/user group add name=crowdsec policy=read,write,api,sensitive,!ftp,!local,!ssh,!reboot,!policy,!test,!password,!sniff,!romon,!rest-api
2/user add name=crowdsec group=crowdsec password=YOUR_SECURE_PASSWORD

Choose your preferred installation method below.

1services:
2  cs-routeros-bouncer:
3    image: ghcr.io/jmrplens/cs-routeros-bouncer:latest
4    container_name: cs-routeros-bouncer
5    restart: unless-stopped
6    ports:
7      - "2112:2112"  # Prometheus metrics (optional)
8    environment:
9      CROWDSEC_URL: "http://crowdsec:8080/"
10      CROWDSEC_BOUNCER_API_KEY: "your-bouncer-api-key"
11      MIKROTIK_HOST: "192.168.0.1:8728"
12      MIKROTIK_USER: "crowdsec"
13      MIKROTIK_PASS: "your-password"
14    # Or mount a config file:
15    # volumes:
16    #   - ./config.yaml:/etc/cs-routeros-bouncer/config.yaml

1docker compose up -d

Download the latest release from the Releases page:

Automatic setup (recommended):

1# Download (replace with your architecture: amd64, arm64, armv7)
2wget https://github.com/jmrplens/cs-routeros-bouncer/releases/latest/download/cs-routeros-bouncer_linux_amd64.tar.gz
3tar xzf cs-routeros-bouncer_linux_amd64.tar.gz
4
5# Automated install: copies binary, creates config, installs and starts systemd service
6sudo ./cs-routeros-bouncer setup
7
8# Edit configuration with your CrowdSec API key and MikroTik credentials
9sudo nano /etc/cs-routeros-bouncer/cs-routeros-bouncer.yaml
10
11# Restart after editing config
12sudo systemctl restart cs-routeros-bouncer

The setup subcommand accepts optional flags:

To uninstall:

1sudo cs-routeros-bouncer uninstall        # Keeps config files
2sudo cs-routeros-bouncer uninstall -purge  # Also removes config

1# Download
2wget https://github.com/jmrplens/cs-routeros-bouncer/releases/latest/download/cs-routeros-bouncer_linux_amd64.tar.gz
3tar xzf cs-routeros-bouncer_linux_amd64.tar.gz
4
5# Install
6sudo install -m 755 cs-routeros-bouncer /usr/local/bin/
7sudo mkdir -p /etc/cs-routeros-bouncer
8sudo cp cs-routeros-bouncer.yaml /etc/cs-routeros-bouncer/cs-routeros-bouncer.yaml
9
10# Edit configuration
11sudo nano /etc/cs-routeros-bouncer/cs-routeros-bouncer.yaml
12
13# Install systemd service
14sudo tee /etc/systemd/system/cs-routeros-bouncer.service > /dev/null << 'EOF'
15[Unit]
16Description=CrowdSec RouterOS Bouncer
17After=network-online.target crowdsec.service
18Wants=network-online.target
19
20[Service]
21Type=simple
22ExecStart=/usr/local/bin/cs-routeros-bouncer -c /etc/cs-routeros-bouncer/cs-routeros-bouncer.yaml
23Restart=on-failure
24RestartSec=10
25
26[Install]
27WantedBy=multi-user.target
28EOF
29
30sudo systemctl daemon-reload
31sudo systemctl enable --now cs-routeros-bouncer

1git clone https://github.com/jmrplens/cs-routeros-bouncer.git
2cd cs-routeros-bouncer
3make build
4
5# Option 1: Automated install
6sudo bin/cs-routeros-bouncer setup
7
8# Option 2: Manual install
9sudo install -m 755 bin/cs-routeros-bouncer /usr/local/bin/

All options can be set via YAML config file or environment variables. Environment variables override config file values.

See config/cs-routeros-bouncer.yaml for the full annotated reference.

The essential settings to get the bouncer running. Most deployments only need these.

Fine-tuning options for decision filtering, TLS, performance, firewall customization, and observability. The defaults work well for most setups.

1crowdsec:
2  api_url: "http://localhost:8080/"
3  api_key: "your-key"
4mikrotik:
5  address: "192.168.0.1:8728"
6  username: "crowdsec"
7  password: "your-password"
8firewall:
9  ipv6:
10    enabled: false
11  raw:
12    enabled: false

1crowdsec:
2  api_url: "http://localhost:8080/"
3  api_key: "your-key"
4mikrotik:
5  address: "192.168.0.1:8729"
6  username: "crowdsec"
7  password: "your-password"
8  tls: true
9firewall:
10  ipv4:
11    enabled: true
12  ipv6:
13    enabled: true
14  filter:
15    enabled: true
16    chains: ["input"]
17  raw:
18    enabled: true
19    chains: ["prerouting"]
20  deny_action: "drop"
21  rule_placement: "top"
22  block_input:
23    interface_list: "WAN"
24  block_output:
25    enabled: true
26    interface_list: "WAN"
27metrics:
28  enabled: true
29  listen_port: 2112
30logging:
31  level: "info"

1crowdsec:
2  api_url: "http://localhost:8080/"
3  api_key: "your-key"
4  origins: ["crowdsec", "cscli"]
5mikrotik:
6  address: "192.168.0.1:8728"
7  username: "crowdsec"
8  password: "your-password"

1. Connects to CrowdSec LAPI and MikroTik RouterOS API (connection pool with 4 connections)
2. Creates firewall rules (filter and/or raw) that reference named address lists
3. Collects all current CrowdSec decisions (bans and deletes are collected simultaneously to avoid stale data)
4. Reconciles with MikroTik address lists — adds missing IPs using script-based bulk add (chunks of 100), removes stale ones in parallel
5. Populates in-memory address cache for O(1) lookups during runtime

• Ban: Adds IP to the MikroTik address list with the CrowdSec ban duration as timeout (~1–3 ms)
• Unban: Checks in-memory cache first — if IP not present, skips API call entirely; otherwise finds and removes the IP immediately
• Uses an optimistic-add pattern (~1–3 ms per IP vs ~400 ms with lookup-first)

• Removes all bouncer-managed firewall rules from MikroTik
• Address list entries remain and expire naturally via their MikroTik timeout

The bouncer creates rules with descriptive comments for identification:

1;;; crowdsec-bouncer:filter-input-input-v4 @cs-routeros-bouncer
2chain=input action=drop src-address-list=crowdsec-banned
3
4;;; crowdsec-bouncer:raw-prerouting-input-v4 @cs-routeros-bouncer
5chain=prerouting action=drop src-address-list=crowdsec-banned

Rules are placed at the top of the chain by default (rule_placement: top) to ensure they are evaluated first. If dynamic/built-in rules occupy the top positions (e.g., RouterOS fasttrack counters), the bouncer iterates through subsequent positions until it finds one where the rule can be placed.

Tested on a MikroTik RB5009UG+S+ (ARM64, 4 cores @ 1400 MHz, 1 GB RAM, RouterOS 7.21.3) with the bouncer running on a separate Linux host connected via the RouterOS API (plaintext, port 8728).

The bouncer uses a connection pool (4 parallel API connections), script-based bulk add (chunks of 100 entries), and an in-memory address cache for O(1) lookups during unban operations.

Note: All benchmarks measured on a real RB5009UG+S+ with production traffic. Router CPU includes SNMP monitoring (10 s interval) and normal network forwarding. Individual add/remove operations are typically 1–3 ms per IP (median). Occasional latency spikes (p95 up to ~50 ms) are caused by RouterOS internal scheduling on large address lists.

When CrowdSec sends a new ban decision for an IP that already exists in the MikroTik address list (e.g., a 24-hour ban is replaced by a 7-day ban), the bouncer handles it automatically:

1. Optimistic add — attempts to add the address to RouterOS
2. Conflict detection — RouterOS returns an "already have" error
3. Timeout update — the bouncer finds the existing entry and updates its timeout to the new duration

This ensures the most recent ban duration always takes effect, without creating duplicate entries. The operation typically takes ~5–8 ms (find + update).

1curl http://localhost:2112/health
2# {"status":"ok","routeros_connected":true,"version":"vX.Y.Z"}

Enable with metrics.enabled: true. Available at http://localhost:2112/metrics.

Note: dropped_bytes_total and dropped_packets_total use the _total suffix despite being Gauges. This is because they reflect cumulative counters read from RouterOS — the bouncer sets (not increments) the value each cycle, making Gauge the correct instrument type. The _total suffix is retained for semantic clarity.

The bouncer reports usage metrics directly to the CrowdSec LAPI (default: every 15 min). These metrics appear in the CrowdSec Console and include:

• Active decisions — per-origin (crowdsec, cscli, CAPI) and per-IP-type (ipv4, ipv6)
• Dropped traffic — bytes and packets blocked by MikroTik firewall rules (delta between pushes), per IP type
• Processed traffic — bytes and packets evaluated by all bouncer chains (delta between pushes), per IP type
• Bouncer metadata — type (cs-routeros-bouncer), version, OS info, startup timestamp

Configure with crowdsec.lapi_metrics_interval (set to 0 to disable).

A ready-to-use Grafana dashboard is included at grafana/dashboard.json.

Import steps:

1. In Grafana, go to Dashboards → Import
2. Upload grafana/dashboard.json or paste its contents
3. Select your Prometheus datasource
4. Click Import

The dashboard provides real-time visibility into the bouncer's operation:

Dashboard panels (27 panels in 8 rows):

See CONTRIBUTING.md for development setup and guidelines.

1make build          # Build binary
2make test           # Run tests
3make lint           # Run linter
4make docker-build   # Build Docker image

A comprehensive Bash test suite validates the compiled binary against a real MikroTik router. Tests use SSH, cscli, systemctl, and SNMP — no Go internals are imported.

1# Setup: copy and fill in your environment
2cp tests/functional/.env.example tests/functional/.env
3# Edit .env with your MikroTik SSH credentials, CrowdSec API key, etc.
4
5# Run all groups (except CAPI stress test)
6tests/functional/run_tests.sh
7
8# Run specific groups
9tests/functional/run_tests.sh t1 t2
10
11# Include CAPI stress test (~25k IPs — takes several minutes)
12tests/functional/run_tests.sh --capi
13
14# List available groups
15tests/functional/run_tests.sh --list

See SECURITY.md for the security policy and responsible disclosure process.

MIT

• CrowdSec — open-source collaborative security engine
• go-routeros — Go library for the RouterOS API
• funkolab/cs-mikrotik-bouncer — original Python bouncer (archived)
• nvtkaszpir/cs-mikrotik-bouncer-alt — alternative Python bouncer