AbuseIPDB API - UFW-AbuseIPDB-Reporter - 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, после чего проходит цепочку фильтров, и только выживший пакет превращается в отчёт:
- Проверка на собственный IP сервера: адреса интерфейсов и публичные IPv4/IPv6 (при
IP_ASSIGNMENT: 'dynamic'обновляются по cron, например каждые 6 часов) никогда не репортятся. - Проверка whitelist: файл
whitelist.txtподдерживает отдельные адреса и CIDR, перечитывается на лету. - Проверка special-purpose диапазонов: приватные сети, CGNAT, loopback, link-local, multicast и прочие не глобальные диапазоны отбрасываются через
ipaddr.js. - Отсев UDP: любой UDP-пакет игнорируется согласно политике AbuseIPDB.
- Отсев игнорируемых портов: массив
IGNORED_PORTSв конфиге — например, порт p2p-клиента, чтобы пиры не репортились как сканеры. - Кулдаун: повторный отчёт того же 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 закрывает обратную сторону медали: не только защищает ваш сервер, но и помогает защищать остальных.
Источники
- Репозиторий UFW-AbuseIPDB-Reporter — исходный код, README, install.sh, config.default.js
- Общая библиотека IPDB-Integration-Scripts — сабмодуль с сервисами, флагами и валидациями
- Документация AbuseIPDB API v2 — endpoint'ы, параметры, суточные лимиты, формат bulk-report
- Политика репортинга AbuseIPDB — правила (TCP handshake, запрет UDP/SYN-flood, 60 дней, слияние дублей)
- Справочник категорий AbuseIPDB — ID 1–23
- FAQ AbuseIPDB — abuseConfidenceScore, лимиты, частота репортов
- Тарифы AbuseIPDB — лимиты бесплатного и платных планов (2026)
- Discussion #2: UDP-отчёты и письма AbuseIPDB — декабрь 2024
- Issue #11: false positive с Tor-релеем — июль 2026
- Официальная интеграция Fail2Ban — альтернативный сценарий репортинга
- jseutens/ufw-abuseipdb и trick77/nftables-blacklist — импорт чёрных списков в firewall (обратное направление)
