Вопросы и ответы

Короткие ответы на вопросы, которые чаще всего задают про API v2, оценки, лимиты и миграцию с abuseipdb.com. Если ответа нет — напишите в поддержку: support@abuseipdb.ru.

Раздел «API v2»: Обзор · Проверка IP (CHECK) · Жалобы по IP (REPORTS) · Отправить жалобу (REPORT) · Чёрный список (BLACKLIST) · Проверка подсети (CHECK-BLOCK) · Массовые жалобы (BULK-REPORT) · Удаление жалоб (CLEAR-ADDRESS) · Лимиты · Ошибки · Fail2Ban, CSF, Suricata · FAQ

Начало работы

Что такое API v2?

Программный интерфейс к базе жалоб AbuseIPDB.RU. Позволяет проверить IP, получить список жалоб, выгрузить чёрный список, отправить одну или 10 000 жалоб и проверить подсеть. Полное описание — в Обзоре.

Как получить ключ API?

Личный кабинет https://abuseipdb.ru/dashboard → «API-ключи» → «Создать ключ». Ключ показывается один раз — сохраните его. Бесплатный ключ даёт 1 000 запросов в сутки. Если раздела нет в вашей учётной записи — напишите на support@abuseipdb.ru.

API платный?

Базовый тариф free бесплатный: 1 000 запросов в сутки, все эндпоинты кроме clear-address. Тариф premium (50 000 запросов в сутки) поднимает квоту. clear-address доступен только admin-ключам.

С чего начать интеграцию?

1. Получить ключ. 2. Выполнить проверку адреса:

curl -sG https://api.abuseipdb.ru/api/v2/check \
  --data-urlencode "ipAddress=8.8.8.8" \
  -d maxAgeInDays=90 \
  -H "Key: $API_KEY" \
  -H "Accept: application/json"

1. Отправить тестовую жалобу на публичный адрес, которым вы владеете (локальные/приватные/служебные — 422). 4. Подключить Fail2Ban или свой бэкенд.

Совместимость с abuseipdb.com

Как перейти с abuseipdb.com на AbuseIPDB.RU?

Заменить домен в базовом URL: https://api.abuseipdb.com/api/v2/ → https://api.abuseipdb.ru/api/v2/. Заголовок Key, параметры, конверты ответов и коды ошибок остаются прежними. Таблица соответствия — в Обзоре.

Почему оценка того же IP отличается от abuseipdb.com?

Потому что база локальная. abuseConfidenceScore считается по жалобам, полученным AbuseIPDB.RU, с нашей формулой. Это не ошибка и не «недостача данных»: у каждого сервиса свои наблюдения. Со временем, по мере накопления жалоб, оценка сближается.

Что именно отличается от abuseipdb.com?

Все отличия перечислены ниже в разделе «Чем AbuseIPDB.RU дополняет AbuseIPDB.com». Кратко: у нас один общий дневной счётчик на все эндпоинты (не на каждый), фильтры onlyCountries/exceptCountries/ipVersion бесплатны, CORS включён, есть GET /api/v2/status, Authorization: Bearer и GET-алиасы для некоторых методов.

Клиент шлёт ключ в ?key= — это поддерживается?

Да. Принимаются Key:, Authorization: Bearer, ?key= (строчными) и поле формы key. Рекомендуется заголовок: ключ в URL попадает в журналы сервера и прокси.

Оценка abuseConfidenceScore

Формула оценки

Оценка учитывает различных репортёров (не количество жалоб), их последние жалобы и свежесть этих жалоб:

• каждый репортёр считается один раз, берётся его самая свежая жалоба на этот адрес;
• вес жалобы зависит от возраста: до 30 дней — 1.0, 31–90 дней — 0.5, 91–365 дней — 0.25, старше года — 0;
• сумма весов w переводится в оценку: score = round(100 · w / (w + 3)), но не ниже 25, если w > 0;
• если жалоб нет, оценка 0.

Справочные значения:

Такой же формулой считаются оценки на странице /check/{ip}, в BLACKLIST и в CHECK-BLOCK — цифры всегда согласованы.

Что означает 25%?

Жёсткий минимум для адреса, у которого есть хотя бы одна «засчитанная» жалоба. Ниже 25% оценка не опускается, пока жалобы есть; адрес с оценкой 0 — это адрес без жалоб или с жалобами старше года.

Почему totalReports и numDistinctUsers разные?

totalReports — количество жалоб внутри окна maxAgeInDays. numDistinctUsers — количество разных репортёров. Один человек, отправивший 20 жалоб, даёт totalReports=20, но numDistinctUsers=1, и на оценку влияет как один репортёр.

Почему оценка стала ниже?

Старые жалобы теряют вес: 30 дней → 1.0, 90 дней → 0.5, 365 дней → 0.25, позже → 0. Если репортёры перестали жаловаться, оценка снижается сама. Это защита от «вечных» блокировок.

Проверка адресов

Как проверить много адресов?

Если адреса в одной подсети — /api/v2/check-block (IPv4 /16…/24, IPv6 /48…/64). Для произвольного списка — по одному /check с кэшем на 5–15 минут. Полный список жалоб по адресу — REPORTS.

Поддерживается ли IPv6?

