GuardDog

GuardDog هي أداة سطر أوامر (CLI) تحدد حزم PyPI و npm الخبيثة، ووحدات Go، وصناديق Rust، و RubyGems، وإجراءات GitHub، أو إضافات VSCode. تقوم بتحليل ثابت لشفرة مصدر الحزمة (عبر قواعد YARA) وتحلل بيانات الحزمة الوصفية لاكتشاف هجمات سلسلة التوريد.

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

يقوم بتنزيل وفحص الكود من:

• NPM: الحزم المستضافة في npmjs.org
• PyPI: ملفات المصدر (tar.gz) للحزم المستضافة في PyPI.org
• Go: ملفات مصدر GoLang للمستودعات المستضافة في GitHub.com
• Rust: الصناديق المستضافة على crates.io
• RubyGems: حزم Gem المستضافة في rubygems.org
• GitHub Actions: ملفات مصدر JavaScript للمستودعات المستضافة في GitHub.com
• VSCode Extensions: حزم الإضافات (.vsix) المستضافة في marketplace.visualstudio.com

كيف يعمل GuardDog

يستخدم GuardDog نموذج كشف قائم على المخاطر يربط قدرات الكود بمؤشرات التهديد:

1. الكشف: تحدد القواعد إما القدرات (ما يمكن أن يفعله الكود) أو التهديدات (المؤشرات المشبوهة)
2. الربط: تشكل القدرات والتهديدات الموجودة في نفس الملف مخاطر (تشكل المطابقات عبر الملفات أيضًا مخاطر، بدرجة خطورة مخفضة)
3. التسجيل: يتم تسجيل المخاطر (0-10) بناءً على اكتمال سلسلة الهجوم ودرجة تطوره
4. الإبلاغ: تحصل الحزم على تصنيف خطورة (منخفض/متوسط/مرتفع) مع تفصيل دقيق للمخاطر

لماذا هذا النهج؟

تقوم أدوات SAST التقليدية بوضع علامة على كل نمط مشبوه بشكل مستقل، مما يؤدي إلى إرهاق التنبيهات. يفهم GuardDog أن:

• القدرة وحدها ليست خبيثة (يجب أن تقوم مكتبات الشبكات بطلبات HTTP)
• مؤشرات التهديد وحدها قد تكون إيجابيات كاذبة (ملفات الاختبار، التوثيق)
• القدرة + التهديد معًا يشيران إلى خطر فعلي (كود يمكنه وسوف يفعل شيئًا خبيثًا)

تسجيل المخاطر

تحصل الحزم على درجة من 0-10 بناءً على أربعة عوامل:

العامل	الوزن	الوصف
الخطورة	30%	أعلى نتيجة خطورة (منخفض/متوسط/مرتفع)
سلسلة الهجوم	20%	وجود مراحل هجوم كاملة (مبكرة → متوسطة/متأخرة)
الخصوصية	30%	مدى خصوصية الأنماط للبرامج الضارة مقابل الكود الشرعي
التطور	20%	مستوى تقدم التقنية

تسميات الدرجات:

• 0: لا توجد مخاطر مكتشفة
• 0.1-3: خطر منخفض (تهديدات أحادية المرحلة، خصوصية منخفضة)
• 3.1-7.5: خطر متوسط (سلسلة هجوم جزئية، مؤشرات بيانات وصفية، أو نتائج كود أحادية المرحلة)
• 7.6-10: خطر مرتفع (سلسلة هجوم متعددة المراحل مع أدلة من الكود المصدري — شبه يقين بالاختراق)

مراحل سلسلة الهجوم (استنادًا إلى MITRE ATT&CK):

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

---

تحقق من التكامل الجديد مع Datadog Agent وحزمة محتوى Cloud SIEM content pack لـ GuardDog.

---

البدء

التثبيت

أسهل طريقة لتشغيل GuardDog هي استخدام uvx:

uvx guarddog pypi scan requests

لتثبيته محليًا:

uv tool install guarddog
# أو
pip install guarddog

أو استخدم صورة Docker:

docker pull ghcr.io/datadog/guarddog
alias guarddog='docker run --rm ghcr.io/datadog/guarddog'

ملاحظة: على Windows، طريقة التثبيت الوحيدة المدعومة هي Docker.

استخدامات نموذجية

# فحص أحدث إصدار من حزمة 'requests'
guarddog pypi scan requests

# فحص إصدار محدد من حزمة 'requests'
guarddog pypi scan requests --version 2.28.1

