Использование API
Базовый URL — https://api.f2b.0xhw.com. Здесь доступен только публичный GET API: данные можно искать без авторизации, но изменять чужие блокировки через него нельзя.
Поддерживаются IPv4 и IPv6. Запросы удобно проверять в интерактивном справочнике; спецификация OpenAPI также доступна в формате JSON.
Какие запросы доступны
| Путь | Назначение |
|---|---|
/health | Информация о сервисе |
/v1/lookup?ip=... | Наблюдения для конкретного IP, включая снятые и устаревшие состояния |
/v1/ips | Отфильтрованный список наблюдений с сортировкой и постраничной выдачей |
/v1/stats | Отфильтрованные счётчики и агрегаты по столбцам |
/v1/sources | Источники сбора и состояние обновления jail |
/v1/feed.txt | Дедуплицированный список IP по активным наблюдениям |
Поиск одного IP
curl 'https://api.f2b.0xhw.com/v1/lookup?ip=1.1.1.1'Этот IP приведён как пример вызова. API отвечает обычным образом и при отсутствии наблюдений, при этом observations — пустой массив. Приватные и зарезервированные адреса, а также некорректные значения возвращают 400.
first_seen и last_seen — время в Unix-секундах. active и stale возвращаются как 0 или 1. Их смысл описан в разделе Как читать данные.
Фильтрация и постраничная выдача
Вместо загрузки всего списка можно отобрать записи по стране, jail, организации или времени наблюдения:
curl 'https://api.f2b.0xhw.com/v1/ips?country=JP&jail=sshd&sort=last_seen&order=desc&limit=100'
curl 'https://api.f2b.0xhw.com/v1/ips?ip_prefix=1.1.&limit=100'
curl 'https://api.f2b.0xhw.com/v1/ips?organization=Cloudflare&active=all&limit=100'| Параметр | Значение |
|---|---|
source | Метка источника сбора |
jail | Имя jail |
country | Двухбуквенный код страны в верхнем регистре |
asn | Номер ASN |
active | true (по умолчанию), false или all |
stale | true для источников, не обновлявшихся более 48 часов; false для свежих источников |
ip_prefix | Текстовый префикс канонического IP-адреса, например 1.1. |
organization | Подстрока названия организации без учёта регистра |
first_seen_from, first_seen_to | Включающие границы в Unix-секундах для первого наблюдения |
last_seen_from, last_seen_to | Включающие границы в Unix-секундах для эффективного последнего наблюдения |
sort принимает значения ip, source, jail, country, asn, organization, active, first_seen и last_seen; по умолчанию — ip. order — asc (по умолчанию) или desc.
Курсор привязан к фильтрам и порядку сортировки. Повторное использование курсора с другими условиями возвращает 400. При равных значениях сортировка выполняется по ip, source и jail, поэтому страницы не дублируют и не пропускают наблюдения.
Размер страницы limit по умолчанию равен 100 и не может превышать 500. Если next_cursor является строкой, сохраните те же фильтры и передайте его как cursor в следующем запросе. Не интерпретируйте и не изменяйте курсор.
Текстовый поток
curl -i 'https://api.f2b.0xhw.com/v1/feed.txt?country=JP&limit=1000'Поток возвращает по одному IP в строке и принимает те же фильтры. По умолчанию сортировка выполняется по IP-адресу; курсор привязан к фильтрам. Значение limit по умолчанию — 1000, максимум — 5000. Если возвращается X-Truncated: true, передайте X-Next-Cursor как следующий cursor, чтобы продолжить.
Не переносите этот поток напрямую в список постоянных блокировок. Это наблюдения Fail2ban, а не проверенный перечень злоумышленников. Сначала проверьте политики обнаружения и время записи.
Статистика
Если нужны не отдельные IP, а общая картина, используйте /v1/stats. Он принимает те же фильтры. Без group_by возвращаются итоговые значения и счётчики по стране, ASN, jail и источнику. С group_by возвращается один отсортированный список агрегатов.
curl 'https://api.f2b.0xhw.com/v1/stats?country=JP&group_by=asn&sort=observations&order=desc&limit=20'group_by принимает country, asn, jail или source. sort принимает observations (по умолчанию), ips или value. order по умолчанию — desc, а limit по умолчанию равен 100 и не может превышать 500.
Кэширование и ограничения использования
API ограничивает каждый клиентский IP примерно 120 запросами в минуту и при превышении лимита возвращает 429 с Retry-After. Это приблизительный лимит по узлам сети, а не единый точный глобальный счётчик.
Статистика кэшируется на 15 минут, поток — на 5 минут, остальные API — на 1 минуту. Поэтому результаты могут кратковременно отличаться сразу после сбора. Ограничения бесплатного тарифа или временные сбои также могут сделать API недоступным; при ошибке повторите запрос через некоторый интервал.