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 and periodically, syncs CrowdSec decisions with MikroTik state (adds missing, removes stale)
• High-performance sync — connection pool, script-based bulk add, in-memory cache (~28,700 IPs in ~58 s wall-clock on RB5009 with CAPI)
• 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    # Optional: mount a config file; this path is loaded automatically when present.
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

If setup used custom paths, pass the same values to uninstall:

1sudo cs-routeros-bouncer uninstall \
2  -bin /opt/cs-routeros-bouncer/cs-routeros-bouncer \
3  -config-dir /opt/cs-routeros-bouncer/config \
4  -purge

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
25TimeoutStopSec=90
26
27[Install]
28WantedBy=multi-user.target
29EOF
30
31sudo systemctl daemon-reload
32sudo 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: Checks the in-memory cache first. New addresses are added to the MikroTik address list with the CrowdSec ban duration as timeout (~1–3 ms); cached duplicate ban events skip the RouterOS API entirely.
• Unban: Checks in-memory cache first — if IP not present, skips API call entirely; otherwise finds and removes the IP immediately
• Periodic reconciliation: Every crowdsec.reconciliation_interval (default 15m), fetches active CrowdSec decisions and repairs address-list drift. Set it to 0 to disable; values below 1m are rejected.
• Uses an optimistic-add pattern for cache misses (~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 RouterOS firewall menu by default (rule_placement: top) to ensure they are evaluated early. 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 managed block can be placed.

You can also place the managed rule block after or before an existing rule comment, or at a zero-based RouterOS position:

1firewall:
2  rule_placement:
3    strategy: "after_comment"
4    comment: "drop invalid"
5    comment_match: "contains"
6    fallback: "top"
7    raw:
8      strategy: "top"

For numeric placement, position is required and follows RouterOS print numbering. Out-of-range positions, such as position: 15 when only 10 existing non-bouncer rules are present, append directly at the bottom without fallback or retry. The bouncer retries lower positions only when RouterOS rejects the move before an existing dynamic/built-in rule.

Comment placement uses comment_match: "exact" by default. Use contains for a case-sensitive literal substring match. Missing anchors use fallback (top by default, or bottom). Table-specific filter and raw overrides inherit unspecified fields from the global placement. Protocol-specific firewall.ipv4.rule_placement and firewall.ipv6.rule_placement overrides can refine the global settings for one address family, including protocol-local filter and raw overrides.

Placement precedence is: global placement, global filter/raw override, protocol override, then protocol filter/raw override.

1firewall:
2  rule_placement:
3    strategy: "top"
4  ipv4:
5    rule_placement:
6      strategy: "before_comment"
7      comment: "IPv4 production anchor"
8      fallback: "bottom"
9  ipv6:
10    rule_placement:
11      strategy: "bottom"
12      filter:
13        strategy: "after_comment"
14        comment: "IPv6 filter anchor"
15      raw:
16        strategy: "position"
17        position: 4

Tested on a MikroTik RB5009UG+S+ (ARM64, 4 cores @ 1400 MHz, 1 GB RAM, RouterOS 7.22.1) with the bouncer running on a separate Linux host connected via the RouterOS API (plaintext, port 8728). The CAPI measurements below used mikrotik.pool_size: 10 and crowdsec.reconciliation_interval: 1m.

Router CPU can spike during reconciliation, especially at startup or whenever real drift requires add/remove work. Sustained high RouterOS CPU after reconciliation is not expected from simply keeping entries in memory; it usually points to repeated RouterOS API writes/reconnects, duplicate-decision churn, or unrelated router workload.

The bouncer uses a configurable connection pool (default 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), normal network forwarding, and any active firewall workload. 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 ban decision for an IP that is already known to be present on the router, the bouncer returns from the in-memory cache fast-path and does not write to RouterOS again. This avoids RouterOS management/API churn during repeated stream updates.

If the local cache is cold or out of sync and RouterOS replies with already have such entry, the bouncer treats that as a RouterOS device error, not a connection failure. It keeps the API connection open, finds the existing address-list entry, and updates its timeout/comment without creating a duplicate.

The address list only ever contains one entry per IP. Cached duplicate decisions do not refresh the RouterOS timeout during the same run; startup and periodic reconciliation restore membership by adding missing entries and removing stale ones.

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 (~28k 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 Go bouncer (archived)
• nvtkaszpir/cs-mikrotik-bouncer-alt — alternative Go bouncer