Skip to main content

Machines

CrowdSec is composed of different components that communicate via a Local API. To access it, the various components (CrowdSec agent, cscli and bouncers) need to be authenticated.

info

This documentation is be relevant mostly to administrators that need to setup distributed architectures. Single machine users (or with several machines with independent crowdsec installations) can likely skip this part.

There are two kind of access to the local api :

  • machines: a login/password authentication used by cscli and CrowdSec, it allows to post, get and delete decisions and alerts.
  • bouncers: a token authentication used by bouncers to query the decisions, it only allows to get decisions.

Machines authentication​

caution

The cscli machines command interacts directly with the database (machines add and delete are not implemented in the API), therefore it must have the correct database configuration.

$ cscli machines list

You can view the registered machines with list, and add or delete them:

sudo cscli machines add mytestmachine -a
INFO[0004] Machine 'mytestmachine' created successfully       
INFO[0004] API credentials dumped to '/etc/crowdsec/local_api_credentials.yaml' 
sudo cscli machines delete 82929df7ee394b73b81252fe3b4e5020
cscli machines example
sudo cscli machines list
----------------------------------------------------------------------------------------------------------------------------------
 NAME                              IP ADDRESS  LAST UPDATE                STATUS  VERSION                                         
----------------------------------------------------------------------------------------------------------------------------------
 82929df7ee394b73b81252fe3b4e5020  127.0.0.1   2020-10-31T14:06:32+01:00  ✔️      v0.3.6-3d6ce33908409f2a830af6551a7f5e37f2a4728f 
----------------------------------------------------------------------------------------------------------------------------------
sudo cscli machines add mytestmachine -a
INFO[0004] Machine 'mytestmachine' created successfully       
INFO[0004] API credentials dumped to '/etc/crowdsec/local_api_credentials.yaml' 
sudo cscli machines list      
----------------------------------------------------------------------------------------------------------------------------------
 NAME                              IP ADDRESS  LAST UPDATE                STATUS  VERSION                                         
----------------------------------------------------------------------------------------------------------------------------------
 82929df7ee394b73b81252fe3b4e5020  127.0.0.1   2020-10-31T14:06:32+01:00  ✔️      v0.3.6-3d6ce33908409f2a830af6551a7f5e37f2a4728f 
 mytestmachine                     127.0.0.1   2020-11-01T11:37:19+01:00  ✔️      v0.3.6-6a18458badf8ae5fed8d5f1bb96fc7a59c96163c 
----------------------------------------------------------------------------------------------------------------------------------
sudo cscli machines delete -m 82929df7ee394b73b81252fe3b4e5020
sudo cscli machines list                                      
---------------------------------------------------------------------------------------------------------
 NAME     IP ADDRESS  LAST UPDATE                STATUS  VERSION                                         
---------------------------------------------------------------------------------------------------------
 mytestmachine  127.0.0.1   2020-11-01T11:37:19+01:00  ✔️      v0.3.6-6a18458badf8ae5fed8d5f1bb96fc7a59c96163c 
---------------------------------------------------------------------------------------------------------

Machine register​

It is also possible to register from an agent-only machine to the Local API with cscli lapi and then validate it on the Local API machine.

sudo cscli lapi register --url [crowdsec_local_api_url] --machine [your_machine_name]

Machine auto validation​

warning

If you enabled this feature, make sure to restrict the IP ranges as much as possible.

Any rogue machine registered in your LAPI will be able to push arbitrary alerts, and potentially lock you out.

In some situation, it's not practical to manually create or validate new machines in LAPI (eg, when running in an environment that uses auto-scaling).

It is possible to configure LAPI to automatically accept new machines upon creation with the api.server.auto_registration section:

  api:
    server:
      auto_registration:
        enabled: true
        token: "long_token_that_is_at_least_32_characters_long"
        allowed_ranges:
         - 10.2.0.42/32
         - 10.0.0.0/24

You have to specify both the token and allowed_ranges.

Once the configuration is done, you can pass the token to your registration request with the --token parameter:

cscli lapi register --machine my_machine --token long_token_that_is_at_least_32_characters_long

If the token is valid and the request is coming from an authorized IP range, LAPI will automatically validate the machine and it will be able to login without any further configuration.

If no token is sent, LAPI will treat the request as a normal registration, regardless of the configuration.

If a token is set but invalid, the request will be refused.

CrowdSec ConsoleCrowdSec Console