Інтеграція Fail2ban з UniFi OS Server API для автоматичного блокування IP на роутері


5 хвилин

Навіщо блокувати IP на рівні шлюзу?

Коли ви публікуєте будь-який сервіс в інтернет (наприклад, поштовий сервер Postfix), він одразу стає мішенню для ботнетів. Зупиняти шкідливий трафік на кінцевому хості через iptables – це напівміра, адже пакети вже потрапили у вашу локальну мережу. У цій статті я покажу, як виконується інтеграція Fail2ban з UniFi OS Server API для миттєвого та автоматичного блокування атакуючих IP-адрес безпосередньо на апаратному роутері (у моєму випадку – UniFi UXG-Lite).

Раніше автоматизувати роботу з фаєрволом UniFi було незручно. Класичний UniFi Network Application не мав нормальної підтримки API-ключів, проте з переходом на UniFi OS Server з’явилася повноцінна підтримка API-ключів, що робить інтеграцію з Fail2ban надійною та безпечною.

Нижче я покажу, як налаштувати Fail2ban на вашому сервері для автоматичного додавання зловмисних IP-адрес у чорний список фаєрвола UniFi через REST API.

Створення API-ключа в UniFi OS

Для початку нам потрібно згенерувати токен, який дозволить нашому скрипту автентифікуватися в UniFi OS Server.

  1. Зайдіть у веб-інтерфейс вашого UniFi OS Server.
  2. В меню Integrations клацніть Create New API key
  3. В бічній панелі задайте Name, при необхідності Description та Expiry та клацніть на кнопку Create
  4. Зявиться вікно із токеном, його треба зберегти.

Збережіть згенерований ключ у надійному місці – він знадобиться нам на наступному кроці.

Також вам потрібно заздалегідь створити групу IP-адрес (Firewall Group) у налаштуваннях UniFi Network (наприклад, Postfix Black List) і застосувати її у правилах фаєрвола (Drop). Після створення групи потрібно дізнатися її ідентиіфікатор.

Як створити чорний список я писав в минулій статті: Створення чорного списку IP-адрес за допомогою Zone-Based Firewall на UniFi роутері

Написання Python-скрипта для взаємодії з API

Оскільки UniFi API не підтримує метод PATCH для додавання одного IP, нам потрібно спочатку отримати весь поточний список (GET), додати нову адресу і відправити оновлений список назад (PUT). Щоб список не розростався безконтрольно і не перевищив ліміти роутера, скрипт буде оптимізувати адреси, об’єднуючи їх у мінімальний набір CIDR-підмереж.

Створюємо файл скрипта:

sudo nano /usr/local/bin/unifi_block.py

Додаємо наступний код. Обов’язково замініть UNIFI_IP, API_KEY та GROUP_ID на свої значення.

unifi_block.py
#!/usr/bin/env python3
import sys
import requests
import urllib3
import ipaddress

urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)

UNIFI_IP = "192.168.99.44"
PORT = "11443"
API_KEY = "ВАШ_API_КЛЮЧ"
GROUP_ID = "ВАШ_LIST_ID"
SITE = "default"

BASE_URL = f"https://{UNIFI_IP}:{PORT}/proxy/network/api/s/{SITE}/rest/firewallgroup/{GROUP_ID}"

HEADERS = {
    "Content-Type": "application/json",
    "X-API-Key": API_KEY,
    "Accept": "application/json"
}

def optimize_cidrs(ip_list):
    networks = []
    for ip in ip_list:
        if not ip: 
            continue
        try:
            networks.append(ipaddress.ip_network(ip, strict=False))
        except ValueError:
            continue
    
    collapsed = ipaddress.collapse_addresses(networks)
    result = []
    for net in collapsed:
        # UniFi API може відхиляти /32 для одиночних IP, тому записуємо їх чистою адресою
        if net.prefixlen == 32:
            result.append(str(net.network_address))
        else:
            result.append(str(net))
    return result

def main():
    if len(sys.argv) != 2:
        print("Використання: unifi_block.py <IP_ADDRESS>")
        sys.exit(1)

    new_ip = sys.argv[1]

    # 1. Отримуємо повний поточний стан групи
    try:
        response = requests.get(BASE_URL, headers=HEADERS, verify=False)
        response.raise_for_status()
        data = response.json()
        
        if 'data' not in data or len(data['data']) == 0:
            print("Помилка: не вдалося знайти групу файрволу.")
            sys.exit(1)

        # Беремо весь оригінальний об'єкт
        group_data = data['data'][0]
        current_members = group_data.get('group_members', [])
        
    except Exception as e:
        print(f"Помилка при отриманні даних: {e}")
        sys.exit(1)

    # 2. Додаємо новий IP та оптимізуємо список
    current_members.append(new_ip)
    optimized_members = optimize_cidrs(current_members)

    # 3. Оновлюємо масив IP всередині оригінального об'єкта
    group_data['group_members'] = optimized_members

    # 4. Відправляємо весь об'єкт назад (group_data замість кастомного payload)
    try:
        put_response = requests.put(BASE_URL, headers=HEADERS, json=group_data, verify=False)
        put_response.raise_for_status()
        print(f"Успішно додано {new_ip}. Оптимізовано до {len(optimized_members)} записів.")
    except Exception as e:
        print(f"Помилка при оновленні групи: {e}")
        # Виводимо деталі помилки від сервера UniFi для діагностики, якщо вона повториться
        if hasattr(e, 'response') and e.response is not None:
            print(f"Деталі від API: {e.response.text}")
        sys.exit(1)

