ماسح أمني موحد لخوادم MCP مع أوضاع config و pentest و repo-scan. يُنشئ تقارير SARIF للتكامل مع CI/CD، ويكتشف الأسرار والثغرات وسوء التهيئة عبر محللات token و LLM.
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. مطلوب نماذج LLM لتشغيل اختبار الاختراق. قم بتشغيله قبل النشر الفعلي في الإنتاج.
# 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
قدرات الكشف:
ينشئ MCP X-Ray تقارير بتنسيق SARIF (تنسيق تبادل نتائج التحليل الثابت)، وهو مدعوم على نطاق واسع من قبل الأدوات الأمنية ومنصات 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>
بشكل افتراضي، تستخدم أداة اختبار الاختراق LLM لإنشاء خطط اختبار تلقائياً بناءً على الأدوات المتاحة من خوادم MCP. يمكن أيضاً تخصيص خطط الاختبار وتقديمها كملفات YAML. خطط الاختبار هي ملفات YAML تحتوي على حالات اختبار مع وسائط إدخال ومخرجات متوقعة.
السلوك الافتراضي (خطة اختبار مولدّة بواسطة LLM):
./mcpxray pentest /path/to/mcp/config.json --llm-model claude-sonnet-4-5
خطة اختبار مخصصة:
./mcpxray pentest /path/to/mcp/config.json --test-plan /path/to/test-plan.yaml --llm-model claude-sonnet-4-5
يدعم MCP X-Ray مزودي LLM التاليين لتحليل الأدوات:
claude-sonnet-4-5ANTHROPIC_API_KEYgpt-5OPENAI_API_KEYarn:aws:bedrock: وتحتوي على llamaarn:aws:bedrock:<region>:<account-id>:inference-profile/us.meta.llama3-2-1b-instruct-v1:0لتحليل الأدوات القائم على LLM، قم بتكوين بيانات اعتماد واجهة برمجة التطبيقات LLM الخاصة بك:
export ANTHROPIC_API_KEY=your-api-key
export OPENAI_API_KEY=your-api-key
يتطلب كل مزود متغير البيئة الخاص به. يكتشف الأداة تلقائياً المزود الذي يجب استخدامه بناءً على اسم النموذج.
بالنسبة لنماذج AWS Bedrock، قم بتكوين بيانات اعتماد AWS باستخدام إحدى الطرق القياسية لـ AWS SDK:
# الخيار 1: متغيرات البيئة
export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key
export AWS_REGION=us-east-1
# الخيار 2: ملف بيانات اعتماد AWS (~/.aws/credentials)
# الخيار 3: دور IAM (عند التشغيل على EC2/ECS/Lambda)
يستخدم MCP X-Ray AWS SDK الذي سيقوم بتحميل بيانات الاعتماد تلقائياً من البيئة أو ملف بيانات الاعتماد أو دور IAM.
نرحب بالمساهمات! يرجى التأكد من أن: