Codex Security

يساعدك Codex Security على العثور على الثغرات الأمنية في شفرتك البرمجية والتحقيق فيها وإصلاحها. استخدم سير عمل الأمان الخاصة به في Codex، أو أتمتها باستخدام واجهة سطر الأوامر @openai/codex-security وحزمة تطوير البرامج TypeScript SDK.

• في Codex: اختر سير عمل أمان.
• في الطرفية: ثبّت واجهة سطر الأوامر وافحص مستودعك.
• في الأتمتة: استخدم TypeScript SDK أو GitHub Action.

الميزات

• افحص المستودعات، أو المسارات المحددة، أو تغييرات Git. تُشغّل الفحوصات العميقة عمال استكشاف متوازيين على المستودعات والمسارات المحددة.
• تحقّق من النتائج المرشحة، وأنشئ تصحيحات، وتحقق من الإصلاحات الموجودة.
• صِغ سياسات SECURITY.md واحفظ نماذج التهديدات للمراجعة لاحقًا.
• تصفّح الفحوصات والنتائج المحفوظة، وحدّد التكرارات، وقيّم الخطورة وفقًا لمعاييرك الخاصة، واقترح المسؤولين من الشفرة البرمجية وسجل Git.
• استورد تنبيهات فحص الشفرة البرمجية من GitHub، وصدّر SARIF أو JSON أو CSV، وانشر النتائج إلى Linear أو إلى خدمة نتائج.
• أتمت الفحوصات عبر المستودعات أو مكونات المشروع، بما في ذلك في CI والحاويات.

الاستخدام في Codex

افتح مستودعك في جلسة Codex مع تفعيل إضافة Codex Security، ثم اطلب:

شغّل فحص Codex Security على هذا المستودع، مع التركيز على المصادقة و التفويض. أعد التقرير المحفوظ والأدلة المصدرية وحدود التغطية.

يحفظ الفحص المكتمل تقريرًا ونتائج وتغطية ونموذج تهديدات عند توفره. استخدم تلك النتائج للتحقيق في النتائج، أو طلب تصحيح، أو التحقق من إصلاح موجود. راجع دليل سير عمل الوكيل لإعداد الإضافة، واختيار المهام، والاسترداد عند عدم توفر الأدوات المطلوبة.

البدء السريع

يتطلب Node.js 22.13.0+ ضمن 22.x، أو Node.js 24.x أو 26.x، وPython 3.10+. يتطلب Python 3.10 أيضًا tomli.

ثبّت واجهة سطر الأوامر عالميًا وسجّل الدخول:

npm install --global @openai/codex-security
cs login

cs هو اسم مستعار قصير لـ codex-security؛ كلا الأمرين يشغّلان نفس واجهة سطر الأوامر (CLI). ينشئ التثبيت كلا الأمرين في دليل الملفات التنفيذية العامة الخاص بـ npm، والذي يجب أن يكون ضمن PATH الخاص بك. إذا كان cs يُحلّ بالفعل إلى أداة أخرى، فاستخدم codex-security بدلاً من ذلك. إذا توقف npm بخطأ EEXIST بخصوص cs، فاستخدم npx @openai/codex-security دون تثبيت عام.

شغّل الفحص من دليل المستودع:

cs scan .

إذا كان لديك وصول إلى Daybreak Blue، فأضف --cyber-access-program daybreak_blue إلى أمر الفحص. وإلا، فاحذف العلامة أو استخدم --cyber-access-program standard.

لاستخدام مفتاح Daybreak الخاص بـ Codex، مرّر --codex daybreak=true. وهو معطّل افتراضيًا ويتطلب وصولًا متوافقًا. راجع إعداد Daybreak لاستخدام SDK والإضافة، بما في ذلك عمّال الفحص العميق (Deep Scan).

تستخدم عمليات الفحص إرشادات SECURITY.md الموجودة لديك. لتعريفها أو تحديثها، يمكنك اختياريًا صياغة سياسة:

cs policy .

تُحفظ المسودة خارج مستودعك. راجع الفروقات والملاحظات، وحرّر المسودة، ثم انسخ SECURITY.md فقط إلى هدف السياسة الموضح. يمكنك إجراء الفحص دون إنشاء سياسة.

للتشغيل دون تثبيت عام، استبدل cs في هذه الأمثلة بـ npx @openai/codex-security، على سبيل المثال:

npx @openai/codex-security scan .

بالنسبة لـ CI، عيّن OPENAI_API_KEY أو CODEX_API_KEY في بيئة عملية الفحص. على الأجهزة البعيدة أو بدون واجهة، استخدم login --device-auth إذا كانت مساحة العمل لديك تسمح بذلك، أو سجّل الدخول عبر SSH.

