Binary Ninja Headless MCP

एक हेडलेस Binary Ninja सर्वर जो MCP (मॉडल कॉन्टेक्स्ट प्रोटोकॉल) बोलता है, जो AI एजेंटों को डीप रिवर्स-इंजीनियरिंग वर्कफ़्लो — डिसअसेंबली, IL, पैचिंग, टाइप्स, xrefs, और बहुत कुछ — तक पूर्ण पहुँच देता है, बिना GUI के।

उसी Docker कंटेनर में चलाने के लिए डिज़ाइन किया गया है जहाँ एजेंट रनटाइम है। कोई साइडकार नहीं, कोई अतिरिक्त सेवा नहीं।

यह पूरा प्रोजेक्ट---कोड, परीक्षण और दस्तावेज़ीकरण---100% वाइब कोडेड है।

क्यों

मौजूदा Binary Ninja MCP सर्वर या तो GUI-बाउंड हैं या सीमित टूल सतह प्रकट करते हैं। यह सर्वर केवल हेडलेस है और सैंडबॉक्स्ड VM/कंटेनर वातावरण में एजेंट-संचालित वर्कफ़्लो के लिए डिज़ाइन किया गया है: एजेंट को विश्लेषण प्रणाली पर पूर्ण नियंत्रण मिलता है, रिवर्स इंजीनियरिंग के बड़े हिस्सों को स्वचालित करता है, जबकि आप संवादात्मक रूप से प्रक्रिया पर चर्चा और मार्गदर्शन करते हैं।

लक्ष्य एक ऐसा इंटरफ़ेस है जहाँ एजेंट समय के साथ एक विश्लेषण का निरीक्षण, परिष्कृत और विस्तार कर सकते हैं — टाइप्स, प्रतीकों और मेटाडेटा को अपडेट करना, विश्लेषण डेटाबेस को वृद्धिशील रूप से सुधारना, पैच लागू करना और undo/redo के साथ सुरक्षित रूप से पुनरावृत्त करना, और जब किसी वर्कफ़्लो को विशिष्ट कुछ चाहिए तो कस्टम स्क्रिप्ट चलाना।

विशेषताएँ

• 181 उपकरण 36 फीचर समूहों में: विश्लेषण, डिसअसेंबली, IL, पैचिंग, undo/redo, टाइप्स, वर्कफ़्लो, मेमोरी, खोज, xrefs, स्क्रिप्टिंग, और बहुत कुछ।
• डिफ़ॉल्ट रूप से केवल-पढ़ने सुरक्षित म्यूटेशन वर्कफ़्लो (undo/redo, लेन-देन) के साथ।
• स्क्रिप्टिंग पहुँच binja.eval और binja.call के माध्यम से जो कुछ भी टूल कैटलॉग कवर नहीं करता।
• Stdio और TCP ट्रांसपोर्ट।
• Binary Ninja के अलावा कोई रनटाइम निर्भरता नहीं।
• फ़ेक बैकएंड मोड CI और विकास के लिए Binary Ninja लाइसेंस के बिना।

पूर्वापेक्षाएँ

• Python 3.11+
• एक Binary Ninja इंस्टॉलेशन जिसमें हेडलेस-सक्षम लाइसेंस हो और binaryninja Python मॉड्यूल आपके रनटाइम में आयात करने योग्य हो (वास्तविक विश्लेषण के लिए)
• CI/विकास के लिए Binary Ninja के बिना, फ़ेक बैकएंड मोड का उपयोग करें

स्थापना

git clone https://github.com/mrphrazer/binary-ninja-headless-mcp.git
cd binary-ninja-headless-mcp
pip install .

या क्लोन किए बिना सीधे रेपो रूट से इंस्टॉल करें:

pip install git+https://github.com/mrphrazer/binary-ninja-headless-mcp.git

त्वरित आरंभ

Stdio ट्रांसपोर्ट (डिफ़ॉल्ट):

python3 binary_ninja_headless_mcp.py

TCP ट्रांसपोर्ट:

python3 binary_ninja_headless_mcp.py --transport tcp --host 127.0.0.1 --port 8765

फ़ेक बैकएंड मोड (Binary Ninja की आवश्यकता नहीं):

python3 binary_ninja_headless_mcp.py --fake-backend

AI एजेंटों के साथ उपयोग करें

यह सर्वर stdio (डिफ़ॉल्ट) या tcp पर मानक MCP बोलता है, इसलिए कोई भी MCP-सक्षम एजेंट होस्ट इसका उपयोग कर सकता है।

Claude Code

claude mcp add binary_ninja_headless_mcp -- python3 /path/to/binary-ninja-headless-mcp/binary_ninja_headless_mcp.py

या इसे अपने प्रोजेक्ट के .mcp.json में जोड़ें:

{
  "mcpServers": {
    "binary_ninja_headless_mcp": {
      "command": "python3",
      "args": ["binary_ninja_headless_mcp.py"],
      "cwd": "/path/to/binary-ninja-headless-mcp"
    }
  }
}

Codex

codex mcp add binary_ninja_headless_mcp -- python3 binary_ninja_headless_mcp.py

जेनेरिक MCP होस्ट

• binary_ninja_headless_mcp नाम का एक सर्वर पंजीकृत करें।
• कमांड python3 का उपयोग करें जिसमें args ["binary_ninja_headless_mcp.py"] हों जब cwd रेपो रूट हो, या args में पूर्ण स्क्रिप्ट पथ का उपयोग करें।
• cwd को रेपो पथ पर सेट करें यदि आप चाहते हैं कि सापेक्ष पथ जैसे samples/ls सही ढंग से हल हों।
• stdio ट्रांसपोर्ट का उपयोग करें जब तक कि आपके होस्ट को TCP की आवश्यकता न हो।
• फ़ेक मोड (Binary Ninja स्थापित नहीं) के लिए, --fake-backend जोड़ें।
• health.ping पर कॉल करके कनेक्टिविटी सत्यापित करें, फिर session.open।

Docker सह-स्थान पैटर्न

अनुशंसित तैनाती मॉडल: एजेंट प्रक्रिया और इस MCP सर्वर को एक ही कंटेनर इमेज में चलाएँ।

उदाहरण आधारभूत:

FROM python:3.11-slim
WORKDIR /app
COPY . /app
RUN python -m pip install --upgrade pip && pip install ruff pytest
CMD ["python3", "binary_ninja_headless_mcp.py"]

यदि आपको कंटेनर में वास्तविक Binary Ninja विश्लेषण की आवश्यकता है, तो इसी इमेज में अपना Binary Ninja रनटाइम + लाइसेंस सेटअप जोड़ें और इस MCP सर्वर के साथ कॉन्फ़िगर किए गए एजेंट को शुरू करें।

MCP विधियाँ

• initialize
• ping
• tools/list
• tools/call
• shutdown

tools/list व्यवहार:

• स्पष्ट पेजिनेशन पैरामीटर के बिना, पूर्ण टूल कैटलॉग लौटाता है।
• यदि offset या limit प्रदान किया गया है, तो पेजिनेटेड आउटपुट का उपयोग करता है (पेजेड मोड में डिफ़ॉल्ट offset=0, limit=50)।
• इसके माध्यम से फ़िल्टरिंग का समर्थन करता है:
  • prefix (उदाहरण binary.)
  • query (टूल नाम/विवरण के विरुद्ध सबस्ट्रिंग मिलान)
• पेजिनेशन मेटाडेटा लौटाता है: offset, limit, total, has_more।
• जब कोई पेज छोटा किया जाता है (has_more=true), तो next_offset और एक notice संकेत शामिल करता है।

टूल कॉल प्रतिक्रिया व्यवहार:

• structuredContent विहित पूर्ण पेलोड है।
• content[0].text एक संक्षिप्त सारांश स्ट्रिंग है (पूर्ण JSON डुप्लिकेशन नहीं)।
• यह विभाजन जानबूझकर है ताकि संदर्भ उपयोग छोटा रखा जा सके जबकि पूर्ण मशीन-पढ़ने योग्य डेटा अभी भी उजागर हो।

