From 5b9f7a259b15c31789a419f1a0d8b40123eaa833 Mon Sep 17 00:00:00 2001 From: Laurence Date: Mon, 16 Sep 2024 11:36:08 +0100 Subject: [PATCH 1/4] enhance: update readme, improve wording, remove some older images/videos --- README.md | 118 ++++++++++++++++-------------------------------------- 1 file changed, 35 insertions(+), 83 deletions(-) diff --git a/README.md b/README.md index a900f0ee514..ec53d0a1662 100644 --- a/README.md +++ b/README.md @@ -37,37 +37,30 @@ ## -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. It builds on the principles of fail2ban but offers IPV6 compatibility. 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 blocks known malicious IP addresses. +- **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 @@ -76,88 +69,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 :

- CrowdSec + CrowdSec

-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§ion=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 - -
- Initial configuration is automated, providing functional out-of-the-box setup - -
- -### Out of the box detection - -
- Baseline detection is effective out-of-the-box, no fine-tuning required (click to expand) - -
- -### Easy bouncer deployment - -
- It's trivial to add bouncers to enforce decisions of crowdsec (click to expand) - -
- -### Easy dashboard access - -
- It's easy to deploy a metabase interface to view your data simply with cscli (click to expand) - -
- -### Hot & Cold logs - -
- Process cold logs, for forensic, tests and chasing false positives & false negatives (click to expand) - -
+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, similar to fail2ban, 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). From f3aea8c0dfd00d39661b0bdb2bda5aa2dfc367ac Mon Sep 17 00:00:00 2001 From: Laurence Date: Mon, 16 Sep 2024 13:50:09 +0100 Subject: [PATCH 2/4] enhance: update readme --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index ec53d0a1662..daf81b2a25f 100644 --- a/README.md +++ b/README.md @@ -37,12 +37,13 @@ ## -CrowdSec is a open-source, modern, and collaborative behavior detection engine that works with a global IP reputation network. It builds on the principles of fail2ban but offers IPV6 compatibility. CrowdSec uses Grok patterns to analyze logs and YAML scenarios to detect malicious behavior. +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. ## :tada: Benefits - **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 blocks 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 eb42ae1d07360f34e0ab2afb5bd7a9fd1ab09bc4 Mon Sep 17 00:00:00 2001 From: Laurence Date: Tue, 17 Sep 2024 08:34:42 +0100 Subject: [PATCH 3/4] enhance: remove f2b, only keep one ref --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index daf81b2a25f..0b3a6d0c904 100644 --- a/README.md +++ b/README.md @@ -103,7 +103,7 @@ You can read more about the [CrowdSec data model](https://www.crowdsec.net/our-d This repository contains the code for the two main components of CrowdSec: -- **`crowdsec`**: The daemon, similar to fail2ban, that reads, parses, enriches, and applies heuristics to logs. This is the component responsible for "detecting" attacks. +- **`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. From c16f799ddbc9a100342a1937d3fa0ab0cb3a76e4 Mon Sep 17 00:00:00 2001 From: Laurence Date: Tue, 17 Sep 2024 08:36:57 +0100 Subject: [PATCH 4/4] enhance: change block to contains as we dont know what they will do --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0b3a6d0c904..5964af1f368 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ CrowdSec is a open-source, modern, and collaborative behavior detection engine t ## :tada: Benefits - **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 blocks known malicious IP addresses. +- **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.