deepsec

deepsec هو ماسح ثغرات مدعوم بالوكلاء (Agents) يمكنك تشغيله في البنية التحتية الخاصة بك، مُحسَّن لإجراء مراجعة عند الطلب لجميع الأكواد في المستودعات الحالية واسعة النطاق.

deepsec مصمم لكشف المشكلات صعبة الاكتشاف التي ظلت كامنة في التطبيقات لفترة طويلة. وهو مُهيأ لاستخدام أفضل النماذج بأقصى مستويات التفكير (قابلة للضبط عبر --thinking-level، انظر docs/models.md)، مما يعني أن الفحوصات قد تكلف آلافًا أو حتى عشرات الآلاف من الدولارات لقواعد الأكواد الكبيرة. وجد عملاؤنا أن التكلفة تستحق العناء بالنظر إلى السرعة التي تمكنوا بها من تصحيح ثغرات كانت ستبقى دون إصلاح.

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

ابدأ

انتقل إلى جذر المستودع الذي تريد فحصه، ثم:

npx deepsec init       # creates .deepsec/ with this repo as the first project
cd .deepsec
pnpm install           # installs deepsec from npm

# Proceed as instructed by `init` output

الآن اجعل وكيل البرمجة لديك يجري الإعداد الأولي للتثبيت. افتح الوكيل الذي تختاره وأدخل المطالبة التالية:

اقرأ .deepsec/node_modules/deepsec/SKILL.md لفهم الأداة. ثم اقرأ .deepsec/data/<id>/SETUP.md واتبعها: تصفّح README لهذا المستودع، وأي ملفات AGENTS.md/CLAUDE.md، وعددًا من ملفات الأكواد التمثيلية، ثم استبدل كل قسم من .deepsec/data/<id>/INFO.md.

اجعلها قصيرة — استهدف 50–100 سطرًا إجمالًا. اختر 3–5 أمثلة لكل قسم، وليس تعدادًا شاملًا. اذكر البدائيات (مساعدات المصادقة، الوسائط) دون أرقام أسطر. تجاهل فئات CWE العامة — المطابقات المدمجة تغطيها. غطِّ فقط ما هو خاص بالمشروع. يُحقن INFO.md في كل دفعة فحص؛ السياق المطوَّل يُضعف الإشارة.

ثم نفّذ الفحص من داخل .deepsec/:

pnpm deepsec scan
pnpm deepsec process    
pnpm deepsec revalidate # optional, cuts FP rate
pnpm deepsec export --format md-dir --out ./findings

إذا شعرت أن deepsec يجب أن ينظر إلى أجزاء أكثر من الكود، فامنحه وثيقة كتابة المطابقات للعثور على نقاط بداية أكثر قيمة في قاعدة الأكواد لديك.

الوثائق

• docs/getting-started.md — دليل إرشادي للفحص الأول
• docs/reviewing-changes.md — process --diff لمراجعة طلبات السحب (PR) وكبوابة في CI
• docs/supported-tech.md — الأطر والأنظمة البيئية التي يتعرف عليها deepsec افتراضيًا
• docs/writing-matchers.md — اطلب من وكيل البرمجة لديك توسيع مجموعة المطابقات
• docs/configuration.md — مرجع deepsec.config.ts
• docs/plugins.md — تأليف الإضافات (Plugins)
• docs/models.md — اختيار النماذج، الافتراضيات، حالات الرفض، النماذج المستقبلية
• docs/vercel-setup.md — مفاتيح / رموز AI Gateway و Vercel Sandbox
• docs/architecture.md — تفاصيل خط المعالجة (Pipeline) الداخلية
• docs/data-layout.md — مخططات data/ (FileRecord, RunMeta, …)
• docs/faq.md — التكلفة، اختيار النموذج، وضع الحماية (Sandbox)، معدل النتائج الإيجابية الخاطئة (FP)
• samples/ — نقاط بداية جاهزة للنسخ واللصق (حاليًا: webapp/)

مزود الذكاء الاصطناعي

عند التشغيل محليًا، يتراجع deepsec إلى اشتراكك الحالي في claude / codex إذا كنت قد سجّلت الدخول على هذا الجهاز. الاشتراكات (Claude Pro/Max و ChatGPT Plus) مفيدة لتقييم deepsec لكنها عمومًا لا توفر هامشًا كافيًا لفحوصات المستودعات الكاملة.

للفحوصات الفعلية، استخدم Vercel AI Gateway. مفتاح واحد يغطي كلاً من Claude و Codex، وحصص البوابة الافتراضية مصممة للأبحاث عالية التزامن.

AI_GATEWAY_API_KEY=vck_...

انظر docs/vercel-setup.md للحصول على مفتاح ولإعداد Vercel Sandbox. لتجاوز البوابة، اضبط ANTHROPIC_AUTH_TOKEN + ANTHROPIC_BASE_URL (أو زوج OpenAI) بشكل صريح. القيم الصريحة لها الأولوية دائمًا على توسيع AI_GATEWAY_API_KEY.

إذا توقف تشغيل process أو revalidate لأن بيانات اعتماد المزوّد العلوي نفدت حصتها أو رصيدها، يتوقف deepsec بسلاسة ويخبرك أين تُعيد الشحن. أعد تشغيل نفس الأمر بعد ذلك فيستأنف من حيث توقف.

التنفيذ الموزّع (اختياري)

يمكن للمستودعات الأحادية الكبيرة (Monorepos) توزيع العمل عبر الأجهزة الافتراضية الدقيقة (MicroVMs) في Vercel Sandbox:

pnpm deepsec sandbox process --project-id my-app --sandboxes 10 --concurrency 4

يتطلب حساب Vercel. يتم ضغط شجرة العمل المحلية في ملف tar ورفعها؛ ويُستثنى .git. كل من رموز OIDC (محليًا) ورموز الوصول (في CI) مدعومة — انظر docs/vercel-setup.md.

النموذج الأمني لـ deepsec نفسه

تعامل مع deepsec باعتباره وكيل برمجة يتمتع بوصول كامل إلى الصدفة (Shell) على البيئة التي يعمل عليها. وهو مصمم للعمل على مدخلات موثوقة (كودك المصدري)، لكنك قد تظل قلقًا بشأن حقن المطالبات (Prompt Injection) بسبب الاعتماديات الخارجية أو الأكواد المضمنة (Vendored Code).

التشغيل في بيئة عزل (Sandbox) (انظر أعلاه) يحد من التعرض المحتمل بشكل كبير:

• يتم حقن مفاتيح API الخاصة بوكلاء البرمجة خارج بيئة العزل، وبالتالي لا يمكن تسريبها إلى الخارج
• بالنسبة لبيئات العزل الخاصة بالعاملين، يقتصر الخروج الشبكي من بيئة العزل على مضيفي وكلاء البرمجة (يُسمح بالخروج أثناء عملية التمهيد (Bootstrap)، لكن ذلك لا يشغّل وكيل البرمجة)

مرجع سير العمل

الترخيص

Apache 2.0. انظر LICENSE و NOTICE.