Network Sandbox Engine (NSE)

محرك Linux لاختبار جدار حماية nftables بشكل حتمي داخل فضاءات أسماء شبكة معزولة.

لماذا NSE؟ • الميزات • المتطلبات • التثبيت • البدء السريع • كيف يعمل • هيكل المشروع

لماذا NSE؟

اختبار مجموعات قواعد جدار الحماية على نظام Linux حي يحمل مخاطر كبيرة: القواعد المشوهة قد تُسقط جلسات إدارة SSH، أو تُسرّب حركة نصية واضحة أثناء الاختبار، أو تترك جداول جدار حماية يتيمة نشطة على المضيف.

يوفر Network Sandbox Engine (NSE) بيئة اختبار آمنة وقابلة للتكرار. فهو يبني فضاءات أسماء شبكة Linux مؤقتة، ويوصل أزواج إيثرنت افتراضية، ويُجمّع مجموعات قواعد nftables، ويحقن حزمًا اصطناعية من الطبقة الثانية والثالثة باستخدام Scapy. تحدث كل عملية تقييم داخل فضاء اسم العزل: لا يتم تغيير حالة جدار الحماية على المضيف أبدًا.

الخصائص المعمارية الرئيسية:

• صفر تعديل على المضيف: يتم تحميل مجموعات القواعد حصريًا في فضاءات أسماء عزل مؤقتة (nse_<uuid>) وتُزال بالكامل أثناء التفكيك.
• أوراكل ذاتي التحقق: كل تشغيل يحقن حزمة canary قبل حزم الاختبار ومرة أخرى بعدها، ولا يُبلّغ عن نتيجة إلا إذا تمت ملاحظة أثر النواة لكليهما. راجع عقد الأوراكل.
• مكدس مزدوج وطوبولوجيات: دعم أصلي لحركة IPv4 وIPv6، بالإضافة إلى طوبولوجيات Gateway متعددة فضاءات الأسماء للتحقق من قواعد التوجيه وNAT والتمرير.
• سطح صغير وقابل للتدقيق: حزمة واحدة، لا خادم ويب، لا JavaScript. يبلغ حجم nse/ حوالي 1150 عبارة بتغطية اختبار 98%.

يتطلب صلاحيات الجذر

ينشئ NSE فضاءات أسماء شبكة، ويحمّل مجموعات قواعد nftables، ويقرأ أحداث تتبع النواة، لذا يعمل بصلاحيات الجذر. وهو لا يفتح مقبسًا ولا منفذًا ولا نقطة نهاية RPC من أي نوع — إنه مكتبة وواجهة سطر أوامر تستدعيها أنت، ولا يحتفظ بالصلاحيات إلا طوال مدة التشغيل.

أزالت الإصدارات 2.1.0 واجهة الويب FastAPI/Svelte التي كانت تُشحن مع الإصدارات السابقة. كانت تلك الواجهة تعمل داخل العملية بصلاحيات الجذر بدءًا من الإصدار 2.0.0، وهو ما شكّل سطح هجوم كبير لأداة اختبار؛ لا يزال الكود موجودًا في سجل git عند الوسم v2.0.0 إذا كنت بحاجة إليه.

عقد الأوراكل

اختبار جدار الحماية هو تأكيد سلبي — "هذه الحزمة لم تمر" — والتأكيد السلبي لا قيمة له ما لم يكن من المعروف أن الأداة تعمل. فمراقب التتبع الذي لم يتصل بالنواة أبدًا وجدار حماية حجب كل شيء ينتجان مخرجات متطابقة بايتًا ببايت.

لذلك يرفض NSE الإبلاغ عن حكم لا يستطيع إثبات أنه قاسه:

تُستبعد حزم canary من النتائج بواسطة معرّف التتبع، لذا لا تظهر أبدًا في تدفق أحكامك.

تُثبت مجموعة الاختبارات أن هذا صحيح، بدلًا من مجرد تأكيده: يُجبر make test-blind المحلل على عدم فهم أي شيء، ويفشل البناء ما لم يخرج المشغّل بقيمة غير صفرية. تعمل تلك المهمة في CI عند كل دفعة.

الميزات

