همگام‌سازی فهرست آی‌پی سرور با مسیر بلاک و چالش فایروال ابری آروان

وقتی سایت پشت CDN قرار دارد، بخشی از کنترل ترافیک در لبه شبکه انجام می‌شود و بخشی روی سرور اصلی. اگر فهرست آی‌پی‌های مسدودشده روی سرور با فایروال CDN هماهنگ نباشد، مدیریت دو مجموعه قانون به کاری تکراری تبدیل می‌شود. این راهنما اسکریپتی را بررسی می‌کند که داده‌های آماده‌شده از Imunify360 را می‌خواند و به قوانین فایروال آروان تبدیل می‌کند.

مخاطب مقاله مدیر سرور یا توسعه‌دهنده‌ای است که به تنظیمات دامنه در آروان، کلید API مناسب و محیط اجرای پایتون دسترسی دارد. کد کامل پروژه در ادامه آمده و توضیحات بر اساس همین نسخه نوشته شده‌اند. مثال‌های ورودی آموزشی هستند و نتیجه اجرای واقعی روی حساب شما محسوب نمی‌شوند.

این اتصال دقیقاً چه کاری انجام می‌دهد؟

ورودی برنامه فایل imunify_ips.json است؛ اسکریپت به‌تنهایی به Imunify360 وصل نمی‌شود و خروجی آن را دریافت نمی‌کند. بنابراین تهیه فهرست کامل و به‌روز، مسئولیت مرحله‌ای جداگانه در فرایند شماست. مسیر داده چنین است: خروجی Imunify360، فایل JSON، اعتبارسنجی و دسته‌بندی آی‌پی‌ها، سپس درخواست به API فایروال آروان.

در این طراحی، تصمیم‌های محلی مربوط به بلاک و کپچا به دو گروه مستقل تبدیل می‌شوند. هدف انتقال همه تنظیمات امنیتی، همه محدودیت‌های سرور یا همه قابلیت‌های Imunify360 نیست. همچنین این اتصال فقط روی ترافیکی اثر دارد که از مسیر CDN و قوانین دامنه عبور می‌کند؛ محافظت از دسترسی مستقیم سرور اصلی همچنان نیازمند تنظیمات مستقل است.

نصب وابستگی‌ها و تنظیم کلید API

فایل اسکریپت را در پوشه‌ای مثل /opt/imunify-arvan قرار دهید و یک محیط مجازی بسازید. دستورهای زیر نمونه نصب در محیط لینوکسی با پایتون و ماژول venv در دسترس هستند:

cd /opt/imunify-arvan
python3 -m venv venv
source venv/bin/activate
pip install requests python-dotenv

این پروژه فقط دو وابستگی خارجی اصلی دارد: requests برای HTTP و python-dotenv برای خواندن تنظیمات. فایل .env را کنار اسکریپت بسازید:

DOMAIN=example.com
ARVAN_API_KEY=YOUR_API_CREDENTIAL

نام دامنه را بدون https:// و بدون مسیر وارد کنید. مقدار کلید باید مجوز کار با فایروال همان دامنه را داشته باشد. کد اگر مقدار کلید با Bearer یا Apikey شروع شود، آن را بدون تغییر می‌فرستد؛ در غیر این صورت پیشوند Bearer اضافه می‌کند. این رفتار همین پیاده‌سازی است؛ قالب اعتبارنامه حساب خود را بررسی کنید و در صورت نیاز پیشوند درست را صریح بنویسید.

اسکریپت فایل تنظیمات را نسبت به مسیر خودش پیدا می‌کند. متغیرهایی که از قبل در محیط اجرا تعریف شده‌اند، با فراخوانی فعلی load_dotenv جایگزین نمی‌شوند. در نتیجه اگر کلید تازه داخل فایل ظاهراً اثر ندارد، متغیرهای محیط سرویس یا شل را هم بررسی کنید. فایل تنظیمات را وارد مخزن عمومی نکنید و دسترسی خواندن آن را محدود نگه دارید.

تهیه فایل imunify_ips.json از Imunify360

روی سروری که Imunify360 نصب است و با دسترسی لازم، دستور زیر را اجرا کنید تا فهرست محلی آی‌پی‌های بلاک و کپچا با قالب JSON نمایش داده شود:

imunify360-agent ip-list local list --purpose drop captcha --json

برای ذخیره خروجی در فایل ورودی اسکریپت، از داخل پوشه اسکریپت اجرا کنید:

imunify360-agent ip-list local list --purpose drop captcha --json > imunify_ips.json

