Arxi بوابة القرار أصل أساسي
Docs
وثائق بوابة القرار

تقييم بوابة حتمي وقابل لإعادة التشغيل مع قرارات قابلة للتدقيق.

وثائق Asset Core

دليل الأمان

نظرة سريعة

ما: ضوابط الأمان للثقة، التوقيعات، الإفصاح، والوصول لماذا: منع التلاعب بالأدلة وتقليل تعرض البيانات من: مهندسو الأمان، فرق الامتثال، مشغلو الإنتاج المتطلبات السابقة: evidence_flow_and_execution_model.md

وضعيات مسبقة

تقوم Decision Gate بشحن أربعة إعدادات مسبقة (انظر preset_configs.md):

  • Quickstart-Dev: مصادقة محلية فقط، تجاوز السجل محلي فقط، تم تفعيل الإذن المطور.
  • موصى به افتراضي: مصادقة محلية فقط مع خرائط رئيسية صريحة؛ تجاوز السجل غير مفعل.
  • مُعزَّز: مصادقة الحامل، تعطيل مساحة الأسماء الافتراضية، يتطلب توقيع المخطط.
  • Container-Prod: مصادقة حامل، إنهاء TLS في الاتجاه العلوي، إعدادات افتراضية بدون حالة.

هذه الإعدادات مسبقة الصنع واضحة عن عمد. إذا قمت بتغيير الوضعية (وضع المصادقة، الافتراضات الخاصة بالنطاق، ACL السجل، مسارات الثقة)، قم بتحديث الإعدادات المسبقة وأعد تشغيل اختبارات النظام.

فشل-مغلق العمارة

قرار بوابة يفشل مغلقة: الأدلة المفقودة أو غير الصالحة تنتج unknown، مما يحتجز البوابات.

تم تطبيق ضوابط الأمان (بالترتيب):

  1. حد أدنى لثقة المسار (min_lane)
  2. التحقق من الرابط (إذا تم تكوينه)
  3. التحقق من التوقيع (إذا لزم الأمر)
  4. تقييم المقارن (ثلاثي الحالة)

تحكم الوصول

الوصول إلى الأداة (API MCP)

يتم التحكم في الوصول إلى الأداة بواسطة [server.auth].

[server.auth]
mode = "bearer_token"
bearer_tokens = ["token-1", "token-2"]
allowed_tools = ["scenario_define", "scenario_start", "scenario_next"]

أنماط:

  • local_only (افتراضي): حلقة العودة + stdio فقط
  • bearer_token: HTTP Authorization: Bearer <token> مطلوب
  • mtls: يستخدم رأس x-decision-gate-client-subject من وكيل موثوق ينهي TLS

ملاحظة السجل:

  • schema_registry.acl.allow_local_only = true يتجاوز تعيين المبدأ للمتصلين المحليين فقط. استخدمه فقط لتوجيه المطورين/المستخدمين المحليين.

ربط غير دائري

ربط HTTP/SSE مع غير حلقة التكرار يتطلب جميع ما يلي:

  1. --allow-non-loopback أو DECISION_GATE_ALLOW_NON_LOOPBACK=1
  2. [server.tls] تم تكوينه أو server.tls_termination = "upstream"
  3. المصادقة غير المحلية (bearer_token أو mtls)

لـ mtls داخل الحاوية، يجب تعيين server.tls.client_ca_path و require_client_cert = true. بالنسبة لإنهاء TLS في الاتجاه العلوي، فرض mTLS عند الوكيل وتمرير x-decision-gate-client-subject.

مسارات الثقة

يتم تصنيف الأدلة إلى مسارات:

  • تم التحقق منه: دليل تم جلبه من المزود
  • تم التأكيد: فحص مسبق للأحمال

يتم تطبيق الحد الأدنى للمسار بواسطة:

[trust]
min_lane = "verified"   # or "asserted"

إذا كانت حارة الأدلة أقل من الحد الأدنى، تصبح الحالة غير معروفة ويتم تسجيل خطأ trust_lane في حزمة التشغيل.

وضع المطور المرن

[dev]
permissive = true

التأثيرات:

  • يصبح min_lane الفعال asserted لمعظم المزودين.
  • تبقى مقدمو الخدمة المدرجون في dev.permissive_exempt_providers صارمين (افتراضي: assetcore, assetcore_read).
  • غير مسموح به عندما namespace.authority.mode = "assetcore_http".

التحقق من التوقيع

تم تكوينه باستخدام trust.default_policy:

[trust]
# Require Ed25519 signatures from these public key files.
default_policy = { require_signature = { keys = ["/etc/decision-gate/keys/provider.pub"] } }

