crowdsec/README.md

113 lines
4.4 KiB
Markdown
Raw Normal View History

<p align="center"> :warning: <b>Crowdsec BETA </b> :warning: </p>
2020-05-15 16:23:34 +00:00
<p align="center">
<img src="docs/assets/images/crowdsec_logo1.png" alt="CrowdSec" title="CrowdSec" />
</p>
<p align="center">
<img src="https://github.com/crowdsecurity/crowdsec/workflows/tests/badge.svg">
<img src="https://github.com/crowdsecurity/crowdsec/workflows/build/badge.svg">
2020-07-28 13:46:08 +00:00
<a href='https://coveralls.io/github/crowdsecurity/crowdsec?branch=master'><img src='https://coveralls.io/repos/github/crowdsecurity/crowdsec/badge.svg?branch=master' alt='Coverage Status' /></a>
<img src="https://goreportcard.com/badge/github.com/crowdsecurity/crowdsec">
<img src="https://img.shields.io/github/license/crowdsecurity/crowdsec">
2020-06-10 10:14:27 +00:00
<img src="https://github.com/crowdsecurity/crowdsec/workflows/Hub-CI/badge.svg">
2020-05-15 16:23:34 +00:00
</p>
<p align="center">
2020-05-18 11:55:21 +00:00
:books: <a href="https://doc.crowdsec.net">Documentation</a>
2020-05-15 16:34:08 +00:00
:diamond_shape_with_a_dot_inside: <a href="https://hub.crowdsec.net">Hub</a>
:speech_balloon: <a href="https://discourse.crowdsec.net">Discourse </a>
2020-05-15 16:23:34 +00:00
</p>
2020-05-15 09:39:16 +00:00
2020-05-15 11:00:54 +00:00
## About the crowdsec project
2020-05-15 09:39:16 +00:00
2020-05-27 14:28:06 +00:00
Crowdsec is an open-source and lightweight software that allows you to detect peers with malevolent behaviors and block them from accessing your systems at various levels (infrastructural, system, applicative).
2020-05-15 09:39:16 +00:00
2020-05-27 14:28:06 +00:00
To achieve this, Crowdsec reads logs from different sources (files, streams ...) to parse, normalize and enrich them before matching them to threats patterns aka scenarios.
2020-05-15 09:39:16 +00:00
2020-05-27 14:28:06 +00:00
Crowdsec is a modular and plug-able framework, it ships a large variety of well known popular scenarios; users can choose what scenarios they want to be protected from as well as easily add new custom ones to better fit their environment.
2020-05-19 12:11:11 +00:00
Detected malevolent peers can then be prevented from accessing your resources by deploying [blockers](https://hub.crowdsec.net/browse/#blockers) at various levels (applicative, system, infrastructural) of your stack.
2020-05-15 09:39:16 +00:00
2020-05-15 11:00:54 +00:00
One of the advantages of Crowdsec when compared to other solutions is its crowded aspect : Meta information about detected attacks (source IP, time and triggered scenario) are sent to a central API and then shared amongst all users.
2020-05-15 09:39:16 +00:00
2020-05-19 12:11:11 +00:00
Besides detecting and stopping attacks in real time based on your logs, it allows you to preemptively block known bad actors from accessing your information system.
2020-05-15 09:39:16 +00:00
## Install it !
Find the [latest release](https://github.com/crowdsecurity/crowdsec/releases/latest)
Ensure you have dependencies :
<details open>
<summary>for Debian based distributions</summary>
```bash
apt-get install bash gettext whiptail curl wget
```
</details>
<details>
<summary>for RedHat based distributions</summary>
```bash
yum install bash gettext newt curl wget
```
</details>
```bash
curl -s https://api.github.com/repos/crowdsecurity/crowdsec/releases/latest | grep browser_download_url| cut -d '"' -f 4 | wget -i -
tar xvzf crowdsec-release.tgz
cd crowdsec-v*
sudo ./wizard.sh -i
```
2020-05-26 10:09:27 +00:00
## Key points
2020-05-26 13:41:40 +00:00
### Fast assisted installation, no technical barrier
2020-05-26 10:09:27 +00:00
2020-05-26 13:41:40 +00:00
<details open>
<summary>User is assisted during setup, providing functional out-of-the-box setup</summary>
<img src="https://github.com/crowdsecurity/crowdsec/blob/master/docs/assets/images/crowdsec_install.gif">
</details>
2020-05-22 10:15:49 +00:00
2020-05-26 13:41:40 +00:00
### Out of the box detection
2020-05-26 10:09:27 +00:00
2020-05-26 13:41:40 +00:00
<details>
2020-05-27 14:31:08 +00:00
<summary>Baseline detection is effective out-of-the-box, no fine-tuning required (click to expand)</summary>
2020-05-26 13:41:40 +00:00
<img src="https://github.com/crowdsecurity/crowdsec/blob/master/docs/assets/images/out-of-the-box-protection.gif">
</details>
2020-05-26 10:09:27 +00:00
2020-05-26 13:41:40 +00:00
### Easy blocker deployment
2020-05-26 10:09:27 +00:00
2020-05-26 13:41:40 +00:00
<details>
2020-05-27 14:31:08 +00:00
<summary>It's trivial to add blockers to enforce decisions of crowdsec (click to expand)</summary>
2020-05-26 13:41:40 +00:00
<img src="https://github.com/crowdsecurity/crowdsec/blob/master/docs/assets/images/blocker-installation.gif">
</details>
### Easy dashboard access
<details>
2020-05-27 14:31:08 +00:00
<summary>It's easy to deploy a metabase interface to view your data simply with cscli (click to expand)</summary>
2020-05-26 13:41:40 +00:00
<img src="https://github.com/crowdsecurity/crowdsec/blob/master/docs/assets/images/cscli-metabase.gif">
</details>
2020-05-22 10:15:49 +00:00
2020-05-15 11:00:54 +00:00
## About this repository
2020-05-15 09:39:16 +00:00
2020-05-15 11:00:54 +00:00
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 heuristis 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.
2020-05-15 09:39:16 +00:00
## :warning: Beta version
Please note that crowdsec is currently in beta version, use with caution !