Project Structure

Directory layout

• Directorycmd/

  • Directorycs-routeros-bouncer/

    • main.go CLI entrypoint
• 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
  • 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)

  • …
• Directorylocal/

  • Directorydocs-legacy/ Original MkDocs docs (archive)

    • …
• Directorygrafana/

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

  • …
• 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

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/routeros

MikroTik RouterOS API client:

• 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)