• محرك داخل العملية: واجهة Python مباشرة (run_test_pipeline) تُرجع نماذج Pydantic منظمة (TestRequest، TraceEvent).
• حقن حزم Scapy: تزوير حزم TCP عشوائية (مع أعلام SYN وACK وFIN وRST مخصصة)، وUDP، وICMP، وICMPv6.
• طوبولوجيات معزولة:
  • Simple: فضاء اسم عزل واحد (nse_<id>) موصول مباشرة بالمضيف.
  • Gateway: سلسلة Router (nse_router_<id>) وServer (nse_server_<id>) لاختبار التمرير وNAT.
• تنظيف تلقائي: تكشف عمليات المسح عند بدء التشغيل عن فضاءات الأسماء وأزواج veth المتبقية من التشغيلات المُجهضة السابقة وتزيلها. تتضمن عمليات التفكيك إعادة محاولات بتراجع أسي.
• مشغّل اختبارات YAML عبر CLI: تنفيذ مجموعات اختبار YAML تصريحية لخطوط أنابيب CI/CD الآلية (nse-runner). يخرج بقيمة غير صفرية عند حكم خاطئ وعند حكم فشل في ملاحظته.
• معايير جودة صارمة: فحص أنواع ثابت كامل (mypy --strict)، وفرض حدود معمارية (import-linter)، وتنسيق ruff، ومسنّنة تغطية (، الحد الأدنى 98%).

المتطلبات

• نظام Linux (نواة 5.4 أو أحدث مع دعم فضاءات أسماء الشبكة وnftables)
• Python 3.10+
• nftables (nft)
• iproute2 (ip)
• صلاحيات الجذر (مطلوبة لـ ip netns وعمليات تتبع النواة)

على أنظمة Debian أو Ubuntu:

sudo apt update && sudo apt install -y nftables iproute2 conntrack

التثبيت

1. حزمة PyPI (موصى بها)

ثبّت المحرك الأساسي مع دعم CLI:

pip install "network-sandbox-engine[cli]"

2. تثبيت يدوي من المصدر

للتطوير المحلي:

git clone https://github.com/onyks-os/NetworkSandboxEngine.git
cd NetworkSandboxEngine
make setup

البدء السريع

1. مكتبة Python بدون واجهة

import asyncio
from nse.core.netns_controller import NetnsController
from nse.core.pipeline import run_test_pipeline
from nse.models.test_request import TestRequest, PacketSpec

rules = """
table ip filter {
    chain input {
        type filter hook input priority 0; policy drop;
        tcp dport 80 accept
    }
}
"""

request = TestRequest(
    rules=rules,
    packets=[
        PacketSpec(protocol="tcp", src_ip="10.0.0.1", dst_ip="10.0.0.2", dst_port=80),
        PacketSpec(protocol="tcp", src_ip="10.0.0.1", dst_ip="10.0.0.2", dst_port=22),
    ],
)


async def main():
    controller = NetnsController()
    events = await run_test_pipeline(request=request, controller=controller)
    for evt in events:
        if evt.verdict:
            print(f"[{evt.chain}] Verdict: {evt.verdict}")


asyncio.run(main())

2. مشغّل مجموعة اختبارات YAML (CLI)

أنشئ ملف اختبار firewall_test.yaml:

tests:
  - name: "Allow HTTP Port 80, Drop SSH Port 22"
    topology: simple
    rules: |
      table ip filter {
        chain input {
          type filter hook input priority 0; policy drop;
          tcp dport 80 accept
        }
      }
    packets:
      - protocol: tcp
        src_ip: 10.0.0.1
        dst_ip: 10.0.0.2
        dst_port: 80
        expected_verdict: ACCEPT
      - protocol: tcp
        src_ip: 10.0.0.1
        dst_ip: 10.0.0.2
        dst_port: 22
        expected_verdict: DROP

expected_verdict لكل حزمة. تُرفض المفاتيح غير المعروفة بدلًا من استخدام قيم افتراضية، لذا يفشل خطأ إملائي في المجموعة بدلًا من أن يصبح بصمت توقعًا لم تكتبه أبدًا.

شغّل المجموعة بصلاحيات الجذر:

sudo nse-runner --file firewall_test.yaml

رموز الخروج: 0 طابقت كل الحزم؛ 1 كان حكم خاطئًا أو لم يتمكن المحرك من ملاحظة حكم. تُبلّغ أخطاء الأوراكل بشكل منفصل عن إخفاقات جدار الحماية، لأنها تعني أن القياس تعطّل، وليس مجموعة القواعد.

