guarddog

# GuardDog

[![Test](https://github.com/DataDog/guarddog/actions/workflows/checks.yml/badge.svg)](https://github.com/DataDog/guarddog/actions/workflows/checks.yml)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/DataDog/guarddog/badge)](https://securityscorecards.dev/viewer/?uri=github.com/DataDog/guarddog)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/12273/badge)](https://www.bestpractices.dev/projects/12273)

<p align="center">
  <img src="https://raw.githubusercontent.com/DataDog/guarddog/v3/docs/images/logo.png?raw=true" alt="GuardDog" width="300" />
</p>

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

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

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

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

![استخدام GuardDog التجريبي](https://raw.githubusercontent.com/DataDog/guarddog/v3/docs/images/demo.png?raw=true)

## كيف يعمل 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):
- **مبكرة**: الوصول الأولي، قدرات التنفيذ
- **متوسطة**: الثبات، التهرب من الدفاع، الوصول إلى بيانات الاعتماد
- **متأخرة**: القيادة والتحكم، استخراج البيانات، التأثير
---
### تحقق من [التكامل](https://docs.datadoghq.com/integrations/guarddog/) الجديد مع Datadog Agent وحزمة محتوى Cloud SIEM [content pack](https://app.datadoghq.com/security/siem/content-packs?query=guarddog) لـ GuardDog.
---

## البدء

### التثبيت

أسهل طريقة لتشغيل GuardDog هي استخدام [`uvx`](https://docs.astral.sh/uv/guides/tools/):

```sh
uvx guarddog pypi scan requests
```

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

```sh
uv tool install guarddog
# أو
pip install guarddog
```

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

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

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

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

```sh
# فحص أحدث إصدار من حزمة '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](https://github.com/always-further/nono-py)). تمنع البيئة المعزولة جميع الوصول إلى الشبكة وتقيد عمليات نظام الملفات فقط بالمسارات اللازمة للتحليل. يحمي هذا من الحزم الخبيثة التي تحاول تنفيذ كود أثناء استخراج الأرشيف أو الفحص.

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

```sh
# الافتراضي: يتطلب البيئة المعزولة، ويخرج بخطأ إذا كانت غير متاحة
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، إما كمجلد/بادئة أو كائن أرشيف واحد:

```sh
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 نوعين من قواعد الكشف، وكلاهما يشارك في محرك التسجيل القائم على المخاطر:

* **قواعد الكود المصدري** (YARA): تحليل ثابت لشفرة مصدر الحزمة يكشف القدرات والتهديدات
* **قواعد البيانات الوصفية** (كاشفات Python): تحليل بيانات الحزمة الوصفية من السجل يكشف مؤشرات هجمات سلسلة التوريد

للقائمة الكاملة للقواعد لكل نظام بيئي، راجع **[RULES.md](https://github.com/datadog/guarddog/blob/v3/RULES.md)**.

للإرشادات حول كتابة قواعد جديدة، راجع **[WRITING_RULES.md](https://github.com/datadog/guarddog/blob/v3/WRITING_RULES.md)**.

## تشغيل GuardDog في إجراء GitHub

أسهل طريقة لدمج GuardDog في خط أنابيب CI الخاص بك هي الاستفادة من تنسيق إخراج SARIF، ورفعه إلى ميزة [code scanning](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning) في GitHub.

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

إجراء GitHub نموذجي باستخدام GuardDog:

```yaml
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
```


## التطوير

### تشغيل نسخة محلية من GuardDog

* تأكد من أن poetry لديه بيئة مع `python >=3.10` `poetry env use 3.10.0`
* تثبيت التبعيات `poetry install`
* تشغيل guarddog `poetry run guarddog` أو `poetry shell` ثم تشغيل `guarddog`

### اختبارات الوحدة

تشغيل جميع اختبارات الوحدة: `make test`

تشغيل اختبارات الوحدة ضد استدلالات البيانات الوصفية للحزم: `make test-metadata-rules` (الاختبارات [هنا](https://github.com/DataDog/guarddog/tree/v3/tests/analyzer/metadata)).

### قياس الأداء

يمكنك تشغيل GuardDog على حزم شرعية وخبيثة لتحديد الإيجابيات الكاذبة والسلبيات الكاذبة. راجع [./tests/samples](https://github.com/datadog/guarddog/blob/v3/tests/samples)

### فحوصات جودة الكود

شغّل مدقق الأنواع باستخدام
```shell
mypy --install-types --non-interactive guarddog
```
والمدقق اللغوي باستخدام
```shell
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 |

## المشرفون

* [Sebastian Obregoso](https://www.linkedin.com/in/sebastianobregoso/)
* [Ian Kretz](https://github.com/ikretz)
* [Tesnim Hamdouni](https://github.com/tesnim5hamdouni)

## المؤلفون
* [Ellen Wang](https://www.linkedin.com/in/ellen-wang-4bb5961a0/)
* [Christophe Tafani-Dereeper](https://github.com/christophetd)

## الإقرارات

الإلهام:
* [Backstabber’s Knife Collection: A Review of Open Source Software Supply Chain Attacks](https://arxiv.org/pdf/2005.09535)
* [What are Weak Links in the npm Supply Chain?](https://arxiv.org/pdf/2112.10165.pdf)
* [A Survey on Common Threats in npm and PyPi Registries](https://arxiv.org/pdf/2108.09576.pdf)
* [A Benchmark Comparison of Python Malware Detection Approaches](https://arxiv.org/pdf/2209.13288.pdf)
* [Towards Measuring Supply Chain Attacks on Package Managers for Interpreted Languages](https://arxiv.org/pdf/2002.01139)