ida-cli

أداة سطر أوامر IDA بدون واجهة رسومية ومجموعة أدوات تعتمد على المهارات (skill-first) لتحليل الملفات الثنائية على macOS و Linux. يقوم ida-cli تلقائيًا باختيار الواجهة الخلفية (backend) المناسبة، ويشغّل خادمًا محليًا عند الحاجة، ويوفّر نفس الواجهة كسطر أوامر مسطّح، ونقل عبر MCP عبر stdio، ونقل عبر HTTP القابل للبث عبر MCP.

中文说明

نقطتا دخول للمستخدم

• الثنائي المحلي ida-cli (عميل + خدمة في ملف تنفيذي واحد)
• مهارة ida-cli القابلة للتثبيت (skill/SKILL.md) لبيئات الوكلاء (agents)

تقوم طبقة خدمة العامل/الموجّه (worker / router) الأساسية بتشغيلها وإيقافها واجهة سطر الأوامر تلقائيًا. ما عليك سوى تشغيل serve / serve-http بشكل صريح عندما تريد فعليًا خدمة طويلة الأمد وقابلة للعنونة من الخارج.

مصفوفة الدعم

المنصات المضيفة

• المدعومة: macOS، Linux
• غير المدعومة: Windows

سياسة وقت التشغيل لـ IDA

يتم اختيار الواجهة الخلفية في وقت التشغيل عبر probe-runtime. لا يزال البناء يتطلب IDA SDK لأن الطبقة الأصلية المضمّنة مرتبطة به؛ وفي وقت التشغيل، يفتح سطر الأوامر IDA نفسه من IDADIR أو مسار تثبيت شائع معدّل.

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

على أنظمة تشغيل IDA 9.x المدعومة، يمكن لـ ida-cli أن:

• فتح ملفات PE / ELF / Mach-O الثنائية الخام وإعادة استخدام قواعد بيانات .i64 المخزنة مؤقتًا
• سرد الدوال وحلّها (resolve)، وفك التجميع حسب العنوان أو الاسم، وإلغاء الترجمة عبر Hex-Rays
• الاستعلام عن المقاطع (segments) والسلاسل النصية والاستيرادات والتصديرات ونقاط الدخول والرموز العامة
• حلّ سياق العنوان ↔ المقطع / الدالة / الرمز
• قراءة البايتات / السلاسل / الأعداد الصحيحة، وتطبيق أدوات read_* و convert_number المساعدة
• الاستعلام عن المراجع المتبادلة (xrefs) إلى / من عنوان (بما في ذلك المراجع إلى السلاسل وحقول البنى)
• بناء رسوم الاستدعاءات (callgraphs) والكتل الأساسية ومسارات تدفق التحكم
• البحث في النصوص، والقيم الفورية (immediates)، والبايتات، والتعليمات، والمعاملات، والكود الزائف
• تعريف / تطبيق الأنواع، وإعادة تسمية الرموز والمتغيرات المحلية، وتعيين التعليقات
• تشغيل مقتطفات IDAPython عبر run_script

البنود المفتوحة: بعض العمليات ذات الكتابة المكثفة وتحرير الأنواع المتقدم لا تزال جزئية على idat-compat. راجع docs/TOOLS.md للحصول على قائمة الأدوات المُولّدة.

بدء سريع

الموصى به: تثبيت المهارة

نقطة الدخول الافتراضية هي مهارة ida-cli، وليس تثبيت CLI يدويًا.

# list the skill exposed by this repository
npx -y skills add https://github.com/cpkt9762/ida-cli --list

# install the ida-cli skill for Codex
npx -y skills add https://github.com/cpkt9762/ida-cli --skill ida-cli --agent codex --yes --global

بعد التثبيت، تأتي المهارة مع غلاف التشغيل (bootstrap wrapper) الخاص بها:

~/.agents/skills/ida-cli/scripts/ida-cli.sh --help
~/.agents/skills/ida-cli/scripts/ida-cli.sh probe-runtime
~/.agents/skills/ida-cli/scripts/ida-cli.sh --path /path/to/binary list-functions --limit 20

إذا كان ida-cli مفقودًا، يقوم الغلاف بتثبيته عبر مثبّت المستودع قبل تمرير الأمر.

التثبيت المباشر لـ CLI (اختياري)

استخدم هذا فقط إذا كنت تريد CLI مستقلًا دون المرور عبر المهارة.

curl -fsSL https://raw.githubusercontent.com/cpkt9762/ida-cli/master/scripts/install.sh | bash -s -- --add-path

تنويعات مفيدة:

# install a specific release
curl -fsSL https://raw.githubusercontent.com/cpkt9762/ida-cli/master/scripts/install.sh | bash -s -- --tag v0.9.3 --add-path

# build directly from a branch or ref
curl -fsSL https://raw.githubusercontent.com/cpkt9762/ida-cli/master/scripts/install.sh | bash -s -- --ref master --build-from-source --add-path

ملاحظات:

