traceforce/mcp-xrayماسح أمني موحد لخوادم MCP مع أوضاع config و pentest و repo-scan. يُنشئ تقارير SARIF للتكامل مع CI/CD، ويكتشف الأسرار والثغرات وسوء التهيئة عبر محللات token و LLM.
[!NOTE] هل تبحث عن تأمين مهارات وكلاء الذكاء الاصطناعي؟ اطّلع على Skill X-Ray، وهو ماسح أمان ثابت مفتوح المصدر يحلّل حزم المهارات بحثًا عن سلوك خبيث أو محفوف بالمخاطر قبل التثبيت، دون تنفيذها.
MCP X-Ray هو حل موحّد مفتوح المصدر لفحص الأمان واختبار الاختراق لخوادم بروتوكول سياق النموذج (MCP). وهو يُنشئ تقارير SARIF جاهزة للإنتاج لتكامل سلس مع أدوات الأمان وخطوط أنابيب CI/CD. يمكن اختياريًا رفع نتائج الفحص إلى Traceforce Atlas لإدارة الأمان وتتبّعه مركزيًا. يضم Atlas أكثر من 600 خادم MCP في سجله، مما يوفّر قاعدة بيانات شاملة لتقييم الأمان لمنظومة MCP.
# Clone the repository
git clone https://github.com/traceforce/mcp-xray
cd mcp-xray
# Install required dependencies (buf, etc.)
make install-dependencies
# Build everything (generates protobuf code and builds the binary)
# The binary will be created as `mcpxray` in the current directory
make all
افحص إعدادات MCP بحثًا عن المشكلات الأمنية؛ شغّله قبل اختبار الاختراق لأخذ خط أساس لإعدادك.
# Scan a specific MCP config file (uses token analyzer by default)
./mcpxray config-scan /path/to/mcp/config.json
# Scan all known MCP config paths automatically for Cursor, Claude and Windsurf.
# Known config locations (relative to home directory):
# ~/.cursor/mcp.json (Cursor)
# ~/Library/Application Support/Claude/claude_desktop_config.json (Claude Desktop)
# ~/.codeium/windsurf/mcp_config.json (Windsurf)
./mcpxray config-scan --scan-known-configs
# Use LLM analyzer for more extensive and deepr analysis
./mcpxray config-scan /path/to/mcp/config.json --analyzer-type llm --llm-model claude-3-5-sonnet-20241022
# Specify custom output file
./mcpxray config-scan /path/to/mcp/config.json --output custom-report.sarif.json
قدرات الكشف:
نفّذ خطط الاختبار الأمني عن طريق إجراء استدعاءات أدوات فعلية ضد خوادم MCP. يُشترط استخدام LLMs لتشغيل اختبار الاختراق. شغّل هذا قبل النشر الفعلي في بيئة الإنتاج.
# Run pentest with auto-generated test plan (requires LLM model)
./mcpxray pentest /path/to/mcp/config.json --llm-model claude-sonnet-4-5
# Use a custom test plan YAML file
./mcpxray pentest /path/to/mcp/config.json --test-plan /path/to/test-plan.yaml --llm-model claude-sonnet-4-5
قدرات الكشف: تنفيذ الشيفرة، وSSRF، واجتياز المسار، وتجاوز التفويض، وحقن المدخلات، والكشف عن المعلومات، وثغرات DoS
افحص قاعدة الشيفرة بحثًا عن الثغرات؛ استخدمه عندما تملك الشيفرة أو تكون قادرًا على تغييرها.
# Scan current directory
./mcpxray repo-scan
# Scan a specific repository
./mcpxray repo-scan /path/to/repository
# Specify custom output file
./mcpxray repo-scan --output custom-report.sarif.json
قدرات الكشف:
يستخدم تحليل التلوث SAST محرك OpenGrep. ثبّت
الملف التنفيذي المثبّت والمُتحقَّق منه بـ SHA عبر make install-opengrep (Linux x86_64/arm64، macOS
arm64/x86_64). على المنصات الأخرى، ثبّت opengrep بنفسك واضبط
MCPXRAY_OPENGREP_BIN. يُفعَّل تحليل التلوث عبر التثبيت: يشغّله repo-scan
كلما كان المحرك المثبّت قابلًا للحل، وعندما يكون المحرك غائبًا يتخطى تحليل التلوث
ويظل يشغّل SCA والأسرار وقواعد الأوامر غير الآمنة.
لتحليل التلوث بين الملفات وبين الإجراءات على Go وTypeScript (وPython)، ثبّت محرك CodeQL. يُفعَّل عبر التثبيت أيضًا، وتُدمج نتائجه مع نتائج OpenGrep:
make install-codeql # pinned CodeQL bundle (Linux x86_64, macOS, Windows)
./mcpxray repo-scan <repo> # every installed engine runs; results merged
يبني CodeQL قاعدة بيانات لكل لغة، لذا يستغرق الفحص وقتًا أطول بشكل ملحوظ بمجرد تثبيت الحزمة؛
وهذه التكلفة هي ثمن التحليل عبر الملفات. للعودة إلى المرور السريع داخل الملف الواحد،
أزل محرك التحليل بالطريقة نفسها التي ثبّتته بها: احذف الحزمة من make install-codeql
(فهي موجودة بجوار الملف التنفيذي)، أو أزل تعيين MCPXRAY_CODEQL_BIN إذا كنت قد وجّهته إلى ملف تنفيذي محدد. يستخرج Python
وTypeScript دون الحاجة إلى بناء (فلا يُنفَّذ الهدف أبدًا). أما Go فليس لديه وضع بلا بناء، لذا
يُجمّع CodeQL الهدف؛ وتُشغَّل تلك الخطوة فقط مع --codeql-allow-build، وإلا تُتخطى مع
تحذير؛ ولا يتوقف الفحص أبدًا بانتظار إدخال من المستخدم.
تحصل كل لغة على ميزانية زمنية تغطي database create بالإضافة إلى analyze — 600 ثانية افتراضيًا.
والهدف الذي يتجاوزها لا يسهم بشيء، لذا ارفعها للمستودعات الكبيرة باستخدام
--codeql-timeout <seconds> (أو MCPXRAY_CODEQL_TIMEOUT)؛ وتفوز الخيار عند تعيين كليهما.
ويُبلَّغ عن تجاوز الميزانية بصيغة timed out after Ns، وليس أبدًا كصفر نظيف.
يولّد MCP X-Ray التقارير بصيغة SARIF (Static Analysis Results Interchange Format)، وهي مدعومة على نطاق واسع من أدوات الأمان ومنصات CI/CD.
ارفع نتائج الفحص إلى Traceforce Atlas لإدارة الأمان المركزية وإعداد التقارير وتتبعها بمرور الوقت. أضف الخيار --upload إلى أي أمر فحص. استخدم --clean-up لإزالة الملفات المولّدة بعد الرفع الناجح.
متغيرات البيئة المطلوبة:
TRACEFORCE_CLIENT_IDTRACEFORCE_CLIENT_SECRETيمكن تنزيل بيانات الاعتماد هذه من صفحة الإعدادات في واجهة Atlas.
# Upload config scan results
./mcpxray config-scan /path/to/mcp/config.json --upload
# Upload with cleanup
./mcpxray config-scan /path/xia-add-registry-imageto/mcp/config.json --upload --clean-up
# Upload pentest results
./mcpxray pentest /path/to/mcp/config.json --llm-model claude-sonnet-4-5 --upload
تتوفر أمثلة على مخرجات الفحص في examples/findings/.
تتوفر ملفات تكوين MCP نموذجية في الدليل examples/mcp_configs/.
يتوفر خادم MCP نموذجي في الدليل examples/mcp_server/:
mcp_server.py: خادم FastMCP يستخدم نقل streamable-httpmcp.json: ملف التكوين للاتصال بالخادمREADME.md: تعليمات إعداد الخادم وفحصهيوفر MCP X-Ray طريقتين لتحليل أمان الأدوات:
يستخدم محلل الرموز مطابقة الأنماط القائمة على القواعد للكشف السريع عن المشكلات الأمنية في أوصاف الأدوات. وهو سريع، ولا يتطلب مفاتيح API، ويعمل دون اتصال بالإنترنت. يستخدم محلل الرموز نوعين من القواعد:
internal/configscan/tokenanalyzer/token_rules.yaml. تحدد كل قاعدة:
internal/yararules/unsafe_patterns.yar. تكشف هذه القواعد عن أنماط أوامر النظام غير الآمنة.الاستخدام:
mcpxray config-scan --analyzer-type token
يستخدم محلل LLM نماذج اللغة الكبيرة لإجراء تحليل دلالي عميق لأوصاف الأدوات، مما يوفر رؤى أمنية أكثر شمولاً.
الاستخدام:
mcpxray config-scan --analyzer-type llm --llm-model <model-name>