Да, во всех эндпоинтах. Результат: ipVersion=6. Двоеточия в IPv6 требуют URL-кодирования: в curl используйте --data-urlencode.

Что такое isPublic?

Признак публично маршрутизируемого адреса. Для приватных диапазонов (10/8, 172.16/12, 192.168/16), loopback (127/8), link-local и служебных адресов isPublic=false. Жалобы на такие адреса разрешены (удобно для тестов), но в интернете они смысла не имеют.

Что такое isWhitelisted?

Адрес найден в белом списке оператора. В AbuseIPDB.RU значение всегда true/false. Белый список — это «презумпция невиновности», но решение о блокировке лучше принимать по abuseConfidenceScore.

Жалобы и удаление

Как удалить свою жалобу?

DELETE /api/v2/clear-address?ipAddress=<IP> — удаляет только ваши жалобы на этот адрес. Нужен admin-ключ; обычному ключу вернётся 403. Подробности — CLEAR-ADDRESS.

Как удалить чужую жалобу на мой адрес?

Форма takedown-запроса на странице /check/{ip}. CLEAR-ADDRESS чужие жалобы не удаляет. Укажите адрес, дату жалобы и причину.

Почему вторая жалоба получает 429?

Правило дедупликации: один репортёр не может жаловаться на один адрес чаще раза в 15 минут. Ответ: You can only report the same IP address once in 15 minutes. Это защита от накрутки. Для проверки отправьте жалобу на свой публичный адрес дважды подряд — второй ответ будет 429.

Можно ли пожаловаться на приватный адрес?

Нет. Жаловаться можно только на публичные адреса: локальные (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), link-local (169.254.0.0/16, fe80::/10), CGNAT (100.64.0.0/10), служебные и документационные диапазоны отклоняются с 422. Причина проста: такой адрес не может быть источником удалённой атаки, а в публичной базе он бесполезен — его нельзя заблокировать на периметре. Проверка GET /api/v2/check локальные адреса по-прежнему принимает (вернёт isPublic=false).

У меня в комментарии персональные данные — что делать?

Немедленно удалите жалобу через CLEAR-ADDRESS (admin-ключ) или напишите в поддержку. Комментарии публичны; ответственность за PII в них лежит на отправителе.

Лимиты и ошибки

Какие дневные лимиты?

free — 1 000, premium — 50 000, admin — 1 000 000 запросов на ключ в сутки. Счётчик общий на все эндпоинты и обнуляется в 00:00 UTC. Актуальный лимит всегда в заголовке X-RateLimit-Limit.

Как узнать, сколько запросов осталось?

Читайте X-RateLimit-Remaining и X-RateLimit-Reset в ответе. При 429 ждите Retry-After секунд.

Чем отличаются два вида 429?

Daily rate limit of N requests exceeded… — исчерпана суточная квота, ждать Retry-After. You can only report the same IP address (…) once in 15 minutes — дедупликация жалоб, ждать 15 минут. См. Ошибки.

Почему 422?

Ошибка валидации параметра: неверный ipAddress, maxAgeInDays вне 1…365, perPage вне 1…100, категория вне 1…23. В теле есть source.parameter. Полный справочник — Ошибки.

Пришёл 403 на clear-address — почему?

Эндпоинт доступен только admin-ключам. Используйте другой ключ или обратитесь в поддержку.

Безопасность

Можно ли вызывать API из браузера?

CORS открыт (Access-Control-Allow-Origin: *) — это расширение AbuseIPDB.RU, технически запрос из браузера пройдёт. Но не вставляйте ключ API в публичный JavaScript: любой посетитель увидит его в исходниках. Для браузера делайте серверный прокси.

Где хранить ключ?

В переменной окружения или файле с правами 600, не в git. Ключ хранится у нас в виде SHA-256-хэша и показывается один раз при создании.

Ключ утёк — что делать?

Отзовите его в кабинете и создайте новый. Все запросы отозванного ключа получают 401. Для каждого ключа видно last_used_at и last_used_ip — сверьте с ожидаемым.

Почему не стоит передавать ключ в query-строке?

Он попадёт в журналы веб-сервера, прокси и систем мониторинга. Ваш ключ, ваш риск: используйте заголовок Key.

Чем AbuseIPDB.RU дополняет AbuseIPDB.com

Расширения помечены явно. Всё, что не помечено, работает как на abuseipdb.com.

Русский язык и локальные данные

• Документация и человеческий интерфейс — на русском; API отвечает теми же английскими detail, что и abuseipdb.com (клиенты ищут по тексту).
• Данные хранятся на сервере в России и не отправляются в сторонние сервисы для основной проверки.
• Поддержка на русском: support@abuseipdb.ru.

Чего у нас нет (честно)

• Нет глобальной базы abuseipdb.com: оценка строится по нашим жалобам.
• Нет тарифной сетки Standard/Webmaster/Supporter/Basic/Premium — у нас free/premium/admin.
• Нет кода 402 Payment Required для check-block: ограничение — формат маски (422).
• STIX/TAXII-фидов пока нет.

Поддержка

При обращении указывайте: HTTP-код, detail ошибки, время запроса (UTC) и адрес, по которому делался запрос. Ключ API не присылайте — он не нужен поддержке.