وثائق كتاب Sibuna 1.0.0-beta.3
اللغة: العربية
English简体中文한국어日本語EspañolDeutschहिन्दीالعربية
في هذه الصفحة

الجزء الحادي عشر: بطاقة مرجع سريع

أبقِ هذه البطاقة بجانب الطرفية: البناء، والتشغيل، والإعداد، والتوجيه، والمراقبة، والتشخيص. يضم الجزء العاشر الجداول الكاملة، وتضم هذه البطاقة ما يكتبه المشغل.

البناء

cargo build --release -p sibuna                          # ⁧البرنامج الخدمي + SQLite + وحدة التحكم⁩
cargo build --release -p sibuna --no-default-features    # ⁧في الذاكرة، بلا أي حزمة خارجية⁩
cargo build --release -p sibuna --features postgres-tls  # ⁧عناقيد PostgreSQL المشتركة⁩
rustup target add wasm32-unknown-unknown   # ⁧أو اضبط SIBUNA_POW_WASM / SIBUNA_CONSOLE_WASM⁩
cargo test            # ⁧اختبارات الوحدات والبرنامج الخدمي الحي والتخزين ووحدة التحكم⁩
cargo clippy --all-targets && cargo fmt --check
cargo xtask check     # ⁧فحص حدود 70 سطرًا / 1,408 سطرًا / 99 عمودًا⁩
cargo xtask browser   # ⁧فحوص Chromium بلا واجهة⁩
cargo xtask bench product   # ⁧المنتجات كاملة تحت wrk -> benchmarks/results/⁩
guidedog build        # ⁧هذا الكتاب (guidedog dsc: سجلات SID)⁩

التشغيل

# ⁧Shield (الافتراضي): PoW + WAF، مع التمرير إلى المنفذ 3000⁩
sibuna -p 8080 -u 3000 -s /etc/sibuna/secret
# ⁧Gate: إثبات العمل فقط⁩
sibuna --gate -p 8080 -u 3000 -s /etc/sibuna/secret
# ⁧forward auth خلف Nginx/Caddy (يثق بـ X-Forwarded-For)⁩
sibuna -m forward_auth --host 127.0.0.1 -p 8080 -s /etc/sibuna/secret
# ⁧Edge: سياسات دائمة وسمعة وأدلة جنائية في ⁦<dir>/sibuna.db⁩⁩
sibuna -D /var/lib/sibuna -s /etc/sibuna/secret
# ⁧JA4 من وكيل دخول موثوق (ترويسة Cloudflare؛ وحدة nginx: x-ja4؛ ATS: ja4)⁩
sibuna --ja4-header cf-ja4 --trust-forwarded -p 8080 -u 3000 -s /etc/sibuna/secret
# ⁧عضو في عنقود: PostgreSQL مشتركة ومعرّف عقدة فريد⁩
sibuna --database-url-file /etc/sibuna/database-url --cluster-node 1 -s /etc/sibuna/secret
head -c 32 /dev/urandom | xxd -p -c 64 > /etc/sibuna/secret

وحدة التحكم (معاينة تُفعَّل اختياريًا)

# ⁧هيّئ والبرنامج الخدمي متوقف، ثم شغّل وحدة التحكم⁩
sibuna init-admin admin --data-dir ./data
sibuna --data-dir ./data --console 127.0.0.1:19446

افتح http://127.0.0.1:19446/console/ واستبدل كلمة المرور المؤقتة. أضف --console-location 1.3521,103.8198 لوضع العقدة على الكرة الأرضية. يتطلب الوصول البعيد وكيل HTTPS، ومصدرًا (origin) صريحًا، ونطاقات CIDR للوكلاء الموثوقين؛ اتبع الجزء التاسع. حالة SID 0007 هي Committed. تجتاز وحدة التحكم مسارات عملها في المتصفح على Chromium بلا واجهة (SID 0010، المعيار 5)؛ أما شرطها الرسمي لعزل الأداء فلم يُحسم بعد (الجزء الثامن).

الخيارات الأهم أولًا

الخيار الافتراضي المعنى
-d, --difficulty 16 بتات العمل (عمق PoSW = البتات - 3)
-a, --algorithm posw posw أو hashcash
--posw-challenges 16 عدد عمليات الفتح لكل إثبات
--token-ttl 86400 مدة الجلسة بالثواني
--challenge-ttl 300 مدة التحدي بالثواني
--token-scheme mac mac أو ed25519
--rate-limit / --rate-window 100 / 10 دفعة GCRA لكل نافذة
--ban-seconds 3600 حظر المصيدة
-w, --workers عدد وحدات CPU خيوط قبول الاتصالات
--max-connections 1024 ثم 503
--max-connections-per-ip 64 لكل عنوان نظير (في IPv6: لكل --ipv6-prefix)، ثم 503
--trusted-hops 1 العميل = العنصر رقم n في X-Forwarded-For من اليمين
--ja4-header معطل ترويسة تحمل بصمة JA4 من وكيل الدخول؛ ولا تُقرأ إلا عند الوثوق بالترويسات الممررة
--idle-timeout 15 مهلة جامع الاتصالات الخاملة بالثواني
-P, --policy-file لا شيء سياسة JSON
--trust-forwarded معطل مفعّل في وضع forward auth
--secure-cookie معطل يضيف Secure

