AbuseIPDB API - UFW-AbuseIPDB-Reporter - 2026

Материал из Wiki - Iphoster - the best ever hosting and support. 2005 - 2026
Перейти к:навигация, поиск

Published: 2026-10-17


UFW-AbuseIPDB-Reporter — это open-source инструмент (Node.js + PM2), который в реальном времени читает лог межсетевого экрана UFW и автоматически отправляет заблокированные IP-адреса в базу AbuseIPDB через AbuseIPDB API v2. Проект создан автором Sefinek, распространяется по лицензии GPL-3.0, а по состоянию на 17.10.2026 версия составляет 0.6.3; репозиторий насчитывает 116 звёзд и 7 форков, а сам инструмент включён в официальный список интеграций AbuseIPDB.

Идея проста: серверы постоянно сканируются ботами, UFW видит эти попытки в логах, но по умолчанию просто пишет строки вида [UFW BLOCK] и выбрасывает пакеты. Reporter берёт каждую такую строку, парсит её, отфильтровывает служебный трафик и отправляет отчёт в AbuseIPDB, где адрес попадает в общую базу и повышает свой abuseConfidenceScore — оценку недоверия, которую используют тысячи администраторов, файрволов и сервисов для блокировки атакующих хостов.

В этой статье — подробный разбор, как устроен AbuseIPDB API и как именно Reporter использует его возможности: категории отчётов, суточные лимиты, bulk-отчёты, фильтрация UDP, кулдаун, whitelist, а также известные ограничения и риски инструмента (включая историю с ложными срабатываниями). Данные актуальны на 17.10.2026 и сверены с официальной документацией AbuseIPDB и исходным кодом репозитория.

Обзор

Ключевые параметры
Параметр Значение
Проект UFW-AbuseIPDB-Reporter
Версия 0.6.3 (октябрь 2026)
Автор Sefinek (sefinek.net)
Лицензия GPL-3.0
Стек Node.js ≥ 20.19.0, npm, PM2
Назначение Репорт IP, заблокированных UFW, в AbuseIPDB
Популярность 116 звёзд, 7 форков (на 17.10.2026)

Reporter — это тонкая обёртка над общей библиотекой IPDB-Integration-Scripts (подключена как git-сабмодуль в каталоге scripts). Тот же набор модулей переиспользуется в родственных проектах автора для Cloudflare WAF, T-Pot и Suricata; выбор API-адаптера (AbuseIPDB или альтернативный сервис SniffCat), базового URL и заголовков происходит автоматически по имени репозитория. Благодаря этому ядро в index.js остаётся компактным: парсинг лога, фильтры, кулдаун, отчёт и bulk-буфер.

После запуска через PM2 процесс висит на файле /var/log/ufw.log (через библиотеку тейлинга), при старте определяет собственные IP-адреса сервера (включая публичные IPv4/IPv6 при динамическом адресе — по cron-расписанию), загружает кэш уже отправленных отчётов и whitelist, а затем работает непрерывно. Graceful shutdown при SIGINT/SIGTERM дописывает буфер на диск. Уведомления об ошибках, критических событиях и ежедневная сводка отправляются в Discord по вебхуку.

AbuseIPDB API: лимиты и категории

AbuseIPDB API v2 работает по HTTPS, авторизация — заголовок Key с API-ключом из личного кабинета. Для репортинга важны два endpoint'а: POST /api/v2/report (одиночный отчёт) и POST /api/v2/bulk-report (пакетная отправка CSV-файла). Полный список endpoint'ов — check, reports, blacklist, check-block, clear-address — описан в официальной документации.

Суточные лимиты бесплатного плана Individual (по данным страницы тарифов и документации, 2026):

Операция Бесплатно (Individual) Basic ($25/мес) Premium ($99/мес)
check + report (запросов/день) 1 000 10 000 50 000
bulk-report (запросов/день) 5 100 500
blacklist (запросов/день) 5 (до 10 000 IP) 100 (до 100 000) 500 (до 500 000)

Ключевые правила AbuseIPDB API, которые обязан учитывать любой репортёр:

  • один и тот же IP нельзя репортить чаще раза в 15 минут — повтор получит HTTP 429;
  • суточный лимит APIv2 сбрасывается в 00:00 UTC;
  • отчёты с одинаковым комментарием и категориями за 24 часа сливаются в один;
  • UDP-соединения репортить запрещено полностью, а TCP — только если соединение завершило трёхстороннее рукопожатие (политика Reporting Policy, п. про spoofed source);
  • SYN-flood и UDP-flood репортить нельзя — исходный адрес там скорее всего подделан.

