# Crowdsec

[CrowdSec](https://www.google.com.au/search?q=CrowdSec\&safe=active\&ssui=on\&ved=2ahUKEwirpr2p7aCSAxXAcWwGHVrCIgUQgK4QegQIARAB) is an open-source, community-driven Intrusion Prevention System (IPS) that analyzes server logs to detect and block malicious IP addresses in real time. It acts like a modern, collaborative [Fail2Ban](https://www.google.com.au/url?sa=i\&source=web\&rct=j\&url=https://wz-it.com/en/blog/explained-and-set-up-crowdsec/\&ved=2ahUKEwirpr2p7aCSAxXAcWwGHVrCIgUQy_kOegQIARAD\&opi=89978449\&cd\&psig=AOvVaw0A0EcHScJxDp_VfPoMJywX\&ust=1769229955543000), sharing threat intelligence among users to create a collective, constantly updated, and curated blocklist. 

<div data-full-width="false"><figure><img src="https://docs.crowdsec.net/img/simplified_SE_overview.svg" alt=""><figcaption><p>Stolen from Crowdsec's website</p></figcaption></figure></div>

<table><thead><tr><th width="217.20001220703125"></th><th></th></tr></thead><tbody><tr><td>Crowdsec Engine</td><td>The crowdsec engine is the processor and central logging unit that watches your log files and what is occuring on your server. It tells the bouncer what to do<br>The engine also reports your data back to the Crowdsec UI to manage there if you enable this</td></tr><tr><td>Crowdsec Bouncer</td><td>The bouncer takes action, eg blocking an IP, and requires a connection to the engine to function.</td></tr></tbody></table>

## Before following these guides

All of my Crowdsec guides expect the following:

* [ ] Docker installed
* [ ] Ubuntu or similar OS
* [ ] An existing Crowdsec account
* [ ] You have an enrollment key ready to go [#generate-your-enrollmemt-key](#generate-your-enrollmemt-key "mention") and
* [ ] **You have read this page in its entirety**

## Generate your Enrollmemt key

All of my compose stacks have variables set to enrol your engine into Crowdsec.

1. Navigate to <https://app.crowdsec.net/>
2. Click on 'Enroll' and copy the enrolment key to clipboard

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>This key can be saved to your password vault as it rarely changes</p></div>

## Compose stacks

All of my Crowdsec stacks will include an 'init' (initialization) container, which is used to download the configuration files required. **The configuration file URLs are readable in the compose file and** [**publicly available on my Github**](https://github.com/trentnbauer/HomelabPublic/tree/main/crowdsec)**.** These are my production configs and may change over time. As such, I would recommend hosting your own.

Restarting the stack may re-run the init container. If you have made changes to the config file, these may be overwritten.

#### Here is an example 'init' container,

<pre class="language-yaml" data-overflow="wrap" data-line-numbers><code class="lang-yaml">services:
    init-crowdsec:
    image: alpine:latest
    volumes:
      - crowdsec:/etc/crowdsec
    command: >
      sh -c "apk add --no-cache wget ca-certificates &#x26;&#x26;
             mkdir -p /etc/crowdsec/acquisitions.d &#x26;&#x26;
<strong>             wget -qO /etc/crowdsec/acquis.yaml https://raw.githubusercontent.com/trentnbauer/HomelabPublic/main/crowdsec/unifi.yaml"
</strong></code></pre>

{% hint style="info" %}
I have highlighted the line downloading the configuration file. You can browse to the address to view the contents.
{% endhint %}

***

## Using Crowdsec

### Where should I deploy my Crowdsec Engine/s

Prioritize protecting anything that is

* A bridge between your local network and the internet (e.g. your firewall)
* Port forwarded
* High impact if brought offline

{% hint style="info" %}
While I recommend protecting as much as you can, each engine increases your risk of being rate limited. Because of this, I would recommend protecting your public facing services first.

\
Applications behind a Cloudflare tunnel are not included in this as the entry point is the Cloudflare network. Refer to [Cloudflare security rules](/guides/installation-guides/crowdsec/cloudflare-security-rules.md) for protecting your tunnels.
{% endhint %}

### Add Blocklists

Crowdsource lists are public lists of malicious IP addresses. You can subscribe to a list to automatigically add those to the Cloudflare [Cloudflare](/guides/installation-guides/pelican/cloudflare.md#security-rules) generated by Crowdsec

{% hint style="info" %}
Free tier Crowdsec has a limit on how many blocklists you can subscribe to
{% endhint %}

1. Navigate to <https://app.crowdsec.net/blocklists/> and review the lists. **Most are paid**
2. Open a list that sounds good
3. Click on subscribe
4. Select either organization, or engine (and select your Pelican engine)
5. For remediation, select Captcha
6. Click on OK / Save / Subscribe

### I personally use the below lists

{% embed url="<https://app.crowdsec.net/blocklists/65a56c520469607d9badb817>" %}

{% embed url="<https://app.crowdsec.net/blocklists/65a56c010469607d9badb80f>" %}

{% embed url="<https://app.crowdsec.net/blocklists/65a55718ff8363f6556e9d4b>" %}

### Decisions

Once enrolled, you will be able to see your engines decisions (blocked IPs) at <https://app.crowdsec.net/decisions> alongside some other useful information.&#x20;

{% hint style="info" %}
If this is a fresh install of Crowdsec, you likely won't have any 'decisions' listed
{% endhint %}

Here is an example from my instance;

<figure><img src="/files/MrM9ujRHbwCdpfls39Rm" alt=""><figcaption><p>This malicious IP from Turkmenistan is "very noisey", which means it shows up in a lot of other peoples Crowdsec instances.</p></figcaption></figure>

#### **Unblock an IP**

If you need to delete a false positive or unblock an IP,

1. Navigate to <https://app.crowdsec.net/decisions>&#x20;
2. Click on the bin icon next to the IP address
3. Wait a few minutes for things to sync

or

1. Exec into the relevant engine
2. Run the command `cscli decisions delete --ip IPADDRESS`&#x20;
3. Wait a minute or 2 for Crowdsec to talk to the bouncer, to talk to the service

***

#### Crowdsec is best deployed using a central engine, [per this documentation.](https://docs.crowdsec.net/u/user_guides/multiserver_setup/)

**My guides aren't written this way.** I'm using multiple engines to make it easier to spin up and down stacks. There are some benefits / negatives;

* **Easier to deploy**\
  My stacks are written to be spin-up-and-go. You will only need to accept the enroll request in the Crowdsec UI
* **Risk of being rate limited**\
  Due to having multiple engines, you run the risk of being rate limited by Crowdsec. Each engine increases your API calls.
* **Syncing across engines**\
  Using a central engine will instantly block a malicious IP across all your bouncers. This may not occur using multiple engines.

*If you want to use a single engine, you're best to look at other guides.*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://www.trentbauer.com/guides/installation-guides/crowdsec.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.