ريكون

ريكون هو خادم MCP لهندسة عكسية للملفات القابلة للتنفيذ في ويندوز وتنسيقات ثنائية ذات صلة. يجمع بين إدخال العينات، التقييم الثابت، استرداد الوظائف بمساعدة Ghidra، أدوات متخصصة تعتمد على الإضافات، إدارة القطع الأثرية، وتنفيذ وقت تشغيل ويندوز معزول اختياريًا عبر واجهة بروتوكول سياق النموذج.

يتم تنظيم سير عمل الخادم الحالي الموجه للذكاء الاصطناعي حول سطح بوابة بسيط:

1. استخدم workflow.search لترتيب الملفات الشخصية وسير العمل والقدرات المتخصصة المتطابقة لنوع الملف وهدف المستخدم.
2. استخدم workflow.run action=request_upload لتحميل ملفات المضيف، أو دع workflow.search يوجه العملاء القدامى إلى أدوات توافق إدخال العينات المخفية.
3. استخدم workflow.run action=start مع sample_id المعاد.
4. استخدم workflow.run action=status و workflow.run action=promote لمراقبة وتعميق التشغيل المرحلي.
5. استخدم artifact.read للقطع الأثرية الكاملة المستمرة عندما لا يكون ناتج سير العمل المضغوط كافياً.

sample.*, workflow.analyze.*, workflow.triage, tools.discover, و task.status تبقى مسجلة للتوافق أو الفحص منخفض المستوى، لكن العملاء الجدد يجب أن يفضلوا workflow.search, workflow.run, و artifact.read.

عند الاتصال عبر بوابة rikune-agent عن بعد، يرى عملاء MCP أسماء نقل مستقرة: workflow_search, workflow_run, artifact_read, rikune_tool_call, وعناصر التحكم rikune_connection_*. rikune_connection_refresh يحدث ذاكرة التخزين المؤقت الداخلية للقدرات العلوية فقط؛ لا يوسع قائمة أدوات MCP. استخدم rikune_tool_call فقط بعد أن يحدد workflow_search أداة تحليل داخلية محددة لا تغطيها البوابة الرئيسية لسير العمل أو القطع الأثرية.

ما يوفره ريكون

• خادم MCP stdio لعملاء الذكاء الاصطناعي وبيئات تشغيل العوامل.
• واجهة HTTP API اختيارية ولوحة تحكم للتحميل والتنزيل وفحوصات الصحة وأحداث SSE والوصول إلى القطع الأثرية.
• مساحات عمل للعينات تعتمد على SHA-256 مع ملفات أصلية دائمة وأدلة ذاكرة تخزين مؤقت وقطع أثرية للتحليل وجلسات تحميل.
• استمرارية تعتمد على SQLite للعينات والتحليلات والوظائف والأدلة والقطع الأثرية والدفعات وجلسات التصحيح وبيانات جدولة المهام.
• بنية إضافات مع 111 إضافة مدمجة واكتشاف إضافات خارجية.
• سطح أدوات تدريجي: البوابة الافتراضية الموجهة للذكاء الاصطناعي صغيرة عمداً؛ يستخدم workflow.search نوع العينة والنتائج وبيانات الملف الشخصي لتوجيه نحو القدرات المتخصصة دون كشف كل أداة مسبقاً.
• تحليل وإثراء ثابت لـ PE و ELF و Mach-O و APK/DEX و Office والبرامج الثابتة و UEFI/SMM و CUDA PTX/CUBIN/fatbin والسلاسل النصية و YARA و SBOM والتوقيعات والحزم و .NET و Go و Rust وغيرها.
• تكامل Ghidra و Rizin و RetDec و angr و Capstone و Graphviz و Qiling و PANDA و Speakeasy و Wine و Frida وبيئة وقت التشغيل الديناميكية حيثما كان متاحاً.
• تثبيت خلفي Docker يعتمد على الإضافات مع مستويات افتراضية واختيارية وبحثية ووقت تشغيل و GPU و BYO و sidecar لأدوات الهندسة العكسية المدعومة بالعمال.
• تقسيم اختياري للمحلل/وقت التشغيل لتنفيذ ويندوز مباشر عبر وكيل مضيف ويندوز أو Windows Sandbox أو VM Hyper-V.
• بوابات سياسة للتنفيذ المباشر والوصول إلى الشبكة والتحميل الخارجي وفك التجميع الشامل.

