ModelAudit

قم بتأمين نماذج الذكاء الاصطناعي الخاصة بك قبل النشر. ماسح ثابت يكشف الشيفرات الخبيثة ومؤشرات الباب الخلفي المحتملة وثغرات الأمان في ملفات نماذج تعلّم الآلة — دون تحميلها أو تنفيذها أبدًا.

التوثيق الكامل | أمثلة الاستخدام | الصيغ المدعومة

لماذا ModelAudit

تُنزَّل النماذج من سجلات غير موثوقة، وتمر عبر خطوط التكامل المستمر (CI)، وينتهي بها الأمر في بيئة الإنتاج. أدوات فحص أمان التطبيقات التقليدية (SAST) لا تفحص أكواد pickle opcodes، أو تخطيطات مجموعات HDF5، أو رسوم ONNX proto البيانية، أو توقيعات TensorFlow SavedModel — بينما يقوم ModelAudit بذلك:

فحص ثابت. لا يتم أبدًا تحميل أي نموذج أو إلغاء تسلسله (unpickle) أو تنفيذه.
تغطية الصيغ التي تنتجها فعليًا. أكثر من 40 ماسحًا تغطي pickle وPyTorch وSafeTensors وONNX وTensorFlow وKeras وGGUF والملفات المضغوطة وملفات الإعدادات.
التكامل مع CI. مخرجات قابلة للقراءة آليًا (JSON وSARIF)، ووضع صارم، وأكواد خروج، وماسحات قابلة للاختيار.
إظهار حدود التغطية. الماسحات المعتمدة تُبلّغ عن فجوات التحليل المحدودة مثل القراءات المقتطعة أو استنفاد الميزانيات بدلًا من تقديمها كنتائج مغطاة بالكامل.

أدوات مشابهة: picklescan (pickle فقط، مبني على Python)، fickling (pickle فقط، مبني على AST)، modelscan (pickle + مجموعة فرعية من TensorFlow + Keras). يقدّم ModelAudit تغطية أوسع ويشتمل على محرك Rust أصلي لملفات pickle عبر الحزمة المرافقة modelaudit-picklescan.

البدء السريع

يتطلب Python 3.10-3.13```bash pip install "modelaudit[all]"

Scan a file or directory

modelaudit model.pkl modelaudit ./models/

Export results for CI/CD

modelaudit model.pkl --format json --output results.json

- [المسح والاكتشاف والفيزينغ](#scanning-discovery-and-fuzzing)```
$ modelaudit suspicious_model.pkl

Files scanned: 1 | Issues found: 2 critical, 1 warning

1. suspicious_model.pkl (pos 28): [CRITICAL] Malicious code execution attempt
   Why: Contains os.system() call that could run arbitrary commands

2. suspicious_model.pkl (pos 52): [WARNING] Dangerous pickle deserialization
   Why: Could execute code when the model loads

ما الذي يكتشفه

هجمات تنفيذ الكود في ملفات Pickle وPyTorch وNumPy وJoblib
مؤشرات الباب الخلفي المحتملة — أنماط أوزان مشبوهة، وموترات شاذة، أو إشارات كود مخفي
الأسرار المضمّنة — مفاتيح API ورموز الوصول وبيانات الاعتماد في أوزان النموذج أو البيانات الوصفية
مؤشرات الشبكة — عناوين URL وعناوين IP واستخدام المقابس (sockets) التي قد تتيح تسريب البيانات
استغلال الأرشيفات — اجتياز المسار (path traversal) وهجمات الروابط الرمزية (symlink) في ملفات ZIP/TAR/7z
عمليات تعلم الآلة غير الآمنة — طبقات Lambda، والعمليات المخصصة، وTorchScript/JIT، وحقن القوالب
مخاطر سلسلة التوريد — العبث، وانتهاكات التراخيص، والإعدادات المشبوهة

الصيغ المدعومة

يتضمن ModelAudit 45 ماسحًا مسجلاً يغطي صيغ النماذج والأرشيفات والتهيئة:

