ماذا يحدث عند إيداع مفتاح API عن طريق الخطأ في مستودع الشيفرة: آليتا معالجة و5 ممارسات وقائية في ضوء تحديث ميزة فحص الأسرار في GitHub

ملاحظة الكاتب: ننطلق من آخر تحديث لكواشف GitHub secret scanning لنشرح ما يحدث عند إرسال مفتاح API إلى مستودع الشفرة عن طريق الخطأ، وما الذي يمكن أن يكشفه فحص المنصة، وما الحماية الإضافية التي يحتاج المطور إلى تطبيقها بنفسه.

في 5 نوفمبر 2026، نشر GitHub تحديثًا لخدمة secret scanning في سجل التغييرات: أصبحت SpaceX شريكًا جديدًا في فحص المفاتيح، وأُضيف كاشف لمفاتيح Starlink، كما أُضيفت آلية لتصفية الإنذارات الكاذبة إلى كواشف عدة جهات، منها Alibaba Cloud وAWS وGoogle وTencent Cloud. التحديث قصير، لكنه يطرح سؤالًا لم يفكر فيه كثير من المطورين بجدية: ماذا يحدث بالضبط بعد كتابة مفتاح API في الشفرة ودفعه إلى المستودع؟

هذا ليس تحذيرًا أمنيًا مبالغًا فيه؛ فالمعلومات الواردة في المقال تستند إلى سجل التغييرات الرسمي لـ GitHub. سنشرح آليتَي التعامل مع المفاتيح التي تكتشفها المنصة، وحدود التغطية، ثم نستعرض ممارسات الحماية اليومية لمفاتيح API الخاصة بنماذج الذكاء الاصطناعي، وخطوات التعامل مع تسربها.

ما ستستفيده: في 3 دقائق، ستفهم كيف تختلف طريقة تعامل GitHub secret scanning مع أنواع المفاتيح، وستعرف المخاطر التي تحتاج إلى الوقاية منها بنفسك، وستحصل على طريقة جاهزة لاستخدام متغيرات البيئة وقائمة للتعامل مع الطوارئ.

لمحة سريعة عن تحديث GitHub secret scanning

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

تفاصيل تحسين تصفية النتائج الإيجابية الكاذبة في secret scanning

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

تستحق فكرة «الإقران» بعض التوضيح. تتكون مفاتيح الوصول لدى مزودي الخدمات السحابية عادةً من معرّف مفتاح (Key ID) ومفتاح سري (Secret)، وغالبًا لا يكفي المعرّف وحده لتشكيل بيانات اعتماد كاملة. إذا كانت جميع «المفاتيح المصاحبة» الموجودة بالقرب منه مجرد كلمات عادية تبدو كسلاسل عشوائية، فمن المرجح أن المعرّف مجرد مثال أو تطابق بالمصادفة؛ ويساعد حجب التنبيه بشأنه على تقليل الضوضاء.

آليتان للتعامل مع إرسال مفتاح API بالخطأ

تتضمن ملاحظات التحديث توضيحًا مهمًا: عند العثور على مفتاح تابع لشريك في مستودع عام، يُبلَّغ الجهة التي أصدرته تلقائيًا؛ أما عند العثور على مفتاح مستخدم في مستودع عام أو خاص، فيُنشأ تنبيه من فحص الأسرار (secret scanning). والجهة المسؤولة عن المعالجة تختلف تمامًا بين المسارين.

توضيح الرسم: يعرض المخطط مسارَي الكشف على المنصة و«نقطة عمياء». في حالات مثل استدعاء نماذج الذكاء الاصطناعي، يُنصح بحفظ المفاتيح في متغيرات البيئة، ومتابعة الاستخدام مركزيًا عبر منصة تدعم إدارة الرموز الموحّدة مثل APIYI على apiyi.com، لتقليل الجهد اللازم لتتبّع المفاتيح الموزعة في أماكن متعددة.

مفاتيح الشركاء: تُحال إلى الجهة المصدرة

