github.com/crowdsecurity/crowdsec@v1.6.1/README.md (about)

     1  
     2  <p align="center">
     3  <img src="https://github.com/crowdsecurity/crowdsec-docs/blob/main/crowdsec-docs/static/img/crowdsec_logo.png" alt="CrowdSec" title="CrowdSec" width="400" height="260"/>
     4  </p>
     5  </br>
     6  </br>
     7  </br>
     8  <p align="center">
     9  <img src="https://github.com/crowdsecurity/crowdsec/actions/workflows/go-tests.yml/badge.svg">
    10  <img src="https://github.com/crowdsecurity/crowdsec/actions/workflows/bats.yml/badge.svg">
    11  <a href="https://codecov.io/gh/crowdsecurity/crowdsec">
    12    <img src="https://codecov.io/gh/crowdsecurity/crowdsec/branch/master/graph/badge.svg?token=CQGSPNY3PT"/>
    13  </a>
    14  <img src="https://goreportcard.com/badge/github.com/crowdsecurity/crowdsec">
    15  <img src="https://img.shields.io/github/license/crowdsecurity/crowdsec">
    16  <img src="https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/AlteredCoder/ed74e50c43e3b17bdfc4d93149f23d37/raw/crowdsec_parsers_badge.json">
    17  <img src="https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/AlteredCoder/ed74e50c43e3b17bdfc4d93149f23d37/raw/crowdsec_scenarios_badge.json">
    18  <a href="https://hub.docker.com/r/crowdsecurity/crowdsec">
    19    <img src="https://img.shields.io/docker/pulls/crowdsecurity/crowdsec?logo=docker">
    20  </a>
    21  <a href="https://discord.com/invite/crowdsec">
    22    <img src="https://img.shields.io/discord/921520481163673640?label=Discord&logo=discord">
    23  </a>
    24  </p>
    25  
    26  <p align="center">
    27  :computer: <a href="https://app.crowdsec.net">Console (WebApp)</a>
    28  :books: <a href="https://doc.crowdsec.net">Documentation</a>
    29  :diamond_shape_with_a_dot_inside: <a href="https://hub.crowdsec.net">Configuration Hub</a>
    30  :speech_balloon: <a href="https://discourse.crowdsec.net">Discourse (Forum)</a>
    31  :speech_balloon: <a href="https://discord.gg/crowdsec">Discord (Live Chat)</a>
    32  </p>
    33  
    34  
    35  :dancer: This is a community-driven project, <a href="https://forms.gle/ZQBQcptG2wYGajRX8">we need your feedback</a>.
    36  
    37  ## <TL;DR>
    38  
    39  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.
    40  
    41  ## 2 mins install
    42  
    43  Installing it through the [Package system](https://doc.crowdsec.net/docs/getting_started/install_crowdsec) of your OS is the easiest way to proceed. 
    44  Otherwise, you can install it from source.
    45  
    46  ### From package (Debian)
    47  
    48  ```sh
    49  curl -s https://packagecloud.io/install/repositories/crowdsec/crowdsec/script.deb.sh | sudo bash
    50  sudo apt-get update
    51  sudo apt-get install crowdsec
    52  ```
    53  
    54  ### From package (rhel/centos/amazon linux)
    55  
    56  ```sh
    57  curl -s https://packagecloud.io/install/repositories/crowdsec/crowdsec/script.rpm.sh | sudo bash
    58  sudo yum install crowdsec
    59  ```
    60  
    61  ### From package (FreeBSD)
    62  
    63  ```
    64  sudo pkg update
    65  sudo pkg install crowdsec
    66  ```
    67  
    68  ### From source
    69  
    70  ```sh
    71  wget https://github.com/crowdsecurity/crowdsec/releases/latest/download/crowdsec-release.tgz
    72  tar xzvf crowdsec-release.tgz
    73  cd crowdsec-v* && sudo ./wizard.sh -i
    74  ```
    75  
    76  ## :information_source: About the CrowdSec project
    77  
    78  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.
    79  
    80  The architecture is as follows :
    81  
    82  <p align="center">
    83   <img src="https://github.com/crowdsecurity/crowdsec-docs/blob/main/crowdsec-docs/static/img/crowdsec_architecture.png" alt="CrowdSec" title="CrowdSec"/>
    84  </p>
    85  
    86  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.
    87  
    88  ## Outnumbering hackers all together
    89  
    90  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.
    91  
    92  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.
    93  
    94  ## :point_right: What it is not
    95  
    96  CrowdSec is not a SIEM, storing your logs (neither locally nor remotely). Your data are analyzed locally and forgotten.
    97  
    98  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.
    99  
   100  ## :arrow_down: Install it !
   101  
   102  Crowdsec is available for various platforms :
   103  
   104   - [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)
   105   - An [image](https://hub.docker.com/r/crowdsecurity/crowdsec) is available for docker
   106   - [Prebuilt release packages](https://github.com/crowdsecurity/crowdsec/releases) are also available (suitable for `amd64`)
   107   - You can as well [build it from source](https://doc.crowdsec.net/docs/user_guides/building)
   108  
   109  Or look directly at [installation documentation](https://doc.crowdsec.net/docs/getting_started/install_crowdsec) for other methods and platforms.
   110  
   111  ## :tada: Key benefits
   112  
   113  ### Fast assisted installation, no technical barrier
   114  
   115  <details open>
   116    <summary>Initial configuration is automated, providing functional out-of-the-box setup</summary>
   117    <img src="https://github.com/crowdsecurity/crowdsec-docs/blob/main/crowdsec-docs/static/img/crowdsec_install.gif?raw=true">
   118  </details>
   119  
   120  ### Out of the box detection
   121  
   122  <details>
   123    <summary>Baseline detection is effective out-of-the-box, no fine-tuning required (click to expand)</summary>
   124    <img src="https://github.com/crowdsecurity/crowdsec-docs/blob/main/crowdsec-docs/static/img/out-of-the-box-protection.gif?raw=true">
   125  </details>
   126  
   127  ### Easy bouncer deployment
   128  
   129  <details>
   130    <summary>It's trivial to add bouncers to enforce decisions of crowdsec (click to expand)</summary>
   131    <img src="https://github.com/crowdsecurity/crowdsec-docs/blob/main/crowdsec-docs/static/img/blocker-installation.gif?raw=true">
   132  </details>
   133  
   134  ### Easy dashboard access
   135  
   136  <details>
   137    <summary>It's easy to deploy a metabase interface to view your data simply with cscli (click to expand)</summary>
   138    <img src="https://github.com/crowdsecurity/crowdsec-docs/blob/main/crowdsec-docs/static/img/cscli-metabase.gif?raw=true">
   139  </details>
   140  
   141  ### Hot & Cold logs
   142  
   143  <details>
   144    <summary>Process cold logs, for forensic, tests and chasing false positives & false negatives (click to expand)</summary>
   145    <img src="https://github.com/crowdsecurity/crowdsec-docs/blob/main/crowdsec-docs/static/img/forensic-mode.gif?raw=true">
   146  </details>
   147  
   148  
   149  ## 📦 About this repository
   150  
   151  This repository contains the code for the two main components of crowdsec :
   152   - `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
   153   - `cscli` : the cli tool mainly used to interact with crowdsec : ban/unban/view current bans, enable/disable parsers and scenarios.
   154  
   155  
   156  ## Contributing
   157  
   158  If you wish to contribute to the core of crowdsec, you are welcome to open a PR in this repository.
   159  
   160  If you wish to add a new parser, scenario or collection, please open a PR in the [hub repository](https://github.com/crowdsecurity/hub).
   161  
   162  If you wish to contribute to the documentation, please open a PR in the [documentation repository](http://github.com/crowdsecurity/crowdsec-docs).