Категория отчёта — это числовой ID из справочника: 14 (Port Scan), 22 (SSH), 18 (Brute-Force), 11 (Email Spam), 23 (IoT Targeted) и другие (полный список — Report Categories). Помимо ID в отчёт уходит текстовый комментарий и опциональный timestamp. В ответ сервер возвращает обновлённый abuseConfidenceScore адреса — консервативную оценку 0–100, которая ежедневно пересчитывается с затуханием веса старых отчётов и логарифмически зависит от числа уникальных репортёров.

⚠️ Внимание! UDP нельзя репортить не «по привычке», а по правилам AbuseIPDB: исходный адрес UDP-пакета легко подделать, поэтому такие отчёты считаются вредными для базы. Именно эта норма в декабре 2024 года привела к письмам от AbuseIPDB пользователям Reporter'а — см. раздел «Ограничения и риски»

Как работает Reporter

Поток данных устроен поэтапно. Каждая строка лога с меткой [UFW BLOCK] парсится библиотекой ufw-log-parser, после чего проходит цепочку фильтров, и только выживший пакет превращается в отчёт:

  1. Проверка на собственный IP сервера: адреса интерфейсов и публичные IPv4/IPv6 (при IP_ASSIGNMENT: 'dynamic' обновляются по cron, например каждые 6 часов) никогда не репортятся.
  2. Проверка whitelist: файл whitelist.txt поддерживает отдельные адреса и CIDR, перечитывается на лету.
  3. Проверка special-purpose диапазонов: приватные сети, CGNAT, loopback, link-local, multicast и прочие не глобальные диапазоны отбрасываются через ipaddr.js.
  4. Отсев UDP: любой UDP-пакет игнорируется согласно политике AbuseIPDB.
  5. Отсев игнорируемых портов: массив IGNORED_PORTS в конфиге — например, порт p2p-клиента, чтобы пиры не репортились как сканеры.
  6. Кулдаун: повторный отчёт того же IP в течение IP_REPORT_COOLDOWN (по умолчанию 12 часов) пропускается; кэш хранится в файле tmp/ufw-abuseipdb-reporter.cache и переживает рестарты.

Далее формируется категория и комментарий. Категория выбирается по destination-порту из таблицы в config.default.js; всё, что не попало в таблицу, по умолчанию помечается как Port Scan (14):

Целевой порт Категории AbuseIPDB ID
21 Port Scan + FTP 14, 5
22 Port Scan + SSH 14, 22
23, 2323, 5555, 7547, 8291 Port Scan + IoT Targeted 14, 23
25, 465, 587 Port Scan + Email Spam 14, 11
5060, 5061 Port Scan + Fraud VoIP 14, 8
1900 Port Scan + Bad Web Bot 14, 19
прочие порты Port Scan 14

Комментарий к отчёту собирается из полей пакета и выглядит, например, так:

Blocked by UFW on NY01 [8096/tcp] | SPT: 52458 | TTL: 243 | LEN: 40 | TOS: 0x08 • Reported by: github.com/sefinek/UFW-AbuseIPDB-Reporter

Автор просит не удалять строку-атрибуцию из шаблона комментария — она служит ссылкой на источник отчёта.

Rate limit и bulk-отчёты

Ключевая инженерная фича Reporter'а — корректная работа с суточным лимитом AbuseIPDB. Когда API отвечает 429 с сообщением о дневном лимите, инструмент переходит в режим буферизации: новые отчёты складываются в память и дублируются в CSV-файл tmp/bulk-report-buffer.csv (колонки IP,Categories,ReportDate,Comment), а после сброса лимита (00:01 UTC по коду проекта) отправляются одним пакетным запросом POST /bulk-report в multipart/form-data.

