Allstar

[!IMPORTANT] تم إيقاف تطبيق Allstar المستضاف من OpenSSF. يستمر تطوير Allstar، وهو مشروع فرعي من OpenSSF Scorecard، — يجب عليك الآن تشغيله بنفسك، إما كإجراء GitHub أو كخدمة خلفية.

راجع ossf/allstar#881 لمزيد من التفاصيل.

إذا كانت مؤسستك تعتمد على التطبيق المستضاف، راجع الانتقال من التطبيق المستضاف.

نظرة عامة

• ما هو Allstar؟

ما الجديد في Allstar

• whats-new.md

تعطيل المشكلات غير المرغوب فيها

• المساعدة! يتم إنشاء مشكلات بواسطة Allstar ولا أريدها!

البدء

• الخلفية
• خيارات مستوى المؤسسة
• خيارات التثبيت
  • إنشاء تطبيق GitHub الخاص بك
  • إنشاء مستودع التحكم .allstar الخاص بك
  • تشغيل Allstar كإجراء GitHub
  • تشغيل Allstar كخدمة خلفية
• الانتقال من التطبيق المستضاف

السياسات والإجراءات

• الإجراءات
• السياسات

متقدم

• تعريفات التكوين
• أمثلة التكوين
• تشغيل نسختك الخاصة من Allstar

المساهمة

• المساهمة

نظرة عامة

ما هو Allstar؟

Allstar هو تطبيق GitHub يراقب باستمرار مؤسسات أو مستودعات GitHub للتأكد من الالتزام بأفضل ممارسات الأمان. إذا اكتشف Allstar انتهاكًا لسياسة أمان، فإنه ينشئ مشكلة لتنبيه مالك المستودع أو المؤسسة. بالنسبة لبعض سياسات الأمان، يمكن لـ Allstar أيضًا تغيير إعداد المشروع الذي تسبب في الانتهاك تلقائيًا، وإعادته إلى الحالة المتوقعة.

هدف Allstar هو منحك تحكمًا دقيقًا في الملفات والإعدادات التي تؤثر على أمان مشاريعك. يمكنك اختيار سياسات الأمان التي تريد مراقبتها على مستوى المؤسسة والمستودع، وكيفية التعامل مع انتهاكات السياسات. يمكنك أيضًا تطوير أو المساهمة بسياسات جديدة.

تم تطوير Allstar كجزء من مشروع OpenSSF Scorecard.

ما الجديد في Allstar

تعطيل المشكلات غير المرغوب فيها

إذا كنت تتلقى مشكلات غير مرغوب فيها تم إنشاؤها بواسطة Allstar، فاتبع هذه التعليمات لإلغاء الاشتراك.

البدء

الخلفية

Allstar قابل للتكوين بدرجة كبيرة. هناك ثلاثة مستويات رئيسية للتحكم:

• مستوى المؤسسة: يمكن لمسؤولي المؤسسة اختيار تمكين Allstar على:
  • جميع المستودعات في المؤسسة؛
  • معظم المستودعات، باستثناء بعض المستودعات التي تم إلغاء اشتراكها؛
  • عدد قليل فقط من المستودعات التي تم اشتراكها.

تتم هذه التكوينات في مستودع .allstar الخاص بالمؤسسة.

• مستوى المستودع: يمكن لمشرفي المستودعات في مؤسسة تستخدم Allstar اختيار اشتراك مستودعهم أو إلغاء اشتراكه في عمليات الإنفاذ على مستوى المؤسسة. ملاحظة: هذه الضوابط على مستوى المستودع تعمل فقط عندما يُسمح بـ "تجاوز المستودع" في إعدادات مستوى المؤسسة. تتم هذه التكوينات في دليل .allstar الخاص بالمستودع.

• مستوى السياسة: يمكن للمسؤولين أو المشرفين اختيار السياسات الممكّنة على مستودعات محددة والإجراءات التي يتخذها Allstar عند انتهاك سياسة ما. تتم هذه التكوينات في ملف سياسة yaml إما في مستودع .allstar الخاص بالمؤسسة (للمسؤولين)، أو في دليل .allstar الخاص بالمستودع (للمشرفين).

خيارات مستوى المؤسسة

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

• تتيح لك استراتيجية الاشتراك إضافة المستودعات التي تريد أن يعمل عليها Allstar يدويًا. إذا لم تحدد أي مستودعات، فلن يعمل Allstar على الرغم من تثبيته. اختر استراتيجية الاشتراك إذا كنت تريد فرض السياسات على عدد صغير فقط من إجمالي مستودعاتك، أو تريد تجربة Allstar على مستودع واحد قبل تمكينه على المزيد. منذ إصدار v4.3، يتم دعم أنماط glob لإضافة مستودعات متعددة بسهولة بأسماء متشابهة.

