nuguard

# NuGuard مفتوح المصدر

NuGuard هي مجموعة أدوات أمان مفتوحة المصدر لتطبيقات الذكاء الاصطناعي. هدفها هو توفير أوسع نطاق من اختبارات الاختراق (redteaming) والتحقق السلوكي لتطبيقات الذكاء الاصطناعي العاملة بالوكالة (Agentic AI).

باستخدام NuGuard، يمكن لمطوري الذكاء الاصطناعي التركيز على بناء تطبيقاتهم بينما تقوم NuGuard باختبارها والتحقق منها باستمرار ضد مجموعة واسعة من المخاطر الأمنية، بما في ذلك هجمات سلسلة التوريد، وحقن المطالبات (prompt injection)، وإساءة استخدام أدوات MCP، وهجمات API، وسرقة البيانات، وغيرها. تتيح NuGuard للمطورين تسريع سير عملهم الأمني والوصول إلى مرحلة الإنتاج بثقة أكبر.

تتوفر نسخة تجارية من NuGuard كمنتج SaaS بميزات ودعم إضافيين، يمكنك الاطلاع عليها على http://nuguard.ai.

## ما الذي يفعله

- إنشاء AI-SBOM من قاعدة بيانات محلية أو مستودع Git
- تحليل AI-SBOM للكشف عن المخاطر الأمنية الهيكلية للذكاء الاصطناعي ومشكلات سلسلة التوريد
- اقتراح سياسة سلوكية للذكاء الاصطناعي بناءً على AI-SBOM
- إجراء اختبارات سلوكية ثابتة وديناميكية مصممة خصيصًا حول AI-SBOM والسياسة السلوكية
- إجراء اختبار اختراق (red-teaming) لتطبيق ذكاء اصطناعي معزول: أحدث وأوسع كتالوج لناقلات الهجوم بالإضافة إلى سيناريوهات مخصصة. يشمل ذلك حقن المطالبات، وإساءة استخدام الأدوات، وسرقة البيانات، وسيناريوهات هجوم ذات صلة تختبر مختلف الوكلاء الفرعيين والأدوات والقدرات للنظام المستهدف.
- اقتراحات تلقائية لمعالجة النتائج، بما في ذلك مقتطفات التعليمات البرمجية وتعديلات السياسة
- تصدير النتائج بصيغ النص و JSON و Markdown وسير العمل الموجهة لـ SARIF

## واجهة سطر الأوامر الحالية

منفذة وقابلة للاستخدام الآن:

- `nuguard sbom`
- `nuguard analyze`
- `nuguard scan`
- `nuguard policy`
- `nuguard behavior`
- `nuguard redteam`

## المتطلبات

- Python 3.12+
- `uv` لسير العمل المحلي الموصى به

## التثبيت

**واجهة سطر الأوامر بايثون:**

```bash
pip install nuguard
```

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

```bash
uv sync --dev
```

تشغيل واجهة سطر الأوامر بـ:

```bash
uv run nuguard --help
```

أو، من البيئة الافتراضية:

```bash
. .venv/bin/activate
nuguard --help
```

