Skip to content

Commit c5ea150

Browse files
buixorjdv
buixor
authored and
jdv
committed
start moving sub items in local api
1 parent 143cff2 commit c5ea150

File tree

4 files changed

+194
-178
lines changed

4 files changed

+194
-178
lines changed

‎crowdsec-docs/docs/local_api/authentication.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
id: authentication
3+
title: Authentication
4+
sidebar_position: 5
5+
---
6+
7+
8+
9+
## Authentication
10+
11+
There are three kinds of authentication to the Local API :
12+
13+
1. API Keys: they are used to authenticate Remediation Components (bouncers) and can only read decisions
14+
2. Login/Password: they are used to authenticate Log Processors (machines) and can read, create and delete decisions
15+
3. TLS client certificates:
16+
- they are used to authenticate Remediation Components (bouncers) and Log Processors (machines)
17+
- based on the OU field of the certificate, the Local API will determine what permissions the client has as per the restrictions above (log processor or remediation components)
18+
- this allows the Local API to authenticate clients without generating the clients before hand if you have a dynamic environment
19+
20+
For TLS authentication please see our [dedicated documentation](/local_api/tls_auth.md).
21+
22+
### Remediation Components (Bouncers)
23+
24+
To register a Remediation Component to your API, you need to run the following command on the server where the API is installed:
25+
26+
```bash
27+
sudo cscli bouncers add testBouncer
28+
```
29+
30+
and keep the generated API token to use it in your Remediation Component configuration file.
31+
32+
### Log Processors (machines)
33+
34+
To allow a log processor to communicate with the Local API, each instance will need it own set of credentials which is validated by an admin of the Local API.
35+
36+
There are two ways to register a CrowdSec to a Local API.
37+
38+
1. You can generate credentials directly on the Local API server:
39+
40+
```bash
41+
sudo cscli machines add testMachine
42+
```
43+
44+
:::warning
45+
if you are running this command on the local API server, most likely it will already have it own credentials file. If you are generating credentials for a remote machine you must pass the `-f` flag to generate the credentials to another file.
46+
47+
```bash
48+
sudo cscli machines add testMachine -f /path/to/credentials.yaml
49+
```
50+
or
51+
```bash
52+
sudo cscli machines add testMachine -f- > /path/to/credentials.yaml
53+
```
54+
:::
55+
56+
Upon installation of CrowdSec it will generate it own set of credentials to operate the log processor and local API server.
57+
58+
If you are installing these credentials on a remote machine, you must replace the `local_api_credentials.yaml` file within the configuration directory, you can find the location of this directory [here](/u/troubleshooting/security_engine#where-is-configuration-stored) based on your operating system.
59+
60+
2. You can use `cscli` to send a registration request to the Local API server:
61+
62+
```bash
63+
sudo cscli lapi register -u <api_url>
64+
```
65+
66+
And validate it with `cscli` on the server where the API is installed:
67+
68+
```bash
69+
sudo cscli machines validate <machineName>
70+
```
71+
72+
:::info
73+
You can use `cscli machines list` to list all the machines registered to the API and view the ones that are not validated yet.
74+
:::
75+

‎crowdsec-docs/docs/local_api/configuration.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
---
2+
id: configuration
3+
title: Configuration
4+
sidebar_position: 6
5+
---
6+
7+
8+
## Configuration
9+
10+
### Client
11+
12+
By default, `crowdsec` and `cscli` use `127.0.0.1:8080` as the default Local API. However you might want to use a remote API and configure a different endpoint for your api client.
13+
14+
#### Register to a Remote API server
15+
16+
* On the machine you want to connect to a Local API server, run the following command:
17+
18+
```bash
19+
sudo cscli lapi register -u http://<remote_api>:<port>
20+
```
21+
22+
* On the Local API server, validate the machine by running the command:
23+
24+
25+
```bash
26+
sudo cscli machines list # to get the name of the new registered machine
27+
```
28+
29+
```bash
30+
sudo cscli machines validate <machineName>
31+
```
32+
33+
* Restart the CrowdSec service on the machine you registered once validated:
34+
35+
```bash
36+
sudo systemctl restart crowdsec
37+
```
38+
39+
#### Disable the registered machine Local API
40+
41+
On the machine you ran `cscli lapi register`, it optimal to disable the Local API component to save on resources since it is now forwarding all alerts/decisions to the Local API server.
42+
43+
Within the `config.yaml` file, set `enable` under `api.server` to `false`:
44+
45+
```yaml
46+
api:
47+
server:
48+
enable: false
49+
```
50+
51+
See where the `config.yaml` file is located on your operating system [here](/u/troubleshooting/security_engine#where-is-configuration-stored)
52+
53+
### Server
54+
55+
#### Configure listen URL
56+
57+
If you would like your Local API to be used by a remote CrowdSec installation, you will need to modify the URL it listens on as by default it will listen on the loopback interface.
58+
59+
Modify the [`listen_uri`](/configuration/crowdsec_configuration.md#listen_uri) option in the `config.yaml`.
60+
61+
#### Enable SSL
62+
63+
If your Local API is exposed to the internet, it is recommended to enable SSL or at least use a reverse proxy with SSL termination to secure the communication between the Log Processors / Remediation Components and the Local API.
64+
65+
If your Log Processors and Remediation Components are apart of the same LAN or VPN, then this is not necessary step.
66+
67+
##### Local API SSL
68+
69+
You can configure the Local API to use SSL by setting the `tls` option under `api.server` in the `config.yaml` file.
70+
71+
```yaml
72+
api:
73+
server:
74+
tls:
75+
cert_path: "/path/to/cert.pem"
76+
key_path: "/path/to/key.pem"
77+
```
78+
79+
:::info
80+
If you are using a self signed certificate on connecting Log Processors and Remediation Components you must enable `insecure_skip_verify` options.
81+
:::
82+
83+
- Log Processors (machines)
84+
85+
```yaml
86+
api:
87+
client:
88+
insecure_skip_verify: true
89+
```
90+
91+
- Remediation Components (bouncers)
92+
93+
This can differ based on the configuration please refer to the documentation of the component you are using.
94+
95+
If you would like to read the full configuration options for TLS on the Local API please [see here](/configuration/crowdsec_configuration.md#tls).
96+
97+
You can also refer [here](/local_api/tls_auth.md) for the documentation about TLS authentication.
98+
99+
##### Reverse Proxy
100+
101+
We cannot cover all the reverse proxies available, please refer to the documentation of the reverse proxy you are using. However, the reverse proxy must send the connecting IP address as the `X-Forwarded-For` header to the Local API.
102+
103+
However, when the Local API is behind a reverse proxy you will need to configure the `trusted_proxies` and `use_forwarded_for_headers` options under `api.server` within the `config.yaml` file to be able to get the correct IP address within the database.
104+
105+
```yaml
106+
api:
107+
server:
108+
use_forwarded_for_headers: true
109+
trusted_proxies:
110+
- "127.0.0.1" ## Change this to the proxy IP this is presuming the proxy is on the same machine
111+
```
112+
113+
See where the `config.yaml` file is located on your operating system [here](/u/troubleshooting/security_engine#where-is-configuration-stored)
114+
115+
See the [Local API public documentation](https://crowdsecurity.github.io/api_doc/lapi/).
116+
117+

‎crowdsec-docs/docs/local_api/intro.md‎

Lines changed: 0 additions & 178 deletions
Original file line numberDiff line numberDiff line change
@@ -15,181 +15,3 @@ The Local API (LAPI) is one of the core component of the Security Engine to :
1515
You can find the swagger documentation [here](https://crowdsecurity.github.io/api_doc/lapi/).
1616

1717
This allows you to create [multi-machines architectures](https://crowdsec.net/multi-server-setup/) around CrowdSec or leverage [orchestration technologies](https://crowdsec.net/secure-docker-compose-stacks-with-crowdsec/).
18-
19-
## Authentication
20-
21-
There are three kinds of authentication to the Local API :
22-
23-
1. API Keys: they are used to authenticate Remediation Components (bouncers) and can only read decisions
24-
2. Login/Password: they are used to authenticate Log Processors (machines) and can read, create and delete decisions
25-
3. TLS client certificates:
26-
- they are used to authenticate Remediation Components (bouncers) and Log Processors (machines)
27-
- based on the OU field of the certificate, the Local API will determine what permissions the client has as per the restrictions above (log processor or remediation components)
28-
- this allows the Local API to authenticate clients without generating the clients before hand if you have a dynamic environment
29-
30-
For TLS authentication please see our [dedicated documentation](/local_api/tls_auth.md).
31-
32-
### Remediation Components (Bouncers)
33-
34-
To register a Remediation Component to your API, you need to run the following command on the server where the API is installed:
35-
36-
```bash
37-
sudo cscli bouncers add testBouncer
38-
```
39-
40-
and keep the generated API token to use it in your Remediation Component configuration file.
41-
42-
### Log Processors (machines)
43-
44-
To allow a log processor to communicate with the Local API, each instance will need it own set of credentials which is validated by an admin of the Local API.
45-
46-
There are two ways to register a CrowdSec to a Local API.
47-
48-
1. You can generate credentials directly on the Local API server:
49-
50-
```bash
51-
sudo cscli machines add testMachine
52-
```
53-
54-
:::warning
55-
if you are running this command on the local API server, most likely it will already have it own credentials file. If you are generating credentials for a remote machine you must pass the `-f` flag to generate the credentials to another file.
56-
57-
```bash
58-
sudo cscli machines add testMachine -f /path/to/credentials.yaml
59-
```
60-
or
61-
```bash
62-
sudo cscli machines add testMachine -f- > /path/to/credentials.yaml
63-
```
64-
:::
65-
66-
Upon installation of CrowdSec it will generate it own set of credentials to operate the log processor and local API server.
67-
68-
If you are installing these credentials on a remote machine, you must replace the `local_api_credentials.yaml` file within the configuration directory, you can find the location of this directory [here](/u/troubleshooting/security_engine#where-is-configuration-stored) based on your operating system.
69-
70-
2. You can use `cscli` to send a registration request to the Local API server:
71-
72-
```bash
73-
sudo cscli lapi register -u <api_url>
74-
```
75-
76-
And validate it with `cscli` on the server where the API is installed:
77-
78-
```bash
79-
sudo cscli machines validate <machineName>
80-
```
81-
82-
:::info
83-
You can use `cscli machines list` to list all the machines registered to the API and view the ones that are not validated yet.
84-
:::
85-
86-
## Configuration
87-
88-
### Client
89-
90-
By default, `crowdsec` and `cscli` use `127.0.0.1:8080` as the default Local API. However you might want to use a remote API and configure a different endpoint for your api client.
91-
92-
#### Register to a Remote API server
93-
94-
* On the machine you want to connect to a Local API server, run the following command:
95-
96-
```bash
97-
sudo cscli lapi register -u http://<remote_api>:<port>
98-
```
99-
100-
* On the Local API server, validate the machine by running the command:
101-
102-
103-
```bash
104-
sudo cscli machines list # to get the name of the new registered machine
105-
```
106-
107-
```bash
108-
sudo cscli machines validate <machineName>
109-
```
110-
111-
* Restart the CrowdSec service on the machine you registered once validated:
112-
113-
```bash
114-
sudo systemctl restart crowdsec
115-
```
116-
117-
#### Disable the registered machine Local API
118-
119-
On the machine you ran `cscli lapi register`, it optimal to disable the Local API component to save on resources since it is now forwarding all alerts/decisions to the Local API server.
120-
121-
Within the `config.yaml` file, set `enable` under `api.server` to `false`:
122-
123-
```yaml
124-
api:
125-
server:
126-
enable: false
127-
```
128-
129-
See where the `config.yaml` file is located on your operating system [here](/u/troubleshooting/security_engine#where-is-configuration-stored)
130-
131-
### Server
132-
133-
#### Configure listen URL
134-
135-
If you would like your Local API to be used by a remote CrowdSec installation, you will need to modify the URL it listens on as by default it will listen on the loopback interface.
136-
137-
Modify the [`listen_uri`](/configuration/crowdsec_configuration.md#listen_uri) option in the `config.yaml`.
138-
139-
#### Enable SSL
140-
141-
If your Local API is exposed to the internet, it is recommended to enable SSL or at least use a reverse proxy with SSL termination to secure the communication between the Log Processors / Remediation Components and the Local API.
142-
143-
If your Log Processors and Remediation Components are apart of the same LAN or VPN, then this is not necessary step.
144-
145-
##### Local API SSL
146-
147-
You can configure the Local API to use SSL by setting the `tls` option under `api.server` in the `config.yaml` file.
148-
149-
```yaml
150-
api:
151-
server:
152-
tls:
153-
cert_path: "/path/to/cert.pem"
154-
key_path: "/path/to/key.pem"
155-
```
156-
157-
:::info
158-
If you are using a self signed certificate on connecting Log Processors and Remediation Components you must enable `insecure_skip_verify` options.
159-
:::
160-
161-
- Log Processors (machines)
162-
163-
```yaml
164-
api:
165-
client:
166-
insecure_skip_verify: true
167-
```
168-
169-
- Remediation Components (bouncers)
170-
171-
This can differ based on the configuration please refer to the documentation of the component you are using.
172-
173-
If you would like to read the full configuration options for TLS on the Local API please [see here](/configuration/crowdsec_configuration.md#tls).
174-
175-
You can also refer [here](/local_api/tls_auth.md) for the documentation about TLS authentication.
176-
177-
##### Reverse Proxy
178-
179-
We cannot cover all the reverse proxies available, please refer to the documentation of the reverse proxy you are using. However, the reverse proxy must send the connecting IP address as the `X-Forwarded-For` header to the Local API.
180-
181-
However, when the Local API is behind a reverse proxy you will need to configure the `trusted_proxies` and `use_forwarded_for_headers` options under `api.server` within the `config.yaml` file to be able to get the correct IP address within the database.
182-
183-
```yaml
184-
api:
185-
server:
186-
use_forwarded_for_headers: true
187-
trusted_proxies:
188-
- "127.0.0.1" ## Change this to the proxy IP this is presuming the proxy is on the same machine
189-
```
190-
191-
See where the `config.yaml` file is located on your operating system [here](/u/troubleshooting/security_engine#where-is-configuration-stored)
192-
193-
See the [Local API public documentation](https://crowdsecurity.github.io/api_doc/lapi/).
194-
195-

‎crowdsec-docs/sidebars.js‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -269,6 +269,8 @@ module.exports = {
269269
},
270270
"local_api/database",
271271
"local_api/bouncers",
272+
"local_api/configuration",
273+
"local_api/authentication",
272274
"local_api/tls_auth",
273275
{
274276
type: "link",

0 commit comments

Comments
 (0)