بداية سريعة

محلل Docker ثابت

Docker الثابت هو الإعداد الافتراضي الأكثر أماناً. لا يقوم بتنفيذ العينات.

.\rikune.ps1 install -Profile static -DataRoot "D:\Docker\rikune"

./rikune.sh install --profile static --data-root "$HOME/.rikune"

المكافئ اليدوي:

npm install
npm run build
npm run docker:generate:all
docker compose --env-file .docker-runtime.env -f docker-compose.analyzer.yml up -d --build analyzer

Docker هجين + وقت تشغيل ويندوز

الوضع الهجين يشغل المحلل في Docker ويفوض عمل ويندوز المباشر إلى وكيل مضيف ويندوز. يمكن للوكيل المضيف تشغيل Windows Sandbox عند الطلب أو التحكم في VM Hyper-V مهيأة.

.\rikune.ps1 install -Profile hybrid -InstallRuntime

من Linux/macOS مع مضيف ويندوز عن بعد:

./rikune.sh install --profile hybrid --windows-host <windows-host> --windows-user <windows-user>

ربط عميل MCP لا يبدأ Windows Sandbox أو يشغل عينة. يبدأ عمل وقت التشغيل المباشر فقط عندما تطلبه أداة صراحة، مثل runtime.debug.session.start أو runtime.debug.command أو sandbox.execute أو مرحلة تنفيذ ديناميكي مرقّاة.

تطوير محلي

npm install
npm run build
npm test
node dist/index.js

الحزمة الجذرية تتطلب Node.js 22 أو أحدث. بعض حزم وقت التشغيل الفرعية يمكن تشغيلها على إصدارات أقدم من Node، لكن التطوير في المستودع وواجهة سطر الأوامر الجذرية المنشورة يجب أن تستخدم Node 22+.

تدفق البوابة الرئيسي

بحث وتحميل

ابدأ بـ workflow.search كلما كان سير العمل المطلوب أو نوع الملف أو الخلفية غير واضحة. ترتب الملفات الشخصية المتطابقة وتعيد تلميحات توجيه/جاهزية مضغوطة دون تفعيل الأدوات المتخصصة المخفية.

بالنسبة لملفات المضيف، اتصل بـ workflow.run action=request_upload، ثم أرسل البايتات الخام إلى عنوان URL للتحميل المعاد، ثم اقرأ sample_id من استجابة HTTP. sample.request_upload و sample.ingest هما أدوات مساعدة للتوافق وليس المسار الطبيعي الموجه للذكاء الاصطناعي.

بالنسبة لنشر المحلل عن بعد أو rikune-agent، قم بتعيين API_PUBLIC_BASE_URL أو RIKUNE_API_PUBLIC_BASE_URL أو RIKUNE_ANALYZER_PUBLIC_URL إلى قاعدة واجهة HTTP القابلة للوصول من العميل، مثل http://159.195.136.226:18080. ثم تعيد جلسات التحميل قيم upload_url / status_url عامة بدلاً من عناوين localhost المحلية للحاوية. كما تقوم البوابة عن بعد بتطبيع عناوين تحميل localhost من المحللين الأقدم إلى نقطة نهاية المحلل المهيأة.

إذا كانت واجهة HTTP API مفعلة، فإن POST /api/v1/samples لا يزال متاحاً للتكاملات غير MCP. الإدخال الناجح يعيد sample_id؛ يجب أن يستخدم التحليل sample_id، وليس مساراً محلياً، بعد الاستيراد.

بدء التحليل