• يضع المثبّت المُطلق (launcher) في ~/.local/bin/ida-cli افتراضيًا.
• يضيف --add-path دليل bin هذا إلى ملف rc الخاص بقوقعة الأوامر.
• إذا لم يتم تعيين أي من IDASDKDIR أو IDALIB_SDK وكان البناء المحلي مطلوبًا، يستنسخ المثبّت HexRaysSA/ida-sdk مفتوح المصدر تلقائيًا.
• عند وجود تثبيتات متعددة لـ IDA، قم بتصدير IDADIR بشكل صريح قبل تثبيت أو تشغيل ida-cli.

البناء من المصدر

git clone https://github.com/cpkt9762/ida-cli.git
cd ida-cli

export IDADIR="/Applications/IDA Professional 9.4.app/Contents/MacOS"   # or a Linux install
export IDASDKDIR="/path/to/ida-sdk"                                     # root or ida-sdk/src

cargo build --bin ida-cli
./target/debug/ida-cli --help

استخدام سطر الأوامر

ida-cli يهتم بالعميل أولًا. أي أمر فرعي من نوع عميل يقوم تلقائيًا بتشغيل خادم Streamable-HTTP محلي مرتبط بمنفذ عشوائي ويكتب /tmp/ida-cli.socket للاكتشاف:

./target/debug/ida-cli --path /path/to/sample.bin list-functions --limit 20
./target/debug/ida-cli --path /path/to/sample.bin decompile --addr 0x140001000
./target/debug/ida-cli --path /path/to/sample.bin raw '{"method":"get_xrefs_to","params":{"address":"0x140001000"}}'

الأوامر التي تكون وسيطتها الأولى أمرًا فرعيًا للخدمة (serve، serve-http، serve-worker، probe-runtime) تدخل وضع الخدمة بدلًا من ذلك:

./target/debug/ida-cli serve                          # stdio MCP transport
./target/debug/ida-cli serve-http --bind 127.0.0.1:8765
./target/debug/ida-cli probe-runtime

مثال على مخرجات فحص الواجهة الخلفية:

{"runtime":{"major":9,"minor":1,"build":250226},"backend":"idat-compat","supported":true,"reason":null}

{"runtime":{"major":9,"minor":4,"build":260610},"backend":"native-linked","supported":true,"reason":null}

للاطلاع على سطح CLI الكامل راجع skill/references/cli-tool-reference.md.

متطلبات البناء

• Rust 1.87+
• LLVM / Clang
• مضيف macOS أو Linux
• تثبيت IDA عبر IDADIR (دعم وقت التشغيل يبدأ من IDA 9.0)
• IDA SDK عبر IDASDKDIR أو IDALIB_SDK

يمكن أن يشير مسار SDK إلى أي من التخطيطين:

• /path/to/ida-sdk
• /path/to/ida-sdk/src

ملاحظات وقت التشغيل

idat-compat

واجهة خلفية للتوافق مع IDA 9.0–9.2. تستدعي idat، وتشغّل نصوص IDAPython قصيرة، وتعيد JSON منظمًا إلى بيئة CLI.

native-linked

واجهة خلفية لـ IDA 9.3+. ترتبط بخط idalib المضمّن وتفتح قواعد البيانات داخل العملية (in-process).

مسارات التخزين المؤقت ووقت التشغيل المحلي

• تخزين قاعدة البيانات المؤقت: ~/.ida/idb/
• السجلات: ~/.ida/logs/server.log
• مقبس Unix للخادم: ~/.ida/server.sock
• ملف PID للخادم: ~/.ida/server.pid
• ملف اكتشاف CLI (يربط CLI المسطّح بالمقبس الحي): /tmp/ida-cli.socket
• تخزين مؤقت للاستجابات JSON الكبيرة: /tmp/ida-cli-out/

CI والإصدارات

يقوم GitHub Actions بتجميع واختبار الشجرة على العدائين المستضافين (hosted runners) ضد HexRaysSA/ida-sdk مفتوح المصدر، لذلك لا يعتمد CI على أي تخطيط جهاز خاص.

سلوك سير العمل الحالي:

• عمليات الدفع (pushes) وطلبات السحب (pull requests) ضد master تشغّل التحقق
• عمليات الدفع الموسومة مثل v0.9.3 تبني أرشيفات الإصدارات لـ Linux و macOS
• تُرفق الإصدارات install.sh بالإضافة إلى أرشيفات المنصات

تُبنى ثنائيات الإصدارات ضد كعب SDK (SDK stubs). في وقت التثبيت، يحلّ المُطلق الذي يولّده install.sh بيئة تشغيل IDA المحلية لديك عبر IDADIR أو مجموعة معدّلة من مسارات التثبيت الشائعة قبل استدعاء ida-cli.

التوثيق

• docs/BUILDING.md — البناء من المصدر
• docs/ARCHITECTURE.md — الموجّه، الواجهات الخلفية، الفيدرالية
• docs/TRANSPORTS.md — stdio، HTTP القابل للبث، تعدد IDB
• docs/TOOLS.md — كتالوج الأدوات المُولّد
• docs/TESTING.md — اختبارات التكامل والوحدات
• skill/SKILL.md — تشغيل المهارة وسياسة الاستخدام
• skill/references/cli-tool-reference.md — سطح CLI الكامل

الترخيص

MIT