Codex Security

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

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

الميزات

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

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

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

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

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

البدء السريع

يتطلب 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 scan .

عند اكتمال الفحص، افتح ملف Markdown الموجود في مسار REPORT في الطرفية. نفّذ cs scans show من المستودع نفسه للعثور على أحدث فحص مكتمل مرة أخرى. راجع نطاق الفحص والأعمال اللاحقة لمعرفة كيفية تفسير الاستثناءات في التقرير.

يشغّل cs وcodex-security واجهة CLI نفسها. إذا تعارض الاسم المختصر مع أمر آخر، فاستخدم codex-security. لتخطي التثبيت العام، أو إذا أبلغ npm عن تعارض EEXIST، فاستخدم npx @openai/codex-security بدلاً من cs لتسجيل الدخول والفحص معًا.

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

خيارات الفحص

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

# 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 للاطلاع على دلالات التوقيت وحدود Deep Scan.

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

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

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

تتطلب بعض طلبات الأمن السيبراني والنتائج المحمية Trusted Access for Cyber. بالنسبة للحسابات التي لديها وصول Daybreak، راجع Daybreak opt-in للاطلاع على مفتاح تبديل Codex وCyber access programs لاختيار برنامج بشكل صريح.

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 دون اتصال. لاستجابة ثغرات تطبيقات ServiceNow، راجع تصدير النتائج لـ ServiceNow.

GitHub Actions

لتشغيل فحص أسبوعي للمستودع على Ubuntu المستضاف من GitHub:

1. أضف مفتاح OpenAI API كسر للمستودع باسم CODEX_SECURITY_API_KEY.
2. انسخ سير العمل الأسبوعي إلى .github/workflows/codex-security.yml. استبدل REPLACE_WITH_REVIEWED_COMMIT بـ SHA الخاص بالتوزيع المُ راجَع من إصدار Action.
3. لتجربة سير العمل قبل التشغيل المجدول التالي، افتح Actions → Codex Security repository → Run workflow.