SkillSpector

ماسح أمني لمهارات وكلاء الذكاء الاصطناعي. اكتشف الثغرات والأنماط الخبيثة والمخاطر الأمنية قبل تثبيت مهارات الوكلاء.

نظرة عامة

تُنفَّذ مهارات وكلاء الذكاء الاصطناعي (المستخدمة في Claude Code وCodex CLI وGemini CLI وغيرها) بثقة ضمنية وبأدنى قدر من التدقيق. في المجموعة الفرعية التي جرى تحليلها من مجموعة بيانات البحث والبالغة 31,132 مهارة، تحتوي 26.1% من المهارات على ثغرات وتُظهر 5.2% نية خبيثة محتملة.

يساعدك SkillSpector في الإجابة عن السؤال: "هل تثبيت هذه المهارة آمن؟"

SkillSpector جزء من خط أنابيب NVIDIA Verified Skills، الذي يفحص مهارات الوكلاء ويقيّمها ويوقّعها قبل النشر. تُنشر المهارات التي تجتاز الفحص في كتالوج مهارات NVIDIA.

التوثيق

• فحص مهارات الوكلاء قبل التثبيت — دليل مستضاف: متى تفحص، وكيف تقرأ التقرير، وكيف تتحكم في عمليات التثبيت.
• دليل التطوير — البنية، وتخطيط الحزم، وكيفية توسيع خط أنابيب المحلّل.
• حدود موارد التحليل — حدود الحزم والمحلّلات والقطع المتداخلة والسجل والنتائج وفق مبدأ الفشل المُغلَق.
• إضافة Pi — ثبّت SkillSpector كأداة Pi لفحص المهارات من داخل جلسات الوكلاء.
• إضافة OpenCode — ثبّت SkillSpector كأداة OpenCode وأمر /skillspector لفحص المهارات من داخل جلسات الوكلاء.

الميزات

• مدخلات متعددة الصيغ: افحص مستودعات Git أو عناوين URL أو ملفات zip أو المجلدات أو الملفات المفردة
• 71 نمط ثغرة عبر 17 فئة: حقن الأوامر (prompt injection)، وتسريب البيانات، وتصعيد الامتيازات، وسلسلة التوريد، والوكالة المفرطة، ومعالجة المخرجات، وتسريب موجه النظام، وتسميم الذاكرة، وإساءة استخدام الأدوات، والوكيل المارق، ومقاومة الرفض، وإساءة استخدام المحفّزات، والكود الخطير (AST)، وتتبع التلوث، وتوقيعات YARA، وأقل امتياز في MCP، وتسميم أدوات MCP
• تحليل على مرحلتين: تحليل ثابت سريع + تقييم دلالي اختياري عبر LLM
• عمليات بحث حية عن الثغرات: يستعلم SC4 من OSV.dev للحصول على بيانات CVE في الوقت الفعلي مع تراجع تلقائي إلى وضع عدم الاتصال
• صيغ إخراج متعددة: تقارير Terminal وJSON وMarkdown وSARIF
• تقييم المخاطر: درجة من 0 إلى 100 مع تصنيفات الخطورة وتوصيات واضحة
• الأساس المرجعي / كبت الإيجابيات الكاذبة: اقبل النتائج المعروفة عبر قاعدة glob أو أساس مرجعي بالبصمة بحيث تُظهر عمليات إعادة الفحص المشكلات الجديدة فقط (التوثيق)

البدء السريع

التثبيت

إشعار البرمجيات مفتوحة المصدر: سيقوم هذا المشروع بتنزيل وتثبيت مشاريع برمجيات مفتوحة المصدر إضافية تابعة لجهات خارجية. راجع شروط الترخيص لهذه المشاريع مفتوحة المصدر قبل الاستخدام.

أنشئ بيئة افتراضية وفعّلها أولاً (تفترض جميع أهداف make أن البيئة الافتراضية مفعّلة). استخدم uv أو pip؛ يستخدم Makefile أداة uv إن كانت متاحة، وإلا يستخدم pip.

تثبيت سريع باستخدام uv (CLI فقط):

uv tool install git+https://github.com/NVIDIA/skillspector.git
# Update later: uv tool update skillspector

إذا كنت تخطط لتشغيل skillspector mcp، فقم بتثبيت إضافة MCP وقت التثبيت:

uv tool install 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git'

من المصدر:

# Clone the repository
git clone https://github.com/NVIDIA/skillspector.git
cd skillspector

# Create and activate virtual environment
uv venv .venv && source .venv/bin/activate
# or: python3 -m venv .venv && source .venv/bin/activate