نقاط النهاية تحت /__sibuna/

المسار الرد
challenge الصفحة الوسيطة بصيغة HTML
challenge.json?need=&path= {id, algorithm, difficulty, challenges, expires_at}
verify (POST) {challenge_id, nonce | proof} -> 200 + Set-Cookie، وإلا 400
wasm/sibuna-pow.wasm برنامج حل بحجم 15,181 بايت
worker.js عامل يضم مُبرهِنَي WASM وJS
honeypot يحظر المستدعي، 403؛ و404 لمورد فرعي أو جلب عبر المواقع
health {"status":"ok",...}
metrics نص Prometheus

وجّه هذه المسارات كلها إلى البرنامج الخدمي، ولا توجهها أبدًا إلى الخادم الأصلي.

رموز الحالة

الرمز متى
200 مقبول (forward auth)، والصفحة الوسيطة، والمسارات الداخلية
400 طلب أو هدف (target) مشوّه، أو حل مرفوض (مع جسم تشخيصي)
401 مطلوب تحدٍّ: عميل لا يقبل HTML، أو وضع forward auth
403 رفض من السياسة أو WAF، أو حظر، أو المصيدة
404 مسار /__sibuna/ غير معروف، أو طلب مصيدة مرفوض
413 جسم الحل أكبر من المخزن المؤقت البالغ 64 KB
414 عنوان URL المُبلَّغ عنه للتحدي أطول من 8 KiB
417 توقُّع (Expect) غير مدعوم في الطلب
429 حد GCRA، مع Retry-After بالثواني
431 رأس الطلب أكبر من 16 KB
501 ترميز نقل غير chunked
502 الخادم الأصلي غير قابل للوصول أو استجابته مشوهة
503 بلوغ حدود الاتصالات، أو العقدة قيد التصريف

الترويسات

  • نحو الخادم الأصلي (الوكيل): X-Forwarded-For (نظير المقبس، بعد السلسلة المستلمة عندما تكون موثوقة)، وX-Forwarded-Proto، وX-Real-IP (العميل الذي بُني عليه القرار)، وX-Sibuna-Status: PASS، وX-Sibuna-Rule: <rule>؛ وتُحذف ترويسات hop-by-hop وحقول التمرير البديلة، وكذلك صيغها المكتوبة بشرطة سفلية.
  • رد forward auth: X-Sibuna-Status، وX-Sibuna-Rule، وX-Sibuna-Rule-Hash.
  • رد التحدي: X-Sibuna-Status: CHALLENGE.
  • ملف تعريف الارتباط: __sibuna_token=<75 chars, 139 with ed25519>; Path=/; Max-Age=<ttl>; HttpOnly; SameSite=Lax[; Secure]

هيكل ملف السياسة

{ "default_action": "CHALLENGE", "waf": true,
  "thresholds": {"challenge_at": 10, "deny_at": 40, "bits_step": 5},
  "ip_rules": {"10.0.0.0/8": "ALLOW", "2001:db8::/32": "DENY"},
  "rules": [
    {"name": "api", "path": "/api/*", "headers": {"X-Api-Key": ".*"}, "action": "ALLOW"},
    {"name": "checkout", "path": "/checkout/*", "action": "CHALLENGE",
     "challenge": {"difficulty": 20, "algorithm": "posw"}},
    {"name": "login", "path": "^/login$", "action": "CHALLENGE",
     "limits": {"rate": 10, "window_seconds": 60, "ban_seconds": 600}},
    {"name": "old-tls", "ja4": "t12*", "action": "CHALLENGE"},
    {"name": "headless", "user_agent": "Headless", "action": "WEIGH", "weight": 30} ] }

JA4: بصمة كاملة، أو بادئة مع *؛ لا بصمة، لا مطابقة. الأنماط: * أو .* لأي قيمة؛ ^...$ للتطابق التام؛ * في النهاية لبادئة؛ / في البداية لمسار تام؛ وإلا فسلسلة فرعية دون تمييز حالة الأحرف. تُطابق المسارات في صيغتها المُطبَّعة. الترتيب: WAF -> رفض/سماح الشجرة -> القواعد -> الدرجة -> التجاوز -> تحدي الشجرة -> الروبوتات -> الافتراضي.

التخزين (Edge) بلغة SQL

INSERT INTO policies (id, name, priority, path_pattern, action, difficulty, algorithm,
  header_matchers, cidr_matchers, weight, enabled, created_at, updated_at)
  VALUES ('p1', 'protect', 10, '/checkout/*', 'challenge', 20, 'posw', '{}', '[]', 0, 1,
  unixepoch(), unixepoch());