اتصل بـ workflow.run action=start مع sample_id. تقوم المرحلة الأولى بعمل ملف تعريف سريع وإنشاء أو إعادة استخدام تشغيل تحليل. plan_id المعاد يتوافق مع تشغيل التحليل المستمر.

ترقية المراحل

استخدم workflow.run action=promote لطلب مراحل أعمق. يقوم خط الأنابيب حالياً بنمذجة هذه المراحل:

• fast_profile
• enrich_static
• function_map
• reconstruct
• semantic_reviews
• dynamic_plan
• dynamic_execute
• summarize

يتم وضع العمل الطويل في قائمة الانتظار عبر نظام الوظائف. استطلع حالة المرحلة المضغوطة باستخدام workflow.run action=status.

workflow.run action=status هو العرض الأساسي للتشغيل المرحلي. قد يتم اقتطاع حمولات المرحلة التاريخية الكبيرة مع تحذير على المستوى الأعلى؛ استخدم artifact.read للقطع الأثرية الكاملة. task.status هو عرض توافق خام للعملية/قائمة الانتظار ويشمل ذاكرة external_active_* الخاصة بعمليات المحلل الفرعية.

مراجعة النتائج

أسطح مفيدة للمتابعة:

• workflow.search
• workflow.run
• analysis.context.get
• artifact.read، بالإضافة إلى أدوات مساعدة للتوافق مثل artifact.list و artifact.diff و artifact.download
• report.summarize و report.generate و workflow.summarize
• workflow.semantic_name_review
• workflow.function_explanation_review
• workflow.module_reconstruction_review
• tool.help و و للتوافق/التصحيح

الهندسة المعمارية

مسار الشيفرة الحالي هو:

src/index.ts
  -> loadConfig()
  -> WorkspaceManager / DatabaseManager / PolicyGuard / CacheManager / StorageManager / JobQueue
  -> optional RuntimeClient أو تهيئة Windows sandbox
  -> registerAllTools()
  -> MCP stdio server

توجد وحدات الخادم الأساسية تحت src/core/:

تظل بعض الملفات على المستوى الجذر مثل src/server.ts و src/tool-registry.ts و src/plugins.ts موجهات توافق. يجب أن تستهدف الشيفرة الجديدة src/core/*.

خطط النشر

تتم تهيئة أوضاع وقت التشغيل عبر runtime.mode أو متغيرات البيئة:

• disabled: لا تفويض وقت تشغيل.
• manual: الاتصال بنقطة نهاية وقت تشغيل مزودة.
• remote-sandbox: التفويض إلى وكيل مضيف ويندوز.
• auto-sandbox: المحلل الأصلي لويندوز يطلق Windows Sandbox محلياً.

يجب على المحللات Docker/WSL استخدام remote-sandbox، وليس auto-sandbox.

نظام الإضافات

يتضمن ريكون حالياً 111 إضافة مدمجة تحت src/plugins/<id>/. يمكن للإضافات تسجيل الأدوات، وإعلان التبعيات، وكشف مخطط التهيئة، والمشاركة في خطافات دورة الحياة، وتوفير بيانات Docker الوصفية، وإعلان أدوات محدودة مدعومة بالعمال عبر بيانات workerBackend.

تحتفظ مجموعة العمال الأمامية بأدوات التخطيط فقط كأسطح تقييم وتسليم، ثم تضيف أدوات تنفيذ صريحة بجانبها. تكشف restringer.deobfuscation.run و jsimplifier.pipeline.run و jsir.cascade.normalize و gtirb.ir.generate و remill.lift.run و manifold.fact.extract و qbdi.trace.run و culifter.gpu.artifact.inventory عن عقود العمال عبر workflow.search و plugin.list و tool.help و tool.readiness؛ يبقى tools.discover بوابة توافق منخفضة المستوى. يظل الاكتشاف والجاهزية سلبيين: يبلغان عن بيانات وصفية للخلفية وإرشادات إعداد دون بدء REstringer أو JSIMPLIFIER أو JSIR/CASCADE أو GTIRB أو Remill أو Manifold أو QBDI أو برامج تشغيل GPU أو Node/V8 أو المتصفحات أو أدوات قياس وقت التشغيل.

يقرأ توليد Docker تبعيات الإضافة systemDeps وبيانات حزمة العمال مباشرة. تقوم الصور الافتراضية بتثبيت أغلفة ثابتة منخفضة المخاطر مثل REstringer و JSIMPLIFIER و Manifold و WABT والتحقق من LIEF؛ يمكن للملفات الشخصية الاختيارية تفعيل مسارات ثابتة مثل JSIR/CASCADE و JSVMP و GTIRB و radare2 و Triton-style؛ تظل الخلفيات الثقيلة/وقت التشغيل/GPU/الحساسة للترخيص مقيدة بالملف الشخصي أو BYO أو sidecar.

node scripts/generate-docker.mjs --dry-run
node scripts/generate-docker.mjs --profile=full --backend-profile=optional
node scripts/generate-docker.mjs --all-profiles --dry-run

يتم التحكم في تحميل الإضافات بواسطة PLUGINS:

PLUGINS=*                 # جميع الإضافات المدمجة
PLUGINS=pe-analysis,yara  # إضافات محددة
PLUGINS=-dynamic          # الكل باستثناء الديناميكي

استخدم هذه الأدوات MCP في وقت التشغيل:

• workflow.search
• workflow.run
• plugin.list
• plugin.enable
• plugin.disable
• tools.discover و tool.readiness للتوافق/التصحيح منخفض المستوى

انظر docs/PLUGINS.md و packages/plugin-sdk/README.md.

واجهة HTTP API

عندما يكون api.enabled صحيحاً، يعرض خادم الملفات المدمج:

تتم معالجة مصادقة مفتاح API وتحديد المعدل ورؤوس الأمان و CORS المحدودة بواسطة طبقة HTTP.

المتطلبات الأساسية

الحد الأدنى لتطوير الأساس:

• Node.js 22+
• npm
• Python 3.11+ موصى به للعمال ونصوص التحليل
• Docker 20.10+ و Docker Compose v2 لملفات Docker الشخصية
• Java 21+ لإصدارات Ghidra الحديثة
• Ghidra للتحليل الوظيفي المدعوم بمفكك التجميع
• Windows 10/11 Pro أو Enterprise أو دعم VM مكافئ لمسارات Windows Sandbox و Hyper-V في وقت التشغيل

الأدوات الاختيارية خاصة بالإضافات. قم بتشغيل system.health و system.setup.guide و tool.readiness و plugin.list لرؤية ما هو مفقود في بيئة معينة.

هيكل المشروع

src/
  index.ts                    مدخل الخادم الرئيسي
  core/                       خادم MCP والسجل والمنفذ وتنسيق الإضافات
  core/tool-registry/         أجزاء تسجيل الأدوات/الاستبانات/الموارد المدمجة
  tools/                      تطبيقات الأدوات الأساسية
  workflows/                  سير العمل للتحليل المرحلي والتقييم وإعادة البناء والمراجعة
  analysis/                   حالة التشغيل ومشغل المهام الخلفية
  plugins/                    111 إضافة مدمجة
  persistence/                استمرارية SQLite ومساحة العمل
  sample/                     إنهاء العينة وفحص مساحة العمل
  storage/                    القطع الأثرية والتحميلات والاحتفاظ
  runtime-client/             عميل التفويض لوقت التشغيل من جانب المحلل
  worker/                     تنسيق عمال Ghidra و Python
packages/
  plugin-sdk/                 حزمة SDK العامة للإضافات
  shared/                     أنواع عقود وقت التشغيل والأدوات
  runtime-node/               منفذ وقت تشغيل معزول
  windows-host-agent/         وكيل مضيف Windows Sandbox / Hyper-V
workers/                      نصوص عمل Python وقواعد YARA
docker/                       قوالب Dockerfile المولدة وملفات الملفات الشخصية
docs/                         وثائق الهندسة والإضافات ووقت التشغيل والنشر
tests/                        اختبارات الوحدة والتكامل والنهاية إلى النهاية

أوامر التطوير

npm install
npm run build
npm test
npm run typecheck
npm run validate
npm run docker:generate:all

فحوصات مركزة مفيدة:

npm run test:unit
npm run test:integration
npm run test:e2e
npm run build:runtime

تكوين عميل MCP

بناء محلي:

{
  "mcpServers": {
    "rikune": {
      "command": "node",
      "args": ["D:/Playground/windows-exe-decompiler-mcp-server/dist/index.js"],
      "env": {
        "API_ENABLED": "true",
        "API_PORT": "18080",
        "API_PUBLIC_BASE_URL": "http://127.0.0.1:18080",
        "PLUGINS": "*"
      }
    }
  }
}

Docker stdio:

{
  "mcpServers": {
    "rikune": {
      "command": "docker",
      "args": ["exec", "-i", "rikune-analyzer", "node", "dist/index.js"]
    }
  }
}

حزمة منشورة:

npm install -g rikune
rikune
rikune docker-stdio
rikune agent

التخزين

بشكل افتراضي، يخزن ريكون البيانات المستمرة تحت جذر ريكون على مستوى المستخدم. عادةً ما تقوم مثبتات Docker بتعيين ذلك الجذر إلى دليل مضيف مثل D:\Docker\rikune.

أدلة فرعية شائعة:

• samples/
• artifacts/
• uploads/
• cache/
• logs/
• ملف قاعدة بيانات SQLite
• سجل تدقيق JSONL

يتم تجميع مساحات عمل العينات حسب SHA-256 لتجنب تعارض المسارات والحفاظ على النسخ الأصلية غير القابلة للتغيير.

حدود الأمان

تم تصميم ريكون لتحليل البرامج الضارة والثنائيات غير الموثوقة، لكنه ليس حدود أمان سحرية بحد ذاته.

• يجب أن يكون وضع Docker الثابت هو الوضع الافتراضي للتحليل الروتيني.
• يجب أن يحدث تنفيذ ويندوز المباشر داخل Windows Sandbox أو VM معزولة.
• ترفض عقدة وقت التشغيل بدء التشغيل غير الآمن ما لم يتم تجاوزها صراحة.
• الإجراءات الخطيرة محمية بواسطة PolicyGuard.
• يستخدم تنفيذ الأوامر واجهات برمجة تطبيقات عملية منظمة والتحقق من الأوامر المسموح بها.
• لا تقم بتشغيل عينات غير معروفة على محطة عمل مضيف خارج نموذج عزل وقت التشغيل.

انظر SECURITY.md و TROUBLESHOOTING.md.

خريطة الوثائق

• INSTALL.md: دليل مثبت Docker باللغة الصينية.
• DEPLOYMENT.md: ملفات النشر وهيكل وقت التشغيل.
• docs/ARCHITECTURE.md: هندسة الشيفرة الحالية.
• docs/PLUGINS.md: قائمة الإضافات ومفاهيم SDK ودورة الحياة والاكتشاف.
• docs/ANALYSIS-RUNTIME.md: نموذج التنفيذ المرحلي ووقت التشغيل.
• docs/ASYNC-JOB-PATTERN.md: نمط المهام غير المتزامنة والاستقصاء.
• docs/MIGRATION-ASYNC.md: ملاحظات الانتقال لسير العمل غير المتزامن المرحلي.
• docs/DYNAMIC-RUNTIME-ROADMAP.md: خارطة طريق وقت التشغيل والحالة.
• CONTRIBUTING.md: تدفق التطوير والمساهمة.
• packages/plugin-sdk/README.md: حزمة تأليف الإضافات.
• workers/README.md: عقد عمل Python.

الترخيص

MIT