كيف تقرأ تقرير CodeAuditAgent وتتصرف بناءً عليه

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

ما الذي يُدقَّق

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

ويعتمد مقدار ما يُقرأ من المستودع على خطتك. فالخطة المجانية تغطي مستودعًا واحدًا و3 عمليات تدقيق شهريًا وحتى 20 ملفًا لكل تدقيق. وخطة Starter، بسعر 49 دولارًا شهريًا، تغطي 5 مستودعات و50 عملية تدقيق و40 ملفًا لكل تدقيق. وخطة Pro، بسعر 199 دولارًا شهريًا، تغطي مستودعات بلا حدّ و500 عملية تدقيق و80 ملفًا لكل تدقيق. وتُتخطّى الملفات المفردة التي يتجاوز حجمها 60 كيلوبايت. وتُصفّر أعداد التدقيق الشهرية في بداية كل شهر تقويمي (بتوقيت UTC). كما أن المقتطف الملصوق طريقة سريعة لفحص ملف واحد يقلقك قبل تدقيق المستودع كله.

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

درجة المخاطر

في أعلى كل تقرير درجة مخاطر من 0 إلى 100؛ كما يذكر تصدير Markdown مستوى الخطورة الإجمالي بجوارها. وكلما ارتفعت الدرجة ارتفعت المخاطر. وهي ملخّص لنتائج ذلك التدقيق، مفيد لأمرين: تحديد مدى إلحاح النظر في مستودع، وتتبّع ما إذا كان يتحسن مع الوقت.

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

الخطورة والثقة

لكل نتيجة مستوى خطورة ومستوى ثقة. وهما يجيبان عن سؤالين مختلفين: الخطورة هي مدى سوء الأمر لو كانت النتيجة حقيقية، والثقة هي مدى يقين المراجع من أنها حقيقية.

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

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

تشريح النتيجة

تتبع كل نتيجة البنية نفسها، حتى تستطيع التحقق منها بترتيب ثابت.

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

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

--- a/app/api/invoices/[id]/route.ts
+++ b/app/api/invoices/[id]/route.ts
@@
-  const invoice = await db.invoice.findUnique({ where: { id } });
+  const invoice = await db.invoice.findFirst({
+    where: { id, userId: session.user.id },
+  });
   if (!invoice) return Response.json({ error: 'not_found' }, { status: 404 });

الملاحظات الإيجابية والخطوات التالية

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

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

سير عمل للفرز في الفرق الصغيرة

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

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

أسنِد كل نتيجة إلى مالك واحد. فالنتائج التي يتقاسمها الفريق كله تميل إلى ألا تخص أحدًا.

مستكشف النتائج وعمليات التصدير

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

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

أعد التدقيق لتأكيد الإصلاح

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

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

ما لا يغطيه التقرير

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

وباستخدامه على هذا النحو، يصير التقرير قائمة قصيرة مرتبة بالأولوية من التغييرات مع أدلة مرفقة. أصلح الحرجة، وافحص غير المؤكدة، وأعد التدقيق، وراقب الدرجة وهي تتحرك.