عندما يظهر مفتاح تابع لشريك مثل SpaceX في مستودع عام، يحيله GitHub إلى الشريك لإلغائه أو استبداله قبل إساءة استخدامه. وتمتاز هذه الآلية بأنها لا تعتمد على انتباه المطوّر؛ فحتى لو لم يلاحظ من أرسل المفتاح شيئًا، تتاح للجهة المصدرة فرصة للحد من الضرر سريعًا.

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

مفاتيح المستخدمين: تنبيه ينتظر معالجتك

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

حدود اكتشاف تسرّب مفاتيح API: ما الذي تستطيع المنصة حمايتك منه؟

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

الحد الأول هو قائمة الدعم. لم تسرد ملاحظات التغييرات هذه أنواع مفاتيح مزوّدي النماذج مثل OpenAI وAnthropic، ولم تتناول رموز منصات تجميع واجهات API المختلفة. ولمعرفة ما إذا كانت مدرجة في قائمة الدعم الكاملة لدى GitHub، يجب الرجوع إلى وثائقه؛ وإلى أن تتأكد، فمن الأسلم افتراض أنها «لن تُكتشف».

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

الحد الثالث هو سجل Git. عندما يكتشف كثيرون تسرّبًا، يكون رد فعلهم الأول حذف سطر الشفرة وإجراء عملية إيداع جديدة، لكن المفتاح يظل موجودًا في عمليات الإيداع القديمة. وحتى إذا أُعيدت كتابة السجل باستخدام أدوات مخصصة، فستبقى نسخ منه لدى من سبق لهم استنساخ المستودع. لذلك فالترتيب الصحيح هو «استبدال المفتاح أولًا، ثم تنظيف السجل».

دليل سريع لمنع تسرّب مفتاح API لنماذج الذكاء الاصطناعي

بالنسبة إلى التطبيقات التي تستدعي نماذج اللغة الكبيرة، تكون النتيجة المباشرة لتسرّب المفتاح غالبًا فاتورة غير متوقعة: يستخدم شخص آخر مفتاحك لإرسال عدد كبير من الطلبات، وتُحمّل التكلفة على حسابك. لنبدأ بأبسط طريقة لاستخدام متغيرات البيئة.

مثال مبسّط: قراءة مفتاح API من متغيرات البيئة

import os
import openai

client = openai.OpenAI(
    api_key=os.environ["APIYI_API_KEY"],      # قراءة المفتاح من متغيرات البيئة بدل كتابته مباشرة في الشفرة
    base_url="https://api.apiyi.com/v1"       # واجهة متوافقة مع OpenAI
)

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "你好"}]
)
print(resp.choices[0].message.content)

أضف أيضًا .env إلى ملف .gitignore في المجلد الجذر للمشروع، ووفّر ملف .env.example يحتوي على عناصر نائبة فقط ليستعين به المتعاونون. بذلك، حتى إذا نفّذ أحدهم git add . بالخطأ، فلن يدخل المفتاح الحقيقي إلى منطقة التجهيز.

import os
import logging
from typing import Optional

import openai
from dotenv import load_dotenv  # pip install python-dotenv

logging.basicConfig(level=logging.INFO)
load_dotenv()  # قراءة ملف .env المحلي؛ يُنصح باستخدام إدارة الأسرار في منصة النشر لبيئة الإنتاج


def mask_key(key: str) -> str:
    """الإبقاء على بضعة أحرف من بداية المفتاح ونهايته فقط لتجنب تسجيله كاملًا"""
    if len(key) <= 8:
        return "****"
    return f"{key[:4]}****{key[-4:]}"


def get_client() -> openai.OpenAI:
    api_key: Optional[str] = os.getenv("APIYI_API_KEY")
    if not api_key:
        raise RuntimeError("未找到 APIYI_API_KEY，请在环境变量或 .env 中配置")
    logging.info("使用密钥: %s", mask_key(api_key))
    return openai.OpenAI(
        api_key=api_key,
        base_url="https://api.apiyi.com/v1",
    )


