protocol-remediator

إنه MVP (نموذج أولي عملي) يطبّع نتائج الثغرات (findings) في كود C/C++ الخاص بالبروتوكولات والمنصات إلى أدلة قابلة لإعادة الإنتاج، ويتحقق من التصحيحات المرشحة (candidate patches) في نسخة معزولة. نظرًا لأن code-shield كان اسمًا تشغيليًا ثبت أنه ينطوي على خطر تعارض في الأسماء، فقد استُخدم اسم داخلي محايد للحزمة العامة وواجهة الأوامر (CLI).

محور التنفيذ الحالي ليس نموذج توليد التصحيحات (patch generation model)، بل حلقة التحقق المغلقة التالية.

sanitizer 또는 SARIF
  -> Finding + EvidenceBundle
  -> source context
  -> manual/external-agent patch
  -> 원본 재현
  -> build
  -> patched reproducer
  -> tests
  -> static rescan
  -> bounded refuzz
  -> protocol oracle
  -> verified report

الميزات المُنفَّذة

• نماذج JSON مُصدَّرة (versioned) لـ Finding وEvidenceBundle وPatchProposal وVerificationReport
• انتقالات الحالة: detected → reproducible → contextualized → proposed → plausible → verified
• جمع تقارير AddressSanitizer وMemorySanitizer وUndefinedBehaviorSanitizer
• استيعاب نتائج (findings) SARIF 2.1
• تصدير النتائج المطبَّعة (normalized) إلى SARIF 2.1
• إنشاء سياق JSON قابل للتدقيق حول موقع المصدر (source location)
• إعدادات target/build/gate القائمة على TOML
• مشغّل Docker مع تعطيل الشبكة (network-off) وإسقاط الصلاحيات (capability-drop) وحدود الموارد (resource-limit)
• مشغّل محلي (local) يتطلب موافقة صريحة (opt-in)
• إعادة إنتاج الـ finding في نسخة من الـ target الأصلي، ثم التحقق من الـ patch في نسخة منفصلة
• فحص checksum الخاص بالـ patch، وchecksum الخاص بالـ reproducer، وتجاوز المسار (path escape)، والروابط الرمزية (symlink)، وحدود الملفات والأسطر
• رفض الـ patch لأي مسارات محمية مثل الاختبارات (test) وأدوات fuzz harness ومُعيدي الإنتاج (reproducer)
• محوّل (adapter) لأوامر وكيل التصحيح (patch agent) الخارجي
• الحفاظ على رمز الخروج (exit code) وstdout/stderr والوقت ونتائج الـ gate لكل أمر

المتطلبات

• Python 3.11 أو أحدث
• Git للتحقق من الـ patch
• Docker للتنفيذ المعزول الافتراضي
• Clang لتشغيل الأمثلة

لا توجد تبعيات Python في وقت التشغيل.

التثبيت والاختبار

python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python -m unittest discover -s tests -v

للتشغيل دون تثبيت:

PYTHONPATH=src python3 -m protocol_remediator --help
PYTHONPATH=src python3 -m unittest discover -s tests -v

مجموعة الاختبارات الديناميكية الشاملة (end-to-end) هي مصفوفة fixtures بلغة C/C++ في examples. تعيد إنتاج CWE-121 وCWE-190 وCWE-416 وCWE-787 وCWE-476 فعليًا باستخدام Clang ASan/UBSan، ثم تشغّل الـ gates الستة جميعها لكل patch يستعيد كل invariant. المدخلات ونطاق التحقق لكل fixture موثّقان في examples/README.md.

لتشغيل المصفوفة الفعلية فقط دون إطار عمل اختبارات الوحدة (unit-test framework):

PYTHONPATH=src python3 examples/run_fixture_matrix.py

لتوليد وتشغيل المزيد من الأمثلة المتغيّرة بلغة C/C++ تلقائيًا:

PYTHONPATH=src python3 examples/run_generated_corpus.py --count 50

لا يستخدم هذا الـ runner إطار unittest، بل يُمرّر كل مشروع مولَّد عبر خط الأنابيب نفسه VerificationPipeline. يبقى ملخص النتائج افتراضيًا في artifacts/generated-corpus-summary.json.

الكونسول الأمامي