Практические детали:

  • буфер персистентен: после рестарта процесса неотправленные IP доливаются и отправляются при первой возможности;
  • размер буфера ограничен 100 000 записями — защита от переполнения памяти на очень «шумных» серверах;
  • CSV дробится на чанки с учётом лимита строк bulk-эндпоинта; при ошибке 422 «exceeds the line limit» чанк делится пополам рекурсивно;
  • записи, отклонённые AbuseIPDB (invalidReports: дубликат, невалидный IP, неверная категория), удаляются из буфера без повторной отправки;
  • одиночные POST-запросы не ретраятся автоматически (чтобы не плодить дубли), ретраи — только для GET/5xx/таймаутов;
  • при достижении лимита на аккаунте без поддержки bulk API репорты просто приостанавливаются до сброса.

Такая схема особенно ценна на бесплатном плане: 1 000 одиночных отчётов в день на живом VPS с ботским сканением исчерпываются быстро, а 5 bulk-запросов позволяют «дозалить» накопленное утро.

Установка и настройка

Требования: Ubuntu/Debian, Node.js 20.19.0+, npm, PM2, Git, включённое логирование UFW (sudo ufw logging on, строки пишутся в /var/log/ufw.log) и бесплатный API-ключ AbuseIPDB.

Автоматическая установка (одна команда из README):