بالإضافة إلى ماسحات ضوئية لـ ZIP وTAR و7-Zip وطبقات OCI وقوالب Jinja2 وبيانات JSON/YAML الوصفية والملفات التعريفية (manifests) وبطاقات النماذج والملفات النصية والتعرف على RAR. يتم الإبلاغ عن أرشيفات RAR على أنها غير مدعومة/مغلقة بالفشل بدلاً من تخطيها.

يتم أيضًا التعرف على نماذج TensorFlow SavedModel وMetaGraph protobuf الصالحة بنيويًا عند إعادة تسميتها إلى لواحق غير خاصة بالنماذج. يمكن أيضًا التعرف على نماذج CoreML عند إعادة تسميتها، مع الإبلاغ عن التغطية غير المكتملة بشكل صريح. يتم الاحتفاظ بملفات SafeTensors ذات الإطارات كبيرة الحجم ولكنها معقولة لإجراء تحليل غير حاسم ومحدود ضمن لواحق غير مطلوبة مثل .jpg. يتم أيضًا التعرف على نقاط تفتيش Flax/JAX MessagePack المعقولة بنيويًا عند إعادة تسميتها إلى لواحق غير خاصة بالنماذج؛ يتم الإبلاغ عن الهياكل المعاد تسميتها التي لا يمكن تصنيفها بالكامل كتغطية غير مكتملة. يتم أيضًا التعرف على بيانات تعريف JSON لنقاط تفتيش JAX/Orbax المنظمة عند إعادة تسميتها؛ ويتم الإبلاغ عن المرشحات الكبيرة الحجم والغامضة كتغطية غير مكتملة؛ وقد يظل يتم الإبلاغ عن أنماط الأمان القابلة للملاحظة في البادئة المحدودة الفحص بشكل متحفظ.

عرض وثائق الصيغ الكاملة

المصادر البعيدة

افحص النماذج مباشرة من السجلات البعيدة والتخزين السحابي:```bash

Hugging Face

modelaudit https://huggingface.co/gpt2 modelaudit hf://microsoft/DialoGPT-medium

Cloud storage

modelaudit s3://bucket/model.pt modelaudit gs://bucket/models/

MLflow registry

Non-local artifact stores: export MODELAUDIT_MLFLOW_ALLOWED_ARTIFACT_URIS=s3://trusted-bucket/models

modelaudit models:/MyModel/Production

JFrog Artifactory (files and folders)

Auth: export JFROG_API_TOKEN=...

modelaudit https://company.jfrog.io/artifactory/repo/model.pt modelaudit https://company.jfrog.io/artifactory/repo/models/

DVC-tracked models

modelaudit model.dvc

### متغيرات بيئة المصادقة

- `HF_TOKEN` للمستودعات الخاصة على Hugging Face
- `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` (واختياريًا `AWS_SESSION_TOKEN`) لـ S3
- `GOOGLE_APPLICATION_CREDENTIALS` لـ GCS
- `MLFLOW_TRACKING_URI` للوصول إلى سجل MLflow
- `MODELAUDIT_MLFLOW_ALLOWED_ARTIFACT_URIS` لجذور القطع الأثرية غير المحلية في MLflow (بادئات URI مفصولة بفواصل)
- استخدم جذور خلفية محددة مثل `s3://bucket/prefix`؛ عناوين URI المنطقية مثل `models:/` أو `runs:/` والمسارات البعيدة المشفرة بالنسبة المئوية يتم رفضها.
- `JFROG_API_TOKEN` أو `JFROG_ACCESS_TOKEN` لـ JFrog Artifactory
- `MODELAUDIT_JFROG_ALLOWED_HOSTS` لأسماء مضيفات JFrog المخصصة المفصولة بفواصل والتي قد تستقبل بيانات الاعتماد
- `MODELAUDIT_JFROG_ALLOWED_REDIRECT_HOSTS` لأسماء مضيفات إعادة التوجيه الخارجية المفصولة بفواصل والتي قد يتم تنزيلها بدون بيانات اعتماد
- خزّن بيانات الاعتماد في متغيرات البيئة أو في مدير أسرار، ولا تقم أبدًا بإرسال الرموز/المفاتيح إلى نظام التحكم بالنسخ.