گزینه --purpose drop captcha موارد بلاک و کپچا را انتخاب می‌کند و --json خروجی JSON می‌دهد. فایل ذخیره‌شده باید کنار imunify_to_arvan.py باشد؛ پیش از همگام‌سازی، موفقیت دستور و وجود آرایه items را بررسی کنید.

طبق مستندات رسمی CLI ایمونیفای، دستور list به‌صورت پیش‌فرض فقط ۱۰۰ مورد اول را برمی‌گرداند. برای فهرست بزرگ‌تر، مقدار --limit را متناسب با تعداد رکوردها افزایش دهید یا با --offset همه صفحه‌ها را دریافت و آرایه‌های items را ادغام کنید؛ فایل ناقص را به‌عنوان فهرست کامل همگام‌سازی استفاده نکنید.

ساختار ورودی و اولویت بلاک بر کپچا

فایل زیر را با نام imunify_ips.json کنار اسکریپت قرار دهید. آدرس‌ها صرفاً برای مستندسازی انتخاب شده‌اند:

{
  "items": [
    {"ip": "192.0.2.10", "scope": "local", "purpose": "drop"},
    {"ip": "192.0.2.11", "scope": "local", "purpose": "deny"},
    {"ip": "198.51.100.20", "scope": "local", "purpose": "captcha"},
    {"ip": "192.0.2.10", "scope": "local", "purpose": "captcha"},
    {"ip": "203.0.113.30", "scope": "local", "purpose": "white"}
  ]
}

فقط رکوردهای دارای scope: local بررسی می‌شوند. مقدارهای drop و deny به اکشن deny می‌روند و captcha به challenge تبدیل می‌شود. سایر مقدارها، از جمله white، کنار گذاشته می‌شوند؛ بنابراین وجود یک آی‌پی در فهرست سفید، در این برنامه قانون اجازه عبور ایجاد نمی‌کند.

در مثال بالا، آی‌پی 192.0.2.10 در هر دو گروه دیده می‌شود، اما خط groups["challenge"] -= groups["deny"] آن را از گروه چالش حذف می‌کند. نتیجه مورد انتظار دو آی‌پی در گروه بلاک و یک آی‌پی در گروه چالش است. استفاده از مجموعه‌ها نیز ورودی‌های تکراری را حذف می‌کند.

اعتبارسنجی با ip_address انجام می‌شود. مطابق مستندات رسمی پایتون، این تابع آدرس IPv4 یا IPv6 معتبر را می‌پذیرد و برای ورودی نامعتبر خطا می‌دهد. شبکه‌ای مانند 192.0.2.0/24 آدرس منفرد نیست و این اسکریپت CIDR را پشتیبانی نمی‌کند.

کد کامل اسکریپت imunify_to_arvan.py

نسخه زیر همان کد پروژه است. مقادیر حساس از محیط خوانده می‌شوند و هیچ کلید واقعی در آن قرار ندارد:

import json
import os
import re
from ipaddress import ip_address
from pathlib import Path
from dotenv import load_dotenv
import requests

load_dotenv(Path(__file__).resolve().with_name(".env"))

# تنظیمات
DOMAIN = os.environ.get("DOMAIN", "").strip()
ARVAN_API_KEY = os.environ.get("ARVAN_API_KEY", "").strip()
# API_BASE = f"https://cdn.arvanapis.ir/4.0/domains/{DOMAIN}/firewall/rules"
# API_BASE = f"https://api.cloud.arvan.ir/cdn/4.0/domains/{DOMAIN}/firewall/rules"
API_BASE = f"https://napi.arvancloud.ir/cdn/4.0/domains/{DOMAIN}/firewall/rules"

IPS_PER_RULE = 15
MAX_RULES = 25
MAX_FILTER_LENGTH = 250

RULE_NAMES = {"deny": "imunifyblock", "challenge": "imunifychallenge"}

def request_arvan(method, url, **kwargs):
    if not ARVAN_API_KEY:
        raise ValueError("Set ARVAN_API_KEY in .env before running the script")
    credential = ARVAN_API_KEY
    if not credential.lower().startswith(("apikey ", "bearer ")):
        credential = f"Bearer {credential}"
    response = requests.request(
        method, url,
        headers={
            "Authorization": credential,
            "Content-Type": "application/json",
            "Accept": "application/json",
        },
        timeout=30, allow_redirects=False, **kwargs
    )
    if not 200 <= response.status_code < 300:
        raise requests.HTTPError(
            f"Arvan {method} failed (HTTP {response.status_code}): {response.text}",
            response=response,
        )
    return response.json() if response.content else {}


