PyGhidra-MCP - خادم بروتوكول سياق نموذج Ghidra

نظرة عامة

pyghidra-mcp هو خادم بروتوكول سياق النموذج (MCP) يعمل من سطر الأوامر، ويجلب القوة التحليلية الكاملة لـ Ghidra، وهي مجموعة قوية لهندسة البرمجيات العكسية (SRE)، إلى عالم الوكلاء الأذكياء والأدوات القائمة على نماذج اللغة الكبيرة (LLM). وهو يربط بين ProgramAPI وFlatProgramAPI الخاصة بـ Ghidra بلغة Python باستخدام pyghidra وjpype، ثم يعرض تلك الوظائف عبر بروتوكول سياق النموذج.

MCP هو واجهة موحدة تتيح لنماذج اللغة وأدوات التطوير (مثل VS Code) والوكلاء المستقلين الوصول إلى سياق منظم، واستدعاء الأدوات، والتعاون بذكاء. فكّر في MCP كجسر بين أدوات التحليل القوية ونظام LLM البيئي.

مع pyghidra-mcp، يصبح Ghidra خلفية ذكية—جاهزة للاستجابة للاستعلامات الغنية بالسياق، وأتمتة مهام الهندسة العكسية العميقة، والاندماج في سير العمل المدعوم بالذكاء الاصطناعي.

يدعم pyghidra-mcp الآن وضعي تشغيل:

• وضع headless للتحليل والأتمتة المدفوعين من سطر الأوامر
• وضع --gui، الذي يشغّل Ghidra عبر pyghidra-mcp ويشارك حالة البرنامج الحية مع واجهة المستخدم الرسومية قيد التشغيل

[!NOTE] هذا المشروع التجريبي قيد التطوير النشط. نودّ سماع ملاحظاتكم، وتقارير الأخطاء، وطلبات الميزات، والكود.

هل هذا مجرد Ghidra MCP آخر؟

نعم، إن ghidra-mcp الأصلي رائع. لكن pyghidra-mcp يتبنى نهجًا مختلفًا:

• 🐍 يركّز على الوضع بلا واجهة أولًا، مع دعم الواجهة الرسومية – يعمل بالكامل عبر سطر الأوامر لأتمتة مبسطة، أو يشغّل Ghidra مع --gui عندما تريد التنقل والتعديل المباشر عبر الواجهة الرسومية.
• 🔁 مصمم للأتمتة – مثالي للاندماج مع نماذج اللغة الكبيرة، وخطوط أنابيب CI، والأدوات التي تحتاج إلى سلوك قابل للتكرار.
• ✅ متوافق مع CI/CD – مبني باختبارات وحدة وتكامل قوية لكل من جلسات العميل والخادم.
• 🚀 بدء سريع – يسمح البدء غير المتزامن للخادم ببدء معالجة الطلبات بينما لا تزال الملفات الثنائية قيد التحليل في الخلفية. يدعم التشغيل السريع من سطر الأوامر بأقل إعداد.
• 📦 تحليل على مستوى المشروع – يتيح الهندسة العكسية المتزامنة لجميع الملفات الثنائية في مشروع Ghidra
• 🤖 جاهز للوكلاء – مبني لسير العمل المدفوع بالوكلاء الأذكياء وأتمتة الهندسة العكسية على نطاق واسع.
• 🔍 البحث الدلالي في الكود – يستخدم التضمينات المتجهية (عبر ChromaDB) لتمكين بحث سريع وضبابي عبر الدوال المفككة والتعليقات والرموز—مثالي لاستكشاف الكود الزائف وتصنيف المهام المدفوع بالوكلاء.

يوفر هذا المشروع تجربة تركز على Python أولًا، ومحسّنة للتطوير المحلي، والبيئات بلا واجهة، وسير العمل القابل للاختبار.

مخططات الإعداد

كيف تتصل الأجزاء ببعضها

