Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

enhance: update readme, improve wording, remove some older images/videos #3239

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

enhance: update readme, improve wording, remove some older images/videos #3239

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5b9f7a2
enhance: update readme, improve wording, remove some older images/videos
LaurenceJJones Sep 16, 2024
f3aea8c
enhance: update readme
LaurenceJJones Sep 16, 2024
eb42ae1
enhance: remove f2b, only keep one ref
LaurenceJJones Sep 17, 2024
c16f799
enhance: change block to contains as we dont know what they will do
LaurenceJJones Sep 17, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
119 changes: 36 additions & 83 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,37 +37,31 @@

## <TL;DR>

CrowdSec is a free, modern & collaborative behavior detection engine, coupled with a global IP reputation network. It stacks on fail2ban's philosophy but is IPV6 compatible and 60x faster (Go vs Python), it uses Grok patterns to parse logs and YAML scenarios to identify behaviors. CrowdSec is engineered for modern Cloud / Containers / VM-based infrastructures (by decoupling detection and remediation). Once detected you can remedy threats with various bouncers (firewall block, nginx http 403, Captchas, etc.) while the aggressive IP can be sent to CrowdSec for curation before being shared among all users to further improve everyone's security. See [FAQ](https://doc.crowdsec.net/docs/faq) or read below for more.
CrowdSec is a open-source, modern, and collaborative behavior detection engine that works with a global IP reputation network. CrowdSec builds on the foundational principles of Fail2ban, but introduces an API-driven architecture that allows for greater scalability and flexibility in modern environments. CrowdSec uses Grok patterns to analyze logs and YAML scenarios to detect malicious behavior.

## 2 mins install
## :tada: Benefits

Installing it through the [Package system](https://doc.crowdsec.net/docs/getting_started/install_crowdsec) of your OS is the easiest way to proceed.
Otherwise, you can install it from source.
- **Fast assisted installation, no technical barrier**: The initial configuration is automated, giving you a ready-to-use setup for common services right out of the box.
- **Crowdsourced protection**: Once you join the CrowdSec community, you are automatically protected by the **Community Blocklist**, which contains known malicious IP addresses.
- **Api driven architecture**: CrowdSec is built for high scalability and easy integration with existing infrastructures. If your systems are spread across multiple servers, you can deploy CrowdSec on each one, allowing them to share data and work together seamlessly.
- **Observability**: CrowdSec offers a [SaaS console](https://app.crowdsec.net/signup) that lets you visualize your data and manage your deployments. Additionally, we provide a Prometheus metrics endpoint for monitoring.
- **Compiled Code**: CrowdSec is written in Go and is compiled into a static binary. This eliminates the need for external runtime dependencies, ensuring quick performance and easy deployment across various environments.

### From package (Debian)
## Installation

```sh
curl -s https://packagecloud.io/install/repositories/crowdsec/crowdsec/script.deb.sh | sudo bash
sudo apt-get update
sudo apt-get install crowdsec
```
Checkout our various getting started guides depending on your platform :
- [Linux](https://docs.crowdsec.net/u/getting_started/installation/linux)
- [FreeBSD](https://docs.crowdsec.net/u/getting_started/installation/freebsd)
- [Windows](https://docs.crowdsec.net/u/getting_started/installation/windows)
- [Docker/Podman](https://docs.crowdsec.net/u/getting_started/installation/docker)
- [Kubernetes](https://docs.crowdsec.net/u/getting_started/installation/kubernetes)

### From package (rhel/centos/amazon linux)

```sh
curl -s https://packagecloud.io/install/repositories/crowdsec/crowdsec/script.rpm.sh | sudo bash
sudo yum install crowdsec
```

### From package (FreeBSD)

```
sudo pkg update
sudo pkg install crowdsec
```
We have many more guides on the [documentation](https://docs.crowdsec.net/u/getting_started/installation/linux) so if the above doesn't fit your needs, please check them out.

### From source

We recommend using the above installation options over from source, as you will benefit from automatic updates and a more streamlined experience.

```sh
wget https://github.com/crowdsecurity/crowdsec/releases/latest/download/crowdsec-release.tgz
tar xzvf crowdsec-release.tgz
Expand All @@ -76,88 +70,47 @@ cd crowdsec-v* && sudo ./wizard.sh -i

## :information_source: About the CrowdSec project

Crowdsec is an open-source, lightweight software, detecting peers with aggressive behaviors to prevent them from accessing your systems. Its user-friendly design and assistance offer a low technical barrier of entry and nevertheless a high security gain.
CrowdSec is an open-source, lightweight software that detects patterns of malicious behavior to block bad actors from accessing your systems. With its user-friendly design and support, it provides a low technical barrier to entry while delivering a high level of security.

The architecture is as follows :

<p align="center">
<img src="https://github.com/crowdsecurity/crowdsec-docs/blob/main/crowdsec-docs/static/img/crowdsec_architecture.png" alt="CrowdSec" title="CrowdSec"/>
<img src="https://www.crowdsec.net/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fapi-diagram.512bc091.png&w=2048&q=90" alt="CrowdSec" title="CrowdSec"/>
</p>

Once an unwanted behavior is detected, deal with it through a [bouncer](https://hub.crowdsec.net/browse/#bouncers). The aggressive IP, scenario triggered and timestamp are sent for curation, to avoid poisoning & false positives. (This can be disabled). If verified, this IP is then redistributed to all CrowdSec users running the same scenario.
When unwanted behavior is detected, you can address it using a [Remediation Component](https://hub.crowdsec.net/remediation-components).

## Outnumbering hackers all together

By sharing the threat they faced, all users are protecting each-others (hence the name Crowd-Security). Crowdsec is designed for modern infrastructures, with its "*Detect Here, Remedy There*" approach, letting you analyze logs coming from several sources in one place and block threats at various levels (applicative, system, infrastructural) of your stack.
By sharing the threats you encounter, CrowdSec users help protect each other—hence the name Crowd-Security. Designed for modern infrastructures, CrowdSec follows a "*Detect Here, Remedy There*" approach, allowing you to analyze logs from multiple sources and block threats at different levels of your stack (application, system, or infrastructure).

CrowdSec ships by default with scenarios (brute force, port scan, web scan, etc.) adapted for most contexts, but you can easily extend it by picking more of them from the **[HUB](https://hub.crowdsec.net)**. It is also easy to adapt an existing one or create one yourself.
CrowdSec comes with default scenarios, such as brute force, port scans, and web scans, suitable for most environments. You can easily extend these scenarios by choosing more from the **[HUB](https://hub.crowdsec.net)** or by adapting existing ones or creating your own.

## :point_right: What it is not

CrowdSec is not a SIEM, storing your logs (neither locally nor remotely). Your data are analyzed locally and forgotten.

Signals sent to the curation platform are limited to the very strict minimum: IP, Scenario, Timestamp. They are only used to allow the system to spot new rogue IPs, and rule out false positives or poisoning attempts.

## :arrow_down: Install it !

Crowdsec is available for various platforms :
CrowdSec is not a SIEM; it doesn't store your logs either locally or remotely. Logs are analyzed locally, and only signals are sent to the curation platform.

- [Use our debian repositories](https://doc.crowdsec.net/docs/getting_started/install_crowdsec) or the [official debian packages](https://packages.debian.org/search?keywords=crowdsec&searchon=names&suite=stable&section=all)
- An [image](https://hub.docker.com/r/crowdsecurity/crowdsec) is available for docker
- [Prebuilt release packages](https://github.com/crowdsecurity/crowdsec/releases) are also available (suitable for `amd64`)
- You can as well [build it from source](https://doc.crowdsec.net/docs/user_guides/building)
The signals shared with the curation platform are limited to just a few key data points:
- IP Address
- Scenario
- Timestamp

Or look directly at [installation documentation](https://doc.crowdsec.net/docs/getting_started/install_crowdsec) for other methods and platforms.

## :tada: Key benefits

### Fast assisted installation, no technical barrier

<details open>
<summary>Initial configuration is automated, providing functional out-of-the-box setup</summary>
<img src="https://github.com/crowdsecurity/crowdsec-docs/blob/main/crowdsec-docs/static/img/crowdsec_install.gif?raw=true">
</details>

### Out of the box detection

<details>
<summary>Baseline detection is effective out-of-the-box, no fine-tuning required (click to expand)</summary>
<img src="https://github.com/crowdsecurity/crowdsec-docs/blob/main/crowdsec-docs/static/img/out-of-the-box-protection.gif?raw=true">
</details>

### Easy bouncer deployment

<details>
<summary>It's trivial to add bouncers to enforce decisions of crowdsec (click to expand)</summary>
<img src="https://github.com/crowdsecurity/crowdsec-docs/blob/main/crowdsec-docs/static/img/blocker-installation.gif?raw=true">
</details>

### Easy dashboard access

<details>
<summary>It's easy to deploy a metabase interface to view your data simply with cscli (click to expand)</summary>
<img src="https://github.com/crowdsecurity/crowdsec-docs/blob/main/crowdsec-docs/static/img/cscli-metabase.gif?raw=true">
</details>

### Hot & Cold logs

<details>
<summary>Process cold logs, for forensic, tests and chasing false positives & false negatives (click to expand)</summary>
<img src="https://github.com/crowdsecurity/crowdsec-docs/blob/main/crowdsec-docs/static/img/forensic-mode.gif?raw=true">
</details>
These signals are used solely to detect malicious IPs and to eliminate false positives or malicious manipulation attempts to influence the global reputation system.

You can read more about the [CrowdSec data model](https://www.crowdsec.net/our-data).

## 📦 About this repository

This repository contains the code for the two main components of crowdsec :
- `crowdsec` : the daemon a-la-fail2ban that can read, parse, enrich and apply heuristics to logs. This is the component in charge of "detecting" the attacks
- `cscli` : the cli tool mainly used to interact with crowdsec : ban/unban/view current bans, enable/disable parsers and scenarios.
This repository contains the code for the two main components of CrowdSec:

- **`crowdsec`**: The daemon that reads, parses, enriches, and applies heuristics to logs. This is the component responsible for "detecting" attacks.

- **`cscli`**: The command-line tool used primarily to interact with CrowdSec. It allows you to ban/unban IPs, view current bans, and enable/disable parsers and scenarios.

## Contributing

If you wish to contribute to the core of crowdsec, you are welcome to open a PR in this repository.
If you'd like to contribute to the core of CrowdSec, you're welcome to open a pull request (PR) in the main repository.

If you wish to add a new parser, scenario or collection, please open a PR in the [hub repository](https://github.com/crowdsecurity/hub).
To add a new parser, scenario, or collection, please submit a PR to the [Hub repository](https://github.com/crowdsecurity/hub).

If you wish to contribute to the documentation, please open a PR in the [documentation repository](http://github.com/crowdsecurity/crowdsec-docs).
For contributions to the documentation, open a PR in the [Documentation repository](http://github.com/crowdsecurity/crowdsec-docs).