الجزء الحادي عشر: بطاقة مرجع سريع¶
أبقِ هذه البطاقة بجانب الطرفية: البناء، والتشغيل، والإعداد، والتوجيه، والمراقبة، والتشخيص. يضم الجزء العاشر الجداول الكاملة، وتضم هذه البطاقة ما يكتبه المشغل.
البناء¶
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 على الأكثر، ولا تُفسَّر بايتات الملفات.