def get_arvan_rules():
    rules = []
    page = 1
    while True:
        result = request_arvan("GET", API_BASE, params={"page": page, "per_page": 100})
        rules.extend(result["data"])
        if page >= result.get("meta", {}).get("last_page", 1):
            return rules
        page += 1


def delete_arvan_rule(rule_id):
    return request_arvan("DELETE", f"{API_BASE}/{rule_id}")




def build_rule_payload(ips, action):
    addresses = sorted({ip_address(ip) for ip in ips}, key=lambda ip: (ip.version, int(ip)))
    expression = "ip.src in {" + " ".join(str(ip) for ip in addresses) + "}"
    if not addresses:
        raise ValueError("Cannot build an empty IP rule")
    if len(expression) > MAX_FILTER_LENGTH:
        raise ValueError(f"Filter exceeds {MAX_FILTER_LENGTH} characters")
    payload = {
        "name": RULE_NAMES[action],
        "filter_expr": expression,
        "action": action,
        "is_enabled": bool(addresses),
        "note": "Synced from Imunify360",
    }
    if action == "challenge":
        payload["action_details"] = {"mode": 3, "ttl": 3600, "https_only": False}
    return payload


def is_legacy_rule(rule):
    name = rule.get("name", "")
    return (
        name.startswith(("I360_", "I360-"))
        or re.fullmatch(r"imunify(?:[0-9a-f]{8}|[0-9a-f]{32})", name) is not None
    ) and rule.get("note") == "Synced from Imunify360"


def is_managed_rule(rule):
    name = rule.get("name", "")
    return is_legacy_rule(rule) or any(
        name == prefix or re.fullmatch(re.escape(prefix) + r"[1-9][0-9]*", name)
        for prefix in RULE_NAMES.values()
    )


def build_payloads(groups):
    payloads = []
    for action, ips in groups.items():
        addresses = sorted({ip_address(ip) for ip in ips}, key=lambda ip: (ip.version, int(ip)))
        chunks = []
        chunk = []
        for address in addresses:
            candidate = chunk + [str(address)]
            expression = "ip.src in {" + " ".join(candidate) + "}"
            if chunk and (len(candidate) > IPS_PER_RULE or len(expression) > MAX_FILTER_LENGTH):
                chunks.append(chunk)
                chunk = []
            chunk.append(str(address))
        if chunk:
            chunks.append(chunk)
        for index, chunk in enumerate(chunks, 1):
            payload = build_rule_payload(chunk, action)
            payload["name"] = f"{RULE_NAMES[action]}{index}"
            payloads.append(payload)
    return payloads


def sync():
    with open(Path(__file__).resolve().with_name("imunify_ips.json"), encoding="utf-8") as f:
        imunify_data = json.load(f)["items"]

    groups = {"deny": set(), "challenge": set()}
    for item in imunify_data:
        if item.get("scope") != "local":
            continue
        purpose = item.get("purpose")
        if purpose in ("drop", "deny", "captcha"):
            action = "challenge" if purpose == "captcha" else "deny"
            groups[action].add(str(ip_address(item["ip"])))
    groups["challenge"] -= groups["deny"]
    payloads = build_payloads(groups)
    rules = get_arvan_rules()
    managed = [r for r in rules if is_managed_rule(r)]
    unmanaged_count = len(rules) - len(managed)
    if unmanaged_count + len(payloads) > MAX_RULES:
        raise ValueError(
            f"Need {len(payloads)} Imunify rules plus {unmanaged_count} other rules; "
            f"plan limit is {MAX_RULES}. No rules were changed."
        )
    # Reserve exact matches before reusing old rules for other chunks.
    assignments = []
    used = set()
    for payload in payloads:
        matches = [r for r in managed if r["name"] == payload["name"]]
        if len(matches) > 1:
            raise ValueError(f"Duplicate managed rule: {payload['name']}")
        rule = matches[0] if matches else None
        assignments.append([payload, rule])
        if rule:
            used.add(rule["id"])
    for assignment in assignments:
        payload, rule = assignment
        if rule is None:
            available = [r for r in managed if r["id"] not in used]
            rule = next((r for r in available if r.get("action") == payload["action"]),
                        available[0] if available else None)
            assignment[1] = rule
            if rule:
                used.add(rule["id"])
    for payload, rule in assignments:
        if rule:
            request_arvan("PATCH", f"{API_BASE}/{rule['id']}", json=payload)
            operation = "Updated"
        else:
            request_arvan("POST", API_BASE, json=payload)
            operation = "Created"
        print(f"{operation} {payload['name']}: {payload['filter_expr'].count(' ') - 1} IPs")
    # Remove surplus managed rules only after every desired chunk is saved.
    for rule in managed:
        if rule["id"] not in used:
            delete_arvan_rule(rule["id"])
            print(f"Removed old rule {rule['name']}")


