В версии CrowdSec 1.x реализовал локальный API, к которому может обращаться как клиент приложения, так и пользователь через командную строку, в том числе и на удаленные машины.
Что он умеет?
Наш локальный API делает несколько вещей. Прежде всего, он позволяет полноценно работать баунсерам, которые берегут покой вашего сервера или машины. А также именно через API ведется учет и мониторинг за принятыми системой решениями.
Что за решения? Прежде всего, это блокировка по IP-адресу или целому диапазону адресов, если атака имеет массированный характер. Также может учитываться имя пользователя или вообще любой другой параметр, который вы захотите настроить. Чтобы все это работало, у баунсера просто должен быть ключ нашего API, который сгенерирован на серверной стороне CrowdSec.
Через API можно управлять решениями и сценариями, push-уведомлениями от системы администратору, настраивать оповещения и так далее. Как и должно, API единая точка входа администратора к инфраструктуре системы. В ранних версиях CrowdSec многие вещи, те же баунсеры, настраивались вручную по месту, что было не слишком удобно.
Начинаем пользоваться API
Предположим, что CrowdSec установлен и у вас есть клиент командной строки (CLI). Ваши последующий шаг аутентификация в API.
Для этого вам необходимо сгенерировать ключ баунсера. У большинства баунсеров, предлагаемых на хабе CrowdSec, есть готовый инсталл-сценарий, который сделает за вас, но если вы хотите все установить в ручную, то для получения ключа введите:
cscli bouncers add BouncerdeTestПосле получения ключа вам надо собрать конфиг баунсера:
Если нужно зарегистрировать машину, вы можете сделать это двумя разными способами. Самый простой использовать следующую команду:
cscli machines add MachinedeTest auto
Это действие сгенерирует для вас логин и пароль в файле конфигурации yaml, который вы затем сможете использовать.
Это работает для случая, если вы работаете локально на одном компьютере. Если же вы находитесь на удаленной машине, вам нужно зарегистрировать свой сервер API следующим образом:
cscli lapi register -u <api_url>После надо проверить, добавилась ли машина на локальном сервере, где у нас развернут API. Сделать это можно следующей строкой:
cscli machines validate MachinedeTestЧтобы вывести список зарегистрированных машин просто выполните команду:
Использование API с баунсерами
Теперь для соединения через API достаточно обычного HTTP-запроса. Этого достаточно для локальной работы. Если же речь идет об удаленных машинах, рекомендуем включить HTTPS.
Что касается вызовов API из баунсера, у вас есть 2 доступных метода:
Режим запроса (getDecisions)
Режим запроса позволяет баунсеру отправлять запросы API для получения информации о решениях, принятых в отношении определенных диапазонов IP-адресов, отдельных IP-адресов, имен пользователей и так далее.
Вот как вызвать API (с помощью Curl), чтобы запросить информацию о заблокированном IP:
curl -H "X-Api-Key: e73e3672427ecd8cd9a6487f7e8f4f03"
http://localhost:8080/v1/decisions?ip=98.65.32.47Как видите, мы передаем ключ API и вызываем параметр ?ip, чтобы указать IP-адрес, по которому мы хотим получить информацию.
Возвращаемый ответ мы получим в формате JSON, например:
[{"duration":"2h25m47.212560128s","id":1023,"origin":"cscli","scenario":"manual
'ban' from
'939972095cf1459c8b22cc608eff85daEb4yoi2wiTD7Y3fA'","scope":"Ip","type":"ban","value":"1.2.3.4"}]Вы также можете использовать параметр ?range, чтобы указать диапазон сети, или, если хотите, использовать пару параметров scope+value для запроса информации о конкретном имени пользователя, идентификаторе сеанса и так далее.
curl -H "X-Api-Key: e73e3672427ecd8cd9a6487f7e8f4f03"
http://localhost:8080/v1/decisions?scope=username&value=korbenЕсть еще один вариант. Это
Потоковый режим (getDecisionsStream)
Потоковый режим работает несколько иначе, проще, поскольку он позволяет баунсеру извлекать существующие или новые решения через равные промежутки времени.
Когда баунсер запущен, вы можете получить активные решения, а также только что удаленные, вызвав API с параметром ?Startup true, например:
curl -s -H "X-Api-Key: e73e3672427ecd8cd9a6487f7e8f4f03"
http://localhost:8080/v1/decisions/stream?startup=trueУстановив для параметра ?startup значение false вы будете получать только новые решения, полученные после запуска баунсера.
{ "deleted": null, "new": [ { "duration": "3h59m57.641708614s", "id": 2410, "origin": "cscli", "scenario": "manual 'ban' from '939972095cf1459c8b22cc608eff85daEb4yoi2wiTD7Y3fA'", "scope": "Ip", "type": "ban", "value": "3.3.3.4" } ]}
Если решение не было добавлено, в ответ вернется null:
{ "deleted": null, "new": null}
Используйте API через Watcher (cscli или агент CrowdSec)
Как упоминалось во введении, вам нужно будет предоставить API идентификатор компьютера и пароль. Использование определенных функций API (POST/DELETE) или (GET) в основном осуществляется через интерфейс командной строки или агент CrowdSec, но ничто не мешает вам работать с ним напрямую.
Например, чтобы удалить одно или несколько решений, касающихся определенного IP, сделайте следующее:
curl -X DELETE
"https://localhost:8080/v1/decisions?ip=98.65.32.47" -H "accept:
application/json"
После выполнения этой команды в ответ вы получите строку, которая сообщит, сколько решений было удалено.
Для тех, кто хочет начать работу на более глубоком уровне с исходниками, в репозитории CrowdSec на Github есть код, написанный на Go, который показывает, как подключиться и использовать API.
Все методы API доступны здесь.
Итого
Как видите, локальный API CrowdSec довольно легко изучить и начать использовать в связке с баунсерами. Последние написанны на Go и адаптируемы к вашим конкретным потребностям. Готовые баунсеры можно скачать тут. Также нами написаны специальные баунсеры для работы с Nginx, WordPress, HAProxy, iptables, nftables или даже с облачными межсетевыми экранами Amazon (AWS) и Google (Network FW и Cloud Armor). Их исходники также можно найти на Github. Еще у нас есть баунсеры на LUA и PHP.
И, конечно же, всю дополнительную информацию, исходники, полезные ссылки и еще не опубликованные на Хабре мануалы вы можете найти на официальном сайте CrowdSec.