flowchart LR
    subgraph Clients["Clients"]
        Agent["MCP host / agent"]
        Cli["pyghidra-mcp-cli"]
        User["Ghidra user"]
    end

    subgraph Process["pyghidra-mcp process"]
        Transport["streamable HTTP (recommended)<br/>stdio (local fallback)"]
        Tools["MCP tools"]
        Context["PyGhidra context"]
    end

    Project["Ghidra project<br/>.gpr / .rep"]
    Artifacts["MCP artifacts<br/>ChromaDB + GZF cache"]
    Gui["Ghidra GUI / CodeBrowser<br/>only with --gui"]

    Agent -->|"HTTP (recommended)"| Transport
    Cli -->|"HTTP only"| Transport
    Transport --> Tools
    Tools --> Context
    Context --> Project
    Context --> Artifacts
    Context -.-> Gui
    User -.-> Gui
    Gui -.-> Project

اختيار الوضع

flowchart TD
    Start["What do you need?"]
    Start --> Headless["Agent or automation"]
    Start --> GuiNeed["Live Ghidra GUI control"]
    Start --> Terminal["Interactive terminal client"]

    Headless --> Http["pyghidra-mcp<br/>--transport streamable-http"]
    GuiNeed --> GuiMode["pyghidra-mcp --gui<br/>--transport streamable-http<br/>--project-path project.gpr"]
    Terminal --> HttpServer["Start pyghidra-mcp<br/>--transport streamable-http"]
    HttpServer --> CliMode["Run pyghidra-mcp-cli commands"]

• Headless MCP: استخدم streamable-http. فهو يُبقي Ghidra ومشروعه حيًّا كخادم واحد طويل التشغيل، ويعمل مع كلٍّ من مضيفي MCP وعميل CLI.
• وضع GUI: يُشغّل pyghidra-mcp برنامج Ghidra، ويفتح المشروع، ويكشف أدوات إضافية توجّه CodeBrowser داخل نفس JVM.
• عميل CLI: pyghidra-mcp-cli هو عميل HTTP. ابدأ خادم streamable-http أولًا، ثم أصدر أوامر الطرفية مقابل ذلك الخادم قيد التشغيل.
• stdio: أبقِ على هذا فقط لمضيفي MCP الذين لا يستطيعون الاتصال بنقطة نهاية HTTP.

flowchart TD
    subgraph Clients
        Agent["LLM / MCP host"]
        Cli["pyghidra-mcp-cli"]
        Automation["scripts and CI"]
    end

    subgraph Transports
        Stdio["stdio"]
        Http["streamable-http"]
        Sse["sse legacy"]
    end

    subgraph Server["pyghidra-mcp server"]
        McpServer["MCPServer tool server"]
        Context["PyGhidra context"]
        Indexing["background analysis and Chroma indexing"]

        subgraph Tools["MCP tools"]
            Analysis["decompile, xrefs, bytes, callgraph"]
            Search["symbols, strings, code"]
            ProjectOps["import, delete, metadata, list binaries"]
            Edits["rename function, rename variable, set type, set prototype, set comment"]
            GuiOnly["GUI only: open program, goto, list open programs, set current program"]
        end
    end

    subgraph GhidraRuntime["Ghidra runtime"]
        PyGhidra["pyghidra"]
        Jpype["JPype shared JVM"]
        Project["Ghidra project"]
        Programs["program databases"]
        CodeBrowser["Ghidra GUI / CodeBrowser"]
    end

    Agent --> Http
    Automation --> Http
    Automation --> Sse
    Cli --> Http

    Stdio --> McpServer
    Http --> McpServer
    Sse --> McpServer

    McpServer --> Context
    Context --> PyGhidra
    PyGhidra --> Jpype
    Jpype --> Project
    Project --> Programs
    Context --> Indexing
    Indexing --> Search

    McpServer --> Tools
    Tools --> Context
    GuiOnly -.-> CodeBrowser
    Context -.-> CodeBrowser

المحتويات