if __name__ == "__main__":
    sync()

توضیح توابع و جریان همگام‌سازی

ارسال درخواست‌ها و خواندن قوانین

تابع request_arvan نقطه مشترک همه درخواست‌هاست. هدر احراز هویت و نوع محتوا را می‌سازد، مهلت ۳۰ ثانیه‌ای می‌گذارد و پاسخ خارج از بازه موفق HTTP را به خطا تبدیل می‌کند. دنبال‌کردن خودکار ریدایرکت خاموش است. اگر پاسخ بدنه داشته باشد، برنامه انتظار JSON دارد؛ پاسخ غیر JSON حتی با وضعیت موفق نیز می‌تواند خطای پردازش ایجاد کند.

تابع get_arvan_rules از صفحه اول شروع می‌کند و با استفاده از meta.last_page ادامه می‌دهد. این بخش به ساختار پاسخ API وابسته است. نشانی فعال در این نسخه روی میزبان napi.arvancloud.ir تنظیم شده؛ دو نشانی کامنت‌شده صرفاً در کد باقی مانده‌اند. برای تطبیق قرارداد درخواست با سرویس، به مرجع رسمی API آروان مراجعه کنید. نمایش پویا و جزئیات این مرجع در بررسی این مقاله قابل استخراج نبود؛ رفتار تشریح‌شده از کد پروژه است و تأیید مستقل همه فیلدهای API محسوب نمی‌شود.

تقسیم آی‌پی‌ها و ساخت شرط فایروال

تابع build_payloads آدرس‌ها را ابتدا بر اساس نسخه و سپس مقدار عددی مرتب می‌کند. هر دسته حداکثر ۱۵ عضو دارد، اما اگر طول عبارت از ۲۵۰ کاراکتر عبور کند، دسته زودتر بسته می‌شود. در نتیجه به‌خصوص برای IPv6 تعداد اعضای یک قانون ممکن است کمتر باشد. شرط تولیدشده چنین شکلی دارد:

ip.src in {192.0.2.10 192.0.2.11}

نام قوانین بلاک imunifyblock1 و شماره‌های بعدی است. گروه چالش نیز از imunifychallenge1 شروع می‌شود. برای چالش، کد action_details با مقدارهای mode: 3، ttl: 3600 و https_only: false می‌فرستد. این‌ها تنظیمات همین پروژه‌اند؛ تناسب آن‌ها با نیاز و قرارداد جاری سرویس را پیش از استفاده عملی بررسی کنید.

تشخیص قوانین متعلق به اسکریپت

قوانین با نام‌های دقیق imunifyblock، imunifychallenge و نسخه‌های دارای پسوند عددی مثبت تحت مدیریت برنامه قرار می‌گیرند. برای این نام‌ها وجود یادداشت بررسی نمی‌شود؛ بنابراین قانون دستی هم‌نام نیز ممکن است بازنویسی یا حذف شود. این نام‌ها را برای برنامه رزرو کنید.

قوانین قدیمی با پیشوندهای I360_ یا I360- و برخی نام‌های هش‌مانند فقط زمانی مدیریت می‌شوند که یادداشت آن‌ها دقیقاً Synced from Imunify360 باشد. این تفکیک، امکان بازاستفاده از قوانین نسخه‌های قبلی را فراهم می‌کند. قوانین دیگر در محاسبه ظرفیت شمرده می‌شوند، اما برنامه مستقیماً آن‌ها را ویرایش نمی‌کند.

تخصیص، ذخیره و حذف قانون‌های اضافه

ابتدا همه تطابق‌های دقیق نام رزرو می‌شوند. اگر برای یک نام موردنیاز چند قانون موجود باشد، برنامه پیش از عملیات نوشتن متوقف می‌شود. سپس دسته‌های بدون تطابق از قوانین آزاد قبلی استفاده می‌کنند و اکشن مشابه را ترجیح می‌دهند. قانون موجود با PATCH به‌روز می‌شود و برای قانون تازه POST ارسال می‌شود.

حذف قوانین اضافه در انتهای کار اتفاق می‌افتد؛ یعنی ابتدا باید همه دسته‌های مطلوب ذخیره شوند. با این حال فرایند تراکنشی نیست. اگر درخواست سوم شکست بخورد، دو تغییر موفق قبلی خودکار برگردانده نمی‌شوند. اجرای مجدد نیز الزاماً بدون درخواست نوشتن نیست، چون برنامه حتی برای قانون بدون تغییر هم PATCH می‌فرستد.