def chat(prompt: str, model: str = "gpt-4o-mini", max_tokens: int = 500) -> str:
    client = get_client()
    try:
        resp = client.chat.completions.create(
            model=model,
            messages=[{"role": "user", "content": prompt}],
            max_tokens=max_tokens,
        )
        return resp.choices[0].message.content
    except openai.AuthenticationError:
        # يُنفّذ هذا الجزء عند إلغاء المفتاح أو تدويره، وينبّه إلى تحديث الإعدادات بدل طباعة المفتاح
        return "鉴权失败：密钥可能已失效，请检查并更新配置"
    except Exception as e:
        return f"调用失败: {type(e).__name__}"


if __name__ == "__main__":
    print(chat("用一句话解释什么是密钥轮换"))

🚀 البدء السريع: إذا كنت تعمل على نموذج أولي، يمكنك الحصول على مفتاح API ورصيد اختبار مجاني من APIYI عبر apiyi.com، ثم الاتصال مباشرة باستخدام متغير البيئة كما في المثال أعلاه. يتيح لك مفتاح واحد التبديل بين استدعاء نماذج شائعة مثل OpenAI وClaude وGemini، ما يقلّل أيضًا من عناء حفظ مفاتيح منفصلة لدى مزودين متعددين.

5 ممارسات يومية للحماية من تسرّب مفتاح API

أكثر ما يغفل عنه المبتدئون هو «تخصيص المفاتيح حسب الاستخدام» و«مراقبة الاستخدام». فإذا كان المشروع يستخدم مفتاحًا واحدًا لكل شيء وتسرّب هذا المفتاح، فقد تضطر إلى إيقاف الخدمة بالكامل لتغييره. أما عند فصل المفاتيح، فيكفي استبدال المفتاح المتأثر وحده.

التعامل مع تسرب مفتاح API وتحليل آثاره

إذا اكتشفت أن مفتاحًا قد أُرسل إلى المستودع، سواء من خلال تنبيه بفحص الأسرار، أو إشعار من الجهة المصدرة، أو أثناء مراجعة الشفرة بنفسك، فاتبع الخطوات التالية بالترتيب:

1. ألغِ صلاحية المفتاح القديم فورًا: احذف المفتاح المسرّب أو عطّله من لوحة تحكم الجهة التي أصدرته. هذه هي الخطوة الوحيدة التي توقف الضرر فعليًا.
2. أنشئ مفتاحًا جديدًا وحدّث النشر: أضف المفتاح الجديد إلى متغيرات البيئة أو نظام إدارة الأسرار، ثم أعد نشر الخدمة.
3. راجع الاستخدام والفواتير: تحقّق من وجود استدعاءات غير معتادة أو نماذج غير مألوفة أو ارتفاع مفاجئ في التكاليف خلال فترة التسرب.
4. نظّف سجل Git: بعد استبدال المفتاح، استخدم أداة لإعادة كتابة السجل وتنظيف الالتزامات القديمة، وأبلغ المتعاونين بضرورة استنساخ المستودع مجددًا.
5. راجع الحادث وعزّز الحماية: أضف تدابير مثل .gitignore والفحص قبل الالتزام، لمنع تكرار المشكلة.

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

التأثير على المطورين

• تحسين جودة التنبيهات: تجعل تصفية الإنذارات الكاذبة التنبيهات المتعلقة ببيانات اعتماد الخدمات السحابية الشائعة، مثل AWS وAlibaba Cloud وTencent Cloud، أكثر موثوقية، وتشجع الفرق على التعامل بجدية مع كل تنبيه.
• لا تعتمد على الاكتشاف كخط دفاع أخير: عليك التحقق بنفسك مما إذا كانت مفاتيح نماذج الذكاء الاصطناعي مدرجة في قائمة الأنواع المدعومة. وإلى أن تتأكد، افترض أن «المنصة لن تكتشفها نيابة عنك».
• يجب تصحيح ترتيب المعالجة: استبدل المفتاح أولًا، ثم نظّف السجل، بدلًا من الاكتفاء بحذف الشفرة.

