سطر أوامر بايثون Ghidra MCP
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/41597/82f9c5eb55db6134d47587275fce66c4ed32b86b5332f7e2d610fa0214070a7f.png" width=60% >
</p>
<p align="center">
<img align="center" alt="GitHub Workflow Status (with event)" src="https://img.shields.io/github/actions/workflow/status/clearbluejar/pyghidra-mcp/pytest-devcontainer-repo-all.yml?style=for-the-badge&label=pytest">
<img align="center" alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/pyghidra-mcp?color=yellow&label=PyPI%20downloads&style=for-the-badge">
<img align="center" src="https://img.shields.io/github/stars/clearbluejar/pyghidra-mcp?style=for-the-badge">
</p>
# PyGhidra-MCP - خادم بروتوكول سياق نموذج Ghidra
### نظرة عامة
**`pyghidra-mcp`** هو خادم بروتوكول سياق النموذج (MCP) يعمل من سطر الأوامر، ويجلب القوة التحليلية الكاملة لـ [Ghidra](https://ghidra-sre.org/)، وهي مجموعة قوية لهندسة البرمجيات العكسية (SRE)، إلى عالم الوكلاء الأذكياء والأدوات القائمة على نماذج اللغة الكبيرة (LLM).
وهو يربط بين [ProgramAPI](https://ghidra.re/ghidra_docs/api/ghidra/program/model/listing/Program.html) و[FlatProgramAPI](https://ghidra.re/ghidra_docs/api/ghidra/program/flatapi/FlatProgramAPI.html) الخاصة بـ Ghidra بلغة Python باستخدام `pyghidra` و`jpype`، ثم يعرض تلك الوظائف عبر بروتوكول سياق النموذج.
MCP هو واجهة موحدة تتيح لنماذج اللغة وأدوات التطوير (مثل VS Code) والوكلاء المستقلين الوصول إلى سياق منظم، واستدعاء الأدوات، والتعاون بذكاء. فكّر في MCP كجسر بين أدوات التحليل القوية ونظام LLM البيئي.
مع `pyghidra-mcp`، يصبح Ghidra خلفية ذكية—جاهزة للاستجابة للاستعلامات الغنية بالسياق، وأتمتة مهام الهندسة العكسية العميقة، والاندماج في سير العمل المدعوم بالذكاء الاصطناعي.
يدعم `pyghidra-mcp` الآن وضعي تشغيل:
- وضع `headless` للتحليل والأتمتة المدفوعين من سطر الأوامر
- وضع `--gui`، الذي يشغّل Ghidra عبر `pyghidra-mcp` ويشارك حالة البرنامج الحية مع واجهة المستخدم الرسومية قيد التشغيل
> [!NOTE]
> هذا المشروع التجريبي قيد التطوير النشط. نودّ سماع ملاحظاتكم، وتقارير الأخطاء، وطلبات الميزات، والكود.
## هل هذا مجرد Ghidra MCP آخر؟
نعم، إن [ghidra-mcp](https://github.com/LaurieWired/GhidraMCP) الأصلي رائع. لكن `pyghidra-mcp` يتبنى نهجًا مختلفًا:
- 🐍 **يركّز على الوضع بلا واجهة أولًا، مع دعم الواجهة الرسومية** – يعمل بالكامل عبر سطر الأوامر لأتمتة مبسطة، أو يشغّل Ghidra مع `--gui` عندما تريد التنقل والتعديل المباشر عبر الواجهة الرسومية.
- 🔁 **مصمم للأتمتة** – مثالي للاندماج مع نماذج اللغة الكبيرة، وخطوط أنابيب CI، والأدوات التي تحتاج إلى سلوك قابل للتكرار.
- ✅ **متوافق مع CI/CD** – مبني باختبارات وحدة وتكامل قوية لكل من جلسات العميل والخادم.
- 🚀 **بدء سريع** – يسمح البدء غير المتزامن للخادم ببدء معالجة الطلبات بينما لا تزال الملفات الثنائية قيد التحليل في الخلفية. يدعم التشغيل السريع من سطر الأوامر بأقل إعداد.
- 📦 **تحليل على مستوى المشروع** – يتيح الهندسة العكسية المتزامنة لجميع الملفات الثنائية في مشروع Ghidra
- 🤖 **جاهز للوكلاء** – مبني لسير العمل المدفوع بالوكلاء الأذكياء وأتمتة الهندسة العكسية على نطاق واسع.
- 🔍 البحث الدلالي في الكود – يستخدم التضمينات المتجهية (عبر ChromaDB) لتمكين بحث سريع وضبابي عبر الدوال المفككة والتعليقات والرموز—مثالي لاستكشاف الكود الزائف وتصنيف المهام المدفوع بالوكلاء.
يوفر هذا المشروع تجربة تركز على Python أولًا، ومحسّنة للتطوير المحلي، والبيئات بلا واجهة، وسير العمل القابل للاختبار.
## مخططات الإعداد
### كيف تتصل الأجزاء ببعضها
```mermaid
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
```
### اختيار الوضع
```mermaid
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.
<details>
<summary>البنية التفصيلية وسطح الأدوات</summary>
```mermaid
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
```
</details>
## المحتويات
- [PyGhidra-MCP - خادم بروتوكول سياق نموذج Ghidra](#pyghidra-mcp---ghidra-model-context-protocol-server)
- [نظرة عامة](#overview)
- [هل هذا خادم Ghidra MCP آخر؟](#yet-another-ghidra-mcp)
- [مخططات الإعداد](#setup-diagrams)
- [كيفية ترابط المكونات](#how-the-pieces-connect)
- [اختيار الوضع](#choosing-a-mode)
- [المحتويات](#contents)
- [البدء](#getting-started)
- [مُحسَّن للوكلاء](#optimized-for-agents)
- [عميل CLI](#cli-client)
- [التثبيت](#installation)
- [البدء السريع مع CLI](#quick-start-with-cli)
- [إنشاء المشاريع وإدارتها وفتح المشاريع الموجودة](#project-creation-management-and-opening-existing-projects)
- [إنشاء مشاريع جديدة](#creating-new-projects)
- [بنية مشروع مكتفية ذاتيًا](#self-contained-project-structure)
- [إنشاء مشروع أساسي](#basic-project-creation)
- [إنشاء مشروع مخصص](#custom-project-creation)
- [إنشاء مشاريع متعددة مترابطة](#creating-multiple-related-projects)
- [فتح مشاريع Ghidra الموجودة](#opening-existing-ghidra-projects)
- [الفتح عبر ملف .gpr](#opening-by-gpr-file)
- [وضع واجهة المستخدم الرسومية](#gui-mode)
- [الإعدادات الافتراضية عند بدء التشغيل والمشاريع الكبيرة](#startup-defaults-and-large-projects)
- [التطوير](#development)
- [الإعداد](#setup)
- [الاختبار والجودة](#testing-and-quality)
- [واجهة برمجة التطبيقات](#api)
- [الأدوات](#tools)
- [العمليات الدفعية](#batch-operations)
- [أدوات القراءة / التحليل](#read--analysis-tools)
- [عمليات المشروع](#project-operations)
- [أدوات التحرير / التعديل](#edit--mutation-tools)
- [أدوات التحكم بواجهة المستخدم الرسومية (`--gui` فقط)](#gui-control-tools---gui-only)
- [الاستخدام](#usage)
- [ربط الملفات التنفيذية باستخدام Docker](#mapping-binaries-with-docker)
- [Streamable HTTP](#streamable-http)
- [Python](#python)
- [Docker](#docker)
- [Claude Code](#claude-code)
- [Codex](#codex)
- [الإدخال/الإخراج القياسي (stdio)](#standard-inputoutput-stdio)
- [Python](#python-1)
- [Docker](#docker-1)
- [الاستخدام مع OpenWeb-UI و MCPO](#using-with-openweb-ui-and-mcpo)
- [مع `uvx`](#with-uvx)
- [مع Docker](#docker-2)
- [الأحداث المرسلة من الخادم (SSE)](#server-sent-events-sse)
- [Python](#python-2)
- [Docker](#docker-3)
- [الإلهام](#inspiration)
- [المساهمة والمجتمع والتشغيل من المصدر](#contributing-community-and-running-from-source)
- [سير عمل المساهمين](#contributor-workflow)
## البدء
ابدأ خادم Streamable HTTP دائم باستخدام [حزمة Python](https://pypi.org/p/pyghidra-mcp) و [`uv`](https://docs.astral.sh/uv/guides/tools/):
```bash
uvx pyghidra-mcp \
--transport streamable-http \
--project-path /absolute/path/to/ghidra-projects \
/absolute/path/to/binary
```
يصبح الخادم بعد ذلك متاحًا على `http://127.0.0.1:8000/mcp`. اتركه قيد التشغيل واضبط عميل MCP لديك لاستخدام هذا العنوان؛ توضح أمثلة [Claude Code](#claude-code) و[Codex](#codex) أدناه الإعداد المتوقع.
لتشغيل واجهة Ghidra الرسومية الحية والتحكم بها من MCP، استخدم `--gui` مع `streamable-http`:
```bash
uvx pyghidra-mcp \
--gui \
--transport streamable-http \
--host 127.0.0.1 \
--port 8000 \
--project-path /absolute/path/to/ghidra-projects \
--project-name my_project
```
> [!IMPORTANT]
> يقوم `--gui` بتشغيل Ghidra عبر `pyghidra-mcp`. وهو لا يتصل بنسخة Ghidra خارجية قيد التشغيل بالفعل.
أو، شغّله كـ [حاوية Docker](https://ghcr.io/clearbluejar/pyghidra-mcp):
```bash
docker run --rm -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp
```
## محسّن للوكلاء
يحافظ `pyghidra-mcp` على واجهة MCP ضيقة عمدًا حتى يستهلك عملاء الوكلاء رموزًا (tokens) أقل في اكتشاف الأدوات واختيار الوسائط.
- **أوصاف أدوات قصيرة**: تُبقى سلاسل التوثيق (docstrings) لأدوات MCP مختصرة حتى تبقى مخططات أدوات MCPServer صغيرة ورخيصة للإرسال إلى النماذج.
- **انضباط السياق**: تُرجع الأدوات بيانات منظمة ومركّزة بدلًا من إغراق السياق بالبرنامج بأكمله افتراضيًا. تُشكَّل نتائج فك التجميع والبحث عن الرموز والمراجع المتقاطعة لدعم التحليل التكراري بدلًا من استجابة واحدة كبيرة.
- **أدوات واجهة المستخدم الرسومية فقط عند الحاجة**: عناصر التحكم الخاصة بواجهة المستخدم الرسومية فقط مثل `open_program_in_gui` و`list_open_programs` و`set_current_program` و`goto` لا تُتاح إلا عند تشغيل الخادم مع `--gui`.
- **واجهة سطر الأوامر اختيارية**: إذا لم تكن MCP واجهتك المفضلة، فإن `pyghidra-mcp-cli` يوفر عميلًا مباشرًا لسطر الأوامر عبر HTTP مع أوامر مجمّعة لسير عمل التحرير والتحليل الشائعة.
يحافظ هذا على قابلية استخدام الخادم الافتراضي لوكلاء LLM وتكاملات بيئات التطوير المتكاملة (IDE) والأتمتة دون كشف سطح أدوات غير ضروري أو عناصر تحكم خاصة بواجهة المستخدم الرسومية في الجلسات بلا واجهة رسومية.
## عميل سطر الأوامر
لتجربة أكثر تفاعلية على سطر الأوامر، يمكنك استخدام حزمة **pyghidra-mcp-cli** المنفصلة، والتي توفر واجهة سهلة الاستخدام للتفاعل مع خادم pyghidra-mcp قيد التشغيل.
### التثبيت
ثبّت عميل سطر الأوامر باستخدام [`uv`](https://docs.astral.sh/uv/) (موصى به):
```bash
uvx pyghidra-mcp-cli
```
أو قم بالتثبيت باستخدام pip:
```bash
pip install pyghidra-mcp-cli
```
### البدء السريع باستخدام CLI
1. **ابدأ الخادم** (في طرفية واحدة):
```bash
pyghidra-mcp --transport streamable-http /bin/ls
```
2. **استخدم واجهة سطر الأوامر (CLI)** (في طرفية أخرى):
```bash
# List available binaries
pyghidra-mcp-cli list binaries
# Decompile a function
pyghidra-mcp-cli decompile --binary ls main
# Decompile with callees, referenced strings, and cross-references
pyghidra-mcp-cli decompile --binary ls main --callees --strings --xrefs
# Search for symbols (supports regex patterns)
pyghidra-mcp-cli search symbols --binary ls printf -l 10
```
> [!NOTE]
> يتصل CLI بـ pyghidra-mcp عبر HTTP لتجنب الحمل الزائد لبدء التشغيل الذي يستغرق من 10 إلى 60 ثانية لتشغيل عملية Ghidra جديدة لكل أمر. راجع [CLI README](https://github.com/clearbluejar/pyghidra-mcp/blob/main/cli/README.md) للحصول على الوثائق الكاملة.
## إنشاء المشاريع وإدارتها وفتح المشاريع الموجودة
### إنشاء مشاريع جديدة
يمكنك إنشاء مشاريع جديدة بعدة طرق، اعتمادًا على سير عملك:
#### بنية مشروع مكتفية ذاتيًا
ينشئ `pyghidra-mcp` **بنية مشروع مكتفية ذاتيًا** حيث يكون لكل مشروع مشروع Ghidra الخاص به ومخرجات pyghidra-mcp. يضمن ذلك عزلاً كاملاً وإدارة سهلة للمشاريع.
#### إنشاء مشروع أساسي
```bash
# Create a new project with default settings
pyghidra-mcp
# Creates:
$ tree pyghidra_mcp_projects/
pyghidra_mcp_projects/
├── my_project.gpr
├── my_project-pyghidra-mcp
│ ├── chromadb
│ └── gzfs
└── my_project.rep
```
#### إنشاء مشروع مخصص
```bash
# Create project with custom name and location
pyghidra-mcp --project-path ~/analysis/malware_study --project-name malware_analysis
$ tree ~/analysis/
/home/vscode/analysis/
└── malware_study
├── malware_analysis.gpr
├── malware_analysis-pyghidra-mcp
│ ├── chromadb
│ └── gzfs
└── malware_analysis.rep
```
#### إنشاء مشاريع متعددة مترابطة
```bash
# Create separate projects for different analysis focuses
mkdir ~/reverse_engineering_workspace
# Project for suspicious binaries
pyghidra-mcp --project-path ~/reverse_engineering_workspace/suspicious_binaries --project-name suspicious_analysis
# Project for packed malware
pyghidra-mcp --project-path ~/reverse_engineering_workspace/packed_malware --project-name packed_analysis
```
### فتح مشاريع Ghidra الموجودة
إذا كانت لديك مشاريع Ghidra موجودة (ملفات `.gpr`)، يمكنك فتحها مباشرة باستخدام `pyghidra-mcp`:
#### الفتح عبر ملف .gpr
```bash
# Open existing Ghidra project (project name derived from filename)
pyghidra-mcp --project-path ~/existing/ghidra/my_research.gpr
# Result: ~/existing/ghidra/my_research-pyghidra-mcp/
# └── chromadb/, gzfs/ (pyghidra-mcp additions)
```
### وضع واجهة المستخدم الرسومية
استخدم وضع واجهة المستخدم الرسومية عندما تريد أن تعمل إجراءات MCP على نفس كائنات البرنامج الحية التي يعرضها Ghidra.
- يتطلب `--gui` استخدام `--transport streamable-http` (أو `--transport http` كاسم مستعار)
- يمكن أن يكون `--project-path` دليل مشروع بالإضافة إلى `--project-name`، أو ملف `.gpr` موجود. يتم إنشاء المشاريع المفقودة تلقائيًا.
- يتم تشغيل Ghidra بواسطة `pyghidra-mcp`، الذي يحافظ على معاملات واجهة المستخدم الرسومية و MCP في نفس JVM
- يتم عرض الأدوات الخاصة بواجهة المستخدم الرسومية فقط عند التشغيل مع `--gui`
مثال:
```bash
pyghidra-mcp \
--gui \
--transport streamable-http \
--project-path /absolute/path/to/my_research.gpr
```
وضع GUI هو الخيار الصحيح عندما تريد:
- فتح أو تبديل البرامج في CodeBrowser
- التنقل في القائمة إلى دالة أو عنوان
- إعادة تسمية الدوال أو إضافة تعليقات ورؤية تلك التغييرات فوراً في Ghidra
### الإعدادات الافتراضية عند بدء التشغيل والمشاريع الكبيرة
لا يتطلب `pyghidra-mcp` وجود `--wait-for-analysis` بشكل افتراضي. يمكن للخادم أن يبدأ بينما يستمر التحليل والفهرسة من جانب MCP في الخلفية.
هذا مهم للمشاريع الكبيرة:
- بدء مشروع يحتوي على العديد من الملفات الثنائية لا يحتاج إلى حجب بدء تشغيل الخادم
- `--wait-for-analysis` متاح عندما تريد مشروعاً محللاً بالكامل قبل تقديم الطلبات
- بالنسبة للمشاريع الكبيرة الموجودة، توقع أن يختلف جاهزية التحليل والفهرسة حسب كل ملف ثنائي
القيد الحالي:
- حالة تحليل Ghidra وحالة الفهرسة من جانب MCP منفصلتان
- يمكن أن يكون الملف الثنائي محللاً بالكامل في Ghidra بينما لا يزال `search_strings` أو `search_code` الدلالي في انتظار الفهرسة من جانب MCP
- هذا أكثر وضوحاً عند فتح مشاريع كبيرة موجودة
عملياً:
- لا يزال بإمكان التفكيك والتنقل وإعادة التسمية والتعليقات العمل لملف ثنائي بينما تلحق ميزات البحث المعتمدة على الفهرسة
- إذا كانت زمن بدء التشغيل أهم من جاهزية البحث الفورية، فاحتفظ بالإعداد الافتراضي `--no-wait-for-analysis`
- إذا كانت الجاهزية الفورية أهم من وقت بدء التشغيل، فاستخدم `--wait-for-analysis`
## التطوير
يستخدم هذا المشروع `Makefile` لتبسيط التطوير والاختبار. يُستخدم `ruff` للفحص والتنسيق، وتُستخدم خطافات `pre-commit` لضمان جودة الكود.
### الإعداد
1. **تثبيت `uv`**: إذا لم يكن `uv` مثبتاً لديك، يمكنك تثبيته باستخدام pip:
```bash
pip install uv
```
أو اتبع دليل التثبيت الرسمي لـ `uv`: [https://docs.astral.sh/uv/install/](https://docs.astral.sh/uv/install/)
2. **إنشاء بيئة افتراضية وتثبيت التبعيات**:
```bash
make dev-setup
source ./.venv/bin/activate
```
3. **تعيين متغير بيئة Ghidra**: نزّل Ghidra وثبّته، ثم عيّن متغير البيئة `GHIDRA_INSTALL_DIR` إلى دليل تثبيت Ghidra الخاص بك.
```bash
# For Linux / Mac
export GHIDRA_INSTALL_DIR="/path/to/ghidra/"
# For Windows PowerShell
[System.Environment]:https://raw.githubusercontent.com/clearbluejar/pyghidra-mcp/main/:SetEnvironmentVariable(%27GHIDRA_INSTALL_DIR%27,%27C:%5Cpath%5Cto%5Cghidra%27)
```
### الاختبار والجودة
يوفر `Makefile` عدة أهداف للاختبار وجودة الكود:
- `make run`: تشغيل خادم MCP.
- `make test`: تشغيل مجموعة الاختبارات الكاملة (الوحدة والتكامل).
- `make test-unit`: تشغيل اختبارات الوحدة.
- `make test-integration`: تشغيل اختبارات التكامل.
- `make test-integration-fast`: تشغيل اختبار التكامل السريع الخفيف المستخدم بواسطة pre-commit.
- `make test-integration-gui`: تشغيل اختبارات تكامل GUI. يتطلب تثبيت Ghidra يعمل ودعم GUI.
- `make lint`: فحص نمط الكود باستخدام `ruff`.
- `make format`: تنسيق الكود باستخدام `ruff`.
- `make typecheck`: تشغيل فحوصات ثابتة خفيفة باستخدام `ruff`.
- `make check`: تشغيل جميع فحوصات الجودة.
- `make dev`: تشغيل سير عمل التطوير (التنسيق والفحص).
- `make build`: بناء حزم التوزيع.
- `make clean`: تنظيف مخرجات البناء والذاكرة المؤقتة.
التقسيم الموصى به:
- pre-commit: `ruff` و`pyright` واختبارات الوحدة واختبار تكامل سريع خفيف واحد
- GitHub Actions: تغطية تكامل Linux headless الكاملة، وGUI على Linux تحت `Xvfb`، وتغطية CLI، واختبارات macOS السريعة الحالية
- CI المجدول: تغطية التوافق مع إصدارات macOS / Ghidra الأقدم
- محلي/يدوي: تصحيح أخطاء GUI الأثقل الخاص ببيئات محددة وفحوصات سلامة الإصدار
## API
### الأدوات
تمكّن نماذج LLM من تنفيذ الإجراءات وإجراء حسابات حتمية والتفاعل مع الخدمات الخارجية.
#### عمليات الدفعات
يقبل `decompile_function` و`list_xrefs` هدفاً واحداً أو قائمة من الأهداف، مما يقلل من عدد الرحلات ذهاباً وإياباً عند تحليل سلاسل الاستدعاء أو رموز متعددة دفعة واحدة.
```jsonc
// Decompile three functions in one call, with callees and xrefs attached
{
"binary_name": "firmware.bin",
"name_or_address": ["main", "init_hardware", "0x08001234"],
"include_callees": true,
"include_xrefs": true
}
// Get cross-references for multiple symbols at once
{
"binary_name": "firmware.bin",
"name_or_address": ["malloc", "free", "realloc"]
}
```
تُعاد أخطاء كل عنصر ضمنيًا (مع نجاح الأهداف الأخرى):
```jsonc
[
{"name": "main", "code": "void main() { ... }", "callees": ["init_hardware"], "xrefs": [...]},
{"name": "0xdeadbeef", "code": "", "error": "Function or symbol '0xdeadbeef' not found."}
]
```
#### أدوات القراءة / التحليل
- `search_code(binary_name: str, query: str, limit: int = 5, offset: int = 0, search_mode: str = "semantic", include_full_code: bool = True, preview_length: int = 500, similarity_threshold: float = 0.0)`: البحث في الكود الزائف المُفكَّك (pseudo-C) باستخدام البحث الشعاعي الدلالي أو المطابقة الحرفية.
- `list_xrefs(binary_name: str, name_or_address: str | list[str])`: سرد الإحالات المرجعية (cross-references) إلى الدالة (الدوال) أو الرمز (الرموز) أو العنوان (العناوين). يقبل هدفًا واحدًا أو قائمة للبحث الدفعي.
- `gen_callgraph(binary_name: str, function_name: str, direction: str = "calling", display_type: str = "flow", condense_threshold: int = 50, top_layers: int = 3, bottom_layers: int = 3, max_run_time: int = 120)`: يُنشئ مخطط استدعاء MermaidJS لدالة محددة. يدعم كلاً من الاتجاهين "calling" (الدوال التي تستدعيها الدالة الهدف) و"called" (الدوال التي تستدعي الدالة الهدف) مع أنواع عرض متعددة.
- `decompile_function(binary_name: str, name_or_address: str | list[str], include_callees: bool = False, include_strings: bool = False, include_xrefs: bool = False, timeout_sec: int = 30)`: تفكيك الدالة (الدوال) بالاسم أو العنوان. يقبل هدفًا واحدًا أو قائمة للتفكيك الدفعي. تُرفق أعلام الاستجابة الغنية الدوال المُستدعاة والنصوص و/أو الإحالات المرجعية بكل نتيجة. يُطبَّق `timeout_sec` لكل هدف ويحدّ من كل محاولة تفكيك بشكل مستقل.
- `list_exports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25)`: يسرد جميع الدوال والرموز المُصدَّرة من ملف ثنائي محدد (يدعم التعبيرات النمطية للاستعلام).
- `list_imports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25)`: يسرد جميع الدوال والرموز المُستوردة لملف ثنائي محدد (يدعم التعبيرات النمطية للاستعلام).
- `read_bytes(binary_name: str, address: str, size: int = 32)`: يقرأ البايتات الخام من الذاكرة عند عنوان محدد. قد تتضمن العناوين السداسية العشرية البادئة `0x` أو تحذفها.
- `search_strings(binary_name: str, query: str, limit: int = 100)`: يبحث في النصوص داخل ملف ثنائي.
- `search_symbols_by_name(binary_name: str, query: str, functions_only: bool = False, offset: int = 0, limit: int = 25)`: البحث عن الرموز داخل ملف ثنائي بالاسم. يدعم أنماط التعبيرات النمطية (مثل `^main$`، `func.*one`) مع مطابقة غير حساسة لحالة الأحرف، أو استعلامات النصوص الفرعية العادية. اضبط `functions_only=True` لاستبعاد التسميات والمتغيرات والرموز غير الدالية الأخرى.
#### عمليات المشروع
- `import_binary(binary_path: str)`: يستورد ملفًا ثنائيًا من مسار محدد إلى مشروع Ghidra الحالي. إذا كان المسار دليلًا، فسيتم فحصه بشكل تكراري واستيراد جميع ملفات الملفات الثنائية المدعومة، مع الحفاظ على بنية الدليل داخل مشروع Ghidra.
- `list_project_binaries()`: يسرد الملفات الثنائية في مشروع Ghidra الحالي. في وضع واجهة المستخدم الرسومية (GUI)، يشمل ذلك الملفات الثنائية للمشروع الموجودة على القرص حتى لو لم تكن مفتوحة حاليًا في CodeBrowser.
- `list_project_binary_metadata(binary_name: str)`: يسترجع البيانات الوصفية التفصيلية لملف ثنائي محدد، بما في ذلك البنية والمترجم وتنسيق الملف القابل للتنفيذ ومقاييس التحليل وتجزئات الملف.
- `delete_project_binary(binary_name: str)`: يحذف ملفًا ثنائيًا (برنامجًا) من مشروع Ghidra.
#### أدوات التعديل / التغيير
- `rename_function(binary_name: str, name_or_address: str, new_name: str)`: إعادة تسمية دالة بالاسم أو العنوان. في وضع واجهة المستخدم الرسومية (GUI)، يعمل هذا كمعاملة Ghidra مباشرة ويحدّث البرنامج المفتوح.
- `rename_variable(binary_name: str, function_name_or_address: str, variable_name: str, new_name: str)`: إعادة تسمية معامل دالة أو متغير محلي بالاسم الدقيق داخل دالة محددة. إذا كان الاسم مفقودًا أو غامضًا داخل تلك الدالة، تُرجع الأداة خطأً بدلاً من التخمين. في وضع واجهة المستخدم الرسومية (GUI)، يعمل هذا كمعاملة Ghidra مباشرة ويحدّث البرنامج المفتوح.
- `set_variable_type(binary_name: str, function_name_or_address: str, variable_name: str, type_name: str)`: تعيين نوع البيانات لمعامل دالة أو متغير محلي بالاسم الدقيق داخل دالة محددة. إذا كان الاسم مفقودًا أو غامضًا داخل تلك الدالة، تُرجع الأداة خطأً بدلاً من التخمين. يتم تحليل `type_name` باستخدام محلل أنواع البيانات في Ghidra مقابل مدير أنواع بيانات البرنامج.
- `set_function_prototype(binary_name: str, function_name_or_address: str, prototype: str)`: تعيين نموذج أولي لدالة من سلسلة توقيع كاملة. تُمرّر الأداة دائمًا النموذج الأولي عبر محلل التوقيعات الأصلي في Ghidra وتُرجع خطأ المحلل الأساسي أو خطأ التطبيق إذا كان النموذج الأولي غير صالح.
---
[Read more](https://github.com/clearbluejar/pyghidra-mcp)