• تتيح استراتيجية إلغاء الاشتراك (موصى بها) تمكين Allstar على جميع المستودعات وتسمح لك بتحديد المستودعات التي تريد إلغاء اشتراكها من عمليات إنفاذ Allstar يدويًا. يمكنك أيضًا اختيار إلغاء اشتراك جميع المستودعات العامة أو جميع المستودعات الخاصة. اختر هذا الخيار إذا كنت تريد تشغيل Allstar على جميع المستودعات في مؤسسة ما، أو تريد إلغاء اشتراك عدد صغير فقط من المستودعات أو نوع معين (أي عام مقابل خاص) من المستودعات. منذ إصدار v4.3، يتم دعم أنماط glob لإضافة مستودعات متعددة بسهولة بأسماء متشابهة.

خيارات التثبيت

يعمل Allstar على مؤسستك كتطبيق GitHub: تقوم بإنشاء التطبيق، وتقوم بتشغيل العملية التي تصادق عليه. لذلك يتكون الإعداد من خطوتين مشتركتين في كل نشر — إنشاء التطبيق و إنشاء مستودع التحكم — ثم اختيار كيفية تشغيله:

الإجراء هو الخيار الأقل تكلفة من الاثنين وهو المكان الذي يجب أن تبدأ فيه معظم المؤسسات؛ يمكنك الانتقال إلى خدمة خلفية لاحقًا دون تغيير أي تكوين سياسة.

إنشاء تطبيق GitHub الخاص بك

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

اتبع تعليمات المشغل - إنشاء تطبيق GitHub، وسجل معرف التطبيق والمفتاح الخاص. كلا وضعي التشغيل يحتاجان إليهما.

إنشاء مستودع التحكم .allstar الخاص بك

يقرأ Allstar تكوينه من مستودع باسم .allstar في مؤسستك.

أسرع طريقة لإنشاء واحد هي من النموذج:

1. افتح مستودع النموذج وانقر على زر "Use this template"
2. في حقل اسم المستودع، اكتب .allstar
3. انقر على "Create repository from template"

يعمل هذا على تمكين جميع سياسات Allstar الحالية السياسات على جميع المستودعات باستخدام استراتيجية إلغاء الاشتراك، مع إجراء issue. يمكنك تغيير أي منها لاحقًا.

للتحكم الدقيق من البداية — اختيار استراتيجية الاشتراك أو إلغاء الاشتراك وكتابة ملفات السياسات الفردية بنفسك — اتبع تعليمات التثبيت اليدوي بدلاً من ذلك.

تشغيل Allstar كإجراء GitHub

يعمل هذا الخيار على تشغيل Allstar كوظيفة مجدولة باستخدام GitHub Actions، لذلك لا توجد بنية تحتية لتشغيلها تتجاوز GitHub نفسه.

اتبع تعليمات تثبيت GitHub Actions لإعداد إجراء متكرر في مستودع .allstar الخاص بك، وتقويته، ومراقبة نتائجه.

تشغيل Allstar كخدمة خلفية

يعمل هذا الخيار على تشغيل Allstar كعملية مستمرة، تكتشف وتحل الانتهاكات بشكل مستمر بدلاً من جدول زمني.

راجع تعليمات المشغل لتشغيل العملية، وإدارة الأسرار، وتحديد الحجم، والمتغيرات البيئية المتاحة.

الانتقال من التطبيق المستضاف

إذا كانت مؤسستك تستخدم التطبيق المستضاف من OpenSSF، فإن تكوينك ينتقل كما هو. مستودع التحكم .allstar، وallstar.yaml، وكل ملف سياسة يستمر في العمل دون تغيير؛ ما تستبدله هو فقط العملية التي تقرأها.

للانتقال:

1. أنشئ تطبيق GitHub الخاص بك وقم بتثبيته على مؤسستك بنفس وصول المستودع الذي كان للتطبيق المستضاف.
2. أبقِ مستودع .allstar الحالي كما هو تمامًا.
3. شغّل Allstar كإجراء أو كخدمة خلفية.
4. قم بإلغاء تثبيت allstar-app من مؤسستك، إذا كان لا يزال يظهر تحت الإعدادات -> تطبيقات GitHub.