if __name__ == "__main__":
    main()

Робимо скрипт виконуваним:

sudo chmod +x /usr/local/bin/unifi_block.py

Встановлення Fail2ban та залежностей

На хост-системі, де працює ваш сервіс (або звідки є доступ до його логів), встановлюємо Fail2ban та необхідні бібліотеки Python:

sudo apt update
sudo apt install fail2ban python3-requests python3-urllib3

Fail2ban дозволяє створювати власні дії (actions), які виконуються при виявленні атаки. Створимо конфіг для нашого API-скрипта.

Створюємо файл дії:

sudo nano /etc/fail2ban/action.d/unifi-api.conf

Вставляємо наступний код. Fail2ban автоматично підставить IP-адресу зловмисника замість тегу <ip>:

[Definition]
# Дія, яка виконується при блокуванні IP
actionban = /usr/local/bin/unifi_block.py <ip>

# Дія при розблокуванні (можна залишити порожнім, або написати окремий скрипт для видалення,
# але зазвичай при апаратних перманентних блокуваннях це не потрібно)
actionunban =

# Дія при старті jail
actionstart =

# Дія при зупинці jail
actionstop =

# Дія для перевірки стану
actioncheck =

Налаштування Jail

Тепер потрібно вказати Fail2ban, за якими логами слідкувати і яку дію викликати. Налаштуємо це на прикладі Postfix.

Детальніше про можливості самого шлюзу читайте в огляді шлюзу UniFi Gateway Lite (UXG-Lite).

Відкриваємо локальний файл налаштувань:

sudo nano /etc/fail2ban/jail.local

Додаємо конфігурацію:

[postfix-unifi]
enabled  = true
filter   = postfix
# Вкажіть правильний шлях до лог-файлу вашого сервісу
logpath  = /var/log/mail.log 
# Використовуємо наш щойно створений action
action   = unifi-api
maxretry = 3
findtime = 3600
# -1 означає перманентне блокування (видаляти адреси з UniFi можна через GUI)
bantime  = -1

Зверніть увагу: якщо ваш сервіс Postfix встановлено на хості, переконайтеся, що шлях logpath вказує на реальне розташування змонтованого лог-файлу на хост-системі.

Запуск та перевірка роботи

Застосовуємо нові налаштування:

sudo systemctl restart fail2ban
sudo fail2ban-client status postfix-unifi

Щоб не чекати, поки Fail2ban знову знайде цього зловмисника, запустіть скрипт вручну і перевірте, чи проходить запит:

/usr/local/bin/unifi_block.py 2.27.35.164/31

Отримаємо відповідь:

Успішно додано 2.27.35.164/31. Оптимізовано до 3 записів.

Щоб переконатися в тому, що дані записані, необхідно оновити сторінку в самому веб інтерфейсі

Переходимо у веб-інтерфейс UniFi OS Server. Якщо все налаштовано правильно, тестова адреса миттєво з’явиться у вашій групі, а роутер автоматично заблокує будь-який трафік від неї ще на підході до вашої мережі.

Висновки: Захист на рівні апаратного шлюзу

Перенесення блокування з рівня хоста (програмного iptables на сервері) на рівень апаратного шлюзу (UniFi UXG-Lite) – це якісно новий етап у захисті власної інфраструктури. Ми не просто відбиваємо атаки на наш поштовий сервер, ми зупиняємо зловмисників ще до того, як їхні пакети потраплять у локальну мережу. Це економить ресурси сервера та унеможливлює подальше сканування інших ваших сервісів з тих самих IP-адрес.

Завдяки появі повноцінної підтримки API-ключів у UniFi OS Server, ця інтеграція нарешті стала стабільною, безпечною і позбавленою “костилів” із постійним оновленням сесійних cookie, як це було в старих версіях Network Application.

Що ми отримали в результаті:

  1. Повна автоматизація: Fail2ban працює як розумний аналізатор — самостійно знаходить загрозу в логах і миттєво віддає команду фаєрволу.
  2. Оптимізація ресурсів: Python-скрипт не просто сліпо додає адреси, а розумно об’єднує їх у CIDR-підмережі. Це гарантує, що апаратні ліміти роутера не будуть вичерпані навіть при масованих атаках з сусідніх адрес.
  3. Гнучкість: За цією ж логікою можна захищати не лише Postfix, а й SSH, Nginx, WordPress чи будь-який інший сервіс, який залишає сліди у логах.

Тепер ваша домашня лабораторія чи робочий сервер захищені надійно та елегантно. Сподіваюсь, цей гайд зекономить вам час і допоможе зробити вашу мережу безпечнішою.