# Install for production use
make install

# Or install with development dependencies
make install-dev

Docker (بدون الحاجة إلى Python)

شغّل SkillSpector دون تثبيت Python عبر بنائه محليًا من Dockerfile المضمّن. تعتمد الصورة على صورة Docker الرسمية لـ Python 3.12-slim-bookworm.

ابنِ الصورة:

make docker-build
# or: docker build -t skillspector .

فحص دليل محلي عبر تركيب دليلك الحالي في /scan، وهو دليل العمل داخل الحاوية:

docker run --rm -v "$PWD:/scan" skillspector scan ./my-skill/ --no-llm

الفحص مع تحليل LLM عن طريق تمرير بيانات الاعتماد باستخدام ملف .env محلي:

cat > .env <<'EOF'
SKILLSPECTOR_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
EOF

docker run --rm \
  -v "$PWD:/scan" \
  --env-file .env \
  skillspector scan ./my-skill/

أو مرّر بيانات الاعتماد مباشرةً من بيئة shell الخاصة بك:

docker run --rm \
  -v "$PWD:/scan" \
  -e SKILLSPECTOR_PROVIDER=anthropic \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  skillspector scan ./my-skill/

اكتب تقريرًا إلى نظام ملفات المضيف عن طريق الكتابة إلى الدليل المثبَّت:

docker run --rm --user "$(id -u):$(id -g)" \
  -v "$PWD:/scan" \
  skillspector scan ./my-skill/ --no-llm --format json --output report.json

اسم مستعار اختياري لعمليات الفحص الثابتة المتكررة:

alias skillspector-docker='docker run --rm -v "$PWD:/scan" skillspector'
skillspector-docker scan ./my-skill/ --no-llm

الاستخدام الأساسي

# Scan a local skill directory
skillspector scan ./my-skill/

# Scan a single SKILL.md file
skillspector scan ./SKILL.md

# Scan a Git repository
skillspector scan https://github.com/user/my-skill

# Scan a zip file
skillspector scan ./my-skill.zip

حدود الحجم

يفرض SkillSpector حدين مستقلين على المدخلات البعيدة والأرشيفية للحد من تأثير التنزيلات المفرطة الحجم والقنابل المضغوطة (zip bombs):

• حد الاستيعاب لكل عملية: INGEST_MAX_BYTES (100 MiB) — يُطبَّق على تنزيلات URL المتدفقة، وإجمالي الحجم غير المضغوط لأرشيفات zip، واستخدام القرص بعد الاستنساخ لمستودعات Git.
• حد أعضاء zip: INGEST_MAX_ZIP_MEMBERS (10,000) — يحد من عدد المدخلات في ملف zip واحد.

لاحظ أن حد التحليل البالغ 1 MB لكل ملف (MAX_FILE_BYTES) هو حد منفصل ولاحق: فهو يحدد ما ستقرأه المحللات الفردية من دليل تم استيعابه بالفعل. أما حدود الاستيعاب أعلاه فتحدد مقدار المحتوى الذي يمكن أن يصل إلى القرص في المقام الأول. أي تجاوز لأي من حدي الاستيعاب يفشل بشكل مغلق مع IngestLimitExceededError.

صيغ الإخراج

# Terminal output (default) - pretty formatted
skillspector scan ./my-skill/

# JSON output - machine readable
skillspector scan ./my-skill/ --format json --output report.json

# Markdown output - for documentation
skillspector scan ./my-skill/ --format markdown --output report.md

# SARIF output - for CI/CD integration and IDE tooling
skillspector scan ./my-skill/ --format sarif --output report.sarif

الفحص الدفعي

افحص أدلة كاملة من المهارات على التوازي من contrib/batch_scan/:

python -m contrib.batch_scan.batch_scan ./my-skills/ --no-llm
python -m contrib.batch_scan.batch_scan ./my-skills/ --workers 20 -f json -o report.json
python -m contrib.batch_scan.batch_scan ./tests/fixtures/ -f terminal --workers 20

يدعم الكشف متعدد اللغات (zh/ja/ko) والإخراج بصيغة terminal/JSON/Markdown.

لفحوصات LLM بدرجة تزامن أعلى، قم بتهيئة مفاتيح API متعددة وفقًا لـ .env.example — تعمل المجموعة على تحسين الإنتاجية والمرونة، بشرط ألا تشترك المفاتيح في حد معدل على مستوى الحساب.

راجع دليل المساهمين للحصول على التفاصيل.