INSERT INTO ip_reputation (ip_or_cidr, reputation_score, banned_until, trigger_rule, hits, last_seen)
  VALUES ('198.51.100.7', -100, unixepoch() + 86400, 'analyst', 1, unixepoch());
SELECT s.client_ip, s.violation_category, s.path, s.campaign_id
  FROM incidents_fts f JOIN security_incidents s ON s.id = f.rowid
  WHERE incidents_fts MATCH 'union' ORDER BY rank LIMIT 20;

SQLite (sqlite3 <dir>/sibuna.db)؛ تُكتب الإجراءات بأحرف صغيرة. الدرجة \(\le -50\) -> بادئة رفض؛ و\(\ge 50\) -> سماح. العنقود: السر نفسه على كل عقدة، وقاعدة بيانات PostgreSQL واحدة، و--features postgres-tls، و--database-url-file <file> --cluster-node N مع قيمة N فريدة من 1 إلى 8,388,607؛ بلا قائمة أعضاء، ولا قائد، ولا TLS للعنقود (SID 0011).

التشخيصات

العنوان المعنى
MALFORMED CHALLENGE عُدّل المعرف أو اقتُطع؛ اجلب معرفًا جديدًا
INVALID CHALLENGE TAG لم يصدر عن هذه البذرة أو هذه العقدة
CHALLENGE EXPIRED أقدم من TTL أو انحراف الساعة > 60 s
CLIENT FINGERPRINT MISMATCH تغير العنوان أو User-Agent
DIFFICULTY NOT MET لا تحقق القيمة المؤقتة عدد البتات الصفرية المطلوب
INVALID PROOF OF SEQUENTIAL WORK لا تصل عمليات الفتح إلى الجذر
WRONG SOLUTION TYPE قيمة مؤقتة لـ PoSW أو إثبات لـ Hashcash
DOUBLE SPEND PREVENTED استُخدم التحدي من قبل
STORE FULL امتلأت مجموعة الحلول المُنفَقة؛ اخفض TTL أو ارفع --spent-tags
NETWORK BINDING MISMATCH نُسخ ملف تعريف الارتباط إلى عميل آخر
INVALID COMMAND LINE خيار غير معروف، أو قيمة خاطئة، أو خيار من خيارات Zaxonlite المُزالة

المقاييس التي ينبغي التنبيه عليها: denied، وrate_limited، وoverloaded، وupstream_errors، وincidents_dropped، وincident_write_failures، وbans_refused، وforwarded_invalid (كلها بصيغة sibuna_*_total).

أرقام جديرة بالحفظ

معرف التحدي 70 محرفًا (حمولة 36 بايت + وسم 16 بايت)؛ الرمز 75 محرفًا (40 + 16)، و139 مع Ed25519؛ بايتات الإثبات \(32(1 + t(n+1))\)؛ عمق PoSW = البتات - 3، ضمن المدى 4 إلى 24؛ مخزن الطلب المؤقت 64 KB؛ حد الرأس 16 KB؛ الجزء المفحوص من الجسم 8 KB؛ مجموعة الحلول المُنفَقة 1,048,576 وسمًا (--spent-tags)؛ خلايا المعدل 262,144 لكل جدول (--rate-table-cells)؛ الحظر 65,536 موضعًا (--ban-table-slots)؛ 64 اتصالًا لكل عنوان عميل؛ حلقة الحوادث 512؛ الدفعة 32؛ مسافة الحملة 0.35 على أحدث 16,384 تضمينًا؛ keep-alive حتى 4,096 طلبًا لكل اتصال؛ مجمّع اتصالات الخادم الأصلي 256 مقبسًا؛ طابور مهام التخزين 32.

توجيه وكيل الدخول

استخدم وصفة Nginx أو Caddy في الجزء التاسع، Forward Auth خلف وكيل دخول. وجّه /__sibuna/* مباشرة؛ وقرّر الإذن لطلبات التطبيق بناءً على عنوان URI الأصلي، والطريقة، وعنوان العميل الموثوق. استبدل ترويسات تدقيق Sibuna الواردة بنتيجة التفويض. يحتاج Nginx إلى معالجة صريحة للتحدي، وللحالة 429، ولتعذر خدمة المصادقة.

ينقل reverse_proxy أجسام HTTP/1.1 المقبولة واتصالات WebSocket؛ أما forward_auth فيمنح القبول وينقلها وكيل الدخول. ولا يستطيع Sibuna فحص الأجسام التي لا تصله في طلب المصادقة، ولا استجابات الخادم الأصلي، ولا عدّها. ينتهي TLS عند وكيل الدخول؛ ودعم HTTP/2 الأصلي مؤجل. تستخدم عمليات الرفع Content-Length أو الترميز المجزأ (chunked)؛ ولا يرى الفحص إلا بادئة 8 KiB على الأكثر، ولا تُفسَّر بايتات الملفات.