الواجهة الأمامية المبنيّة بـ Vite + React + TypeScript، والتي تتيح استعراض حالة التنفيذ الحالية كلوحة تحكم تشغيلية، موجودة في frontend. يعرض هذا الكونسول في شاشة واحدة: مصفوفة الـ fixtures، والـ corpus المولَّد، وواجهة الاتصال بخادم Hermes API، والـ gates الخاصة بالتحقق، والـ invariants الخاصة بسلامة الأدلة (evidence safety).

cd frontend
npm install
npm run dev

خادم التطوير الافتراضي هو http://127.0.0.1:5173. يمكن التحقق من بناء الإنتاج (production build) عبر ما يلي:

cd frontend
npm run build

CLI

استيعاب نتائج sanitizer (findings)

protocol-remediator ingest-sanitizer \
  --log asan.log \
  --reproducer crash.input \
  --target-name parser \
  --revision 0123456789abcdef \
  --variant asan-x86_64 \
  --output intake/parser-crash

المخرجات:

intake/parser-crash/finding.json
intake/parser-crash/evidence.json

استيعاب SARIF

protocol-remediator ingest-sarif \
  --sarif results.sarif \
  --output intake/sarif

تصدير SARIF

protocol-remediator export-sarif \
  --finding intake/parser-crash/finding.json \
  --finding intake/another/finding.json \
  --output artifacts/findings.sarif

إنشاء context محايد للنموذج

protocol-remediator context \
  --finding intake/parser-crash/finding.json \
  --evidence intake/parser-crash/evidence.json \
  --target-root /path/to/target \
  --output intake/parser-crash/context.json

التحقق من patch قائم

protocol-remediator verify \
  --config /path/to/target/target.toml \
  --finding intake/parser-crash/finding.json \
  --evidence intake/parser-crash/evidence.json \
  --patch candidate.patch \
  --artifacts artifacts

رمز الخروج هو 0 عند التحقق الناجح (verified)، و1 عند فشل التحقق، و2 عند خطأ في الإعداد أو الإدخال.

خادم Hermes agent API

عند تشغيل خادم Hermes API، يمكن لأمر remediate طلب الـ patch عبر HTTP API بدلًا من أمر محلي. الـ endpoint الافتراضي هو POST /v1/patches، ويستقبل الـ finding والـ evidence والـ context وأرشيف مساحة عمل الـ target (workspace archive)، ثم يعيد unified diff.

مثال على تشغيل الخادم:

PYTHONPATH=src python3 -m protocol_remediator.hermes_server \
  --host 127.0.0.1 \
  --port 8765

بعد التثبيت، يمكن أيضًا استخدام سكربت الكونسول (console script):

hermes-agent-server --host 127.0.0.1 --port 8765

لإرفاق أمر backend تشغيلي، كرّر --backend-command لكل وسيط (argument) على حدة. يدعم العناصر النائبة (placeholders) {context} و{workspace} و{patch_output}:

hermes-agent-server \
  --backend-command my-patch-agent \
  --backend-command --context \
  --backend-command {context} \
  --backend-command --workspace \
  --backend-command {workspace} \
  --backend-command --output \
  --backend-command {patch_output}

في target.toml، حدِّد وضع Hermes كما يلي:

[agent]
mode = "hermes"
url = "http://127.0.0.1:8765"
timeout_seconds = 30

ثم استخدم أمر remediate الحالي كما هو:

protocol-remediator remediate \
  --config examples/length-prefixed-parser/target.hermes.toml \
  --finding artifacts/hermes-cli-input/finding.json \
  --evidence artifacts/hermes-cli-input/evidence.json \
  --artifacts artifacts/hermes-cli

للتأكد الشامل (end-to-end) أثناء التطوير، استخدم الـ runner التالي. يشغّل هذا الـ runner خادم Hermes مؤقتًا، ويستلم الـ patch عبر عميل API، ثم يُكمل حلقة التحقق المغلقة حتى النهاية:

PYTHONPATH=src python3 examples/run_hermes_demo.py

إنشاء وكيل أوامر خارجي والتحقق منه (command agent)

لاستدعاء أمر محلي مباشرة دون استخدام Hermes، حدِّد أمر الوكيل (agent command) في target.toml كمصفوفة نصوص:

