Отправить жалобу (REPORT)

POST https://api.abuseipdb.ru/api/v2/report — отправить одну жалобу на IP-адрес. Это ядро сервиса: каждая жалоба делает базу точнее и возвращает вам обновлённую оценку адреса.

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

Запрос

# POST: отправляем данные формы (application/x-www-form-urlencoded)
curl https://api.abuseipdb.ru/api/v2/report \
  --data-urlencode "ip=89.205.125.160" \
  -d categories=18,22 \
  --data-urlencode "comment=SSH login attempts with user root." \
  --data-urlencode "timestamp=2023-10-18T11:25:11-04:00" \
  -H "Key: YOUR_OWN_API_KEY" \
  -H "Accept: application/json"

Параметры

categories можно передать и массивом (categories[]=18&categories[]=22) — это расширение AbuseIPDB.RU, удобное для PHP-форм.

comment и timestamp очищаются и нормализуются на сервере. timestamp принимает ISO 8601 со смещением (2023-10-18T11:25:11-04:00), Z, простую дату и unix-время; мусор возвращает 422, а не молча подменяется на «сейчас».

Три способа передать тело

Все три работают одинаково — выбирайте тот, что удобнее вашему клиенту.

# 1. application/x-www-form-urlencoded (как в примере выше): -d и --data-urlencode

# 2. application/json
curl https://api.abuseipdb.ru/api/v2/report \
  -H "Content-Type: application/json" \
  -H "Key: YOUR_OWN_API_KEY" \
  -H "Accept: application/json" \
  --data '{"ip":"89.205.125.160","categories":"18,22","comment":"SSH brute-force","timestamp":"2023-10-18T11:25:11-04:00"}'

# 3. multipart/form-data — удобно, если комментарий содержит переводы строк и двоичные символы
curl https://api.abuseipdb.ru/api/v2/report \
  -F "ip=89.205.125.160" \
  -F "categories=18,22" \
  -F "comment=SSH login attempts" \
  -H "Key: YOUR_OWN_API_KEY" \
  -H "Accept: application/json"

Ответ

{
  "data": {
    "ipAddress": "89.205.125.160",
    "abuseConfidenceScore": 52
  }
}

Формула оценки описана в FAQ: учитываются различные репортёры и свежесть их последних жалоб.

Дедупликация: одна жалоба на адрес за 15 минут

Один и тот же репортёр не может пожаловаться на один и тот же адрес чаще, чем раз в 15 минут. Повторная жалоба в это окно не сохраняется и возвращает 429 с точным текстом AbuseIPDB:

{
  "errors": [
    {
      "detail": "You can only report the same IP address (`89.205.125.160`) once in 15 minutes.",
      "status": 429,
      "source": { "parameter": "ip" }
    }
  ]
}

• Окно считается от момента сохранения, а не от указанного в timestamp времени инцидента.
• Ограничение — на пару «репортёр + адрес»: разные репортёры могут жаловаться на один адрес одновременно.
• Повторная жалоба по прошествии 15 минут сохраняется и снова влияет на оценку.
• Уникальный индекс в базе не даёт двум одновременным запросам обойти правило.

Какие адреса репортить нельзя

Жалоба означает «этот адрес атаковал меня». Такой адрес обязан быть глобально маршрутизируемым: локальные и служебные диапазоны не могут быть источником удалённой атаки, а диапазоны для примеров (RFC) никому не принадлежат. Поэтому отчёт по ним отклоняется с 422:

{
  "errors": [
    {
      "detail": "The ip address must be a public IPv4 or IPv6 address. Local, private, reserved and documentation ranges cannot be reported.",
      "status": 422,
      "source": { "parameter": "ip" }
    }
  ]
}

Полный запрещённый список (32 диапазона):

Локальные/приватные: 10.0.0.0/8, 100.64.0.0/10 (CGNAT), 127.0.0.0/8 (loopback), 169.254.0.0/16 (link-local), 172.16.0.0/12, 192.168.0.0/16, ::1/128, fc00::/7 (ULA), fe80::/10 (IPv6 link-local).

