datadog/guarddog🐍 🔍 GuardDog هي أداة CLI لتحديد حزم PyPI وnpm الخبيثة
GuardDog هي أداة سطر أوامر (CLI) تحدد حزم PyPI و npm الخبيثة، ووحدات Go، وصناديق Rust، و RubyGems، وإجراءات GitHub، أو إضافات VSCode. تقوم بتحليل ثابت لشفرة مصدر الحزمة (عبر قواعد YARA) وتحلل بيانات الحزمة الوصفية لاكتشاف هجمات سلسلة التوريد.
ما الذي يجعل GuardDog مختلفًا: بدلاً من مجرد سرد الأنماط المشبوهة، يقوم GuardDog بربط النتائج لتحديد المخاطر الفعلية بناءً على سلاسل الهجوم. تحتاج الحزمة إلى كل من القدرة على تنفيذ إجراء (مثل الوصول إلى الشبكة) ومؤشر تهديد (مثل نطاق مشبوه) في نفس الملف ليتم تصنيفها على أنها عالية الخطورة.
يقوم بتنزيل وفحص الكود من:
يستخدم GuardDog نموذج كشف قائم على المخاطر يربط قدرات الكود بمؤشرات التهديد:
تقوم أدوات SAST التقليدية بوضع علامة على كل نمط مشبوه بشكل مستقل، مما يؤدي إلى إرهاق التنبيهات. يفهم GuardDog أن:
تحصل الحزم على درجة من 0-10 بناءً على أربعة عوامل:
| العامل | الوزن | الوصف |
|---|---|---|
| الخطورة | 30% | أعلى نتيجة خطورة (منخفض/متوسط/مرتفع) |
| سلسلة الهجوم | 20% | وجود مراحل هجوم كاملة (مبكرة → متوسطة/متأخرة) |
| الخصوصية | 30% | مدى خصوصية الأنماط للبرامج الضارة مقابل الكود الشرعي |
| التطور | 20% | مستوى تقدم التقنية |
تسميات الدرجات:
مراحل سلسلة الهجوم (استنادًا إلى MITRE ATT&CK):
أسهل طريقة لتشغيل 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
عند فحص الحزم، يقوم GuardDog بتشغيل تحليل الكود المصدري داخل بيئة معزولة على مستوى النواة (Linux عبر Landlock، macOS عبر Seatbelt، باستخدام nono). تمنع البيئة المعزولة جميع الوصول إلى الشبكة وتقيد عمليات نظام الملفات فقط بالمسارات اللازمة للتحليل. يحمي هذا من الحزم الخبيثة التي تحاول تنفيذ كود أثناء استخراج الأرشيف أو الفحص.
افتراضيًا، البيئة المعزولة مطلوبة: إذا لم تكن متاحة على المنصة، يفشل الفحص بدلاً من التشغيل دون حماية. للفحص بدونها، يجب عليك تمرير --no-sandbox صراحةً:
# الافتراضي: يتطلب البيئة المعزولة، ويخرج بخطأ إذا كانت غير متاحة
guarddog pypi scan requests
# تعطيل البيئة المعزولة صراحةً
guarddog pypi scan requests --no-sandbox
بالنسبة للحزم البعيدة، تعمل ثلاث مراحل بمستويات امتياز مختلفة:
تم تقديم البيئة المعزولة للتخفيف من ثغرات اجتياز المسار وتنفيذ الكود أثناء استخراج الأرشيف (CVE-2022-23530، CVE-2022-23531، CVE-2026-22870، CVE-2026-22871).
يمكن لـ GuardDog فحص حزمة مخزنة في S3، إما كمجلد/بادئة أو كائن أرشيف واحد:
guarddog npm scan s3://my-bucket/path/to/package/
guarddog npm scan s3://my-bucket/path/to/package.tar.gz
يستخدم هذا بيانات اعتماد AWS الحالية لديك (متغيرات البيئة، ~/.aws، SSO، أو دور IAM). يتحقق GuardDog من المصادقة عبر STS قبل القيام بأي شيء ويخرج بخطأ إذا لم يتم العثور على بيانات اعتماد صالحة. تتم مزامنة الكائنات إلى دليل مؤقت، ويتم فحصها تحت البيئة المعزولة مثل أي محتوى غير موثوق، وتتم إزالتها من القرص بعد ذلك.
يستخدم GuardDog نوعين من قواعد الكشف، وكلاهما يشارك في محرك التسجيل القائم على المخاطر:
للقائمة الكاملة للقواعد لكل نظام بيئي، راجع RULES.md.
للإرشادات حول كتابة قواعد جديدة، راجع WRITING_RULES.md.
أسهل طريقة لدمج GuardDog في خط أنابيب CI الخاص بك هي الاستفادة من تنسيق إخراج SARIF، ورفعه إلى ميزة code scanning في GitHub.
باستخدام هذا، تحصل على:
إجراء GitHub نموذجي باستخدام GuardDog:
name: GuardDog
on:
push:
branches:
- main
pull_request:
branches:
- main
permissions:
contents: read
jobs:
guarddog:
permissions:
contents: read # for actions/checkout to fetch code
security-events: write # for github/codeql-action/upload-sarif to upload SARIF results
name: Scan dependencies
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v7
- run: uvx guarddog pypi verify requirements.txt --output-format sarif --exclude-rules repository_integrity_mismatch > guarddog.sarif
- name: Upload SARIF file to GitHub
uses: github/codeql-action/upload-sarif@v3
with:
category: guarddog-builtin
sarif_file: guarddog.sarif
python >=3.10 poetry env use 3.10.0poetry installpoetry run guarddog أو poetry shell ثم تشغيل guarddogتشغيل جميع اختبارات الوحدة: make test
تشغيل اختبارات الوحدة ضد استدلالات البيانات الوصفية للحزم: make test-metadata-rules (الاختبارات هنا).
يمكنك تشغيل GuardDog على حزم شرعية وخبيثة لتحديد الإيجابيات الكاذبة والسلبيات الكاذبة. راجع ./tests/samples
شغّل مدقق الأنواع باستخدام
mypy --install-types --non-interactive guarddog
والمدقق اللغوي باستخدام
flake8 guarddog --count --select=E9,F63,F7,F82 --show-source --statistics --exclude tests/analyzer/sourcecode,tests/analyzer/metadata/resources,evaluator/data
flake8 guarddog --count --max-line-length=120 --statistics --exclude tests/analyzer/sourcecode,tests/analyzer/metadata/resources,evaluator/data --ignore=E203,W503
يمكن تخصيص سلوك GuardDog باستخدام متغيرات البيئة:
| متغير البيئة | الوصف | القيمة الافتراضية |
|---|---|---|
GUARDDOG_PARALLELISM | عدد الخيوط المستخدمة للمعالجة المتوازية | عدد وحدات المعالجة المركزية المتاحة |
GUARDDOG_VERIFY_EXHAUSTIVE_DEPENDENCIES | تحليل جميع الإصدارات الممكنة من التبعيات (true/false) | false |
GUARDDOG_NPM_INCLUDE_DEV_DEPENDENCIES | تضمين devDependencies عند فحص ملفات npm package.json (true/false)؛ يمكن أيضًا تبديله لكل استدعاء باستخدام guarddog npm verify --include-dev-dependencies | false |
GUARDDOG_TOP_PACKAGES_CACHE_LOCATION | موقع دليل ذاكرة التخزين المؤقت للحزم الأعلى | guarddog/analyzer/metadata/resources |
GUARDDOG_YARA_EXT_EXCLUDE | قائمة مفصولة بفواصل لامتدادات الملفات المستبعدة من فحص YARA | ini,md,rst,txt,lock,json,yaml,yml,toml,xml,html,csv,sql,pdf,doc,docx,ppt,pptx,xls,xlsx,odt,changelog,readme,makefile,dockerfile,pkg-info,d.ts |
| متغير البيئة | الوصف | القيمة الافتراضية |
|---|---|---|
GUARDDOG_NEW_DEPENDENCY_RISK_THRESHOLD | الحد الأدنى لدرجة المخاطر لتبعية مضافة حديثًا لتمييز الحزمة الأصلية في قاعدة risky_new_dependency | 5.0 |
ينفذ GuardDog فحوصات أمنية متعددة عند استخراج أرشيفات الحزم للحماية من قنابل الضغط وهجمات استنفاد واصفات الملفات:
| متغير البيئة | الوصف | القيمة الافتراضية |
|---|---|---|
GUARDDOG_MAX_UNCOMPRESSED_SIZE | الحد الأقصى المسموح به للحجم غير المضغوط بالبايت (يمنع استنفاد مساحة القرص) | 2147483648 (2 جيجابايت) |
GUARDDOG_MAX_COMPRESSION_RATIO | الحد الأقصى المسموح به لنسبة الضغط (يكتشف أنماط الضغط المشبوهة) | 100 (100:1) |
GUARDDOG_MAX_FILE_COUNT | الحد الأقصى لعدد الملفات المسموح به في الأرشيف (يمنع استنفاد واصفات الملفات/inodes) | 100000 |
الإلهام: