Project Structure

Directory layout

• Directorycmd/

  • Directorybenchmark/ RouterOS operation benchmark tool

    • …
  • Directorycs-routeros-bouncer/

    • main.go CLI entrypoint
  • Directoryperfmon/ Router instrumentation and charting

    • …
• Directoryinternal/

  • Directoryconfig/

    • config.go Configuration struct and loading
    • config_test.go
    • doc.go Package documentation
  • Directorycrowdsec/

    • bouncer_iface.go CrowdSec bouncer interface
    • crowdsec_test.go
    • doc.go Package documentation
    • logrus_adapter.go Logrus-to-zerolog adapter
    • logrus_adapter_test.go
    • mock_bouncer_test.go
    • stream.go Streaming mode
    • stream_test.go
  • Directorymanager/

    • crowdsec_iface.go CrowdSec stream interface
    • doc.go Package documentation
    • manager.go Central orchestrator
    • manager_test.go
    • mock_test.go
    • routeros_iface.go RouterOS client interface
    • start_test.go Startup and reconciliation tests
  • Directorymetrics/

    • doc.go Package documentation
    • Directorylapi/ CrowdSec LAPI usage metrics

      • …
    • metrics.go Prometheus metric definitions
    • metrics_test.go
    • server.go HTTP server for /metrics and /health
  • Directoryrosapi/ Vendored RouterOS API client

    • client.go Dial, login, command dispatch
    • error.go RouterOS !trap errors
    • logger.go Logging hook
    • Directoryproto/ Wire protocol

      • …
    • reply.go Reply assembly
    • run.go Sentence execution
  • Directoryrouteros/

    • addresslist.go Address list operations
    • bulk.go Bulk script operations
    • client.go RouterOS API client
    • client_mock_test.go
    • conn_iface.go RouterOS connection interface
    • doc.go Package documentation
    • firewall.go Firewall rule operations
    • mock_conn_test.go
    • pool.go Connection pool
    • routeros_test.go
• Directorydocs/ Documentation (Starlight)

  • …
• Directorygrafana/

  • dashboard.json Grafana dashboard
• Directoryconfig/ Example configuration files

  • …
• Directorydocker/

  • Dockerfile Docker build
• go.mod Go module definition
• LICENSE MIT License
• README.md Project readme

Package responsibilities

cmd/cs-routeros-bouncer

CLI entrypoint. Handles:

• Subcommand routing (setup, uninstall, version, help) and runtime flags (-c, -version)
• Signal handling (SIGTERM, SIGINT)
• Graceful shutdown coordination

cmd/benchmark

Single-operation RouterOS benchmark, described in Benchmarking. Development and capacity planning only.

cmd/perfmon

Router-side instrumentation, also covered in Benchmarking:

• Cross-builds a 10 Hz /proc/stat sampler and packs it as a container image without Docker
• Installs it on a RouterOS device idempotently (veth, NAT, firewall list membership) and removes exactly what it created
• Pulls capture windows from Loki as CSV and renders the lifecycle chart

internal/config

Configuration management:

• Loads configuration from YAML file and/or environment variables
• Validates all parameters
• Provides sensible defaults
• Maps environment variable names to config struct fields

internal/crowdsec

CrowdSec LAPI integration:

• HTTP client for CrowdSec Local API
• Streaming mode: polls for new/deleted decisions
• Decision filtering by origin, scenario, and scope
• TLS certificate support

internal/manager

Central orchestrator that connects all components:

• Startup: connects to CrowdSec and MikroTik, creates firewall rules, runs reconciliation
• Runtime: processes streaming decisions (bans/unbans)
• Shutdown: removes firewall rules, closes connections
• Error handling and retry logic

internal/metrics

Observability:

• Prometheus metric definitions and registration
• Health check endpoint (/health)
• RouterOS system metrics collector (CPU, memory, temperature)
• HTTP server for /metrics and /health endpoints

internal/rosapi

The RouterOS API protocol itself, vendored so the project owns the wire format rather than depending on an unmaintained third party. It is a pruned fork: the asynchronous and listen modes are gone, as is MD5 challenge login, because this bouncer uses none of them and each was surface area to maintain.

• proto/: sentence encoding, length-prefixed word framing, reader and writer
• Synchronous command dispatch under a mutex, with a per-command deadline
• !trap/!fatal mapping to Go errors, with password redaction in logs

internal/routeros

MikroTik RouterOS API client, built on internal/rosapi:

• Connection pool with configurable size
• Address list operations (add, remove, list)
• Firewall rule operations (create, delete, list)
• System information queries
• Bulk script execution for reconciliation
• Parallel execution helper (ParallelExec)