From 1dc7633571359d4366fee9f82df11601809deaec Mon Sep 17 00:00:00 2001 From: blotus Date: Fri, 20 Sep 2024 14:47:09 +0200 Subject: [PATCH] Update documentation for LAPI self registration (#623) --- .../configuration/crowdsec_configuration.md | 50 ++++++++++++++++++- .../user_guides/machines_management.mdx | 39 +++++++++++++++ 2 files changed, 88 insertions(+), 1 deletion(-) diff --git a/crowdsec-docs/docs/configuration/crowdsec_configuration.md b/crowdsec-docs/docs/configuration/crowdsec_configuration.md index 0fa8dcfd..ecf46e8e 100644 --- a/crowdsec-docs/docs/configuration/crowdsec_configuration.md +++ b/crowdsec-docs/docs/configuration/crowdsec_configuration.md @@ -193,6 +193,11 @@ api: #- 127.0.0.1 #- ::1 #- 10.0.0.0/24 + auto_registration: + enabled: + token: + allowed_ranges: + - 10.0.0.0/24 prometheus: enabled: "(true|false)" level: "(full|aggregated)" @@ -706,7 +711,11 @@ api: - bouncers_ou crl_path: "" cache_expiration: "" - + auto_registration: + enabled: + token: + allowed_ranges: + - 10.0.0.0/24 ``` #### `cti` @@ -808,6 +817,11 @@ server: - bouncers_ou crl_path: "" cache_expiration: "" + auto_registration: + enabled: + token: + allowed_ranges: + - 10.0.0.0/24 ``` ##### `enable` @@ -953,6 +967,40 @@ The format must be compatible with golang [time.Duration](https://pkg.go.dev/tim IPs or IP ranges which have admin access to API. The APIs would still need to have API keys. 127.0.0.1 and ::1 are always given admin access whether specified or not. +#### `auto_registration` + +This section configures LAPI to automatically accept new machine registrations + +```yaml +auto_registration: + enabled: + token: + allowed_ranges: + - 10.0.0.0/24 +``` + +##### `enabled` +> bool + +Whether automatic registration should be enabled. + +Defaults to `false`. + +##### `token` +> string + +Token that should be passed in the registration request if LAPI needs to automatically validate the machine. + +It must be at least 32 chars, and is mandatory if the feature is enabled. + +##### `allowed_ranges` +> []string + +IP ranges that are allowed to use the auto registration features. + +It must have at least one entry if the feature is enabled + + ### `prometheus` This section is used by local API and crowdsec. diff --git a/crowdsec-docs/unversioned/user_guides/machines_management.mdx b/crowdsec-docs/unversioned/user_guides/machines_management.mdx index 30c457fb..9e17f7bf 100644 --- a/crowdsec-docs/unversioned/user_guides/machines_management.mdx +++ b/crowdsec-docs/unversioned/user_guides/machines_management.mdx @@ -101,3 +101,42 @@ import CodeBlock from '@theme/CodeBlock'; + +### 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: + +```yaml + 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: + +```bash +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. \ No newline at end of file