Skip to main content
Version: Next

Blocklist mirror

📚 Documentation💠 Hub💬 Discourse

This bouncer exposes CrowdSec's active decisions via provided HTTP endpoints in pre-defined formats. It can be used by network appliances which support consumption of blocklists via HTTP.

Installation from packages#

Setup crowdsec repositories.

sudo apt install crowdsec-blocklist-mirror

Installation using docker:#

Refer to docker hub docs

Manual installation via script#

First, download the latest crowdsec-blocklist-mirror release.

tar xzvf crowdsec-blocklist-mirror.tgzsudo ./install.sh

From source#

Run the following commands:

git clone https://github.com/crowdsecurity/crowdsec-blocklist-mirror.gitcd crowdsec-blocklist-mirror/make releasetar xzvf crowdsec-blocklist-mirror.tgzcd crowdsec-blocklist-mirror-v*/sudo ./install.sh

Configuration#

Before starting the crowdsec-blocklist-mirror service, please edit the configuration file to add your API URL and key. The default configuration file is located under : /etc/crowdsec/bouncers/

$ vim /etc/crowdsec/bouncers/crowdsec-blocklist-mirror.yaml
config_version: v1.0crowdsec_config:  lapi_key: ${API_KEY}  lapi_url: http://127.0.0.1:8080/  update_frequency: 10s  include_scenarios_containing: []  exclude_scenarios_containing: []  only_include_decisions_from: []  insecure_skip_verify: false
blocklists:  - format: plain_text # Supported formats are either of "plain_text"    endpoint: /security/blocklist    authentication:      type: none # Supported types are either of "none", "ip_based", "basic"      user:      password:      trusted_ips: # IP ranges, or IPs which don't require auth to access this blocklist        - 127.0.0.1        - ::1
listen_uri: 127.0.0.1:41412tls:  cert_file:  key_file:
metrics:  enabled: true  endpoint: /metrics
log_media: filelog_dir: /var/log/log_level: infolog_max_size: 40log_max_age: 30log_max_backups: 3enable_access_logs: truecompress_logs: true

crowdsec_config#

lapi_url:#

The URL of CrowdSec LAPI. It should be accessible from whichever network the bouncer has access.

lapi_key:#

It can be obtained by running the following on the machine CrowdSec LAPI is deployed on.


sudo cscli -oraw bouncers add cloudflarebouncer # -oraw flag can discarded for human friendly output.

update_frequency:#

The bouncer will poll the CrowdSec every update_frequency interval.

include_scenarios_containing:#

Ignore IPs banned for triggering scenarios not containing either of provided word.

exclude_scenarios_containing:#

Ignore IPs banned for triggering scenarios containing either of provided word.

only_include_decisions_from:#

Only include IPs banned due to decisions orginating from provided sources. eg value ["cscli", "crowdsec"]

insecure_skip_verify:#

Set to true to skip verifying certificate.

listen_uri:#

Location where the mirror will start server.

tls_config#

cert_file:#

Path to certificate to use if TLS is to be enabled on the mirror server.

key_file:#

Path to certificate key file.

metrics:#

enabled:#

Boolean (true|false). Set to true to enable serving and collecting metrics.

endpoint:#

Endpoint to serve the metrics on.

blocklists:#

List of blocklists to serve. Each blocklist has the following configuration.

format:#

Format of the blocklist. Currently only plain_text is supported.

endpoint:#

Endpoint to serve the blocklist on.

authentication:#

Authentication related config.

type:#

Currently "basic" and "ip_based" authentication is supported. You can disable authentication completely by setting this to 'none'.

  • basic: It's Basic HTTP Authentication. Only requests with valid user and password as specified in below config would pass through

  • ip_based: Only requests originating from trusted_ips would be allowed.

user:#

Valid username if using basic authentication.

password:#

Password for the provided user and using basic authentication.

trusted_ips:#

List of valid IPv4 and IPv6 IPs and ranges which have access to blocklist. It's only applicable when authentication type is ip_based.

You can then start the service via:

sudo systemctl start crowdsec-blocklist-mirror

Formats#

The bouncer can expose the blocklist in the following formats. You can configure the format of the blocklist by setting it's format paramter to any of the supported formats described below.

plain_text#

Example:

1.2.3.44.3.2.1

Observability#

The bouncer by default exposes the metrics at <listen_uri>/metrics . listen_uri is where the blocklist is served.

The exposed metrics are:

  • lapi_requests_total : This is the count of total calls made to the CrowdSec LAPI by bouncer.
  • lapi_requests_failures_total : This is the total number of failed calls to CrowdSec LAPI.
  • blocklist_requests_total: This is counter vector for each route denoting total requests made.
  • active_decision_count: This is the current count of total number IPs served by the blocklist mirror.

Alerting when LAPI is unreachable#

The metrics can be used to receive alerts if the bouncer can't reach LAPI via prometheus. The following prometheus rule can be used.

# rules.ymlgroups:- name: lapi  rules:  - alert: LAPIFailure    expr: delta(lapi_requests_failures_total[15s]) > 0    for: 5m

In prometheus alertmanager you can then handle as needed. A sample alertmanger config which posts a simple message on slack when LAPI request fails would look like:

# alertmanager.ymlglobal:  resolve_timeout: 1m  slack_api_url: '<your_slack_webhook_url>'
route:  receiver: 'lapi'
receivers:  - name: 'lapi'
    slack_configs:    - channel: '#crowdsec-notifications'       send_resolved: true      text: Bouncer can't reach LAPI