الجزء العاشر: المرجع التفصيلي والتشخيص¶
نقاط النهاية، والمقاييس، وفهرس الأخطاء، ومخطط السياسة، وجداول التخزين في مكان واحد.
نقاط النهاية¶
| نقطة النهاية | الطريقة | الوظيفة |
|---|---|---|
/__sibuna/challenge |
GET | الصفحة الوسيطة |
/__sibuna/challenge.json?need=&path= |
GET | يصدر تحديًا عديم الحالة: تحدده تذكرة المتطلبات الواردة في استجابة التحدي، وإلا يُقيَّم عنوان URL المُبلَّغ عنه في صيغته المُطبَّعة (414 إذا تجاوز 8 KiB، و400 لمسار ليست له صيغة مُطبَّعة). يعيد {id, algorithm, difficulty, challenges, expires_at} |
/__sibuna/verify |
POST | يقبل {"challenge_id", "nonce"} أو {"challenge_id", "proof"}؛ ويعيد 200 مع Set-Cookie، أو 400 مع تشخيص، أو 413 لجسم أكبر من مخزن الاتصال المؤقت |
/__sibuna/wasm/sibuna-pow.wasm |
GET | وحدة برنامج الحل، بحجم 14,744 بايت (wasm_bytes في benchmarks/results/primitives-latest.json)، قابلة للتخزين المؤقت ساعة واحدة |
/__sibuna/worker.js |
GET | Web Worker يضم مُبرهِنَي WASM وJavaScript، قابل للتخزين المؤقت ساعة واحدة |
/__sibuna/honeypot |
GET | يحظر المستدعي مدة --ban-seconds ويسجل حادثًا؛ 403. لا يحظر إلا طلب المستوى الأعلى (بلا Sec-Fetch-Dest أو بقيمة document، وبلا Sec-Fetch-Site عابر للمواقع)؛ ويُجاب أي طلب آخر بـ 404 ويُحتسب |
/__sibuna/health |
GET | حالة الحيوية بصيغة JSON مع اسم المحرك، والإصدار، ووضع الوكيل، وخوارزمية الإثبات |
/__sibuna/metrics |
GET | تنسيق نص Prometheus (الإصدار 0.0.4) |
يُجاب أي مسار آخر تحت /__sibuna/ بـ 404. يستهلك الإصدار والتحقق ميزانية --challenge-rate-limit المستقلة، ويُرفض العنوان المحظور بـ 403 على كل مسار. تحمل استجابات التحدي X-Sibuna-Status: CHALLENGE؛ وتحمل الطلبات المقبولة X-Sibuna-Status: PASS وX-Sibuna-Rule نحو الخادم الأصلي (وX-Sibuna-Rule-Hash، بالنظام الست عشري، في ردود forward-auth). يتلقى العميل الذي لا يقبل HTML الحالة 401 مع {"error":"challenge_required","challenge":"/__sibuna/challenge.json?need=<ticket>"}.
يقدم مستمع الإدارة الاختياري المستقل /console/. هيّئ حساب مسؤوله محليًا بالأمر sibuna init-admin، ثم استبدل كلمة المرور المؤقتة عند أول تسجيل دخول. يتطلب /console/api/stats و/console/ws جلسة موثقة (بما فيها جلسة الكشك). يدمج اتصال WebSocket الإحصاءات والأحداث والعقد والسياسة والتحديات والتدقيق في قناة واحدة، مع لقطات محدودة وفروق واستعادة للفجوات. يتصل نظراء الإدارة بـ /console/peer، وتقع كل مسارات API تحت /console/api/. لا تُرصد عدادات أخطاء الخادم الأصلي في وضع forward-auth. يوثق الجزء التاسع مسارات عمل وحدة التحكم، ونشرها عبر HTTPS، والحدود الحالية لـ SID 0007.
المقاييس¶
عدادات معروضة بالصيغة sibuna_<name>_total بتنسيق نص Prometheus، بهذا الترتيب:
| العداد | يزداد عندما |
|---|---|
incidents_persisted، incident_batches |
السجلات والمعاملات التي أكد خيط التخزين تثبيتها |
incidents_dropped، incident_write_failures |
إضافات إلى الطابور رُفضت لامتلاء الحلقة، ومحاولات تثبيت فاشلة |
requests |
وصل طلب مُحلَّل إلى مرحلة التوجيه (بما في ذلك المسارات المحجوزة) |
allowed، denied، challenged |
اتُخذ قرار سياسة (قبول، أو رفض، أو إصدار تحدٍّ أو إعادة إصداره) |
challenges_issued |
أنشأ /__sibuna/challenge.json سجل تحدٍّ |
solutions_accepted، solutions_rejected |
قبل /__sibuna/verify إثباتًا أو رفضه |
rate_limited |
رفض GCRA طلبًا (429): حد الطلبات، أو ميزانية التحديات، أو حصة قاعدة |
banned |
رُفض عنوان محظور، أو حظرت المصيدة عنوانًا |
bans_issued |
سُجّل حظر (من المصيدة، أو حظرٌ تفرضه حصة قاعدة) |
proxied، upstream_errors |
مُرر طلب إلى الخادم الأصلي، أو فشل الخادم الأصلي (502) |
parse_errors |
رُفض رأس مشوه، أو Host مكرر، أو هدف ليست له صيغة مُطبَّعة (400)، أو ترميز نقل غير مدعوم (501) |
overloaded |
أُجيب اتصال يتجاوز --max-connections أو --max-connections-per-ip بـ 503 |
bans_refused |
لم يُسجل حظر لأن كل موضع يمكن أن يأخذه مفتاحه كان يحمل حظرًا ساريًا |
forwarded_invalid |
تعذر تحليل عنوان عميل ممرر موثوق؛ فحُكم على الطلب بعنوان نظير المقبس |
honeypot_refused |
لم يحظر طلبُ المصيدة أحدًا، لأن الذي طلبها صفحة لا شخص |
rate_evictions |
أزاح وصولٌ إلى محدد المعدل خليةَ عميل نشط آخر |
ja4_present |
مع --ja4-header والتمرير الموثوق، حمل الطلب ترويسة واحدة بالضبط بذلك الاسم تحتوي على بصمة JA4 |
ja4_invalid |
مع --ja4-header والتمرير الموثوق، كانت الترويسة مشوهة أو مكررة؛ فحُكم على الطلب دون بصمة |
قد تزيد إعادة المحاولة incident_write_failures دون فقد سجلات، لأن الدفعة المعلقة تُستبقى. راقب الزيادات خلال فترة؛ فالمجاميع وحدها ليست عمق الطابور.
رموز الحالة¶
| الرمز | متى |
|---|---|
| 200 | مقبول (forward-auth)، والصفحة الوسيطة (تصفّح HTML يحتاج إلى تحدٍّ)، والمسارات الداخلية |
| 302 | لا يستخدمه البروتوكول الحالي؛ يجيب التحقق بـ 200 وتعيد الصفحة التحميل |
| 400 | طلب مشوه، أو حقل Host مكرر، أو هدف ليست له صيغة مُطبَّعة، أو بيانات تمرير وصفية غير صالحة، أو جسم مشوه، أو حل مرفوض مع تشخيص بأسلوب Elm |
| 401 | مطلوب تحدٍّ لعميل لا يقبل HTML، أو في وضع forward-auth |
| 403 | رفض من السياسة أو WAF، أو عنوان محظور، أو المصيدة |
| 404 | مسار غير معروف تحت /__sibuna/، أو طلب مصيدة ليس طلبًا من المستوى الأعلى |
| 413 | جسم الحل أكبر من مخزن الاتصال المؤقت البالغ 64 KB |
| 414 | عنوان URL المُبلَّغ عنه للتحدي أطول من 8 KiB |
| 417 | توقُّع (Expect) غير مدعوم في الطلب؛ ويُعالَج 100-continue محليًا |
| 429 | تجاوز حد GCRA؛ Retry-After بالثواني |
| 431 | رأس الطلب أكبر من 16 KB |
| 501 | Transfer-Encoding بترميز غير chunked |
| 502 | الخادم الأصلي غير قابل للوصول، أو كان رأس استجابته مشوهًا أو أكبر من 16 KB |
| 503 | بلوغ حد الاتصالات (--max-connections أو --max-connections-per-ip)، أو العقدة قيد التصريف؛ ويُغلق المقبس بعد الرد |
فهرس الأخطاء¶
يوقف INVALID COMMAND LINE بدء التشغيل عند أي خيار لا يعرفه البرنامج الخدمي، وأي قيمة خارج مداها الموثق، وأي اختيار وضع غير صالح أو غائب أو مكرر. تذكر كتلة الخطأ الخيار، والقيمة المعطاة، والمدى المتوقع، والخطأ (UnknownOption، وMissingValue، وInvalidValue، وInvalidMode، وMissingMode، وDuplicateMode، وRemovedOption لخيار عنقود Zaxonlite، وConflictingOptions لخياري تخزين يستبعد أحدهما الآخر، وMissingOption لعنوان URL لقاعدة بيانات بلا --cluster-node)، وتنتهي بتلميح. يُعرض عنوان URL لقاعدة البيانات بالصيغة [redacted]. حدّد --mode reverse_proxy أو --mode forward_auth مرة واحدة؛ والخيار القصير المكافئ هو -m. يطبع ملف السياسة المرفوض كتلة عنوانها اسم خطئه (مثل INVALID POLICY ACTION) مع الملف، واسم الخطأ، والقاعدة، والحقل، والقيمة. ونمط ja4 الذي لا يمكن أن تطابقه أي بصمة يطبع INVALID POLICY JA4 (InvalidJa4)؛ ويُرفض مستند إدارة وحدة التحكم الذي يحوي مثل هذا النمط بالخطأ نفسه. تُفحص خيارات وحدة التحكم على حدة: يسمي CONSOLE002 خيار وحدة تحكم مشوهًا أو مكررًا، ويسمي CONSOLE001 إعداد وحدة تحكم يخالف قاعدة (StorageRequired بلا تخزين).
| الخطأ | السبب | تلميح |
|---|---|---|
MalformedChallenge |
المعرف ليس سجل تحدٍّ سليم البنية | اجلب تحديًا جديدًا وقدمه دون تغيير |
InvalidChallengeTag |
الوسم لا يجتاز المصادقة؛ لم يصدره هذا العنقود، أو عُدّل | لا يمكن تزوير التحديات؛ اطلب تحديًا جديدًا |
ChallengeExpired |
أقدم من TTL التحدي، أو يحمل وقت إصدار في المستقبل | اطلب تحديًا جديدًا |
FingerprintMismatch |
قُدم من عنوان أو User-Agent مختلف | قدمه من العميل الذي جلبه |
DifficultyNotMet |
لا تحقق قيمة Hashcash المؤقتة البتات الصفرية المطلوبة | واصل البحث عن قيم مؤقتة |
InvalidProof |
لا يفتح إثبات العمل المتسلسل التسميات المُلتزَم بها | شغّل المُبرهِن حتى النهاية بالعمق وعدد عمليات الفتح المحددين في التحدي |
WrongSolutionType |
قيمة مؤقتة لتحدي PoSW أو إثبات لتحدي Hashcash | طابق حقل الحل مع الخوارزمية |
DoubleSpendAttempt |
أُنفق التحدي من قبل | التحديات للاستخدام مرة واحدة |
StoreFull |
امتلأت مجموعة الحلول المُنفَقة | اخفض TTL التحدي أو ارفع --spent-tags |
InvalidTokenSignature |
فشل التحقق من وسم ملف تعريف الارتباط أو توقيعه | أعد المصادقة عبر الصفحة الوسيطة |
TokenExpired |
تجاوز ملف تعريف الارتباط مدة صلاحيته | أعد المصادقة |
TokenBoundAddressMismatch |
قُدم ملف تعريف الارتباط من هوية عميل مختلفة | لا يمكن مشاركة ملفات تعريف الارتباط |
تجيب واجهة API لوحدة التحكم عن الفشل بـ {"error":"<CODE>","hint":"<sentence>"}؛ والتلميح هو النص الذي تعرضه الواجهة (crates/console/src/http/reply.rs).
| الرمز | الحالة | المعنى |
|---|---|---|
CONSOLE002 |
400 | الطلب مشوه، أو كبير جدًا، أو غير مسموح بصيغته |
CONSOLE003 |
503 / 429 | طابور مهام التخزين ممتلئ (32 مهمة)، أو متحقق كلمات المرور مشغول |
CONSOLEQUORUM |
503 | لم تجب قاعدة البيانات خلال مدة انتظار الطلب البالغة 10 ثوانٍ؛ النتيجة غير معروفة، ويواصل مستوى البيانات العمل بآخر سياسة مطبقة |
CONSOLE004 |
503 | لا تستطيع الخدمة الإجابة: غير متاحة في هذا البناء، أو في طور التوقف، أو فشل داخلي |
CONSOLENODE |
400 / 409 / 503 | رُفض أمر عقدة: يسمي عقدة أخرى (400)، أو مراجعة إقلاع أو تحكم قديمة (409)، أو وصل أثناء تنفيذ أمر آخر أو تعذر تسجيل اكتماله (503)؛ افحص إيصال العملية قبل إعادة المحاولة |
CONSOLEMUTATION |
429 | أكثر من ستين تعديلًا إداريًا في دقيقة واحدة من جلسة واحدة |
مخطط السياسة¶
{
"default_action": "ALLOW" | "DENY" | "CHALLENGE",
"waf": true | false,
"inspection": { "path_traversal" | "sqli" | "xss" | "rce": "disabled" | "audit" | "enforce" },
"thresholds": { "challenge_at": int, "deny_at": int, "bits_step": int },
"ip_rules": { "<cidr>": "ALLOW" | "DENY" | "CHALLENGE", ... },
"rules": [ // حتى 128
{
"name": "<kebab-case>", // من 1 إلى 128 بايتًا قابلة للطباعة
"path" | "path_regex": "<pattern>", // حتى 512 بايتًا
"user_agent" | "user_agent_regex": "<pattern>",
"headers" | "headers_regex": { "<Header>": "<pattern>" }, // حتى 4
"remote_addresses" | "cidrs": ["<cidr>", ...], // حتى 8، من IPv4 أو IPv6
"action": "ALLOW" | "DENY" | "CHALLENGE" | "WEIGH",
"weight": int, // لـ WEIGH فقط، -1000..1000
"challenge": { "difficulty": <work bits>, "algorithm": "hashcash" | "posw" },
"limits": { "rate": int, "window_seconds": int, "ban_seconds": int },
"ja4": "<fingerprint>" | "<prefix>*" // 36 بايتًا، أو بادئة يتبعها *
}
]
}
تقع challenge_at وdeny_at بين -1000 و1000، على أن تكون deny_at مساوية لـ challenge_at أو أعلى منها، وتقع bits_step بين 1 و1000. لا تنتمي كتلة challenge إلا إلى قواعد CHALLENGE، ببتات عمل من 1 إلى 64. تمنح limits القاعدة حصتها الخاصة: rate من 1 إلى 1,000,000 وwindow_seconds من 1 إلى 86,400 مطلوبتان، وban_seconds (86,400 على الأكثر) اختيارية، ولا يمكن لقواعد WEIGH حمل حدود. أما ja4 فهو بصمة JA4 كاملة يجب أن تساويها البصمة، أو بادئة يتبعها * يجب أن تبدأ بها البصمة؛ والقيمة * وحدها تطابق أي بصمة، والطلب الذي لا يحمل بصمة لا يطابق أي قاعدة ja4. ويُرفض النمط الذي لا يمكن أن تطابقه أي بصمة بالخطأ InvalidJa4 (الجزء التاسع، بصمات JA4 من وكيل الدخول). تحمل شجرة السمعة في ip_rules 8,192 عقدة على الأكثر. يمكن لكل قاعدة استخدام صيغة واحدة لكل معيار.
صياغة الأنماط: يطابق .* أو * أي شيء؛ ويقيّد ^...$ المطابقة بمسار تام؛ وتجعل * أو /* أو .* في النهاية النمطَ بادئة؛ والنمط الذي يبدأ بـ / مسار تام؛ وأي شيء آخر سلسلة فرعية دون تمييز حالة الأحرف. تطابق أنماط المسار المسارَ في صيغته المُطبَّعة (شرطة مائلة واحدة بين المقاطع، بلا مقاطع نقطية، والمحارف غير المحجوزة غير مهرّبة، وسائر الترميزات المهرّبة بأرقام ست عشرية كبيرة)، لذا لا يطابق النمط الذي يحمل ; أو %2F أو %5C أو \ أي شيء، ومطابقة المسار حساسة لحالة الأحرف (SID 0003).
جداول التخزين¶
policy_revision، وpolicies (مع المعيار ja4_pattern القابل للقيمة NULL بطول 37 بايت على الأكثر)، وpolicy_inspection، وip_reputation، وincident_receipts، وsecurity_incidents (مع التضمين ذي 256 بايت وبصمة ja4 القابلة للقيمة NULL بطول 36 بايت)، وفهرس النص الكامل (incidents_fts، وهو FTS5 على الوحدات المعجمية المُطبَّعة في SQLite؛ والعمود search من نوع tsvector مع فهرس GIN في PostgreSQL)، وsibuna_schema؛ وتضيف وحدة التحكم 33 جدولًا من نوع console_*. تُخزن أسماء الإجراءات والخوارزميات والأوضاع بأحرف صغيرة. معرفات الحوادث هي node_id << 40 | sequence، فريدة عبر العنقود دون تنسيق؛ وتمتد معرفات العقد من 1 إلى 8,388,607.
أهداف البناء¶
| الأمر | النتيجة |
|---|---|
cargo build --release -p sibuna |
البرنامج الخدمي مع تخزين SQLite ووحدة التحكم (الميزات الافتراضية) |
cargo build --release -p sibuna --no-default-features |
برنامج خدمي في الذاكرة بلا تخزين ولا وحدة تحكم، وبلا أي حزمة خارجية |
cargo build --release -p sibuna --features postgres-tls |
برنامج خدمي يتصل أيضًا بقاعدة بيانات PostgreSQL مشتركة عبر TLS مُتحقَّق منه (الميزة postgres وحدها تتصل دون TLS) |
cargo test |
اختبارات الوحدات، واختبارات التكامل على برنامج خدمي قيد التشغيل، واختبارات التخزين ووحدة التحكم (واختبارات PostgreSQL عند ضبط SIBUNA_TEST_DATABASE_URL) |
cargo clippy --all-targets، cargo fmt --check |
فحوص lint والتنسيق (max_width = 99) |
cargo xtask check |
حدود الدالة ذات 70 سطرًا، والملف ذي 1,408 سطرًا، وطول السطر 99/108 عمودًا؛ وبلا محارف جدولة |
cargo xtask browser |
فحوص في Chromium بلا واجهة (sibuna-browser) |
cargo xtask bench <primitives|product|latency> |
قياسات أداء في وضع الإصدار (release)؛ والنتائج في benchmarks/results/<command>-latest.json |
cargo build -p sibuna-pow-wasm --target wasm32-unknown-unknown --profile wasm |
وحدة المتصفح فقط (-p sibuna-console-ui لواجهة وحدة التحكم) |
cargo run -p sibuna-geoip --bin geoip-snapshot -- ... |
تحقق من بيانات البلدان واكتب لقطة GeoIP قابلة للتضمين |
guidedog build / guidedog dsc |
هذا الكتاب / سجلات SID |
يبني سكربت بناء البرنامج الخدمي (cmd/sibuna/build.rs) وحدتي WebAssembly كلتيهما بملف التعريف wasm في مجلد الأهداف لمساحة العمل، ويُفشل البناء عندما تتجاوز واجهة وحدة التحكم 768 KiB. يسمي SIBUNA_POW_WASM وSIBUNA_CONSOLE_WASM وحدات مبنية مسبقًا بدلًا من ذلك، للبناءات التي لا يتوفر فيها الهدف wasm32-unknown-unknown. يسمي SIBUNA_GEOIP_DATA لقطة GeoIP للتضمين؛ ويُفك ترميزها وقت البناء، ويرفضها البناء الذي لا يضم وحدة التحكم (GEOIP001).