# فحص حزمة 'request' باستخدام قاعدتين محددتين
guarddog pypi scan requests --rules exec-base64 --rules code-execution

# فحص حزمة 'requests' باستخدام جميع القواعد باستثناء قاعدة واحدة
guarddog pypi scan requests --exclude-rules exec-base64

# فحص أرشيف حزمة محلي
guarddog pypi scan /tmp/triage.tar.gz

# فحص دليل حزمة محلي
guarddog pypi scan /tmp/triage/

# فحص حزمة مخزنة في S3 (مجلد/بادئة أو كائن أرشيف واحد)
guarddog pypi scan s3://my-bucket/path/to/package/
guarddog pypi scan s3://my-bucket/path/to/package.tar.gz

# فحص كل حزمة مشار إليها في ملف requirements.txt لمجلد محلي
guarddog pypi verify workspace/guarddog/requirements.txt

# فحص كل حزمة مشار إليها في ملف requirements.txt وإخراج ملف sarif - يعمل فقط مع verify
guarddog pypi verify --output-format=sarif workspace/guarddog/requirements.txt

# إخراج JSON إلى الإخراج القياسي - يعمل مع كل الأوامر
guarddog pypi scan requests --output-format=json

# جميع الأوامر تعمل أيضًا على npm و go و crates و rubygems
guarddog npm scan express

guarddog go scan github.com/DataDog/dd-trace-go

guarddog go verify /tmp/repo/go.mod

# فحص صناديق Rust
guarddog crates scan serde

guarddog crates verify /tmp/repo/Cargo.lock

# فحص حزم RubyGems
guarddog rubygems scan rails

guarddog rubygems verify /tmp/repo/Gemfile.lock

# يمكن أيضًا دعم فحص إجراءات GitHub المنفذة في JavaScript
guarddog github_action scan DataDog/synthetics-ci-github-action

guarddog github_action verify /tmp/repo/.github/workflows/main.yml

# فحص إضافات VSCode من السوق
guarddog extension scan ms-python.python

# فحص إصدار محدد من إضافة VSCode
guarddog extension scan ms-python.python --version 2023.20.0

# فحص دليل إضافة VSCode محلي أو أرشيف VSIX
guarddog extension scan /tmp/my-extension/

# التشغيل في وضع التصحيح
guarddog --log-level debug npm scan express

الفحص في بيئة معزولة (Sandbox)

عند فحص الحزم، يقوم GuardDog بتشغيل تحليل الكود المصدري داخل بيئة معزولة على مستوى النواة (Linux عبر Landlock، macOS عبر Seatbelt، باستخدام nono). تمنع البيئة المعزولة جميع الوصول إلى الشبكة وتقيد عمليات نظام الملفات فقط بالمسارات اللازمة للتحليل. يحمي هذا من الحزم الخبيثة التي تحاول تنفيذ كود أثناء استخراج الأرشيف أو الفحص.

افتراضيًا، البيئة المعزولة مطلوبة: إذا لم تكن متاحة على المنصة، يفشل الفحص بدلاً من التشغيل دون حماية. للفحص بدونها، يجب عليك تمرير --no-sandbox صراحةً:

# الافتراضي: يتطلب البيئة المعزولة، ويخرج بخطأ إذا كانت غير متاحة
guarddog pypi scan requests

# تعطيل البيئة المعزولة صراحةً
guarddog pypi scan requests --no-sandbox

بالنسبة للحزم البعيدة، تعمل ثلاث مراحل بمستويات امتياز مختلفة:

1. التنزيل وتحليل البيانات الوصفية يعملان بدون بيئة معزولة (يحتاجان إلى وصول للشبكة)
2. استخراج الأرشيف يعمل في عملية فرعية معزولة (الشبكة محظورة، نظام الملفات مقيد)
3. تحليل الكود المصدري (YARA) يعمل في العملية الرئيسية بعد تطبيق بيئة معزولة (الشبكة محظورة، نظام الملفات مقيد بالملفات المستخرجة)

تم تقديم البيئة المعزولة للتخفيف من ثغرات اجتياز المسار وتنفيذ الكود أثناء استخراج الأرشيف (CVE-2022-23530، CVE-2022-23531، CVE-2026-22870، CVE-2026-22871).

فحص الحزم من S3

يمكن لـ GuardDog فحص حزمة مخزنة في S3، إما كمجلد/بادئة أو كائن أرشيف واحد:

guarddog npm scan s3://my-bucket/path/to/package/
guarddog npm scan s3://my-bucket/path/to/package.tar.gz