## التثبيت```bash
# Broad scanner coverage (recommended; excludes the TensorFlow runtime and platform-specific TensorRT)
pip install "modelaudit[all]"

# Core only (static scanners, pickle, NumPy, archives, manifests, metadata)
pip install modelaudit

# Specific frameworks (TensorFlow installs on Python 3.11-3.12; ONNX installs on Python 3.10-3.12)
pip install "modelaudit[tensorflow,pytorch,h5,onnx,safetensors]"

# CI/CD environments
pip install "modelaudit[all-ci]"

# On Python 3.11-3.12, add TensorFlow only when you need runtime-dependent checkpoint or weight analysis
pip install "modelaudit[all,tensorflow]"

# Docker
docker run --rm -v "$(pwd)":/app ghcr.io/promptfoo/modelaudit:latest model.pkl

إضافة ONNX، بما في ذلك جزء ONNX من modelaudit[all]، مُعبأة لبيثون 3.10-3.12. تتطلب الإضافات التي تحتوي على PyTorch بيثون 3.10-3.12 أو CPython 3.13 القياسي (مع تمكين GIL)؛ wheels المُرقّعة الخاصة بـ PyTorch 2.13 لا تدعم CPython 3.13t (free-threaded). استخدم CPython القياسي، لأن ماسح pickle الأصلي في ModelAudit أيضًا لا يدعم CPython 3.13t. على Apple Silicon، تتطلب الإضافات التي تحتوي على PyTorch إصدار macOS 14 أو أحدث لأن wheels تستهدف macosx_14_0_arm64؛ يظل التثبيت الأساسي فقط متاحًا للمسح الثابت على macOS 11-13.

خيارات CLI

الأوامر الأساسية:```bash modelaudit [PATHS...] # Default scan command modelaudit scan [OPTIONS] PATHS... # Explicit scan command modelaudit scan --list-scanners # List scanner IDs for targeted scans modelaudit metadata [OPTIONS] PATH # Extract model metadata safely (no deserialization by default) modelaudit doctor [--show-failed] # Diagnose scanner/dependency availability modelaudit debug [--json] [--verbose] # Environment and configuration diagnostics modelaudit cache [stats|clear|cleanup] [OPTIONS]

خيارات الفحص الشائعة:```text
--format {text,json,sarif}   Output format (default: auto-detected)
--output FILE                Write results to file
--strict                     Fail on warnings, scan all file types, strict license validation
--sbom FILE                  Generate CycloneDX SBOM
--stream                     Process files one-by-one; remote downloads are deleted after scanning
--assume-shard-family        Treat explicitly listed cross-directory shards as one model family
--max-size SIZE              Size limit (e.g., 10GB)
--timeout SECONDS            Override scan timeout
--dry-run                    Preview what would be scanned
--verbose / --quiet          Control output detail
--blacklist PATTERN          Additional patterns to flag
--no-cache                   Disable result caching
--cache-dir DIR              Set cache directory for downloads and scan results
--progress                   Force progress display
--scanners LIST              Only run selected scanners (IDs/classes; comma-separated or repeated)
--exclude-scanner NAME       Exclude a scanner from the active set (comma-separated or repeated)
--list-scanners              List scanner IDs, class names, extensions, and dependencies