تبقى المشكلات التي قدمها التطبيق المستضاف سابقًا في مستودعاتك. تحدد نسختك الخاصة مشكلاتها بنفس تسمية allstar (أو issueLabel المهيأ)، لذلك ستتبناها وتغلقها عند حل الانتهاكات، بدلاً من تقديم مشكلات مكررة.

السياسات والإجراءات

الإجراءات

يمكن تكوين كل سياسة بإجراء سيتخذه Allstar عندما يكتشف أن مستودعًا غير ملتزم.

• log: هذا هو الإجراء الافتراضي، ويحدث فعليًا لجميع الإجراءات. يتم تسجيل جميع نتائج وتفاصيل تشغيل السياسة. السجلات حاليًا مرئية فقط لمشغل التطبيق، وتتم مناقشة خطط لكشفها.
• issue: ينشئ هذا الإجراء مشكلة GitHub. يتم إنشاء مشكلة واحدة فقط لكل سياسة، ويصف النص تفاصيل انتهاك السياسة. إذا كانت المشكلة مفتوحة بالفعل، يتم تنبيهها بتعليق كل 24 ساعة بدون تحديثات (غير قابل للتكوين من قبل المستخدم حاليًا). إذا تغيرت نتيجة السياسة، سيتم ترك تعليق جديد على المشكلة وربطه في نص المشكلة. بمجرد معالجة الانتهاك، سيتم إغلاق المشكلة تلقائيًا بواسطة Allstar خلال 5-10 دقائق.
• fix: هذا الإجراء خاص بالسياسة. ستقوم السياسة بإجراء تغييرات على إعدادات GitHub لتصحيح انتهاك السياسة. لن تتمكن جميع السياسات من دعم هذا (انظر أدناه).

إجراءات مقترحة، ولكن لم يتم تنفيذها بعد. ستتم إضافة التعريفات في المستقبل.

• block: يمكن لـ Allstar تعيين فحص حالة GitHub وحظر أي طلب سحب في المستودع من الدمج إذا فشل الفحص.
• email: سيرسل Allstar بريدًا إلكترونيًا إلى مسؤولي المستودع.
• rpc: سيرسل Allstar استدعاء إجراء عن بعد إلى بعض الأنظمة الخاصة بالمؤسسة.

تكوين الإجراء

يتوفر إعدادان لتكوين إجراء المشكلة:

• issueLabel متاح على مستوى المؤسسة والمستودع. سيؤدي تعيينه إلى تجاوز التسمية الافتراضية allstar التي يستخدمها Allstar لتحديد مشكلاته.

• issueRepo متاح على مستوى المؤسسة. سيؤدي تعيينه إلى فرض إنشاء جميع المشكلات التي تم إنشاؤها في المؤسسة في المستودع المحدد.

السياسات

