In version CrowdSec 1.x, implemented a local API, which can be accessed by both the application client and the user via the command line, including to remote machines.
What can he do?
Our local API does several things. First of all, it allows bouncers to fully work, which protect the peace of your server or machine. And also it is through the API that accounting and monitoring of the decisions made by the system is carried out.
What are the solutions? First of all, this is blocking by IP address or a whole range of addresses, if the attack is massive. It can also take into account the username or any other parameter that you want to configure. For this to work, the bouncer just needs to have our API key generated on the server side of CrowdSec.
Through the API, you can manage solutions and scenarios, push notifications from the system to the administrator, configure alerts, and so on. As it should, the API is a single point of entry for the administrator to the system infrastructure. In earlier versions of CrowdSec, many things, the same bouncers, were manually configured "in place", which was not very convenient.
Getting started using the API
Let's assume that CrowdSec is installed and you have a command line client (CLI). Your next step is API authentication.
To do this, you need to generate a bouncer key. Most of the bouncers offered on the CrowdSec hub have a ready-made installation script that will do it for you, but if you want to install everything manually, then to get the key, enter:
cscli bouncers add BouncerdeTest
After receiving the key, you need to collect the bouncer config:
If you need to register the machine, you you can do it in two different ways. The easiest is to use the following command:
cscli machines add MachinedeTest –auto
This action will generate a username and password for you in a yaml config file that you can then use.
This works if you are working locally on the same computer. If you are on a remote machine, you need to register your API server as follows:
cscli lapi register -u <api_url>
After that, you need to check if the machine has been added on the local server where we have deployed the API. This can be done with the following line:
cscli machines validate MachinedeTest
To display a list of registered cars, simply run the command:
Using the API with bouncers
Now, a simple HTTP request is enough to connect via the API. This is enough for local work. If we are talking about remote machines, we recommend enabling HTTPS.
Regarding API calls from the bouncer, you have 2 available methods:
Request Mode (getDecisions)
Request Mode allows the bouncer to send API requests to get information about decisions made on specific IP ranges, specific IP addresses, usernames, and so on. Further.
Here's how to call the API (using Curl) to request information about the blocked IP:
curl -H "X-Api-Key: e73e3672427ecd8cd9a6487f7e8f4f03" http://localhost:8080/v1/decisions?ip=98.65.32.47
As you can see, we pass the API key and call the? Ip parameter to specify the IP address we want to receive information from.
We will get the return response in JSON format, for example:
[{"duration":"2h25m47.212560128s","id":1023,"origin":"cscli","scenario":"manual 'ban' from '939972095cf1459c8b22cc608eff85daEb4yoi2wiTD7Y3fA'","scope":"Ip","type":"ban","value":"1.2.3.4"}]
You can also use the? Range parameter to specify the range of the network, or, if you prefer, use the scope + value parameter pair to request information about a specific username, session ID, and so on.
curl -H "X-Api-Key: e73e3672427ecd8cd9a6487f7e8f4f03" http://localhost:8080/v1/decisions?scope=username&value=korben
There is another option. This is
Streaming mode (getDecisionsStream)
Streaming mode works a little differently, simpler because it allows the bouncer to fetch existing or new solutions at regular intervals.
When the bouncer is running, you can get the active solutions as well as the ones just removed by calling the API with the? Startup "true" parameter, for example:
curl -s -H "X-Api-Key: e73e3672427ecd8cd9a6487f7e8f4f03" http://localhost:8080/v1/decisions/stream?startup=true
By setting the? Startup parameter to false, you will only receive new solutions received after the bouncer was launched.
{ "deleted": null, "new": [ { "duration": "3h59m57.641708614s", "id": 2410, "origin": "cscli", "scenario": "manual 'ban' from '939972095cf1459c8b22cc608eff85daEb4yoi2wiTD7Y3fA'", "scope": "Ip", "type": "ban", "value": "3.3.3.4" } ] }
If no solution has been added, the response will return "null":
{ "deleted": null, "new": null }
Use the API through Watcher (cscli or CrowdSec agent)
As mentioned in the introduction, you will need to provide the API with a computer id and password. Using certain API functions (POST / DELETE) or (GET) is mostly done through the command line interface or the CrowdSec agent, but nothing prevents you from working with it directly.
For example, to remove one or more solutions for a specific IP, do the following: After executing this command, you will receive a line in response that tells you how many solutions were removed. For those looking to get deeper into the source, the CrowdSec repository on Github has code written in Go that shows how to connect and use the API.
curl -X DELETE "https://localhost:8080/v1/decisions?ip=98.65.32.47" -H "accept: application/json"
All API methods are available here.
Total
As you can see, the local CrowdSec API is pretty easy to learn and use in conjunction with bouncers. The latter are written in Go and are adaptable to your specific needs. Ready bouncers can be downloaded here . We have also written special bouncers for working with Nginx, WordPress, HAProxy, iptables, nftables, or even cloud firewalls Amazon (AWS) and Google (Network FW and Cloud Armor). Their sources can also be found on Github . We also have bouncers for LUA and PHP .
And, of course, you can find all additional information, sources, useful links and manuals not yet published on Habré on the official CrowdSec website .