Служебные/зарезервированные: 0.0.0.0/8, 192.0.0.0/24, 192.88.99.0/24, 198.18.0.0/15, 224.0.0.0/4 (multicast), 240.0.0.0/4, 255.255.255.255/32, ::/128, ::ffff:0:0/96 (IPv4-mapped), 64:ff9b::/96 и 64:ff9b:1::/48 (NAT64), 100::/64, 2001::/32 (Teredo), 2001:2::/48, 2001:10::/28 и 2001:20::/28 (ORCHID), 2002::/16 (6to4), ff00::/8 (multicast).

Диапазоны для примеров: 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24 (RFC 5737), 2001:db8::/32 (RFC 3849), 3fff::/20 (RFC 9637).

Это сознательное ужесточение: база публичная, и жалоба на 192.168.1.5 или 127.0.0.1

не приносит пользы никому — такой адрес всё равно нельзя заблокировать на периметре.

Как тогда тестировать интеграцию

1. Возьмите публичный адрес, который контролируете (например, IP своего же сервера или

второго сервера в другом дата-центре) — это безопасно: жалоба описывает атаку, а не портит чужой адрес.

1. Отправьте жалобу один раз → 200. Отправьте её же сразу повторно → 429 с текстом

«You can only report the same IP address once in 15 minutes.» — это и есть проверка дедупликации.

1. Для проверки форматов ответов используйте стабильные публичные адреса (8.8.8.8, 1.1.1.1)

на чтение и GET /api/v2/status.

1. Проверка GET /api/v2/check по-прежнему принимает локальные адреса (вернёт isPublic=false,

usageType=Reserved) — ограничение касается только отправки жалоб.

Категории жалоб

categories — список целых идентификаторов 1…23 через запятую. Дубликаты схлопываются, порядок значения не имеет. Эту же таблицу можно посмотреть на странице /categories.

Правила: неизвестный или отсутствующий идентификатор — 422 с source.parameter=categories; дубликаты схлопываются; все 23 идентификатора — допустимы.

Персональные данные (PII)

Внимание. Комментарии к жалобам видны другим пользователям. Вырезайте персональные данные: имена, логины реальных людей, адреса, телефоны, содержимое переписки, токены и пароли. Ответственность за раскрытые в комментарии данные лежит на отправителе.

Безопасный комментарий — это фрагмент технического лога без персональных данных:

Nov  7 02:14:07 srv sshd[1234]: Failed password for invalid user admin from 203.0.113.7 port 51544 ssh2

Плохой комментарий: содержит e-mail, телефон или полное имя сотрудника.

Примеры

Python:

import requests
from datetime import datetime, timezone

API_KEY = "YOUR_OWN_API_KEY"
BASE = "https://api.abuseipdb.ru/api/v2"

def report_ip(ip: str, categories: list[int], comment: str = "", when: str | None = None) -> dict:
    payload = {
        "ip": ip,
        "categories": ",".join(str(c) for c in categories),
        "comment": comment[:1024],
    }
    if when is not None:
        payload["timestamp"] = when
    response = requests.post(
        f"{BASE}/report",
        data=payload,
        headers={"Key": API_KEY, "Accept": "application/json"},
        timeout=15,
    )
    if response.status_code == 429:
        # либо дедупликация 15 минут, либо дневной лимит — смотрите detail
        raise RuntimeError(response.json()["errors"][0]["detail"])
    response.raise_for_status()
    return response.json()["data"]

print(report_ip("89.205.125.160", [18, 22], "SSH brute-force from 127.0.0.1"))

PHP:

<?php
function report_ip(string $ip, array $categories, string $comment = ''): array
{
    $ch = curl_init('https://api.abuseipdb.ru/api/v2/report');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query([
            'ip' => $ip,
            'categories' => implode(',', $categories),
            'comment' => mb_substr($comment, 0, 1024),
        ]),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Key: ' . getenv('ABUSEIPDB_KEY'),
            'Accept: application/json',
            'Content-Type: application/x-www-form-urlencoded',
        ],
        CURLOPT_TIMEOUT => 15,
    ]);
    $body = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);

    if ($status !== 200) {
        throw new RuntimeException("API v2 HTTP $status: $body");
    }

    return json_decode($body, true)['data'];
}

Ошибки REPORT

Точные примеры тел — Обработка ошибок. Массовая отправка — BULK-REPORT. Удаление своих жалоб — CLEAR-ADDRESS.