गुणवत्ता और परीक्षण

यह रिपॉजिटरी अच्छी तरह से परीक्षित है और इसमें लागू गुणवत्ता द्वार हैं।

• परीक्षण सूट: वर्तमान संग्रहित परीक्षण संख्या के लिए pytest --collect-only -q चलाएँ।
• CI वर्कफ़्लो लागू करता है:
  • ruff format --check .
  • ruff check .
  • pytest
• CI BINARY_NINJA_HEADLESS_MCP_FAKE_BACKEND=1 का उपयोग करता है ताकि चेक Binary Ninja इंस्टॉलेशन की आवश्यकता के बिना चलें।
• अतिरिक्त संरचनात्मक परीक्षण टूल रजिस्ट्री स्थिरता और बैकएंड पहुँच की पुष्टि करते हैं।

संदर्भ नियंत्रण

• केवल-पढ़ने का मोड खोले गए सत्रों के लिए डिफ़ॉल्ट है (read_only=true)।
• binary.basic_blocks_at और function.basic_blocks पेजिनेटेड (offset/limit) हैं।
• memory.read में एक कठिन प्रतिक्रिया सीमा है: length <= 65536।

सीमाएँ

• एंटरप्राइज़ API वर्तमान में कवर नहीं हैं।
• डीबगर API वर्तमान में कवर नहीं हैं।

सुरक्षा मॉडल

• MCP संचार (stdio/tcp) डिफ़ॉल्ट रूप से अप्रमाणित है।
• सर्वर binja.eval के माध्यम से मनमानी स्क्रिप्टिंग और binja.call के माध्यम से व्यापक API पहुँच को उजागर करता है।
• यह विश्वसनीय, कंटेनरीकृत एजेंट वातावरण के लिए डिज़ाइन द्वारा है।
• इस सर्वर को सीधे अविश्वसनीय उपयोगकर्ताओं या नेटवर्क पर प्रकट न करें।

स्थानीय देव वर्कफ़्लो

ruff format --check .
ruff check .
BINARY_NINJA_HEADLESS_MCP_FAKE_BACKEND=1 pytest -q

फ़ीचर फ़ज़र

samples/ls के विरुद्ध व्यापक टूल सतह का अभ्यास करने के लिए अंतर्निहित MCP फ़ीचर फ़ज़र का उपयोग करें।

वास्तविक Binary Ninja बैकएंड:

python3 -m binary_ninja_headless_mcp.fuzzer --binary samples/ls --iterations 120 --seed 1337

फ़ेक बैकएंड स्मोक रन:

python3 -m binary_ninja_headless_mcp.fuzzer --binary samples/ls --fake-backend --iterations 20

JSON कवरेज रिपोर्ट लिखें:

python3 -m binary_ninja_headless_mcp.fuzzer --binary samples/ls --report-json /tmp/mcp-fuzzer-report.json

उपयोगी फ़्लैग:

• --min-success-tools N: गैर-शून्य से बाहर निकलता है यदि N से कम उपकरण सफल हुए।
• --verbose: फ़ज़ करते समय प्रत्येक टूल कॉल प्रिंट करें।
• --update-analysis: update_analysis=true के साथ सीड सत्र खोलें।

फ़ीचर कैटलॉग

सर्वर वर्तमान में 36 फीचर समूहों में 181 उपकरण प्रदर्शित करता है।

analysis

• analysis.status: विश्लेषण स्थिति प्राप्त करें।
• analysis.progress: विश्लेषण प्रगति स्नैपशॉट प्राप्त करें।
• analysis.update: अतुल्यकालिक विश्लेषण अद्यतन ट्रिगर करें।
• analysis.update_and_wait: विश्लेषण अद्यतन चलाएँ और पूर्णता की प्रतीक्षा करें।
• analysis.abort: विश्लेषण रद्द करें।
• analysis.set_hold: विश्लेषण कतार को होल्ड/रीलीज़ करें।