[agent]
mode = "command"
command = [
  "my-patch-agent",
  "--context",
  "{context}",
  "--workspace",
  "{workspace}",
  "--output",
  "{patch_output}",
]
timeout_seconds = 900

ثم نفّذ الأمر التالي:

protocol-remediator remediate \
  --config /path/to/target/target.toml \
  --finding intake/parser-crash/finding.json \
  --evidence intake/parser-crash/evidence.json \
  --artifacts artifacts

لا يستدعي الـ core أي LLM API معيّن بشكل مباشر. العقد (contract) هو أن backend الخاص بـ Hermes أو الأمر الخارجي يقرأ الـ context وينشئ unified diff. يعمل الوكيل (agent) على نسخة مؤقتة، وليس على الـ target الأصلي.

إعداد target

مثال كامل موجود في target.toml.

[project]
name = "my-protocol"
language = "c++"
root = "."

[executor]
mode = "docker"
image = "my-frozen-toolchain@sha256:..."
timeout_seconds = 300
network = false

[reproduction]
failure_regex = "AddressSanitizer|heap-buffer-overflow"

[verification]
required_gates = [
  "build",
  "reproducer",
  "tests",
  "rescan",
  "refuzz",
  "protocol",
]

[gates]
build = [["cmake", "-S", ".", "-B", "build"], ["cmake", "--build", "build"]]
reproducer = [["./build/fuzz_target", "{reproducer}"]]
tests = [["ctest", "--test-dir", "build", "--output-on-failure"]]
rescan = [["./tools/run-sast", "--fail-on-new"]]
refuzz = [["./tools/refuzz", "--seconds", "60"]]
protocol = [["./tools/protocol-oracle"]]

كل أمر هو مصفوفة وسائط (arguments) وليس سلسلة shell. العناصر النائبة المدعومة:

• {workspace}: مسار الـ target المؤقت كما يراه المشغّل (executor)
• {reproducer}: مسار الـ reproducer المنسوخ إلى الـ target المؤقت بعد التحقق من الـ checksum

كل من build وreproducer مطلوبان دائمًا. في السياسة الافتراضية، تكون الـ gates الستة جميعها إلزامية. إذا وُجدت gate لا يمكن استخدامها بسبب طبيعة الهدف، يجب تعديل ذلك صراحةً في required_gates، ويبقى التعديل ظاهرًا في التقرير.

المخرجات (Artifacts)

كل عملية تحقق (run) تحفظ ما يلي:

artifacts/run_<id>/
  candidate.patch
  context.json
  evidence.input.json
  finding.input.json
  finding.final.json
  patch-proposal.json
  patch-stats.json
  verification-report.json

يحتوي verification-report.json على مخرجات أوامر خط الأساس (baseline) والأمر المُصحَّح (patched). بما أن الـ PoC أو السجلات (logs) قد تحتوي على أسرار، يجب تطبيق سياسة وصول واحتفاظ منفصلة على مستودع الـ artifacts.

حدود الأمان

• التوصية الافتراضية هي صورة Docker مثبّتة (pinned) مع network=false.
• يتطلب المشغّل المحلي (local executor) التصريح الصريح بـ allow_local=true، ولا يجوز استخدامه مع target غير موثوق.
• سياسة البيانات الخاصة بأوامر LLM الصادرة إلى الخارج يقررها المشغّل (operator). لا يقوم الـ core بأي رفع تلقائي.
• plausible هي حالة اجتازت الـ build والـ reproducer الأصلي فقط.
• verified أيضًا ليست إثباتًا لتكافؤ البرامج (program equivalence) ولا تحل محل الموافقة البشرية.
• لم يُنفَّذ دمج تلقائي (auto-merge).

أولويات التنفيذ القادمة

1. محوّل (adapter) target حقيقي لـ ProFuzzBench/AFLNet
2. جامع (collector) لتسلسل رسائل البروتوكول وآثار الحالة (state trace)
3. محوّل CodeQL اختياري ومُصدِر (emitter) لنماذج source/sink بلغة C/C++
4. تشغيل ASan/UBSan/MSan مع مصفوفة معماريات (architecture matrix)
5. protocol oracle تفاضلي (differential) قائم على corpus سليم
6. runner خاص بـ AutoPatchBench وتقرير benchmark كمّي

أسس البحث وقرارات التصميم موثّقة في docs/research.