3. داخل حاوية

podman build -t nse .
podman run --rm --cap-add=NET_ADMIN --cap-add=NET_RAW \
    -v "$PWD/firewall_test.yaml:/suite.yaml:ro" nse --file /suite.yaml

مفيد لتثبيت إصدار nftables الذي تُختبر قواعدك مقابله.

كيف يعمل

ينسّق NSE أنظمة شبكة نواة Linux وواجهات التتبع عبر خط أنابيب تنفيذ منظم متعدد المراحل:

graph TD
    subgraph Step1["1. Test Specification"]
        Req["<b>TestRequest</b><br/>ruleset + packets + topology"]
    end

    subgraph Step2["2. Ephemeral Netns Sandbox"]
        direction TB
        Netns["<b>Netns Setup</b><br/>nse_&lt;id&gt; & veth links"]
        RuleEng["<b>Rule Engine</b><br/>validate & load nftables"]
        Inject["<b>Scapy Injector</b><br/>L2/L3 packet injection"]
        NFT["<b>Kernel nftables</b><br/>meta nftrace set 1"]

        Netns --> RuleEng
        RuleEng --> Inject
        Inject --> NFT
    end

    subgraph Step3["3. Trace Evaluation & Oracle"]
        direction TB
        Harvester["<b>Trace Harvester</b><br/>nft monitor trace stream"]
        Oracle["<b>Deterministic Oracle</b><br/>TraceEvents & verdicts"]

        Harvester --> Oracle
    end

    Step1 --> Step2
    Step2 --> Step3

1. التحقق من مجموعة القواعد: يُجري RuleEngine.validate() تشغيلًا تجريبيًا لمجموعة القواعد باستخدام nft --check -f.
2. تهيئة العزل: ينشئ NetnsController فضاء اسم الشبكة المعزول ويهيّئ واجهات إيثرنت الافتراضية (veth).
3. تهيئة التتبع: تُحمّل مجموعات القواعد في فضاء الاسم مع تسليح تتبع النواة (meta nftrace set 1).
4. حقن الحزم: يحقن ScapyInjector إطارات اصطناعية عبر وصلة veth.
5. حصاد الأحكام: يلتقط TraceHarvester أحداث nft monitor trace ويُرجع كائنات TraceEvent منظمة.
6. التفكيك: يُحذف فضاء الاسم وجميع واجهات veth المرتبطة به تلقائيًا.

للاطلاع على المواصفات التقنية الكاملة، راجع دليل المعمارية التقنية.

هيكل المشروع

NetworkSandboxEngine/
├── nse/                        # Core PyPI package (network-sandbox-engine)
│   ├── core/                   # Kernel primitives, pipeline, and naming rules
│   ├── models/                 # Pydantic models (TestRequest, PacketSpec, TraceEvent)
│   └── cli/                    # Headless YAML runner entrypoint
├── docs/                       # Architecture specs and MkDocs web documentation
├── tests/                      # Unit, golden file, and privileged e2e tests
│   └── fixtures/nft_trace/     # Golden `nft monitor trace` corpus
├── pyproject.toml              # Build backend configuration
└── Makefile                    # Local automation and CI workflow

الإصدار

وسم واحد. git push origin vX.Y.Z يبني، ويوقّع باستخدام Sigstore، وينشر إصدار GitHub، ويرفع إلى TestPyPI، ويثبّت من TestPyPI ويُجري اختبارًا سريعًا عليه، وعندها فقط يرفع إلى PyPI. تدرّب باستخدام make release-dry.

راجع docs/RELEASING.md.

التوثيق

التوثيق التفاعلي الكامل متاح على الويب على:
https://onyks-os.github.io/nse/

ابنِ التوثيق محليًا:

make docs

قدّم التوثيق مع إعادة التحميل الفوري على http://127.0.0.1:8000:

make docs-serve

الاختبار وCI المحلي

شغّل الفحص الثابت واختبارات الوحدة:

make verify

شغّل تحقق CI المحلي الكامل (يتضمن الفحص، واختبارات الوحدة، وبناء الواجهة الأمامية، وبناء التوثيق، واختبار PyPI السريع، واختبارات التكامل ذات الصلاحيات):

make ci-local

الترخيص

هذا المشروع مرخّص بموجب MIT License.