على غرار تكوين تمكين تطبيق Allstar، يتم تمكين جميع السياسات وتكوينها بملف yaml إما في مستودع .allstar الخاص بالمؤسسة، أو في دليل .allstar الخاص بالمستودع. كما هو الحال مع التطبيق، تكون السياسات اشتراكية افتراضيًا، كما أن إجراء log الافتراضي لن ينتج نتائج مرئية. طريقة بسيطة لتمكين جميع السياسات هي إنشاء ملف yaml لكل سياسة بالمحتوى التالي:```yaml optConfig: optOutStrategy: true action: issue

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

### حماية الفرع

ملف الإعداد لهذه السياسة يُسمى `branch_protection.yaml`، و[تعريفات الإعداد موجودة هنا](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/branch#OrgConfig).

تتحقق سياسة حماية الفرع من أن [إعدادات حماية الفرع في GitHub](https://docs.github.com/en/github/administering-a-repository/defining-the-mergeability-of-pull-requests/about-protected-branches) مُعدّة بشكل صحيح وفقًا للإعداد المحدد. سيصف نص المشكلة أي إعداد غير صحيح. راجع [توثيق GitHub](https://docs.github.com/en/github/administering-a-repository/defining-the-mergeability-of-pull-requests/about-protected-branches) لتصحيح الإعدادات.

سيقوم إجراء `fix` بتغيير إعدادات حماية الفرع لتتوافق مع إعداد السياسة المحدد.

### القطع الأثرية الثنائية

ملف الإعداد لهذه السياسة يُسمى `binary_artifacts.yaml`، و[تعريفات الإعداد موجودة هنا](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/binary#OrgConfig).

تتضمن هذه السياسة [الفحص من scorecard](https://github.com/ossf/scorecard/#scorecard-checks). قم بإزالة القطعة الأثرية الثنائية من المستودع لتحقيق الامتثال. نظرًا لأن نتائج scorecard قد تكون مطولة، قد تحتاج إلى تشغيل [scorecard نفسه](https://github.com/ossf/scorecard) لرؤية جميع المعلومات التفصيلية.

### CODEOWNERS

ملف الإعداد لهذه السياسة يُسمى `codeowners.yaml`، و[تعريفات الإعداد موجودة هنا](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/codeowners#OrgConfig).

تتحقق هذه السياسة من وجود [ملف `CODEOWNERS`](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) في مستودعاتك.

### المتعاونون الخارجيون

ملف الإعداد لهذه السياسة يُسمى `outside.yaml`، و[تعريفات الإعداد موجودة هنا](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/outside#OrgConfig).

تتحقق هذه السياسة مما إذا كان أي [متعاون خارجي](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/adding-outside-collaborators-to-repositories-in-your-organization) لديه صلاحيات مسؤول (افتراضيًا) أو صلاحيات دفع (اختياريًا) على المستودع. يجب أن يكون لأعضاء المؤسسة فقط هذه الصلاحيات، وإلا يمكن للأعضاء غير الموثوقين تغيير إعدادات مستوى المسؤول وارتكاب تعليمات برمجية خبيثة.

### SECURITY.md

ملف الإعداد لهذه السياسة يُسمى `security.yaml`، و[تعريفات الإعداد موجودة هنا](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/security#OrgConfig).

تتحقق هذه السياسة من أن المستودع يحتوي على ملف سياسة أمان في `SECURITY.md` وأنه ليس فارغًا. ستحتوي المشكلة المُنشأة على رابط إلى [تبويب GitHub](https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository) الذي يساعدك على إضافة سياسة أمان إلى مستودعك.

### سير العمل الخطير

ملف الإعداد لهذه السياسة يُسمى `dangerous_workflow.yaml`، و[تعريفات الإعداد موجودة هنا](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/workflow#OrgConfig).

سيتم تشغيل هذه السياسة على **جميع** الفروع، راجع الأساس المنطقي [هنا](https://github.com/ossf/allstar/issues/569).

تتحقق هذه السياسة من ملفات إعداد GitHub Actions workflow (`.github/workflows`)، بحثًا عن أي أنماط تطابق سلوكًا خطيرًا معروفًا. راجع [توثيق OpenSSF Scorecard](https://github.com/ossf/scorecard/blob/main/docs/checks.md#dangerous-workflow) لمزيد من المعلومات حول هذا الفحص.

### فحص Scorecard العام

ملف الإعداد لهذه السياسة يُسمى `scorecard.yaml`، و[تعريفات الإعداد موجودة هنا](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/scorecard#OrgConfig).

تشغّل هذه السياسة أي فحص scorecard مدرج في إعداد `checks`. يجب أن تحصل جميع الفحوصات المُشغّلة على درجة مساوية أو أعلى من إعداد `threshold`. يرجى الاطلاع على [توثيق OpenSSF Scorecard](https://github.com/ossf/scorecard/blob/main/docs/checks.md) لمزيد من المعلومات حول كل فحص.

#### رفع SARIF

يمكن لسياسة Scorecard اختياريًا رفع النتائج كـ [SARIF](https://sarifweb.azurewebsites.net/) إلى تبويب **Security > Code Scanning** في كل مستودع. يمنح هذا مسؤولي المؤسسة رؤية لنتائج Scorecard جنبًا إلى جنب مع أدوات الأمان الأخرى (CodeQL، Dependabot، إلخ) دون الحاجة إلى إعداد workflow لكل مستودع.

لتفعيل رفع SARIF، أضف حقل `upload` إلى ملف `scorecard.yaml` الخاص بك:```yaml
optConfig:
  optOutStrategy: true
action: issue
checks:
  - Binary-Artifacts
  - Signed-Releases
threshold: 8
upload:
  sarif: true

المتطلبات:

• يجب أن يمتلك تطبيق GitHub الخاص بـ Allstar صلاحية Code scanning alerts على مستوى المستودع مضبوطة على Read & write (نطاق API: security_events). هذه الصلاحية ليست من بين الصلاحيات التي يحتاجها Allstar عادةً، لذا أضفها إلى تطبيقك قبل تفعيل رفع SARIF.
• رفع SARIF غير حاجب: إذا فشل الرفع (مثلًا بسبب صلاحيات مفقودة)، يستمر فحص السياسة بشكل طبيعي.
• يكتشف اكتشاف التغييرات مقارنةً بـ SHA لرأس HEAD في المستودع ويتخطى الفحص والرفع عندما لا يكون المستودع قد دُفع إليه منذ آخر رفع.

