FLAWED

Fix Like Artifacts with Embedded Defects

أداة بحثية لقياس مدى جودة قيام وكلاء الذكاء الاصطناعي بترقيع الثغرات الأمنية.

البدء السريع · مجموعات البيانات · التوثيق · نموذج الأمان · المساهمة

تقوم FLAWED بسحب مشروع مفتوح المصدر عند إصدار معروف باحتوائه على ثغرة، وتُسلّم وكيل ذكاء اصطناعي وصفاً للخلل، وتطلب منه كتابة ترقيع. لا يرى الوكيل أبداً الإصلاح الحقيقي الموجود في المصدر الأصلي.

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

كيف تعمل

flowchart LR
    spec[bug spec] --> clone
    clone["clone<br/>(open net)"] --> generate
    generate["generate<br/>(offline)"] --> validate
    validate["validate<br/>(offline)"] --> ast["ast<br/>(offline)"]
    generate -.->|"patch.diff"| store[(Postgres)]
    validate -.->|"verdict"| store
    ast -.->|"summary"| store
    store --> ui[web UI + notebook]

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

الميزات

تُشغّل FLAWED واجهات سطر أوامر Claude وCodex وGemini في مواجهة مباشرة بنفس المدخلات.

البدء السريع

[!WARNING] تقوم FLAWED بتركيب مقبس Docker (مكافئ لصلاحيات الجذر على المضيف) وتنفّذ كوداً خارجياً غير موثوق داخل حاويات مراحلها. شغّلها على جهاز تثق به لتحمّل هذا العبء. راجع docs/security-model.md.

تحتاج إلى Docker، مع إمكانية الوصول إلى مقبس الخدمة.

# 1. Configure. Writes .env for you (data dir + provider API keys)
./setup.sh

# 2. Bring up the stack (Postgres, API + worker, web UI, notebook)
docker compose up --build

# 3. Open http://127.0.0.1:8080

ثم ابدأ تشغيلك الأول.

1. استورد مواصفة خلل. توجد مواصفات نموذجية تحت bugs/. اسحب واحدة إلى صفحة Bug Specs في واجهة الويب، أو استخدم سطر الأوامر.

   ./scripts/import-all-bugs.sh
   

2. أطلق تشغيلاً من واجهة الويب. اختر المواصفة، والوكيل + النموذج، والمتغير، وعدد التكرارات. تبثّ صفحة التشغيل التقدم مباشرة.

[!NOTE] التشغيل الأول ضد مصدر كبير (مثل Chromium) يكون بطيئاً. تستنسخ مرحلة التحقق المستودع بأكمله مرة واحدة للمقارنة مع الترقيع الأصلي الحقيقي. يُخزَّن الاستنساخ مؤقتاً ويُعاد استخدامه بعد ذلك.

make dev                        # uv sync + web deps
docker compose up -d postgres   # FLAWED needs a Postgres to talk to
cp .env.example .env            # points FLAWED_DB_URL at it
uv run flawed init              # builds base images, creates the schema
uv run flawed serve             # API + worker + webapp on port 8080

مواصفات الخلل

مواصفة الخلل هي وحدة المدخل. تحمل مستودعاً، وإصداراً يحتوي على ثغرة، ووصفاً للخلل، ومُعيد إنتاج اختياري، ومجموعة من متغيرات التوجيه التي تحاكي كيف قد يُبلَّغ عن الخلل بشكل واقعي (نتيجة SAST، تقرير مكافأة الثغرات، إشعار محظور، PoC خام، …). المواصفات مُصدَّرة بإصدارات وغير قابلة للتغيير، بحيث لا يتغير توجيه تشغيل تاريخي وحكمه بصمت أبداً.

توجد بنية JSON في bugs.schema.json وهي موثّقة في docs/bug-specs.md. تصف جميع المواصفات المضمّنة ثغرات مُفصح عنها علناً ومُصلحة في المصدر الأصلي.

التخزين

Postgres هو المصدر الوحيد للحقيقة. توجد بيانات التشغيل الوصفية و بايتات المخرجات (الترقيعات، الأحكام، النصوص، السجلات) في قاعدة البيانات، بحيث يُلتقط النشر بالكامل عبر قاعدة بياناته. دليل data/ هو مساحة عمل مؤقتة تُركّبها المراحل في وقت التشغيل.

• نسخ احتياطي / استعادة نشر كامل باستخدام scripts/export_dataset.py وscripts/import_dataset.py (متاحان أيضاً من واجهة الويب).
• إعادة بناء شجرة مخرجات على القرص للفحص دون اتصال باستخدام scripts/export_artifacts.py.
• تغييرات المخطط تُدار باستخدام Alembic (يعمل uv run alembic upgrade head تلقائياً عند بدء التشغيل).

مجموعات البيانات

ننشر مجموعات بيانات جاهزة بحيث يمكنك تحميل حملات مكتملة بدلاً من تشغيل كل شيء بنفسك. كل مجموعة بيانات هي ملف .tar.gz للقطة كاملة واحدة، مستضاف على https://flawed.s3.us-east-1.amazonaws.com.

جميع الحملات في حزمة واحدة.