### يمكن لمستخدمي Claude استخدام أوامر الإضافات.
اتبع التعليمات في [docs/plugin-guide.md](https://github.com/nuguardai/nuguard/blob/develop/docs/plugin-guide.md) لإعداد إضافة NuGuard لـ Claude واستخدامها لتشغيل أوامر مثل `/nuguard-sbom` و `/nuguard-analyze` و `/nuguard-redteam` مباشرة من محادثاتك مع Claude.

## بداية سريعة

### 1. إنشاء AI-SBOM

```bash
nuguard sbom generate --source . --output app.sbom.json
```

يمكنك أيضًا فحص مستودع عن بُعد:

```bash
nuguard sbom generate \
  --from-repo https://github.com/org/repo \
  --ref main \
  --output app.sbom.json
```

### 2. تشغيل التحليل الثابت

```bash
nuguard analyze --sbom app.sbom.json --format markdown
```

المخرجات النموذجية:

- `markdown` للمراجعة البشرية
- `json` للأتمتة
- `sarif` لخطوط مسح الكود

### 3. الاختبارات السلوكية

```bash
nuguard behavior \
  --sbom app.sbom.json \
  --target http://localhost:3000 \
  --format markdown
```

### 4. اختبار اختراق تطبيق مباشر (Red-Team)

```bash
nuguard redteam \
  --config nuguard.yaml \
  --output reports/redteam.md \
  --format markdown
```

لتغطية أكثر شمولاً لاختبار الاختراق (red-team)، يمكنك أيضًا توفير:

- سياسة معرفية باستخدام `--policy`
- قيم canary باستخدام `--canary`
- ملف إعدادات باستخدام `--config`

### 5. تشغيل خط الأنابيب الموحد

```bash
nuguard scan \
  --source . \
  --output-dir nuguard-reports
```

افتراضيًا، يقوم هذا بتشغيل إنشاء AI-SBOM بالإضافة إلى التحليل الثابت في مسار واحد. لتضمين عمليات التحقق من السياسة واختبار الاختراق، قم بتفعيل تلك الخطوات وتوفير المدخلات المطلوبة:

```bash
nuguard scan \
  --source . \
  --steps sbom,analyze,policy,redteam \
  --policy cognitive_policy.md \
  --target http://localhost:3000 \
  --output-dir nuguard-reports
```

## الإعدادات

يدعم NuGuard إعدادات المشروع من خلال `nuguard.yaml`. يوجد مثال جاهز للتعديل في [`nuguard.yaml.example`](https://github.com/nuguardai/nuguard/blob/develop/nuguard.yaml.example).

المجالات الرئيسية في مثال الإعدادات:

- `sbom`: مسار AI-SBOM الحالي
- `source`: دليل المصدر للإنشاء
- `policy`: مسار السياسة المعرفية
- `llm`: إعدادات النموذج للميزات المدعومة بنماذج لغوية كبيرة
- `behavior`: عنوان URL الهدف، نقطة النهاية، وإعدادات ملف تعريف الاختبار للاختبارات السلوكية
- `redteam`: عنوان URL الهدف، نقطة النهاية، ملف canary، ملفات التعريف، مرشحات السيناريو، إعدادات المحادثة الموجهة، وضوابط تشغيل النتائج (`finding_triggers.*`)
- `analyze`: الحد الأدنى لمستوى الخطورة
- `database`: إعدادات التخزين المدعومة بـ SQLite أو Postgres
- `output`: تنسيق الإخراج وعتبة الفشل

تتجاوز خيارات سطر الأوامر إعدادات `nuguard.yaml`، التي تتجاوز متغيرات البيئة والإعدادات الافتراضية المضمنة.

## Canary لاختبار الاختراق

يمكن لـ NuGuard مراقبة قيم canary المزروعة أثناء الاختبار الديناميكي لإنتاج نتائج عالية الثقة حول سرقة البيانات. ابدأ من [`canary.example.json`](https://github.com/nuguardai/nuguard/blob/develop/canary.example.json)، وأنشئ ملف `canary.json` المحلي الخاص بك، وقم بزرع تلك القيم في النظام المستهدف، ثم وجه `nuguard redteam` إلى ذلك الملف باستخدام `--canary`.

مزيد من التفاصيل متوفرة في [`docs/redteam-engine.md`](https://github.com/nuguardai/nuguard/blob/develop/docs/redteam-engine.md).

## التطوير

تثبيت تبعيات التطوير:

```bash
make dev
```

تشغيل الاختبارات:

```bash
make test
```

تشغيل فحص الجودة (linting) والتحقق من الأنواع:

```bash
make lint
```

تنسيق قاعدة الكود:

```bash
make fmt
```

## النشر

يتضمن هذا المستودع سير عمل GitHub Actions للنشر الموثوق (Trusted Publishing) إلى TestPyPI و PyPI:

- [publish-testpypi.yml](https://github.com/nuguardai/nuguard/blob/develop/.github/workflows/publish-testpypi.yml)
- [publish-pypi.yml](https://github.com/nuguardai/nuguard/blob/develop/.github/workflows/publish-pypi.yml)

قبل أن تتمكن سير العمل من النشر، قم بتكوين الناشرين الموثوقين (Trusted Publishers) في TestPyPI و PyPI لمشروع `nuguard` بـ:

- owner/org: `NuGuardAI`
- repository: `nuguard`
- workflow file: `publish-testpypi.yml` أو `publish-pypi.yml`
- environment: `testpypi` أو `pypi`

سير العمل الموصى به للإصدار:

1. قم بتشغيل سير عمل TestPyPI يدويًا من GitHub Actions.
2. تحقق من تثبيت الحزمة وسلوك واجهة سطر الأوامر من TestPyPI.
3. أنشئ إصدارًا على GitHub لتشغيل سير عمل نشر PyPI.

### فحوصات السلامة قبل النشر

قبل النشر إلى TestPyPI أو PyPI، قم بتشغيل بوابة السلامة السريعة متعددة التطبيقات.

مشغل مرة واحدة:

```bash
bash tests/apps/prepublish-sanity.sh
```

يقوم هذا المشغل بـ:

- فحص سريع للتطبيق (`nuguard --help` بالإضافة إلى اختبارات محلية حرجة)
- تشغيل سلوكي في الوضع الديناميكي مع سير عمل `intent_happy_path`
- تشغيل اختبار اختراق مع `profile: ci`
- بوابات الجودة والقطع الأثرية (تقارير غير فارغة، سيناريوهات منفذة غير صفرية، فحوصات صارمة للمصدر ونقطة النهاية، وحواجز حماية من أخطاء النقل)

ملفات الإعدادات قبل النشر التي يستخدمها المشغل:

- `tests/apps/openai-cs-agents-demo/nuguard.prepublish.yaml`
- `tests/apps/Gemini-Auto-app/nuguard.prepublish.yaml`
- `tests/apps/pinnacle-bank-app/nuguard-azure.prepublish.yaml`

تشغيل يدويًا لكل تطبيق (إذا لزم الأمر):

```bash
# OpenAI CS agents demo
uv run nuguard sbom generate --config tests/apps/openai-cs-agents-demo/nuguard.prepublish.yaml --format json -o tests/apps/openai-cs-agents-demo/openai-cs.sbom.json
uv run nuguard behavior --config tests/apps/openai-cs-agents-demo/nuguard.prepublish.yaml --mode dynamic --format json --format markdown --output tests/apps/openai-cs-agents-demo/reports/openai-cs-prepublish-behavior --verbose
uv run nuguard redteam --config tests/apps/openai-cs-agents-demo/nuguard.prepublish.yaml --format json --format markdown --output tests/apps/openai-cs-agents-demo/reports/openai-cs-prepublish-redteam --verbose

# Gemini Auto app
uv run nuguard sbom generate --config tests/apps/Gemini-Auto-app/nuguard.prepublish.yaml --format json -o tests/apps/Gemini-Auto-app/gemini-auto.sbom.json
uv run nuguard behavior --config tests/apps/Gemini-Auto-app/nuguard.prepublish.yaml --mode dynamic --format json --format markdown --output tests/apps/Gemini-Auto-app/reports/gemini-auto-prepublish-behavior --verbose
uv run nuguard redteam --config tests/apps/Gemini-Auto-app/nuguard.prepublish.yaml --format json --format markdown --output tests/apps/Gemini-Auto-app/reports/gemini-auto-prepublish-redteam --verbose

# Pinnacle Bank app
uv run nuguard sbom generate --config tests/apps/pinnacle-bank-app/nuguard-azure.prepublish.yaml --format json -o tests/apps/pinnacle-bank-app/pinnacle-bank.sbom.json
uv run nuguard behavior --config tests/apps/pinnacle-bank-app/nuguard-azure.prepublish.yaml --mode dynamic --format json --format markdown --output tests/apps/pinnacle-bank-app/reports/pinnacle-bank-prepublish-behavior --verbose
uv run nuguard redteam --config tests/apps/pinnacle-bank-app/nuguard-azure.prepublish.yaml --format json --format markdown --output tests/apps/pinnacle-bank-app/reports/pinnacle-bank-prepublish-redteam --verbose
```

مهم:

- لا تستخدم `|| true` في عمليات النشر المقررة.
- رمز الخروج `2` قد يشير إلى نتائج أو بوابات سياسة؛ تعامل معه كإشارة واعتمد على فحوصات جودة التقرير لتحديد النجاح/الفشل.

## ملاحظات المستودع

- يحتوي المستودع حاليًا على مخرجات أمثلة وتركيبات اختبار مرجعية تحت `tests/output/`
- بعض اختبارات الاختراق والاختبارات المرجعية اختيارية ومقيدة بمتغيرات البيئة
- تعتمد الميزات المدعومة بنماذج لغوية كبيرة على توفر بيانات اعتماد المزود عبر متغيرات البيئة

## الترخيص

معلومات الترخيص متوفرة في ملف [LICENSE](https://github.com/nuguardai/nuguard/blob/develop/LICENSE).