ملاحظات:

  • كل إدخال في keys هو مسار ملف. قد يحتوي ملف المفتاح على بايتات مفتاح عمومي خام بحجم 32 بايت أو نص بتنسيق base64.
  • EvidenceResult.signature.key_id يجب أن يتطابق مع سلسلة مسار المفتاح المكونة.
  • يتم التحقق من التوقيع على JSON القياسي لـ HashDigest.
  • إذا كان evidence_hash موجودًا، يجب أن يتطابق مع الهاش القياسي لقيمة الدليل.

إذا فشل التحقق من التوقيع، فإن استدعاء المزود يفشل وتصبح الحالة unknown مع تسجيل provider_error.

تحقق من الرابط

يتم تكوين المراسي عبر تكوين الخادم، وليس السيناريو:

[anchors]
[[anchors.providers]]
provider_id = "assetcore_read"
anchor_type = "assetcore.anchor_set"
required_fields = ["assetcore.namespace_id", "assetcore.commit_id", "assetcore.world_seq"]

قواعد الربط (بالضبط):

  • EvidenceResult.evidence_anchor.anchor_type يجب أن يتطابق.
  • anchor_value يجب أن يكون سلسلة تحتوي على JSON قياسي.
  • يجب أن يتم تحليل JSON إلى كائن.
  • يجب أن توجد الحقول المطلوبة وأن تكون من نوع سلسلة نصية أو رقم (لا توجد قيم منطقية، مصفوفات، كائنات، أو قيم فارغة).

تنتج الانتهاكات anchor_invalid وتصبح الحالة unknown.

إفصاح الأدلة

evidence_query يمكن أن يعيد القيم الخام، لكن الكشف يخضع لسياسة التحكم:

[evidence]
allow_raw_values = false
require_provider_opt_in = true

[[providers]]
name = "json"
type = "builtin"
config = { root = "/var/lib/decision-gate/evidence", root_id = "evidence-root", max_bytes = 1048576, allow_yaml = false }
allow_raw = true

السلوك:

  • إذا تم حظر الكشف الخام، يقوم Decision Gate بتحرير value و content_type ولكنه لا يزال يعيد الهاشات والمرتكزات.
  • هذا ليس خطأ JSON-RPC.
  • أسماء المزودين فريدة؛ المعرفات المدمجة (time, env, json, http) محجوزة.

معالجة الحمولة الخاصة بالتقديم/التفعيل

scenario_submit.payload و scenario_trigger.payload هما قنوات سجل التدقيق. يقوم Decision Gate بالاحتفاظ بهذه الحمولة في حالة التشغيل وقطع التشغيل حسب التصميم. يجب على التكاملات تجنب إرسال الأسرار الخام من خلال هذه الحقول.

النمط الموصى به:

  • إرسال مراجع/مقابض غير شفافة في الحمولة.
  • حل الأسرار من مدير أسرار مخصص خارج DG.

إعدادات الإنتاج الآمنة

[server]
transport = "http"
bind = "0.0.0.0:4000"
mode = "strict"

[server.auth]
mode = "bearer_token"
bearer_tokens = ["token-1"]

[server.tls]
cert_path = "/etc/decision-gate/tls/cert.pem"
key_path = "/etc/decision-gate/tls/key.pem"

[trust]
min_lane = "verified"
default_policy = { require_signature = { keys = ["/etc/decision-gate/keys/provider.pub"] } }

[evidence]
allow_raw_values = false
require_provider_opt_in = true

[anchors]
[[anchors.providers]]
provider_id = "json"
anchor_type = "file_path_rooted"
required_fields = ["root_id", "path"]

[namespace]
allow_default = false

[policy]
engine = "static"

[policy.static]
default = "deny"

[run_state_store]
type = "sqlite"
path = "/var/lib/decision-gate/decision-gate.db"
journal_mode = "wal"
sync_mode = "full"

مهم: بالنسبة للربط غير الدائري، أضف --allow-non-loopback أو قم بتعيين DECISION_GATE_ALLOW_NON_LOOPBACK=1.

سلامة SQLite

يخزن متجر حالة تشغيل SQLite لقطات JSON القياسية ويتحقق من التجزئات عند التحميل. الفساد أو عدم تطابق التجزئات يؤديان إلى الفشل المغلق.

أفضل الممارسات:

  • استخدم حجمًا متينًا (تجنب /tmp).
  • قم بعمل نسخة احتياطية من ملفات .db و -wal و -shm معًا.

الأخطاء الشائعة (تم تصحيحها)

  • “أخطاء التوقيع تعيد signature_invalid.” -> لا. تظهر حالات فشل التوقيع كـ provider_error أثناء استدعاءات الموفر.
  • “سياسة الربط موجودة في السيناريو.” -> لا. تم تكوينها تحت [anchors].
  • “أداة التحكم في سياسة الوصول.” -> لا. [policy] تتحكم في إرسال الحزم فقط. الوصول إلى الأداة هو [server.auth].
  • “evidence_query returns an error when raw values are blocked.” -> لا. القيم محجوبة، وليست مرفوضة.

مرجع متقاطع