يعمل رفع SARIF مع كلتا الطريقتين لتشغيل Allstar: كـ خادم خدمة أو كـ إجراء GitHub.

GitHub Actions

يُسمى ملف الإعداد لهذه السياسة actions.yaml، وتعريفات الإعداد موجودة هنا.

تفحص هذه السياسة ملفات إعداد سير عمل GitHub Actions (.github/workflows) (وتشغيلات سير العمل في بعض الحالات) في كل مستودع لضمان توافقها مع القواعد (مثل: تتطلب، تمنع) المحددة في إعداد السياسة على مستوى المؤسسة.

مسؤولو المستودعات

يُسمى ملف الإعداد لهذه السياسة admin.yaml، وتعريفات الإعداد موجودة هنا.

تتحقق هذه السياسة من أنه افتراضيًا يجب أن يكون لكل المستودعات مستخدم أو مجموعة معيّنة كمسؤول. وتتيح لك اختياريًا تكوين ما إذا كان يُسمح للمستخدمين بأن يكونوا مسؤولين (بدلاً من الفرق).

السياسات المستقبلية

• ضمان تفعيل dependabot.
• التحقق من أن التبعيات مثبتة/مجمدة.

مثال على مستودع الإعداد

انظر هذا المستودع كمثال على استخدام إعداد Allstar. بصفك مسؤول المؤسسة، فكّر في إضافة README.md يحتوي على بعض المعلومات حول كيفية استخدام Allstar في مؤسستك.

متقدم

تعريفات الإعداد

• إعداد التفعيل على مستوى المؤسسة
• إعداد تجاوز المستودع

موقع إعداد ثانوي على مستوى المؤسسة

افتراضيًا، يُتوقع أن تكون ملفات الإعداد على مستوى المؤسسة، مثل ملف allstar.yaml أعلاه، في مستودع .allstar. إذا لم يكن هذا المستودع موجودًا، فسيتم استخدام دليل allstar في مستودع .github كموقع ثانوي. للتوضيح، بالنسبة لـ allstar.yaml:

ينطبق هذا أيضًا على ملفات الإعداد على مستوى المؤسسة للسياسات الفردية، كما هو موضح أدناه.

إعدادات سياسات المستودع في مستودع المؤسسة

سيبحث Allstar أيضًا عن إعدادات السياسات على مستوى المستودع في مستودع .allstar الخاص بالمؤسسة، ضمن الدليل الذي يحمل نفس اسم المستودع. يُستخدم هذا الإعداد بغض النظر عما إذا كان "تجاوز المستودع" معطلاً أم لا.

على سبيل المثال، سيبحث Allstar عن إعداد السياسة لمستودع معين myapp بالترتيب التالي:

موقع الإعداد الأساسي والدمج على مستوى المؤسسة

بالنسبة لملفات إعداد Allstar والسياسات على مستوى المؤسسة، يمكنك تحديد الحقل baseConfig لتحديد مستودع آخر يحتوي على إعداد Allstar الأساسي. يُفسَّر هذا بشكل أفضل بمثال.

لنفترض أن لديك عدة مؤسسات GitHub، ولكنك تريد الحفاظ على إعداد واحد لـ Allstar. مؤسستك الرئيسية هي "acme"، ويحتوي المستودع acme/.allstar على allstar.yaml:```yaml optConfig: optOutStrategy: true issueLabel: allstar-acme issueFooter: Issue created by Acme security team.

You also have a satellite GitHub organization named "acme-sat". You want to
re-use the main config, but apply some changes on top by disabling Allstar on
certain repositories. The repository `acme-sat/.allstar` contains
`allstar.yaml`:

لديك أيضًا منظمة GitHub تابعة باسم "acme-sat". تريد إعادة استخدام
الإعداد الرئيسي، ولكن تطبيق بعض التغييرات فوقه عن طريق تعطيل Allstar على
مستودعات معينة. يحتوي المستودع `acme-sat/.allstar` على
`allstar.yaml`:```yaml
baseConfig: acme/.allstar
optConfig:
  optOutRepos:
  - acmesat-one
  - acmesat-two

سيستخدم هذا جميع الإعدادات من acme/.allstar كإعداد أساسي، ولكن بعد ذلك سيطبق أي تغييرات في الملف الحالي فوق الإعداد الأساسي. الطريقة التي يتم بها تطبيق ذلك موصوفة كـ JSON Merge Patch. يجب أن يكون baseConfig مستودع GitHub بصيغة <org>/<repository>.

المساهمة

راجع CONTRIBUTING.md