سقف قوانین و محدودیت‌های عملی

سه ثابت ابتدای فایل سیاست محلی را تعیین می‌کنند: IPS_PER_RULE=15، MAX_FILTER_LENGTH=250 و MAX_RULES=25. این عددها سقف تضمین‌شده همه پلن‌های آروان نیستند. تغییرشان در فایل نیز ظرفیت سرویس را افزایش نمی‌دهد. مقدار مناسب را با محدودیت حساب و پاسخ API خود هماهنگ کنید.

پیش از نوشتن، تعداد قوانین نهایی موردنیاز به‌علاوه قوانین خارج از مدیریت بررسی می‌شود. اگر حاصل بیشتر از سقف محلی باشد، اجرا بدون تغییر قانون متوقف می‌شود. یک ظرافت مهم وجود دارد: قوانین اضافه تا پایان نگه داشته می‌شوند؛ بنابراین هنگام ایجاد قوانین تازه، تعداد موقت قوانین می‌تواند از تعداد نهایی بیشتر باشد و سرویس درخواست را رد کند.

فایل ورودی باید تصویر کامل وضعیت مطلوب باشد. اگر items خالی شود، برنامه قوانین مدیریت‌شده را حذف می‌کند. اگر به اشتباه فقط بخشی از فهرست را وارد کنید، آی‌پی‌های حذف‌شده از ورودی ممکن است محافظت قبلی خود را در قوانین همین برنامه از دست بدهند. انقضای آی‌پی هم جداگانه خوانده نمی‌شود؛ به‌روزکردن فایل منبع برای حذف موارد منقضی ضروری است.

اجرا، بررسی خروجی و رفع خطا

پس از بررسی فایل ورودی و تنظیمات، برنامه را اجرا کنید:

/opt/imunify-arvan/venv/bin/python /opt/imunify-arvan/imunify_to_arvan.py

خروجی مورد انتظار برای مثال ورودی، بسته به وجود قوانین قبلی، ترکیبی از Created یا Updated است؛ مثلاً:

Created imunifyblock1: 2 IPs
Created imunifychallenge1: 1 IPs

این خروجی موفقیت درخواست‌ها را نشان می‌دهد. برای بررسی اثر واقعی، قوانین ثبت‌شده و ترافیک آزمایشی مجاز را در محیط خود کنترل کنید. ترتیب اجرای قوانین و سایر تنظیمات فایروال دامنه در این کد مدیریت نمی‌شوند و می‌توانند بر نتیجه نهایی اثر داشته باشند.

خطای نبود کلید از خالی‌بودن ARVAN_API_KEY می‌آید. خطای JSON یا آدرس نامعتبر به فایل ورودی مربوط است. پیام Need ... plan limit ... مربوط به سقف محلی است. برای خطای HTTP، کد وضعیت و بدنه پاسخ چاپ‌شده را بررسی کنید؛ ردشدن دسترسی، محدودیت پلن و ناسازگاری فیلدها علت‌های متفاوتی دارند. پاسخ خام را پیش از اشتراک‌گذاری از نظر اطلاعات حساس بازبینی کنید.

برای اجرای دوره‌ای، ابتدا تولید مطمئن فایل ورودی را تکمیل کنید. برنامه فعلی قفل هم‌زمانی، دریافت خودکار داده، حالت dry-run و تکرار خودکار درخواست شکست‌خورده ندارد. زمان‌بندی چند اجرای هم‌پوشان می‌تواند باعث رقابت در تغییر قوانین شود. در نسخه عملیاتی، فایل را پس از تکمیل تولید به‌صورت اتمی جایگزین کنید و تنها یک فرایند همگام‌سازی را در هر لحظه اجرا کنید.

جمع‌بندی

این اسکریپت برای تبدیل یک فهرست آماده از تصمیم‌های محلی Imunify360 به دو گروه بلاک و چالش در آروان طراحی شده است. نقطه شروع مناسب، آزمایش ورودی کوچک، تطبیق ظرفیت پلن و بررسی نام‌های رزروشده است. پس از آن، کیفیت داده ورودی و کنترل اجرای دوره‌ای مهم‌ترین بخش نگهداری اتصال خواهند بود.

اگر برای استقرار و نگهداری این اتصال به کمک نیاز دارید، از خدمات مدیریت سرور لینوکسی استفاده کنید. برای طراحی مسیر تولید داده، زمان‌بندی و رسیدگی به خطاها نیز پشتیبانی دواپس درنا دوپس مسیر مرتبطی برای بررسی نیاز پروژه است.