SkillSpector

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

نظرة عامة

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

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

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

التوثيق

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

الميزات

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

البدء السريع

التثبيت

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

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

تثبيت سريع باستخدام uv (CLI فقط):```bash uv tool install git+https://github.com/NVIDIA/skillspector.git

Update later: uv tool update skillspector

إذا كنت تخطط لتشغيل `skillspector mcp`، فقم بتثبيت إضافة MCP في وقت التثبيت:```bash
uv tool install 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git'

من المصدر:```bash

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](https://github.com/nvidia/skillspector/blob/main/Dockerfile) المضمّن. تعتمد الصورة على صورة Docker الرسمية لـ Python `3.12-slim-bookworm`.

**بناء الصورة:**```bash
make docker-build
# or: docker build -t skillspector .

فحص دليل محلي عن طريق تركيب دليلك الحالي في /scan، وهو دليل العمل الخاص بالحاوية:```bash docker run --rm -v "$PWD:/scan" skillspector scan ./my-skill/ --no-llm

**الفحص مع تحليل LLM** عن طريق تمرير بيانات الاعتماد باستخدام ملف `.env` محلي:```bash
cat > .env <<'EOF'
SKILLSPECTOR_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
EOF

المزايا الرئيسية

التحليل الثابت: تحليل الكود المصدري دون تنفيذ
دعم متعدد اللغات: Python، JavaScript، TypeScript، Java، Go، PHP، Ruby
قواعد قابلة للتخصيص: تحديد أنماط الكشف الخاصة بك
تكامل CI/CD: تكامل سلس مع خطوط أنابيب التطوير
تقارير مفصلة: تقارير بتنسيق JSON وHTML وSARIF
قاعدة بيانات الثغرات: قاعدة بيانات مدمجة لأنماط الثغرات الشائعة

التثبيت

من المصدر

git clone https://github.com/example/security-scanner.git
cd security-scanner
pip install -r requirements.txt
python setup.py install

باستخدام pip

pip install security-scanner

باستخدام Docker

docker pull securityscanner/scanner:latest
docker run -v $(pwd):/scan securityscanner/scanner:latest /scan

الاستخدام

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

# فحص دليل
security-scanner scan /path/to/code

# فحص ملف واحد
security-scanner scan --file app.py

# الفحص باستخدام قواعد مخصصة
security-scanner scan --rules custom-rules.yaml /path/to/code

خيارات متقدمة

# الفحص مع تنسيق إخراج محدد
security-scanner scan --format json --output results.json /path/to/code

# الفحص مع مستوى خطورة محدد
security-scanner scan --severity high,critical /path/to/code

# الفحص مع استبعاد أنماط معينة
security-scanner scan --exclude "tests/*,vendor/*" /path/to/code

التكامل مع CI/CD

# مثال GitHub Actions
name: Security Scan
on: [push, pull_request]
jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Run Security Scanner
        run: |
          pip install security-scanner
          security-scanner scan --format sarif --output results.sarif .
      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: results.sarif

التكوين

ملف التكوين

# .security-scanner.yaml
rules:
  - id: SQL_INJECTION
    enabled: true
    severity: critical
  - id: XSS
    enabled: true
    severity: high
  - id: HARDCODED_SECRETS
    enabled: true
    severity: critical

exclude:
  - "tests/*"
  - "vendor/*"
  - "*.min.js"

output:
  format: json
  verbose: true

القواعد المخصصة

# custom-rules.yaml
rules:
  - id: CUSTOM_RULE_001
    name: "كشف الأنماط الخطرة"
    description: "يكتشف الأنماط الخطرة في الكود"
    severity: high
    pattern: "eval\\s*\\("
    languages:
      - python
      - javascript
    message: "تم اكتشاف استخدام eval() وهو أمر خطير"

أمثلة الكشف

حقن SQL

# كود ضعيف
def get_user(username):
    query = "SELECT * FROM users WHERE username = '" + username + "'"
    cursor.execute(query)
    return cursor.fetchone()

# كود آمن
def get_user(username):
    query = "SELECT * FROM users WHERE username = %s"
    cursor.execute(query, (username,))
    return cursor.fetchone()

البرمجة النصية عبر المواقع (XSS)

// كود ضعيف
element.innerHTML = userInput;

// كود آمن
element.textContent = userInput;

الأسرار المضمنة

# كود ضعيف
API_KEY = "sk-1234567890abcdef"
DATABASE_PASSWORD = "super_secret_password"

# كود آمن
import os
API_KEY = os.environ.get("API_KEY")
DATABASE_PASSWORD = os.environ.get("DATABASE_PASSWORD")

تنسيقات الإخراج

JSON

{
  "scan_id": "abc123",
  "timestamp": "2024-01-15T10:30:00Z",
  "findings": [
    {
      "rule_id": "SQL_INJECTION",
      "severity": "critical",
      "file": "app.py",
      "line": 42,
      "message": "تم اكتشاف ثغرة محتملة في حقن SQL",
      "code_snippet": "query = \"SELECT * FROM users WHERE id = \" + user_id"
    }
  ],
  "summary": {
    "total": 1,
    "critical": 1,
    "high": 0,
    "medium": 0,
    "low": 0
  }
}

SARIF

{
  "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "security-scanner",
          "version": "1.0.0"
        }
      },
      "results": []
    }
  ]
}

المساهمة

نرحب بالمساهمات! يرجى قراءة CONTRIBUTING.md للحصول على التفاصيل.

إعداد بيئة التطوير

git clone https://github.com/example/security-scanner.git
cd security-scanner
python -m venv venv
source venv/bin/activate  # على Linux/Mac
# أو
venv\Scripts\activate  # على Windows
pip install -r requirements-dev.txt

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

pytest tests/

الترخيص

هذا المشروع مرخص بموجب رخصة MIT - راجع ملف LICENSE للحصول على التفاصيل.

إخلاء المسؤولية

هذه الأداة مخصصة لأغراض الاختبار الأمني المصرح به فقط. يجب عليك الحصول على إذن مناسب قبل فحص أي كود لا تملكه.```bash docker run --rm
-v "$PWD:/scan"
--env-file .env
skillspector scan ./my-skill/

أو مرّر بيانات الاعتماد مباشرةً من بيئة shell الخاصة بك:```bash
docker run --rm \
  -v "$PWD:/scan" \
  -e SKILLSPECTOR_PROVIDER=anthropic \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  skillspector scan ./my-skill/

اكتب تقريرًا إلى نظام ملفات المضيف عن طريق الكتابة إلى الدليل المُثبَّت:```bash docker run --rm
-v "$PWD:/scan"
skillspector scan ./my-skill/ --no-llm --format json --output report.json

**اسم مستعار اختياري** لعمليات الفحص الثابت المتكررة:```bash
alias skillspector-docker='docker run --rm -v "$PWD:/scan" skillspector'
skillspector-docker scan ./my-skill/ --no-llm

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

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

