crowdsec/docs/faq.md
Thibault "bui" Koechlin 70055b3fd6
Doc api + minor api fixes (#654)
* add doc for API

* link users guide on metabase without docker

* rename doc and swagger
2021-02-26 17:42:45 +01:00

7.8 KiB

FREQUENTLY ASKED QUESTIONS

What is {{v1X.crowdsec.name}} ?

{{v1X.crowdsec.Name}} is a security open-source software. See the overview.

I've installed crowdsec, it detects attacks but doesn't block anything ?!

Yes, {{v1X.crowdsec.Name}} is in charge of detecting attacks, and {{v1X.bouncers.htmlname}} are applying decisions. If you want to block the detected IPs, you should deploy a bouncer, such as the ones found on the hub !

What language is it written in ?

{{v1X.crowdsec.Name}} is written in Golang.

What licence is {{v1X.crowdsec.name}} released under ?

{{v1X.crowdsec.Name}} is under MIT license.

Which information is sent to the APIs ?

Our aim is to build a strong community that can share malevolent attackers IPs, for that we need to collect the bans triggered locally by each user.

The signal sent by your {{v1X.crowdsec.name}} to the central API only contains only meta-data about the attack :

  • Attacker IP
  • Scenario name
  • Time of start/end of attack

Your logs are not sent to our central API, only meta-data about blocked attacks will be.

What is the performance impact ?

As {{v1X.crowdsec.name}} only works on logs, it shouldn't impact your production. When it comes to {{v1X.bouncers.name}}, it should perform one request to the database when a new IP is discovered thus have minimal performance impact.

How fast is it ?

{{v1X.crowdsec.name}} can easily handle several thousands of events per second on a rich pipeline (multiple parsers, geoip enrichment, scenarios and so on). Logs are a good fit for sharding by default, so it is definitely the way to go if you need to handle higher throughput.

If you need help for large scale deployment, please get in touch with us on the {{v1X.doc.discourse}}, we love challenges ;)

What backend database does {{v1X.crowdsec.Name}} supports and how to switch ?

{{v1X.crowdsec.name}} versions (under v0.3.X) supports SQLite (default) and MySQL databases. See backend configuration for relevant configuration. MySQL here is more suitable for distributed architectures where bouncers across the applicative stack need to access a centralized ban database.

{{v1X.crowdsec.name}} versions (after v1) supports SQLite (default), MySQL and PostgreSQL databases. See databases configuration for relevant configuration. Thanks to the {{v1X.lapi.Htmlname}}, distributed architectures are resolved even with sqlite database.

SQLite by default as it's suitable for standalone/single-machine setups.

How to control granularity of actions ? (whitelists, simulation etc.)

{{v1X.crowdsec.name}} support both whitelists and simulation :

  • Whitelists allows you to "discard" events or overflows
  • Simulation allows you to simply cancel the decision that is going to be taken, but keep track of it

{{v1X.profiles.htmlname}} allows you to control which decision will be applied to which alert.

How to know if my setup is working correctly ? Some of my logs are unparsed, is it normal ?

Yes, crowdsec parsers only parse the logs that are relevant for scenarios :)

Take a look at cscli metrics and understand what do they mean to know if your setup is correct.

How to add whitelists ?

You can follow this guide

How to set up proxy ?

Setting up a proxy works out of the box, the net/http golang library can handle those environment variables:

  • HTTP_PROXY
  • HTTPS_PROXY
  • NO_PROXY

Since {{v1X.cli.name}} uses sudo, you just this line in visudo after setting up the previous environment variables:

Defaults env_keep += "HTTP_PROXY HTTPS_PROXY NO_PROXY"

How to report a bug ?

To report a bug, please open an issue on the repository.

What about false positives ?

Several initiatives have been taken to tackle the false positives approach as early as possible :

  • The scenarios published on the hub are tailored to favor low false positive rates
  • You can find generic whitelists that should allow to cover most common cases (SEO whitelists, CDN whitelists etc.)
  • The simulation configuration allows you to keep a tight control over scenario and their false positives

I need some help

Feel free to ask for some help to the {{v1X.doc.discourse}} or directly in the {{v1X.doc.gitter}} chat.

How to use crowdsec on raspberry pi OS (formerly known as rasbian)

Please keep in mind that raspberry pi OS is designed to work on all raspberry pi versions. Even if the port target is known as armhf, it's not exactly the same target as the debian named armhf port.

The best way to have a crowdsec version for such an architecture is to do:

  1. install golang (all versions from 1.13 will do)
  2. export GOARCH=arm
  3. export CGO=1
  4. Update the GOARCH variable in the Makefile to arm
  5. install the arm gcc cross compilator (On debian the package is gcc-arm-linux-gnueabihf)
  6. Compile crowdsec using the usual make command

How to have a dashboard without docker

cscli dashboard rely on docker to launch the metabase image. If docker is not installed on your machine, here are the step to follow to get crowdsec dashboards without docker:

unzip metabase_sqlite.zip
  • Make crowdsec database reachable from metabase :
sudo mkdir /metabase-data/
sudo ln -s /var/lib/crowdsec/data/crowdsec.db /metabase-data/crowdsec.db
  • Launch Metabase:
sudo MB_DB_TYPE=h2 MB_DB_FILE=<absolute-path>/metabase.db/metabase.db java -jar metabase.jar

!!! warning The default username is crowdsec@crowdsec.net and the default password is !!Cr0wdS3c_M3t4b4s3??. Please update the password when you will connect to metabase for the first time

You can as well check liberodark's helper script for it.

How to configure crowdsec/cscli to use Tor

It is possible to configure cscli and crowdsec to use tor to anonymously interact with our API. All (http) requests made to the central API to go through the tor network.

With tor installed, setting HTTP_PROXY and HTTPS_PROXY environment variables to your socks5 proxy will do the trick.

Running the wizard with tor

$ sudo HTTPS_PROXY=socks5://127.0.0.1:9050 HTTP_PROXY=socks5://127.0.0.1:9050  ./wizard.sh --bininstall

!!! warning Do not use the wizard in interactive (-i) mode if you're concerned, as it will start the service at the end of the setup, leaking your IP address.

Edit crowdsec systemd unit to push/pull via tor

[Service]
Environment="HTTPS_PROXY=socks5://127.0.0.1:9050"
Environment="HTTP_PROXY=socks5://127.0.0.1:9050"
...

Using cscli via tor

$ sudo HTTP_PROXY=socks5://127.0.0.1:9050 HTTPS_PROXY=socks5://127.0.0.1:9050 cscli capi register