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 في واجهة الويب، أو استخدم سطر الأوامر.
   root@kitploit:~

   ./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.

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

من واجهة الويب (موصى به)

Snapshots → Import datasets، الصق أحد روابط الأرشيف أعلاه، وانقر Find archives. تستورد FLAWED رابط .tar.gz مباشراً كما هو وتفكّه إلى لقطاتك. ثم استعده من قائمة اللقطات (الاستعادة خطوة منفصلة ومؤكَّدة صراحةً).

يكتشف الاستيراد أرشيفات متعددة دفعة واحدة فقط عندما يكون الرابط حاوية قابلة للسرد أو صفحة فهرس دليل. لا ينطبق أي منهما هنا، لذا استورد الروابط واحداً تلو الآخر.

يدوياً

نزّل أرشيفاً، وفكّه إلى دليل اللقطات (FLAWED_HOST_SNAPSHOT_DIR، أو ./flawed-snapshots افتراضياً)، وسيظهر في قائمة اللقطات جاهزاً للاستعادة.

curl -LO https://flawed.s3.us-east-1.amazonaws.com/compressed/campaigns/full/cve-2026-45185-exim-bdat-uaf_full_gpt-5.5_1782988292.tar.gz
mkdir -p "$FLAWED_HOST_SNAPSHOT_DIR"
tar -xzf cve-2026-45185-exim-bdat-uaf_full_gpt-5.5_1782988292.tar.gz -C "$FLAWED_HOST_SNAPSHOT_DIR"

الاستيراد يهيّئ الحزمة على القرص فقط. أما استعادتها، التي تستبدل النشر الحالي، فتُجرى بشكل منفصل من صفحة اللقطات.

التوثيق

تخطيط المستودع

packages/
  flawed-core/             models, DB schema, settings
  flawed-orchestrator/     run lifecycle, worker pool, devcontainer driver
  flawed-stage-*/          the pipeline stages (clone, generate, validate, …)
  flawed-agent-runner/     runs INSIDE the container (Claude / Codex / Gemini CLIs)
  flawed-api/              FastAPI + SSE + notebook proxy
  flawed-cli/              the `flawed` CLI
apps/web/                  React + Vite + Tailwind webapp
containers/                base image, network lockdown, notebook container
bugs/                      example bug specs
docs/                      documentation (see above)

التطوير

تحتاج الاختبارات إلى Docker. تُشغّل Postgres خاصاً بها عبر testcontainers.

الترخيص والمساهمة

تُصدر FLAWED تحت رخصة MIT. المساهمات مرحّب بها. راجع CONTRIBUTING.md، ويرجى الإبلاغ عن المشكلات الأمنية بشكل خاص وفقاً لـ SECURITY.md.