اختيار الماسح المستهدف:```bash

Discover scanner IDs and class names

modelaudit scan --list-scanners modelaudit scan --list-scanners --format json

Run only selected scanners

modelaudit scan ./models --scanners pickle,tf_savedmodel modelaudit scan ./model.pkl --scanners PickleScanner

Run the default scanner set except a noisy or slow scanner

modelaudit scan ./models --exclude-scanner weight_distribution

For container formats, include both the container scanner and nested scanner

modelaudit scan ./archive.zip --scanners zip,pickle

`--scanners` يبدأ من قائمة سماح صريحة. يطرح `--exclude-scanner` الماسحات من تلك القائمة أو من مجموعة الماسحات الافتراضية. وينعكس اختيار الماسح في مخرجات JSON تحت `scanner_selection`.

بالنسبة للمجلدات البعيدة، يضيّق ModelAudit التنزيلات بناءً على امتدادات الماسحات المحددة عندما يكون ذلك آمنًا. يُطبَّق التوجيه القائم على المحتوى للملفات المعاد تسميتها بعد الاستحواذ؛ افحص عنوان URL مباشر للملف عندما تكون أسماء الملفات في المستودع مضلِّلة عمدًا.

## استخراج البيانات الوصفية```bash
# Human-readable summary (safe default: no model deserialization)
modelaudit metadata model.safetensors

# Machine-readable output
modelaudit metadata ./models --format json --output metadata.json

# Focus only on security-relevant metadata fields
modelaudit metadata model.onnx --security-only

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

رموز الخروج

0: لم يتم اكتشاف أي مشكلات أمنية
1: تم اكتشاف مشكلات أمنية
2: أخطاء الفحص

القياس عن بُعد والخصوصية

تتضمن ModelAudit قياسًا عن بُعد لموثوقية المنتج وتحليلات الاستخدام.

قد تتضمن البيانات الوصفية التي يتم جمعها استخدام الأوامر والميزات، وبيانات توقيت أو حجم الفحص والتنزيل، واستخدام الماسح الضوئي/نوع الملف، ومعرّفات القواعد المستقرة أو CVE، وإجماليات الخطورة، وامتدادات الملفات المسجلة، وفئات المصدر أو الموفّر العامة، وإصدار وقت التشغيل، والنظام الأساسي، والبيانات الوصفية للـ CI.
لا يتضمن القياس عن بُعد المسارات المحلية الأولية، أو أسماء الملفات، أو معرّفات النماذج أو أسمائها، أو معرّفات المستودعات أو القطع الأثرية، أو مفاتيح الـ buckets أو الكائنات، أو مسارات عناوين URL البعيدة، أو نص المشكلات أو الأخطاء الحر، أو معلومات مستخدم URL، أو سلاسل الاستعلام، أو الأجزاء، أو محتويات النموذج الثنائية.
تُفعّل حزم التثبيت القياس عن بُعد افتراضيًا. يتم تعطيل القياس عن بُعد تلقائيًا عند تعيين CI=true أو IS_TESTING=true، وفي التثبيتات التطويرية القابلة للتحرير ما لم يتم تعيين MODELAUDIT_TELEMETRY_DEV=1. يتم وضع علامة isRunningInCi=true على الأحداث المرسلة من موفري CI الآخرين (TeamCity وCodeBuild وBitbucket Pipelines وJenkins) بحيث يمكن تصفيتها لاحقًا.
يتم تخزين معرّف مستخدم زائف مستمر في ~/.promptfoo/promptfoo.yaml للربط عبر الأدوات مع Promptfoo، وتستخدم كل جلسة قياس عن بُعد معرّف جلسة جديد. يتم ترحيل المعرّفات الموجودة من ~/.modelaudit/user_config.json عند أول تشغيل بعد الترقية. قد يتم إرفاق قيمة بريد إلكتروني قديمة في هذا الملف، إذا كانت موجودة، بملف تعريف مستخدم التحليلات.

قم بإلغاء الاشتراك صراحةً باستخدام أي من متغيرات البيئة التالية:```bash export PROMPTFOO_DISABLE_TELEMETRY=1

or

export NO_ANALYTICS=1

للاشتراك أثناء تثبيتات التعديل/التطوير:```bash
export MODELAUDIT_TELEMETRY_DEV=1

أمثلة على المخرجات```bash

JSON for CI/CD pipelines