bash <(curl -fsS https://raw.githubusercontent.com/sefinek/UFW-AbuseIPDB-Reporter/main/install.sh)

Интерактивный установщик спросит идентификатор сервера, API-ключ (и проверит его сетевым запросом /check), режим IP (static/dynamic), расписание обновления публичного IP, поддержку IPv6, кулдаун и настройки Discord-вебхука; затем склонирует репозиторий в /opt/ufw-abuseipdb с сабмодулем, выдаст пользователю доступ к логу UFW (chown syslog:$USER; chmod 640) и зарегистрирует автостарт через pm2 startup + pm2 save.

Ручная установка (сокращённо):

sudo apt update && sudo apt upgrade
cd ~
git clone --recurse-submodules https://github.com/sefinek/UFW-AbuseIPDB-Reporter.git ufw-abuseipdb
cd ufw-abuseipdb
npm install --omit=dev
cp config.default.js config.js
sudo chown syslog:"$USER" /var/log/ufw.log
sudo chmod 640 /var/log/ufw.log
npm install -g pm2@latest
sudo mkdir -p /var/log/ufw-abuseipdb
sudo chown -R "$USER":"$USER" /var/log/ufw-abuseipdb
pm2 start
eval "$(pm2 startup | grep sudo)"
pm2 save
pm2 logs ufw-abuseipdb

Главные настройки в config.js: ABUSEIPDB_API_KEY, UFW_LOG_FILE, IP_ASSIGNMENT (static/dynamic), IP_REFRESH_SCHEDULE (cron для динамического IP), IPv6_SUPPORT, IP_REPORT_COOLDOWN (минимум 15 минут — иначе валидация конфига убьёт процесс), IGNORED_PORTS, SERVER_ID (подставляется в комментарий отчёта) и блок Discord-вебхуков. Обновление: npm run update (git pull + npm ci + pm2 restart).

Ограничения и риски

Инструмент хорошо инженерно сделан, но у него есть известные ограничения, о которых стоит знать до установки.

UDP-инцидент 2024 года. До декабря 2024 года Reporter репортит UDP-трафик, за что AbuseIPDB прислал пользователям предупреждающие письма: отчёты о UDP нарушают политику репортинга. Мейнтейнер подтвердил проблему в discussion #2 и 20.12.2024 выпустил фикс — сейчас UDP полностью отфильтровывается на уровне processLogLine. Актуальные версии от UDP-отчётов защищены.

Ложные срабатывания и TCP-флаги. Классификация «неизвестный порт = Port Scan» не анализирует TCP-флаги и направление соединения. В issue #11 (июль 2026) описан случай, когда легитимный трафик не-экзит Tor-релея (SYN+данные от established-соединения к эфемерному порту) был отрепортён как скан портов. Тикет закрыт с метками invalid/wontfix: мейнтейнер указал, что единичные FP не влияют на качество базы, а для борьбы с ними есть whitelist.txt и IGNORED_PORTS. Практический вывод: не стоит запускать Reporter на хосте с легитимными входящими сервисами без тщательного whitelist'а.

Ограничения самого API. Бесплатный план даёт всего 5 bulk-запросов в день; отчёт о том же IP чаще раза в 15 минут невозможен; AbuseIPDB оставляет за собой право удалять отчёты и банить репортёров за нарушения. Следите, чтобы API-ключ не попадал в публичные репозитории: он хранится в config.js (файл в .gitignore).

Особенности установщика. Install.sh нацелен на Debian/Ubuntu и не проверяет архитектуру или дистрибутив заранее; API-ключ кратко печатается в терминале в итоговой сводке; после первой ротации /var/log/ufw.log права на файл могут сброситься и процесс перестанет читать лог (нужно следить за logrotate или перезапускать сервис). Проект не содержит деинсталлятора.

⛔ Предупреждение
Автоматический репортинг «всего заблокированного» без whitelist'а и разбора TCP-флагов может навредить репутации легитимных адресов. Перед запуском на проде обязательно заполните whitelist.txt и IGNORED_PORTS

Сравнение

Инструмент Направление Стек Особенности
UFW-AbuseIPDB-Reporter UFW-лог → AbuseIPDB Node.js + PM2 Фильтры (UDP, own IP, whitelist), кулдаун, bulk-буфер, Discord, 116★
Fail2Ban + action abuseipdb (встроен с v0.10.0) журналы сервисов → AbuseIPDB Python, шаблоны Официальная интеграция; репорт после ban-правила фильтра, инструкция AbuseIPDB
jseutens/ufw-abuseipdb AbuseIPDB-чёрный список → UFW Bash Обратное направление: импорт blacklist в правила UFW; 11★, автор рекомендует nftables-blacklist
trick77/nftables-blacklist публичные чёрные списки → nftables Bash Потребление blacklist'ов (в т.ч. AbuseIPDB) вместо репортинга; 24★

Reporter и Fail2Ban решают смежные, но разные задачи: Fail2Ban банит локально по логам конкретного сервиса и может дополнительно репортить, Reporter же мониторит весь перехваченный UFW трафик и отдаёт его в глобальную базу. Их можно использовать вместе: Fail2Ban — как слой локальной защиты, Reporter — как вклад в общую базу.

FAQ

Нужен ли платный аккаунт AbuseIPDB? Нет. Бесплатного плана (1 000 отчётов/день + 5 bulk-запросов) хватает для большинства VPS; платные тарифы нужны при множестве серверов или если хочется большего лимита и кастомных blacklist'ов.

Почему отчёты уходят не сразу, а копятся? При достижении суточного лимита API (HTTP 429) Reporter переходит в режим буферизации и после сброса лимита в 00:01 UTC отправляет накопленное пакетом через /bulk-report. Это защита от потери отчётов и от бессмысленного долбления API.

Можно ли репортить UDP-сканы? Нет. Политика AbuseIPDB прямо запрещает отчёты об UDP-соединениях, так как исходный адрес UDP легко подделать. Reporter с версии от 19–20.12.2024 самостоятельно отфильтровывает весь UDP-трафик.

Как уменьшить количество ложных отчётов? Заполните whitelist.txt (домашние/партнёрские IP и сети в CIDR), вынесите порты своих легитимных сервисов в IGNORED_PORTS, увеличьте IP_REPORT_COOLDOWN и включите EXTENDED_LOGS для аудита решений до включения реальных отчётов.

Что делать, если мой IP попал в AbuseIPDB по ошибке? Используйте форму bulk reporter / страницу IP на сайте AbuseIPDB для очистки своих отчётов через clear-address (удаляет только ваши отчёты), либо напишите хостинг-провайдеру; а затем добавьте адрес в whitelist Reporter'а, чтобы инцидент не повторился.

Итог

UFW-AbuseIPDB-Reporter — это зрелый и аккуратный способ превратить пассивный лог UFW в активный вклад в глобальную базу AbuseIPDB: реальная защита от самобана, фильтр UDP по политике, кулдаун, умная работа с суточными лимитами через bulk-буфер и приятные бонусы вроде Discord-сводок. Для типового VPS с включённым логированием UFW его достаточно сконфигурировать и забыть.

Главное — понимать границы применимости: инструмент классифицирует заблокированный TCP-трафик крайне консервативно (по умолчанию — Port Scan), не разбирая TCP-флаги, поэтому на хостах с легитимными сервисами обязателен whitelist. В сочетании с Fail2Ban или nftables-blacklist'ом Reporter закрывает обратную сторону медали: не только защищает ваш сервер, но и помогает защищать остальных.

Источники

×
Реклама
← В главную
ИКС 88x31 - Visitor counter