Навіщо блокувати 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.

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

Також вам потрібно заздалегідь створити групу 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-скрипта.
Більше моїх статей про Постфікс: моніторинг Postfix активності в Zabbix або налаштування PostfixAdmin для керування поштовим сервером.
Створюємо файл дії:
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.
Що ми отримали в результаті:
- Повна автоматизація: Fail2ban працює як розумний аналізатор — самостійно знаходить загрозу в логах і миттєво віддає команду фаєрволу.
- Оптимізація ресурсів: Python-скрипт не просто сліпо додає адреси, а розумно об’єднує їх у CIDR-підмережі. Це гарантує, що апаратні ліміти роутера не будуть вичерпані навіть при масованих атаках з сусідніх адрес.
- Гнучкість: За цією ж логікою можна захищати не лише Postfix, а й SSH, Nginx, WordPress чи будь-який інший сервіс, який залишає сліди у логах.
Тепер ваша домашня лабораторія чи робочий сервер захищені надійно та елегантно. Сподіваюсь, цей гайд зекономить вам час і допоможе зробити вашу мережу безпечнішою.