تتطلب بعض طلبات الأمن السيبراني والنتائج المحمية موافقة Trusted Access for Cyber.

خيارات الفحص

اختر نطاقًا ووضع فحص:

# Scan selected paths.
cs scan . --path src --path tests

# Scan committed changes from a base revision to HEAD.
cs scan . --diff origin/main

# Run a deep scan of the repository.
cs scan . --mode deep

استخدم cs scan . --max-time 15 للحصول على مدة استقصاء قياسي استشاريّة مدتها 15 دقيقة. راجع investigation time للاطلاع على دلالات التوقيت وحدود الفحص العميق.

استخدم cs --help لتصفح الأوامر، أو cs scan --help للاطلاع على خيارات الفحص وحدود التكلفة والترقيع بعد الفحص.

بالنسبة لتطبيق موزّع عبر مستودعات متعددة، راجع review one system across repositories. استخدم bulk scans لمراجعات مستودعات مستقلة ضمن حملة واحدة قابلة للاستئناف.

بعد الفحص، inspect its scope and follow-up work لفهم الاستثناءات المسجّلة وتقرير ما إذا كنت ستراجع النتائج، أو تشغّل فحصًا مركّزًا، أو تستعيد تشغيلًا متقطعًا.

TypeScript SDK

ثبّت الحزمة محليًا في مشروع TypeScript الخاص بك:

npm install @openai/codex-security

ثم استورده:

import { CodexSecurity } from "@openai/codex-security";

const security = new CodexSecurity();

try {
  const result = await security.run("/path/to/repository");
  console.log(result.reportPath);
} finally {
  await security.close();
}

يتضمن دليل SDK إعداد الفحص العميق، والتحقق، وتصنيف الخطورة، واقتراحات المالكين، ومعالجة النتائج.

قراءة نتائج Cloud الموجودة

عندما يكون Codex Security Cloud متاحًا لحسابك، يمكن لمهارة $cloud-findings التابعة لإضافة Security قراءة النتائج والتقارير والتعيينات والتحققات المسجّلة وحالة الفحص في Codex desktop أو Codex CLI. يُعدّ Cloud اتصالًا اختياريًا؛ إذ تعمل الفحوصات المحلية دونه.

راجع إعداد اتصال Cloud والقراءة عبر CLI للاطلاع على متطلبات المصادقة ومثال للقراءة فقط.

إنشاء SECURITY.md

استخدم policy لصياغة ملف SECURITY.md جديد أو تحديث ملف موجود. استخدم --path لاختيار مكوّن:

cs policy .
cs policy . --path services/api --knowledge-base architecture.md

يحفظ الأمر مسودته خارج المستودع ويترك الملفات الموجودة دون تغيير. راجع الفروقات والملاحظات، وحرّر المسودة، ثم انسخ SECURITY.md فقط إلى هدف السياسة المعروض. احتفظ بوثائق البنية ونموذج التهديد المحفوظة خارج المستودع.

تستخدم عمليات الفحص بالفعل ملفات SECURITY.md في الجذر والمكوّنات. احتفظ بسياساتك الحالية إن لم تكن بحاجة إلى تغييرات. عند تحديثها، حافظ على تعليمات الإبلاغ عن الثغرات فيها. إذا أفاد الأمر بأن السياسة محدّثة بالفعل، فلا حاجة إلى النسخ.

غالبًا ما تحتوي الملفات في .github/SECURITY.md أو docs/SECURITY.md على تعليمات الإبلاغ. حافظ عليها عند صياغة سياسة؛ فهذه المواقع لا توفّر تلقائيًا إرشادات فحص على مستوى المستودع. راجع دليل السياسة للاطلاع على مواقع السياسة، والأسئلة غير المجابة، والمنتجات المحفوظة، واستخدام SDK.

حفظ نماذج التهديد وتصديرها

تحفظ عمليات الفحص وتوليد السياسات نماذج التهديد مع نتائجها. صدّر نموذجًا محفوظًا دون بدء تحليل آخر:

cs export --scan SCAN_ID --artifact threat-model --output threatmodel.md

احذف --scan لاستخدام أحدث فحص مكتمل للمستودع الحالي. يغطي دليل التصدير أيضًا النتائج، وإخراج SARIF لـ CI، وواجهة برمجة TypeScript دون اتصال.

GitHub Actions

شغّل الفحوصات المجدولة أو اليدوية أو الخاصة بطلبات السحب باستخدام GitHub Action. لفحص أسبوعي للمستودع، أضف مفتاح OpenAI API كسر للمستودع باسم CODEX_SECURITY_API_KEY، ثم احفظ سير العمل هذا في .github/workflows/codex-security.yml. استبدل REPLACE_WITH_REVIEWED_COMMIT بـ SHA الكامل لأحد commits الخاصة بـ Action.