Interactive Security Engine Installation Guide
Welcome! This interactive guide will help you set up your CrowdSec Security Engine and validate each step to ensure proper operation. We'll guide you through detecting and remediating malicious behavior in your services' logs, regardless of your chosen implementation (on host, Docker, Kubernetes)
Note that to go further later you'll be able to enable Application Security and benefit from our ever growing collection of Virtual Patching rules. We'll mention the appropriate dependencies as we go along. Lastly, note that we'll cover a setup that focuses on an autonomous security engine parsing the logs of any services from local or remote servers. In appendix we'll cover the possibility to have distributed security engines on each servers, centralizing their alerts on a central security engine.
Install CrowdSec
The first step is to install the CrowdSec Security Engine somewhere you'll have access to the logs of services you want to protect. You can choose to install it directly on the host, in a Docker container, or in a Kubernetes cluster.
For a first experience, we recommend installing it on a host machine, as it will allow you to easily access the logs of your services and test the remediation capabilities. But if you're comfortable with Docker it also is a great way to get started and run CrowdSec in a containerized environment.
Instructions
/* We'll have to see how precise and embeded we want the various guides to be with this page If we want full guides in here we'd better be able to embed files or pieces of files rather than copy paste */
- Host
- Docker
- Kubernetes
Here are the various hosts you can install CrowdSec on:
// mention guide for linux, Windows, macOS, FreeBSD, pfSense, OPNSense with links to the existing docs// mention the current guide u/getting_started/installation/docker and this page having all the env variable https://hub.docker.com/r/crowdsecurity/crowdsec
To install CrowdSec in a Docker container, you can follow the instructions in our Docker Installation Guide.
For more information on the available environment variables, you can refer to the Docker Hub page.
// mention the current guide u/getting_started/installation/kubernetes and this page having all the env variable https://artifacthub.io/packages/helm/ingress-nginx/ingress-nginx
To install CrowdSec in a Kubernetes cluster, you can follow the instructions in our Kubernetes Installation Guide.
For more information on the available environment variables, you can refer to the Artifact Hub page.
Verification
Let's check that CrowdSec is running and able to retrieve the community blocklist !
Enroll your Security Engine into CrowdSec Console
For advanced monitoring and trouble shooting the CrowdSec Console is a great tool to visualize your Security Engine's activity and alerts.
- [link to doc]
- You'll see a confirmation pop up in the console for enrollment if not you might have conectivity issue to the central API [link to troubleshooting section]
- You'll see the last heartbeat and the status of your Security Engine in the console
- You'll be able to check various configurations for the upcoming steps of the installation
- You'll be warned when a new version of CrowdSec is available
CrowdSec installation health
systemctl status crowdsec
- You should see the service status as "active (running)".
- The port configuration can be setup in config.yaml file or by setting the environment variables depending on your implementation
[ ] Check that your Local API (LAPI) is properly running:
sudo cscli machines list
- You should see a list of machines, including the one you just installed CrowdSec on.
- For an autonomous install the Security Engine is running and connecting to it's own LAPI
- You should see a recent last heartbeat and a checkmark in status.
[ ] Check the metrics can be queried (optionnal for cscli metrics and prometheus):
sudo cscli metrics
- CrowdSec serves the metrics via a prometheus endpoint, check that it's able to run properly
- You should see various tables, most still empty except the Local API Machines Metrics
[ ] Setup hub-update // ?@seb case we need this ?
- ...
CrowdSec connectivity health
[ ] Check your security engine can connect to the Central API
sudo cscli capi status
- You should see: "You can successfully interact with Central API (CAPI)"
- Optionally additional status
- Sharing signals is enabled //+link to doc where to turn this on/off ?
- Pulling community blocklist is enabled //+link to doc where to turn this on/off ?
- Pulling blocklists from the console is enabled //+link to doc where to turn this on/off ?
🚨 Troubleshooting
There could be ports conflicts with other services
The Local API is running on port 8080 by default, and the Metrics server is running on port 6060 by default.
If you have other services running on these ports, you can change the ports in the configuration file /etc/crowdsec/config.yaml or by setting the environment variables CROWDSEC_API_PORT and CROWDSEC_METRICS_PORT when running CrowdSec in a container.
No connectivity to Central API
Check that you have access to internet at least api.crowdsec.net Check that your online api credentials exist /etc/crowdsec/config/online_api_credentials.yaml (default path) Eventually reset them with the following command sudo cscli capi register
Enrollment in Console not working
Make sure you are looking in the proper organization in the console: the enrollment key is linked to your organization.
If you have multiple organizations, you can switch using the organization selector in the top left corner of the console.
If you already checked that there are no connectivity issues, you can try to re-enroll using the --overwrite flag, effectively forcing the engine to link to your organization.
Can't see the latest version of the package
Update your repository and install again. If latest version not available, Might depend on the plateform you're installing it on (be patient, it will come)