### صيغ الإخراج```bash
# 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/:```bash 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) والإخراج إلى الطرفية/JSON/Markdown.

بالنسبة لفحوصات LLM ذات التزامن الأعلى، قم بتهيئة مفاتيح API متعددة وفقًا لـ
[`.env.example`](https://github.com/nvidia/skillspector/blob/main/contrib/batch_scan/.env.example) — تعمل المجموعة على تحسين معدل النقل
والمرونة، بشرط ألا تشترك المفاتيح في حد معدل على مستوى الحساب.

راجع [دليل المساهمة](https://github.com/nvidia/skillspector/blob/main/contrib/batch_scan/docs) للحصول على التفاصيل.

> **ملاحظة حول دعم LLM:** تستهدف التهيئة الافتراضية DeepSeek كخيار
> عام أرخص. من [المتوقع أن يتوقف](https://api-docs.deepseek.com/) DeepSeek-Chat،
> ولا يمتلك المساهم أجهزة لاختبار النماذج المحلية. تم اختبار
> ماسح الدفعات في الأصل مع نقاط نهاية متوافقة مع OpenAI — تطلب افتقار DeepSeek
> لدعم الإخراج المنظم تصحيحات يدوية لتحليل JSON. إذا كان بإمكانك
> المساهمة بواجهة خلفية أكثر عمومية (Ollama أو vLLM أو مزود مختلف)،
> فإن طلبات السحب مرحب بها جدًا.

### كبت الإيجابيات الكاذبة (خط الأساس)

اكبت النتائج المعروفة/المقبولة بحيث يعكس تقييم المخاطر فقط المشكلات
غير المُفرَّزة، وتكشف عمليات إعادة الفحص فقط النتائج *الجديدة*. راجع
[دليل الكبت](https://github.com/nvidia/skillspector/blob/main/docs/SUPPRESSION.md) للحصول على المرجع الكامل.```bash
# Accept all current findings into a baseline (run once), then commit it.
skillspector baseline ./my-skill/ -o .skillspector-baseline.yaml

# Scan against the baseline — only NEW findings are reported and scored.
skillspector scan ./my-skill/ --baseline .skillspector-baseline.yaml

# Review what was suppressed (still excluded from the score).
skillspector scan ./my-skill/ --baseline .skillspector-baseline.yaml --show-suppressed

يمكن أن تستخدم خط الأساس أيضًا قواعد glob المتسامحة مع الانحراف (حسب معرّف القاعدة، أو مسار الملف، أو الرسالة) — راجع .skillspector-baseline.example.yaml. خطوط الأساس ذات البصمة الدقيقة مرتبطة بالأدلة: تغيير المصدر المفحوص أو إصدار SkillSpector يُبقي النتيجة نشطة حتى تتم مراجعتها مرة أخرى. عند تخزين خط أساس محدد أو مخرجات خط الأساس داخل دليل المهارة، يستثني SkillSpector ذلك الملف بالتحديد من تحليل المحتوى حتى لا يُنشئ نص الكبت الخاص به نتائج أو يدخل في البصمات المُعاد توليدها؛ وتبقى الملفات الشقيقة ضمن نطاق الفحص العادي.

تحليل LLM

للحصول على أفضل النتائج، قم بتهيئة نقطة نهاية LLM متوافقة مع OpenAI من أجل التحليل الدلالي. اختر مزوّدًا باستخدام SKILLSPECTOR_PROVIDER؛ فالمزوّدون المستضافون يأتون مع نماذج افتراضية مضمّنة، بينما يعود مزوّدو CLI إلى النموذج الافتراضي لبيئة التشغيل المحلية ما لم يتم تعيين SKILLSPECTOR_MODEL. يعمل SkillSpector أيضًا مع خوادم محلية متوافقة مع OpenAI (Ollama، vLLM، llama.cpp) وبوابات استدلال مُدارة.

المزوّد (`SKILLSPECTOR_PROVIDER`)	متغير بيئة بيانات الاعتماد	نقطة النهاية	النموذج الافتراضي
`openai`	`OPENAI_API_KEY` (+ اختياري `OPENAI_BASE_URL`)	api.openai.com (أو أي URL متوافق مع OpenAI)	`gpt-5.4`
`anthropic`	`ANTHROPIC_API_KEY`	api.anthropic.com	`claude-opus-4-6`
`anthropic_proxy`	`ANTHROPIC_PROXY_API_KEY` + `ANTHROPIC_PROXY_ENDPOINT_URL`	أي وكيل raw-predict بنمط Vertex	`claude-sonnet-4-6`
`bedrock`	`AWS_PROFILE` (اختياري) + `AWS_REGION` — SigV4 عبر boto3	AWS Bedrock Runtime	`us.anthropic.claude-sonnet-4-6-20250915-v1:0`
`nv_build`	`NVIDIA_INFERENCE_KEY`	build.nvidia.com	`deepseek-ai/deepseek-v4-flash`
`claude_cli`	(لا شيء — يستخدم مصادقة CLI المحلية)	ملف `claude` التنفيذي المحلي	النموذج الاحتياطي لبيئة تشغيل Claude المحلية، أو `SKILLSPECTOR_MODEL`
`codex_cli`	(لا شيء — يستخدم مصادقة CLI المحلية)	ملف `codex` التنفيذي المحلي	النموذج الاحتياطي لبيئة تشغيل Codex المحلية، أو `SKILLSPECTOR_MODEL`

Stock OpenAI

export SKILLSPECTOR_PROVIDER=openai export OPENAI_API_KEY=sk-... skillspector scan ./my-skill/

Anthropic

export SKILLSPECTOR_PROVIDER=anthropic export ANTHROPIC_API_KEY=sk-ant-... skillspector scan ./my-skill/

Anthropic via Vertex-style proxy (corporate gateways, GCP Vertex AI)

export SKILLSPECTOR_PROVIDER=anthropic_proxy export ANTHROPIC_PROXY_ENDPOINT_URL=https://my-gateway.example.com/models/claude-sonnet-4-6:streamRawPredict export ANTHROPIC_PROXY_API_KEY=your-bearer-token export SKILLSPECTOR_MODEL=claude-sonnet-4-6 skillspector scan ./my-skill/

AWS Bedrock (Claude via SigV4)

export SKILLSPECTOR_PROVIDER=bedrock

Optional: select an AWS named profile. When unset, the standard

boto3 credential chain (env vars, instance metadata, SSO, etc.) resolves.

export AWS_PROFILE=my-profile

export AWS_REGION=us-west-2 # default if unset

Default model: us.anthropic.claude-sonnet-4-6-20250915-v1:0

Override with any Bedrock model ID, cross-region inference-profile

ID, or your own application-inference-profile ARN:

export SKILLSPECTOR_MODEL=us.anthropic.claude-opus-4-6-20250915-v1:0

skillspector scan ./my-skill/

NVIDIA build.nvidia.com

export SKILLSPECTOR_PROVIDER=nv_build export NVIDIA_INFERENCE_KEY=nvapi-... skillspector scan ./my-skill/

Local Claude CLI — no API key; uses your existing `claude auth login` session

export SKILLSPECTOR_PROVIDER=claude_cli

Uses the local Claude CLI runtime fallback unless SKILLSPECTOR_MODEL is set.

export SKILLSPECTOR_MODEL=claude-sonnet-4-6

skillspector scan ./my-skill/

Local Codex CLI — no API key; uses your existing `codex login` session

Requires: codex CLI installed and authenticated

export SKILLSPECTOR_PROVIDER=codex_cli skillspector scan ./my-skill/

Local Ollama or any OpenAI-compatible endpoint

export SKILLSPECTOR_PROVIDER=openai export OPENAI_API_KEY=ollama export OPENAI_BASE_URL=http://localhost:11434/v1 export SKILLSPECTOR_MODEL=llama3.1:8b skillspector scan ./my-skill/

Override the provider's default model

export SKILLSPECTOR_MODEL=gpt-5.2 skillspector scan ./my-skill/

Skip LLM analysis (faster, static analysis only)

skillspector scan ./my-skill/ --no-llm

### خادم MCP

شغّل SkillSpector كخادم [Model Context Protocol](https://modelcontextprotocol.io)
حتى يتمكن أي وكيل يدعم MCP (Claude Code، Codex CLI، Gemini CLI) أو أي
بيئة تشغيل بعيدة من استدعاء الفحص كأداة و**تعليق عمليات تثبيت المهارات/MCP بناءً على
النتيجة** — مما يحوّل SkillSpector إلى حاجز حماية وقت التشغيل بدلاً من
خطوة تدقيق خارج النطاق.

يتطلب `skillspector mcp` وجود `skillspector[mcp]`.```bash
# Install, or reinstall if you already used the CLI-only path
uv tool install --force 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git'

# FastMCP stdio transport for local CLI agents
skillspector mcp

# streamable HTTP/SSE transport for remote / A2A callers
skillspector mcp --transport http --host 127.0.0.1 --port 8000

نقل stdio هو مسار FastMCP الحالي لوكلاء CLI المحليين، ولا يزال تعليق التهيئة المُبلَّغ عنه في issue #199 ساريًا هناك.

يوفّر الخادم أداة واحدة:

scan_skill(target, use_llm=true, output_format="json") — يفحص عنوان Git URL أو file URL أو ملف .zip أو .md أو دليلًا ويعيد حكمًا منظّمًا: risk_score (0-100)، وseverity، وrecommendation، وsafe_to_install، وfindings. كما يبلّغ عن llm_used / scan_mode بحيث لا يُخطئ أحد في اعتبار درجة منخفضة من فحص ثابت فقط فحصًا كاملًا نظيفًا.

سجّله مع Claude Code عبر:```bash claude mcp add skillspector -- skillspector mcp

> **الأمان — نموذج الثقة في نقل HTTP**
>
> يُشحن نقل HTTP **بدون مصادقة**. أي مُتصل يستطيع الوصول إلى المنفذ يمكنه استدعاء `scan_skill`. عبر stdio أو `127.0.0.1` فإن هذا يمثل نفس حدود الثقة الخاصة بـ CLI. إذا قمت بالربط بواجهة قابلة للتوجيه:
>
> - ضع الخادم خلف وكيل عكسي يقوم بالمصادقة (مثل nginx + mTLS) قبل تعريضه للخارج.
> - يتم **رفض المسارات المحلية وعناوين URL من نوع `file://` تلقائيًا** عبر HTTP لمنع المتصلين غير المصادق عليهم من قراءة ملفات المضيف العشوائية. يتم قبول عناوين Git البعيدة و`.zip` فقط.

## أنماط الثغرات

يكتشف SkillSpector **71 نمط ثغرة** عبر 17 فئة:

### حقن الأوامر (6 أنماط)

| المعرّف | النمط | الخطورة | الوصف |
|----|---------|----------|-------------|
| P1 | تجاوز التعليمات | HIGH | أوامر بتجاهل قيود الأمان |
| P2 | تعليمات مخفية | HIGH | توجيهات خبيثة في التعليقات/النص غير المرئي |
| P3 | أوامر تسريب البيانات | HIGH | تعليمات لإرسال السياق خارجيًا |
| P4 | التلاعب بالسلوك | MEDIUM | تعليمات خفية تغيّر قرارات الوكيل |
| P5 | محتوى ضار | CRITICAL | تعليمات قد تسبب ضررًا جسديًا |
| P9 | حشو المسافات البيضاء | MEDIUM | حشو كبير من المسافات البيضاء يخفي تعليمات أسفل/بجانب المنطقة المرئية |

### مقاومة الرفض (3 أنماط)

| المعرّف | النمط | الخطورة | الوصف |
|----|---------|----------|-------------|
| AR1 | كبت الرفض | HIGH | تعليمات بعدم الرفض أبدًا أو الامتثال دائمًا (مثل "never refuse"، "always comply") |
| AR2 | كبت إخلاء المسؤولية | HIGH | تعليمات بحذف التحذيرات أو إخلاءات المسؤولية أو التعليقات الأخلاقية (مثل "no disclaimers"، "do not moralize") |
| AR3 | إبطال سياسة الأمان | HIGH | صياغة كسر الحماية التي تبطل الحواجز (مثل "you have no restrictions"، "ignore your guidelines"، "do anything now") |

### تسريب البيانات (4 أنماط)

| المعرّف | النمط | الخطورة | الوصف |
|----|---------|----------|-------------|
| E1 | الإرسال الخارجي | MEDIUM | إرسال البيانات إلى عناوين URL خارجية |
| E2 | حصاد متغيرات البيئة | HIGH | تعداد أو نسخ أو البحث في بيانات البيئة لجمع الأسرار |
| E3 | تعداد نظام الملفات | MEDIUM | فحص المجلدات بحثًا عن ملفات حساسة |
| E4 | تسرب السياق | HIGH | إرسال سياق المحادثة خارجيًا |

### تصعيد الصلاحيات (3 أنماط)

| المعرّف | النمط | الخطورة | الوصف |
|----|---------|----------|-------------|
| PE1 | صلاحيات مفرطة | LOW | طلب وصول يتجاوز الوظائف المعلنة |
| PE2 | تنفيذ Sudo/Root | MEDIUM | استدعاء صلاحيات نظام مرتفعة |
| PE3 | الوصول إلى بيانات الاعتماد | HIGH | قراءة مفاتيح SSH أو الرموز أو كلمات المرور |

### سلسلة التوريد (9+ أنماط)

| المعرّف | النمط | الخطورة | الوصف |
|----|---------|----------|-------------|
| SC1 | تبعيات غير مثبتة | LOW | لا توجد قيود إصدار على الحزم |
| SC2 | جلب سكربتات خارجية | HIGH | curl \| bash وتنفيذ كود عن بُعد |
| SC3 | كود مُبهم | HIGH | تنفيذ مُشفّر بـ Base64/hex |
| SC4 | تبعيات معروفة بثغرات | HIGH | تبعيات بها CVEs معروفة (بحث مباشر في OSV.dev) |
| SC5 | تبعيات مهجورة | MEDIUM | حزم غير مُصانة بدون تحديثات أمنية |
| SC6 | انتحال الأسماء | HIGH | أسماء حزم مشابهة لحزم شائعة |
| SC8 | بايت كود Python مُشحون | HIGH | وجود `__pycache__` / `.pyc` (الاكتشاف يتخطى؛ تجاوز بايت كود خبيث) |
| SC9 | أثر تنفيذي مُخفى | HIGH | ملف تنفيذي مُدمج في حاوية مستند أو أثر مخفي/متنكر |

### الوكالة المفرطة (5 أنماط)

| المعرّف | النمط | الخطورة | الوصف |
|----|---------|----------|-------------|
| EA1 | وصول غير مقيّد للأدوات | HIGH | وصول غير مقيّد للأدوات بدون قيود |
| EA2 | اتخاذ قرارات مستقلة | HIGH | قرارات عالية التأثير بدون تدخل بشري |
| EA3 | توسع النطاق | MEDIUM | قدرات تتجاوز الغرض المعلن |
| EA4 | وصول غير محدود للموارد | MEDIUM | لا حدود للمعدل أو الحصص على استهلاك الموارد |
| EA5 | اختيار نموذج أو مزود خارجي | MEDIUM/HIGH | تثبيت نموذج/مزود أو استدعاءات shell لـ coding-CLI يمكنها تبديل حسابات الفوترة |

### معالجة المخرجات (3 أنماط)

| المعرّف | النمط | الخطورة | الوصف |
|----|---------|----------|-------------|
| OH1 | حقن مخرجات غير مُتحقق منها | HIGH | استخدام مخرجات النموذج بدون تعقيم |
| OH2 | مخرجات عبر السياقات | MEDIUM | تدفق المخرجات عبر حدود الثقة بدون تحقق |
| OH3 | مخرجات غير محدودة | MEDIUM | لا حدود على حجم المخرجات أو معدل التوليد |

### تسرب موجه النظام (3 أنماط)

| المعرّف | النمط | الخطورة | الوصف |
|----|---------|----------|-------------|
| P6 | تسرب مباشر | HIGH | تعليمات تكشف موجهات النظام أو القواعد الداخلية |
| P7 | استخراج غير مباشر | MEDIUM | استخراج عبر إعادة الصياغة أو الترجمة أو القنوات الجانبية |
| P8 | تسريب قائم على الأدوات | HIGH | تسريب موجهات النظام عبر كتابة الملفات أو طلبات الشبكة |

### تسميم الذاكرة (3 أنماط)

| المعرّف | النمط | الخطورة | الوصف |
|----|---------|----------|-------------|
| MP1 | حقن سياق دائم | HIGH | محتوى مصمم للاستمرار عبر التفاعلات |
| MP2 | حشو نافذة السياق | MEDIUM | محتوى حشو يزيح قيود الأمان |
| MP3 | التلاعب بالذاكرة | HIGH | العبث بذاكرة الوكيل أو الحالة المخزنة |

### إساءة استخدام الأدوات (3 أنماط)

| المعرّف | النمط | الخطورة | الوصف |
|----|---------|----------|-------------|
| TM1 | إساءة استخدام معاملات الأدوات | HIGH | معاملات مصممة لسلوك غير مقصود (shell=True، --force) |
| TM2 | إساءة استخدام التسلسل | HIGH | سلاسل أدوات تتجاوز فحوصات الأمان الفردية |
| TM3 | إعدادات افتراضية غير آمنة | MEDIUM | إعدادات افتراضية متساهلة للغاية (TLS معطل، لا مصادقة) |

### وكيل مارق (2 أنماط)

| المعرّف | النمط | الخطورة | الوصف |
|----|---------|----------|-------------|
| RA1 | التعديل الذاتي | CRITICAL | تعديل الكود أو الإعدادات الخاصة به في وقت التشغيل |
| RA2 | استمرارية الجلسة | HIGH | استمرارية غير مصرح بها عبر مهام cron أو سكربتات بدء التشغيل |

### إساءة استخدام المشغلات (3 أنماط)

| المعرّف | النمط | الخطورة | الوصف |
|----|---------|----------|-------------|
| TR1 | مشغل واسع للغاية | MEDIUM | أنماط مشغلات تطابق كلمات شائعة |
| TR2 | مشغل أوامر ظل | HIGH | مشغلات تحجب الأوامر المدمجة أو المهارات الأخرى |
| TR3 | مشغل طُعم الكلمات المفتاحية | MEDIUM | مشغلات عامة مصممة لتعظيم التنشيط |

### AST السلوكي (9 أنماط)

| المعرّف | النمط | الخطورة | الوصف |
|----|---------|----------|-------------|
| AST1 | استدعاء exec() | CRITICAL | exec() مباشر يمكّن تنفيذ كود عشوائي |
| AST2 | استدعاء eval() | HIGH | eval() مباشر يقيّم تعبيرات عشوائية |
| AST3 | استيراد ديناميكي | HIGH | \_\_import\_\_() يحمّل وحدات عشوائية في وقت التشغيل |
| AST4 | استدعاء subprocess | HIGH | تنفيذ أوامر خارجية عبر subprocess |
| AST5 | os.system / عائلة exec | HIGH | أوامر shell عبر وحدة os |
| AST6 | استدعاء compile() | MEDIUM | إنشاء كائن كود من النصوص |
| AST7 | getattr() ديناميكي | MEDIUM | وصول عشوائي للسمات بأسماء غير حرفية |
| AST8 | سلسلة تنفيذ خطيرة | CRITICAL | exec/eval مدمج مع مصدر ديناميكي (شبكة، بيانات مُشفرة) |
| AST9 | مصرف getattr() انعكاسي | HIGH | exec انعكاسي عبر `getattr(os,'system')` / `getattr(builtins,'exec')` يتجنب AST1/AST5 |

### تتبع التلوث (5 أنماط)

| المعرّف | النمط | الخطورة | الوصف |
|----|---------|----------|-------------|
| TT1 | تدفق تلوث مباشر | HIGH | تدفق البيانات مباشرة من مصدر إلى مصرف بدون تعقيم |
| TT2 | تدفق تلوث عبر متغير | MEDIUM | تدفق البيانات من المصدر إلى المصرف عبر متغيرات وسيطة |
| TT3 | سلسلة تسريب بيانات الاعتماد | CRITICAL | بيانات الاعتماد (متغيرات البيئة، الأسرار) تتدفق إلى مصارف مخرجات الشبكة |
| TT4 | قراءة ملف إلى تسريب شبكي | HIGH | محتويات الملف تتدفق إلى مصارف مخرجات الشبكة |
| TT5 | إدخال خارجي إلى تنفيذ كود | CRITICAL | إدخال الشبكة أو المستخدم يتدفق إلى مصارف exec/eval/subprocess |

### توقيعات YARA (4 أنماط)

| المعرّف | النمط | الخطورة | الوصف |
|----|---------|----------|-------------|
| YR1 | تطابق برمجية خبيثة | CRITICAL | تطابق قاعدة YARA لتوقيعات برمجيات خبيثة معروفة |
| YR2 | تطابق webshell | CRITICAL | تطابق قاعدة YARA لأنماط webshell |
| YR3 | تطابق مُعدّن عملات | HIGH | تطابق قاعدة YARA لمؤشرات تعدين العملات |
| YR4 | تطابق أداة اختراق / استغلال | HIGH | تطابق قاعدة YARA لأدوات الاختراق أو كود الاستغلال |

### الحد الأدنى من صلاحيات MCP (4 أنماط)

| المعرّف | النمط | الخطورة | الوصف |
|----|---------|----------|-------------|
| LP1 | قدرة غير معلنة | HIGH | الكود يستخدم قدرات غير مدرجة في الصلاحيات المعلنة |
| LP2 | صلاحية حرف بدل | MEDIUM | قائمة الصلاحيات تحتوي على أحرف بدل (\*، all، full، any) |
| LP3 | إعلان صلاحية مفقود | MEDIUM | لا يوجد حقل صلاحيات لكن الكود لديه قدرات قابلة للاكتشاف |
| LP4 | صلاحية مُعلنة بإفراط | LOW | صلاحية معلنة لكن لا توجد قدرة كود مقابلة |

### تسميم أدوات MCP (4 أنماط)

| المعرّف | النمط | الخطورة | الوصف |
|----|---------|----------|-------------|
| TP1 | تعليمات مخفية | HIGH | توجيهات مخفية في البيانات الوصفية (تعليقات HTML، أحرف بعرض صفري، base64، data URIs) |
| TP2 | خداع Unicode | HIGH | حروف متشابهة، تجاوزات RTL، معرّفات مختلطة النص في بيانات الأدوات الوصفية |
| TP3 | حقن وصف المعاملات | MEDIUM | أنماط حقن في تعريفات المعاملات (تجاوزات، رموز نظام، إعدادات افتراضية خبيثة) |
| TP4 | عدم تطابق الوصف مع السلوك | MEDIUM | وصف الأداة المعلن لا يطابق سلوك الكود الفعلي (مدعوم بـ LLM) |

جميع الأنماط المكتشفة مدرجة في الجداول أعلاه.

## تقييم المخاطر

### حساب النقاط

- **مشكلات CRITICAL**: +50 نقطة
- **مشكلات HIGH**: +25 نقطة
- **مشكلات MEDIUM**: +10 نقاط
- **مشكلات LOW**: +5 نقاط
- **السكربتات التنفيذية**: مضاعف 1.3x

### مستويات الخطورة

| النقاط | الخطورة | التوصية |
|-------|----------|----------------|
| 0-20 | LOW | SAFE |
| 21-50 | MEDIUM | CAUTION |
| 51-80 | HIGH | DO NOT INSTALL |
| 81-100 | CRITICAL | DO NOT INSTALL |

## مثال على المخرجات

### مخرجات الطرفية```
 SkillSpector Security Report  v2.0.0

Skill: suspicious-skill
Source: ./suspicious-skill/
Scanned: 2026-01-29 10:30:00 UTC

        Risk Assessment
 Metric          Value
 Score           78/100
 Severity        HIGH
 Recommendation  DO NOT INSTALL

        Components (3)
 File              Type      Lines  Executable
 SKILL.md          markdown    142  No
 scripts/sync.py   python       87  Yes
 requirements.txt  text          3  No

Issues (2)

  HIGH: Env Variable Harvesting (E2)
    Location: scripts/sync.py:23
    Finding: for key, val in os.environ.items():...
    Confidence: 94%
    Explanation: This code collects environment variables containing
    API keys and secrets, then sends them to an external server.

  HIGH: External Transmission (E1)
    Location: scripts/sync.py:45
    Finding: requests.post("https://api.skill.io/env"...
    Confidence: 89%
    Explanation: Data is being sent to an external server. Combined
    with env harvesting above, this indicates credential exfiltration.

الإعدادات

متغيرات البيئة

المتغير	الوصف	مطلوب
`SKILLSPECTOR_PROVIDER`	مزوّد LLM النشط: `openai`، `anthropic`، `anthropic_proxy`، `bedrock`، `nv_build`، `claude_cli`، `codex_cli`، أو `gemini_cli`. تستخدم المزوّدات المستضافة الإعدادات الافتراضية المضمّنة في `model_registry.yaml`؛ ويعود كل من `claude_cli` و`codex_cli` إلى النموذج الافتراضي لبيئة تشغيل CLI المحلية ما لم يتم تعيين `SKILLSPECTOR_MODEL`. القيمة الافتراضية هي `nv_build`.	اختياري
`NVIDIA_INFERENCE_KEY`	بيانات الاعتماد لمزوّد `nv_build` (build.nvidia.com).	مطلوب لتحليل LLM عندما يكون `SKILLSPECTOR_PROVIDER=nv_build`
`OPENAI_API_KEY`	بيانات الاعتماد لمزوّد OpenAI (`SKILLSPECTOR_PROVIDER=openai`). يعمل أيضًا كخيار احتياطي من المستوى الثاني في سلسلة بيانات الاعتماد عندما لا يُرجع المزوّد النشط أي بيانات اعتماد.	مطلوب لتحليل LLM عندما يكون `SKILLSPECTOR_PROVIDER=openai`
`OPENAI_BASE_URL`	تجاوز نقطة نهاية OpenAI (على سبيل المثال، التوجيه إلى Ollama).	اختياري
`SKILLSPECTOR_REASONING_EFFORT`	إعداد اختياري لجهد الاستدلال يعتمد على المزوّد والنموذج. تُشذَّب القيم غير الفارغة وتُمرَّر دون تغيير؛ وعند عدم التعيين أو الفراغ يُحافَظ على السلوك الافتراضي للمزوّد.	اختياري
`SKILLSPECTOR_OUTPUT_LANGUAGE`	تسمية لغة قصيرة من سطر واحد (حروف، أرقام، مسافات، `_`، أو `-`؛ بحد أقصى 64 حرفًا) لنص نتائج LLM القابل للقراءة البشرية مثل الرسائل والتفسيرات والمعالجة. تبقى معرّفات القواعد وقيم الخطورة والمسارات والشيفرة وغيرها من القيم القابلة للقراءة الآلية دون تغيير. عند عدم التعيين أو الفراغ أو القيم غير الصالحة يُحافَظ على لغة الإخراج الافتراضية.	اختياري
`SKILLSPECTOR_TEMPERATURE`	درجة حرارة أخذ العينات الاختيارية من `0` إلى `1` للمزوّدات المستضافة. عند عدم التعيين أو الفراغ يُحافَظ على الإعداد الافتراضي للمزوّد. قد تقلّل القيم الأقل من التباين بين التشغيلات لكنها لا تضمن إخراجًا متطابقًا.	اختياري
`SKILLSPECTOR_SEED`	بذرة أخذ عينات اختيارية صحيحة لمزوّدات OpenAI المتوافقة وAzure OpenAI. لا تستقبلها المزوّدات المستضافة الأخرى ومزوّدات CLI. يبقى دعم المزوّد معتمدًا على النموذج.	اختياري
`ANTHROPIC_API_KEY`	بيانات الاعتماد لمزوّد Anthropic (`SKILLSPECTOR_PROVIDER=anthropic`).	مطلوب لتحليل LLM عندما يكون `SKILLSPECTOR_PROVIDER=anthropic`
`ANTHROPIC_BASE_URL`	تجاوز نقطة نهاية Anthropic الأصلية (الافتراضي: `https://api.anthropic.com`).	اختياري
`ANTHROPIC_PROXY_ENDPOINT_URL`	عنوان URL الكامل لنقطة النهاية لمزوّد وكيل Anthropic (raw-predict بنمط Vertex).	مطلوب عندما يكون `SKILLSPECTOR_PROVIDER=anthropic_proxy`
`ANTHROPIC_PROXY_API_KEY`	رمز Bearer لمزوّد وكيل Anthropic.	مطلوب عندما يكون `SKILLSPECTOR_PROVIDER=anthropic_proxy`
`ANTHROPIC_PROXY_API_VERSION`	قيمة `anthropic_version` المُرسَلة في جسم الطلب (الافتراضي: `vertex-2023-10-16`).	اختياري
`AWS_PROFILE`	ملف تعريف AWS مُسمّى لمزوّد Bedrock — يُصادِق عبر SigV4 من خلال boto3. عند عدم التعيين، تُحلّ سلسلة بيانات اعتماد boto3 القياسية (متغيرات البيئة، بيانات تعريف المثيل، SSO، إلخ).	اختياري (يُستخدم عندما يكون `SKILLSPECTOR_PROVIDER=bedrock`)
`AWS_REGION`	منطقة AWS لنقطة نهاية Bedrock Runtime. الافتراضي هو `us-west-2`.	اختياري (يُستخدم عندما يكون `SKILLSPECTOR_PROVIDER=bedrock`)
`SKILLSPECTOR_MODEL`	تجاوز نموذج المزوّد النشط. بالنسبة للمزوّدات المستضافة، يستبدل هذا الإعداد الافتراضي المضمّن من جدول تحليل LLM. بالنسبة لـ `claude_cli` و`codex_cli`، يُمرَّر هذا كـ `--model` بدلًا من استخدام الخيار الاحتياطي لبيئة تشغيل CLI المحلية.	اختياري
`SKILLSPECTOR_MODEL_REGISTRY`	تجاوز سجل YAML المضمّن لكل مزوّد (`src/skillspector/providers/<provider>/model_registry.yaml`) بمسار مخصص.	اختياري
`SKILLSPECTOR_LOG_LEVEL`	مستوى السجل: `DEBUG`، `INFO`، `WARNING`، `ERROR` (الافتراضي: `WARNING`).	اختياري

مزوّدات CLI (claude_cli، codex_cli): لا حاجة إلى مفتاح API. تُدار المصادقة بالكامل بواسطة جلسة تسجيل الدخول الخاصة بـ agent CLI (claude auth login / codex login). لا يقرأ SkillSpector مفاتيح API أو يمرّرها أبدًا عندما تكون هذه المزوّدات نشطة. تُشغَّل العملية الفرعية في بيئة معزولة مُحصّنة: الأدوات معطّلة، لا MCP، وضع معزول للقراءة فقط (codex)، ويُسلَّم محتوى المهارة غير الموثوق فقط عبر stdin.

خيارات CLI```bash

skillspector scan --help

Options: -f, --format [terminal|json|markdown|sarif] Output format [default: terminal] -o, --output PATH Output file path --no-llm Skip LLM analysis (static only) --yara-rules-dir PATH Extra YARA rules directory -b, --baseline PATH Suppress findings listed in a baseline --show-suppressed List baseline-suppressed findings -V, --verbose Show detailed progress --help Show this message and exit

Generate a baseline of all current findings (see docs/SUPPRESSION.md)

skillspector baseline [-o FILE] [--no-llm] [--reason TEXT]

## دمج SkillSpector

صُمم SkillSpector ليتم تشغيله بواسطة أدوات أخرى (خطوط أنابيب CI، بوابات التثبيت، تكاملات المحرر). رمز الخروج ومخرجات JSON الخاصة به هما عقد مستقر.

### رموز الخروج

ينتهي `skillspector scan` بـ:

| الرمز | المعنى |
|------|---------|
| `0` | اكتمل الفحص، `risk_score` ≤ 50 (التوصية `SAFE` أو `CAUTION`) |
| `1` | اكتمل الفحص، `risk_score` > 50 (التوصية `DO_NOT_INSTALL`) |
| `2` | خطأ (مدخلات غير صالحة، مصدر غير قابل للقراءة، فشل داخلي) |

> يجمع رمز الخروج بين `SAFE` و`CAUTION` في `0`. للتعامل معهما بشكل مختلف (مثل *التحذير* عند `CAUTION` ولكن *الحظر* عند `DO_NOT_INSTALL`)، اقرأ حقل `recommendation` من مخرجات JSON بدلاً من الاعتماد على رمز الخروج.

### مخرجات قابلة للقراءة آلياً

ينتج `--format json` تقرير JSON؛ وبدون `--output`/`-o` يُكتب إلى stdout:```bash
skillspector scan ./my-skill/ --format json

الشكل العام هو (يوضح هذا المثال فحصًا كاملًا مدعومًا بـ LLM؛ مع --no-llm، تكون metadata.llm_requested هي false):```json { "skill": { "name": "...", "source": "...", "scanned_at": "<ISO 8601>" }, "risk_assessment": { "score": 0, "severity": "LOW", "recommendation": "SAFE" }, "components": [ { "path": "...", "type": "...", "lines": 0, "executable": false, "size_bytes": 0 } ], "issues": [ { "id": "...", "category": "...", "severity": "...", "confidence": 0.0, "location": { "file": "...", "start_line": 0 } } ], "metadata": { "has_executable_scripts": false, "skillspector_version": "...", "llm_requested": true, "llm_available": true, "inference_usage": [ { "node": "semantic_security_discovery", "request_kind": "structured_output", "provider": "nv_inference", "model": "azure/anthropic/claude-opus-4-6", "model_source": "provider_response", "usage_source": "provider_response", "prompt_tokens": 1000, "completion_tokens": 100, "cached_tokens": 400, "cache_write_tokens": 50, "total_tokens": 1100 } ] } }

- `risk_assessment.severity` ∈ `LOW | MEDIUM | HIGH | CRITICAL`.
- `risk_assessment.recommendation` ∈ `SAFE | CAUTION | DO_NOT_INSTALL`، مُشتق من severity: `LOW → SAFE`، `MEDIUM → CAUTION`، `HIGH`/`CRITICAL → DO_NOT_INSTALL`.
- يظهر `metadata.llm_error` فقط عند طلب تحليل LLM لكنه غير متاح.
- يحتوي `metadata.inference_usage` على سجل مُنقّى واحد لكل استجابة LLM عندما
  يكشف المزوّد عن عدّادات الرموز. تكون قائمة فارغة عند عدم توفر الاستخدام؛
  لا يقدّر SkillSpector الرموز المفقودة أبدًا. تتضمن إجماليات الـ prompt قراءات
  وكتابات الـ cache بحيث يمكن للتسعير اللاحق فصل تلك الأقسام بأمان.
  يميّز `model_source` بين نموذج مزوّد مُحدَّد بشكل مستقل والنموذج
  المطلوب بالضبط المستخدم عند غياب هوية الاستجابة أو غموضها.
  لا يرسل SkillSpector حاليًا عناصر التحكم في prompt-cache الخاصة بـ Anthropic، لذا
  لا يمكن لطلبات الفحص الخاصة به اختيار مستويات كتابة الـ cache المنفصلة لمدة 5 دقائق أو ساعة واحدة؛
  يتم تطبيع حقول الاستجابة الخاصة بـ TTL بشكل دفاعي إلى عدّاد
  كتابة الـ cache الإجمالي.
- راجع [Inference usage telemetry](https://github.com/nvidia/skillspector/blob/main/docs/INFERENCE_USAGE.md) للحصول على العقد الكامل
  الخاص بالمصدر، ومحاسبة الـ cache، والخصوصية، والاستيعاب الآمن عند الفشل، والتسعير اللاحق.
- يتم تعريف الشكل الكامل لكل مشكلة بواسطة `Finding.to_dict()` في [models.py](https://github.com/nvidia/skillspector/blob/main/src/skillspector/models.py)؛ اعتمد على الحقول أعلاه وتعامل مع أي حقول إضافية على أساس بذل أفضل جهد.

بالنسبة لأدوات CI/IDE، يُصدر `--format sarif` ملف SARIF 2.1.0.

### تعيين البوابة الموصى به

عند استخدام SkillSpector كبوابة تثبيت، اربط التوصية بإجراء:

| `recommendation` | الإجراء المقترح |
|------------------|------------------|
| `SAFE` | السماح |
| `CAUTION` | تنبيه / تحذير المستخدم |
| `DO_NOT_INSTALL` | الحظر |

يحسب SkillSpector نطاق النتيجة والتوصية؛ أما مدى صرامة البوابة (مثل ما إذا كان `CAUTION` يحظر في CI) فهو قرار سياسة للأداة المدمِجة.

## التطوير

### الإعداد

تفترض جميع أهداف `make` أن بيئة افتراضية قد تم إنشاؤها وتفعيلها بالفعل. يستخدم Makefile أداة **uv** إن كانت متاحة، وإلا يستخدم **pip**.```bash
# Clone, create venv, activate, install dev dependencies
git clone https://github.com/NVIDIA/skillspector.git
cd skillspector
uv venv .venv && source .venv/bin/activate
# or: python3 -m venv .venv && source .venv/bin/activate
make install-dev

# Run tests
make test

# Run tests with coverage
make test-cov

# Run linting
make lint

# Format code
make format

كيف يعمل

يستخدم SkillSpector خط أنابيب كشف من مرحلتين:

المرحلة 1: التحليل الساكن

مطابقة أنماط سريعة قائمة على regex عبر 11 محللًا ساكنًا
تحليل سلوكي قائم على AST يكتشف الاستدعاءات الخطرة (exec، eval، subprocess، إلخ)
عمليات بحث حية عن الثغرات عبر OSV.dev لاكتشاف CVEs المعروفة في التبعيات
يفحص جميع الملفات المؤهلة للمحللات في المهارة
استدعاء عالٍ (يكتشف معظم المشكلات)
دقة متوسطة (بعض النتائج الإيجابية الخاطئة)

يُحتفظ بتوقيع OpenSSF Model Signing صالح على المستوى الجذري (skill.oms.sig) في جرد المكونات بنوع oms_signature، لكنه يُستبعد من التحليل الساكن وتحليل محتوى LLM. تحتوي حزم OMS بالضرورة على حقول حمولة وتوقيع وشهادة طويلة مُرمَّزة بـ base64؛ وإلا فقد تصنّف فحوصات الكود المُعتَّم العامة تلك الحقول خطأً كمحتوى تنفيذي مخفي. يتحقق المُعرِّف من البنية الدنيا لـ OMS DSSE/in-toto؛ ولا يتحقق من التوقيع، أو سلسلة الشهادات، أو إدخال سجل الشفافية، أو هوية المُوقِّع. تُفحص ملفات التوقيع غير الصالحة أو غير المعروفة بشكل طبيعي.

المرحلة 2: التحليل الدلالي بواسطة LLM (اختياري)

يقيّم السياق والنية
يرشّح النتائج الإيجابية الخاطئة
يوفّر تفسيرات مقروءة للبشر
يحسّن الدقة إلى ~87%

يتضمن موجّه LLM حمايات ضد كسر الحماية لمنع المهارات الخبيثة من التلاعب بالتحليل.

عمليات البحث الحية عن الثغرات (SC4)

يستخدم SC4 واجهة OSV.dev API لفحص التبعيات مقابل قاعدة بيانات الثغرات مفتوحة المصدر الكاملة — التي تغطي عشرات الآلاف من التنبيهات عبر PyPI وnpm.

لا يتطلب مفتاح API — OSV.dev مجاني وغير مُصادَق عليه.
استعلامات دفعية — تُفحص جميع التبعيات في استدعاء HTTP واحد.
تراجع تلقائي — إذا تعذّر الوصول إلى OSV.dev (بيئة معزولة/دون اتصال)، تُستخدم قائمة تراجع صغيرة مدمجة.
التخزين المؤقت — تُخزَّن النتائج مؤقتًا في الذاكرة لمدة ساعة لتجنّب استدعاءات API المتكررة خلال الجلسة.

تتطلب الأداة وصول HTTPS صادرًا إلى api.osv.dev لبيانات الثغرات الحية. وعندما لا يتوفر ذلك، تقتصر النتائج على قائمة التراجع الساكنة.

نموذج الثقة وخروج البيانات

SkillSpector دفاع متعدد الطبقات، وليس صندوقًا رمليًا. اعرف ما يفعله وما لا يفعله قبل الاعتماد عليه:

لا ينفّذ المهارة المفحوصة أبدًا. جميع التحليلات ساكنة (regex، Python AST، YARA) بالإضافة إلى تقييم LLM الاختياري لـ محتويات الملفات — لا يُشغَّل كود المهارة أبدًا.
يرسل تحليل LLM محتويات الملفات المؤهلة للمحللات إلى المزوّد المُهيَّأ. عند تمكين تحليل LLM (الوضع الافتراضي)، تُرسَل محتويات الملفات إلى نقطة نهاية SKILLSPECTOR_PROVIDER النشطة. تُستبعد ملفات توقيع OMS المعروفة. استخدم --no-llm لإبقاء المحتويات محلية (تحليل ساكن فقط).
يرسل SC4 أسماء التبعيات إلى OSV.dev. يستعلم فحص سلسلة التوريد من OSV.dev بأسماء الحزم والإصدارات التي تُصرّح بها المهارة، للبحث عن CVEs المعروفة. هذا أمر جوهري للفحص ويعمل حتى مع --no-llm. يرسل إحداثيات التبعيات (وليس محتويات الملفات)، ولا يتطلب مفتاح API، ويعود إلى قائمة مضمّنة عند تعذّر الوصول إلى OSV.dev.
لا يعزل المضيف في صندوق رملي. يعلّم SkillSpector على الأنماط الخطرة قبل تثبيت المهارة؛ ولا يحتوي أو يعزل مهارة تختار تثبيتها على أي حال.

القيود

المحتوى غير الإنجليزي: قد يفوت الأنماط بلغات أخرى
الهجمات القائمة على الصور: لا يمكنه تحليل النص في الصور
الكود المشفّر/الثنائي: لا يمكنه تحليل المحتوى المُجمَّع أو المشفّر
السلوك أثناء التشغيل: تحليل ساكن فقط، بلا تنفيذ ديناميكي
SC4 دون اتصال: بدون وصول شبكي إلى api.osv.dev، يستخدم SC4 قائمة تراجع ساكنة صغيرة

خلفية البحث

استنادًا إلى بحث من "Agent Skills in the Wild: An Empirical Study of Security Vulnerabilities at Scale" (Liu et al., 2026):

مجموعة البيانات: 42,447 مهارة من الأسواق الرئيسية
عرضة للثغرات: 26.1% تحتوي على ثغرة واحدة على الأقل
عالية الخطورة: 5.2% تُظهر نية خبيثة محتملة
النتيجة الرئيسية: المهارات التي تحتوي على نصوص برمجية قابلة للتنفيذ أكثر عرضة للثغرات بمقدار 2.12 ضعفًا

تكامل Python API```python

from skillspector import graph

Invoke the LangGraph workflow

result = graph.invoke({ "input_path": "/path/to/skill", "output_format": "json", # terminal, json, markdown, or sarif "use_llm": True, # False for static-only analysis })

Access results

print(f"Risk Score: {result['risk_score']}/100") print(f"Severity: {result['risk_severity']}") print(f"Recommendation: {result['risk_recommendation']}")

for finding in result["filtered_findings"]: print(f"[{finding['severity']}] {finding['rule_id']}: {finding['message']}")

## الترخيص

رخصة Apache 2.0 - راجع [LICENSE](https://github.com/nvidia/skillspector/blob/main/LICENSE) للتفاصيل.

## المساهمة

المساهمات مرحّب بها! يُرجى قراءة إرشادات المساهمة الخاصة بنا وتقديم طلبات السحب.

## الدعم

- **المشكلات**: [مشكلات GitHub](https://github.com/NVIDIA/skillspector/issues)

اقرأ المزيد

SkillSpector v2.10.0

الفئات

SkillSpector v2.10.0

SkillSpector

نظرة عامة

التوثيق

الميزات

البدء السريع

التثبيت

Update later: uv tool update skillspector

Clone the repository

Create and activate virtual environment

or: python3 -m venv .venv && source .venv/bin/activate

Install for production use

Or install with development dependencies

المزايا الرئيسية

التثبيت

من المصدر

باستخدام pip

باستخدام Docker

الاستخدام

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

خيارات متقدمة

التكامل مع CI/CD

التكوين

ملف التكوين

القواعد المخصصة

أمثلة الكشف

حقن SQL

البرمجة النصية عبر المواقع (XSS)

الأسرار المضمنة

تنسيقات الإخراج

JSON

SARIF

المساهمة

إعداد بيئة التطوير

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

الترخيص

إخلاء المسؤولية

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

Scan a local skill directory

Scan a single SKILL.md file

Scan a Git repository

Scan a zip file

الفحص الدفعي

تحليل LLM

Stock OpenAI

Anthropic

Anthropic via Vertex-style proxy (corporate gateways, GCP Vertex AI)

AWS Bedrock (Claude via SigV4)

Optional: select an AWS named profile. When unset, the standard

boto3 credential chain (env vars, instance metadata, SSO, etc.) resolves.

export AWS_PROFILE=my-profile

Default model: us.anthropic.claude-sonnet-4-6-20250915-v1:0

Override with any Bedrock model ID, cross-region inference-profile

ID, or your own application-inference-profile ARN:

export SKILLSPECTOR_MODEL=us.anthropic.claude-opus-4-6-20250915-v1:0

NVIDIA build.nvidia.com

Local Claude CLI — no API key; uses your existing claude auth login session

Requires: claude CLI installed and authenticated (claude auth login)

Uses the local Claude CLI runtime fallback unless SKILLSPECTOR_MODEL is set.

export SKILLSPECTOR_MODEL=claude-sonnet-4-6

Local Codex CLI — no API key; uses your existing codex login session

Requires: codex CLI installed and authenticated

Local Ollama or any OpenAI-compatible endpoint

Override the provider's default model

Skip LLM analysis (faster, static analysis only)

الإعدادات

متغيرات البيئة

خيارات CLI```bash

Generate a baseline of all current findings (see docs/SUPPRESSION.md)

كيف يعمل

المرحلة 1: التحليل الساكن

المرحلة 2: التحليل الدلالي بواسطة LLM (اختياري)

عمليات البحث الحية عن الثغرات (SC4)

نموذج الثقة وخروج البيانات

القيود

خلفية البحث

تكامل Python API```python

Invoke the LangGraph workflow

Access results

الفئات

Local Claude CLI — no API key; uses your existing `claude auth login` session

Local Codex CLI — no API key; uses your existing `codex login` session