Как читать данные
В этих данных легко перепутать «IP когда-то наблюдался» и «IP заблокирован прямо сейчас».
Сбор выполняется периодически, а не в реальном времени. Прежде чем делать выводы по списку адресов, стоит понять, что считается одним наблюдением и какие события в него не попадают.
Единица наблюдения
Одно наблюдение — это сочетание source, jail и ip. Если один и тот же IP обнаружен двумя jail или двумя источниками сбора, он сохраняется как несколько наблюдений.
Например, адрес, замеченный в SSH и Nginx, даст две записи. Поэтому число наблюдений не обязано совпадать с числом уникальных IP.
В статистике observations — количество наблюдений, а ips — количество уникальных IP. Текстовый поток также дедуплицирует IP.
Время и состояние
| Поле | Значение |
|---|---|
first_seen | Когда эта платформа сбора впервые подтвердила адрес |
last_seen | Последнее время сбора, когда адрес был подтверждён |
active = 1 | Присутствует в списке блокировок последнего снимка |
active = 0 | Удалён из списка в более позднем снимке |
stale = 1 | Jail не собирался более 48 часов |
Время показывает, когда состояние увидела система сбора, а не момент, когда Fail2ban впервые заблокировал IP. Отсутствие свежих данных также не означает снятия блокировки. Jail с устаревшими обновлениями исключаются из текущего списка, статистики и потока. Поиск и active=all позволяют просматривать прошлые наблюдения.
Ограничения периодического сбора
Помимо ежедневного формирования отчётов, каждый источник сбора записывает текущий список блокировок в формате JSON. Если ничего не изменилось, он отправляет heartbeat на основе хеша; если изменения есть — применяет diff из полного снимка.
Адрес, который успели заблокировать и разблокировать между двумя снимками, в данных вообще не появится. Это не журнал каждого отдельного события Fail2ban. Этот API не восстанавливает каждый прошлый список блокировок. Записи существуют только с момента, когда эта платформа сбора начала наблюдение.
Страна, ASN и организация
Это значения обогащения из GeoIP (геолокация IP) и RDAP (данные регистрации). Неизвестные значения — null. Коды стран и значения ASN (Autonomous System Number) описывают сети и не определяют гражданство, место жительства, принадлежность или личность человека, отправившего запрос.
Что публикуется
Публичный API предоставляет IP-адреса, открытые метки источников сбора, имена jail, время наблюдений, состояние и сетевое обогащение. Необработанные журналы доступа, тела запросов, имена учётных записей, учётные данные и административные списки исключений не публикуются.
Не используйте наблюдения как готовый список постоянных блокировок. Одна запись об IP не доказывает вредоносного намерения; проверяйте правила обнаружения и состояние. Совместно используемые линии связи и динамическое назначение IP означают, что адрес может использоваться другим пользователем, не тем, кто был при наблюдении.
Как сообщить о ложном срабатывании или проблеме в спецификации
Вопросы о трактовке или несоответствия в спецификации можно сообщить через репозиторий f2b-api на GitHub. Не публикуйте учётные данные, необработанные журналы и персональные данные. При рассмотрении исправления мы разделяем jail, время наблюдения и условия проблемы.