التأثير على القطاع

• استمرار توسّع برنامج الشركاء: من مزودي الخدمات السحابية إلى جهات جديدة مثل SpaceX، يزداد عدد مقدمي الخدمات الراغبين في الانضمام إلى آلية «الاكتشاف ثم الإبلاغ فورًا»، ما قد يواصل تقليص مدة انكشاف المفاتيح في المستودعات العامة.
• الانتقال من كثرة التنبيهات إلى دقتها: تركز معظم التغييرات الأخيرة على تقليل الإنذارات الكاذبة، ما يشير إلى أن المنصة بدأت تولي اهتمامًا أكبر لقابلية التنبيهات للمعالجة، إلى جانب توسيع نطاق التغطية.

الأسئلة الشائعة FAQ

أبرز النقاط حول تسرّب مفاتيح API وفحص الأسرار في GitHub

• آليتان مختلفتان: تُحال مفاتيح الشركاء المكتشفة في المستودعات العامة إلى الجهات التي أصدرتها، بينما تُنشأ تنبيهات لمفاتيح المستخدمين لتتولى معالجتها.
• التحديث الأخير: انضمت SpaceX كشريك، وأضافت أدوات الكشف لست جهات مرشحات للإنذارات الكاذبة، ما جعل التنبيهات أكثر دقة.
• حدود الكشف: لا يمكن التعرّف على المفاتيح غير المدرجة في قائمة الدعم، كما لا يشمل الفحص ملفات الواجهة الأمامية الناتجة أو السجلات أو لقطات الشاشة.
• النافذة الزمنية: يقلّل الفحص مدة انكشاف المفتاح، لكنه لا يسترد المفاتيح التي جُمعت بالفعل.
• ترتيب المعالجة: ألغِ المفتاح وغيّره أولًا، ثم تحقّق من الاستخدام، وأخيرًا نظّف سجل Git.
• طريقة البدء: استخدم متغيرات البيئة لإدارة المفاتيح التي تحصل عليها عبر APIYI apiyi.com، وافصل المفاتيح حسب البيئة وراقب الاستخدام.

الخلاصة

يكشف تحديث فحص الأسرار في GitHub عن ثلاث نقاط:

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

إذا كنت تعمل على دمج نماذج اللغة الكبيرة في تطبيقاتك، فالخيار الأكثر عملية هو إدارة المفاتيح باستخدام متغيرات البيئة منذ أول سطر برمجي، وتخصيص مفتاح مستقل لكل بيئة. يمكنك تجربة هذا الأسلوب بسرعة عبر APIYI apiyi.com؛ إذ يتيح لك مفتاح واحد استدعاء نماذج رائدة من عدة مزودين، كما تسهّل الإدارة المركزية مراجعة الاستخدام.

📚 المراجع

1. سجل تغييرات GitHub – ترقية أدوات كشف الأسرار وإضافة SpaceX شريكًا: الإعلان الرسمي عن هذا التحديث
2. الرابط: github.blog/changelog/2026-11-05-secret-scanning-upgrades-detectors-adds-spacex-as-partner

3. التفاصيل: يتضمن القائمة الكاملة للشركاء وأدوات الكشف الجديدة، والتحسينات على تصفية النتائج الإيجابية الكاذبة

4. وثائق GitHub – فحص الأسرار: شرح الميزة وقائمة العناصر المدعومة كاملةً

5. الرابط: docs.github.com/code-security/secret-scanning
6. التفاصيل: للتحقق من دعم نوع معين من المفاتيح وشروط تفعيل التنبيهات

الكاتب: الفريق التقني في APIYI
للتواصل التقني: تواصلوا معنا عبر الصفحة الرئيسية لموقع APIYI لمعرفة المزيد عن إدارة الرموز المميزة ومتابعة الاستخدام