Rev·Deck — Ghidra के साथ AI-सहायता प्राप्त रिवर्स इंजीनियरिंग

Rev·Deck एक स्थानीय, एकल-उपयोगकर्ता स्थैतिक-विश्लेषण वर्कस्टेशन है। यह एक हेडलेस Ghidra सेवा द्वारा विश्लेषित बाइनरी पर साक्ष्य-प्रथम वेब UI को LLM कॉपायलट के साथ जोड़ता है: नियतिवादी साक्ष्य (फ़ंक्शन, स्ट्रिंग्स, इम्पोर्ट्स, क्रॉस-रेफ़रेंस, एक सीमित कॉल ग्राफ़) को सीधे ब्राउज़ करें, या सहायक से ऐसे सीमित प्रश्न पूछें जिनके तथ्यात्मक दावों को निरीक्षणीय साक्ष्य उद्धृत करना अनिवार्य है।

विश्लेषित बाइनरी कभी निष्पादित नहीं की जातीं। ब्राउज़र केवल इस Flask ऐप से संवाद करता है; ऐप सत्यापित, टाइप किए गए अनुरोधों को Ghidra सेवा तक प्रॉक्सी करता है।

डेमो

https://github.com/user-attachments/assets/fba14dc5-7ad5-4137-9349-ed824da64fbe

त्वरित आरंभ (Docker)

cp .env.example .env      # set API_BASE and MODEL_NAME; set API_KEY if required
docker compose up --build

Docker Compose इंटरपोलेशन के लिए .env को स्वचालित रूप से पढ़ता है। यदि API_BASE या MODEL_NAME अनुपस्थित हो तो यह आरंभ होने से पहले विफल हो जाता है; API_KEY=not-used स्थानीय/कीलेस प्रदाताओं के लिए मान्य रहता है। स्टैक दोनों सेवाएँ आरंभ करता है। http://127.0.0.1:5000 खोलें।

केवल Ghidra सेवा चलाने के लिए:

docker pull biniamfd/ghidra-headless-rest:latest   # ensure the newest image

docker run --rm \
  -p 127.0.0.1:9090:9090 \
  -v "$(pwd)/data:/data/ghidra_projects" \
  --security-opt no-new-privileges:true \
  biniamfd/ghidra-headless-rest:latest

प्रतिलिपि-योग्य पिन के लिए, latest के बजाय परीक्षित रिलीज़ डाइजेस्ट का उपयोग करें:

docker run --rm \
  -p 127.0.0.1:9090:9090 \
  -v "$(pwd)/data:/data/ghidra_projects" \
  --security-opt no-new-privileges:true \
  biniamfd/ghidra-headless-rest:1.2.1@sha256:971591a3a8448d8ed969079b452306e806f36079c3ddd298f4a618d6e2f1442d

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

• Docker और Docker Compose (त्वरित आरंभ मार्ग के लिए), या Python 3.10+ और Node.js 18+ (स्रोत से चलाने के लिए)।
• एक OpenAI-संगत LLM एंडपॉइंट (स्थानीय या होस्टेड) और मॉडल नाम।
• सार्वजनिक Ghidra इमेज: biniamfd/ghidra-headless-rest:latest।

आवश्यक पर्यावरण चर

.env.example को .env में कॉपी करें और इन्हें भरें; पूरी सूची और डिफ़ॉल्ट के लिए वह फ़ाइल देखें।

LLM प्रदाता

Rev·Deck OpenAI SDK के माध्यम से किसी भी OpenAI-संगत Chat Completions एंडपॉइंट से बात करता है, जो पूरी तरह से API_BASE / API_KEY / MODEL_NAME द्वारा कॉन्फ़िगर किया जाता है। कोई प्रदाता-विशिष्ट हेडर, पैरामीटर या मॉडल तर्क नहीं है: एक स्थानीय Ollama सर्वर (API_BASE=http://127.0.0.1:11434/v1), एक सेल्फ-होस्टेड vLLM/llama.cpp/LM Studio एंडपॉइंट, स्वयं OpenAI, या OpenRouter जैसा गेटवे — सभी एक ही तरह काम करते हैं।

उदाहरण .env प्रदाता सेटिंग्स (प्लेसहोल्डर का उपयोग करें, वास्तविक कुंजियाँ कभी कमिट न करें):

# Ollama
API_BASE=http://127.0.0.1:11434/v1
API_KEY=not-used
MODEL_NAME=qwen3:8b

# OpenRouter
API_BASE=https://openrouter.ai/api/v1
API_KEY=replace-with-your-key
MODEL_NAME=anthropic/claude-opus-4.8

# OpenAI
API_BASE=https://api.openai.com/v1
API_KEY=replace-with-your-key
MODEL_NAME=replace-with-a-supported-model-id

# LM Studio, vLLM, or llama.cpp (adjust port/model to the server)
API_BASE=http://127.0.0.1:1234/v1
API_KEY=not-used
MODEL_NAME=replace-with-the-served-model-id

डिफ़ॉल्ट रूप से (LLM_STREAM=auto) सहायक एक स्ट्रीम किया गया प्रतिसाद अनुरोधित करता है और टोकन आते ही उन्हें ब्राउज़र तक पहुँचाता है। स्ट्रीमिंग एक मज़बूत रद्दीकरण गारंटी भी देती है: जब आप प्रतिसाद रोकते हैं (या टैब बंद करते हैं), Rev·Deck तुरंत अंतर्निहित प्रदाता स्ट्रीम बंद कर देता है और कोई और टूल या मॉडल दौर नहीं चलाता, जिससे अपस्ट्रीम जनरेशन समाप्त कर दी जाती है बजाय पृष्ठभूमि में पूर्णता तक चलते रहने के।

सावधानियाँ:

• बिलिंग। रद्द करने पर हमारी ओर से स्ट्रीम तुरंत बंद हो जाती है, लेकिन कुछ होस्टेड प्रदाता क्लाइंट के जल्दी डिस्कनेक्ट होने के बावजूद उन टोकनों के लिए बिल करते हैं जो वे पहले ही उत्पन्न कर चुके होते हैं (या पूरी कंप्लीशन के लिए)। गारंटी अधिक कार्य न करने के बारे में है, प्रदाता की बिलिंग नीति के बारे में नहीं।
• संगतता। हर OpenAI-संगत एंडपॉइंट टूल्स के साथ स्ट्रीमिंग स्वीकार नहीं करता। auto के अंतर्गत, यदि प्रदाता स्ट्रीम किए गए अनुरोध को संगतता त्रुटि (HTTP 400/404/405/422) के साथ किसी भी सामग्री या टूल-कॉल आउटपुट से पहले अस्वीकार करता है, तो Rev·Deck एक बार एकल ब्लॉकिंग कॉल पर वापस आ जाता है और प्रक्रिया के शेष भाग के लिए इसे याद रखता है। प्रमाणीकरण (401/403), दर-सीमा (429), और सर्वर (5xx) त्रुटियों को संगतता समस्याएँ नहीं माना जाता और चुपचाप पुनः प्रयास करने के बजाय उन्हें त्रुटियों के रूप में दर्शाया जाता है। स्ट्रीमिंग को पूरी तरह छोड़ने के लिए LLM_STREAM=false सेट करें, या इसे आवश्यक करने के लिए LLM_STREAM=true (कोई फ़ॉलबैक नहीं)।

उपयोग कैसे करें

ऐप खोलें और विश्लेषण कार्य आरंभ करने के लिए एक बाइनरी अपलोड करें। स्पष्ट सादा-पाठ सामग्री Ghidra को भेजे जाने से पहले पुष्टि माँगती है; स्पष्ट रॉ-बाइनरी ओवरराइड का उपयोग केवल तभी करें जब सामग्री जानबूझकर फ़र्मवेयर/डेटा हो न कि एक निष्पादन योग्य प्रारूप। विश्लेषण पूर्ण होने पर, दो वर्कस्पेस टैब के बीच स्विच करें:

• विश्लेषण — नियतिवादी साक्ष्य दृश्य: सारांश, फ़ंक्शन (फ़िल्टर/पेजिनेट), इम्पोर्ट्स, स्ट्रिंग्स, एक क्वेरी दृश्य, एक फ़ंक्शन इंस्पेक्टर (स्यूडोकोड, क्रॉस-रेफ़रेंस, सीमित कॉल ग्राफ़, हेक्सडंप), और — जब कनेक्टेड Ghidra सेवा उनका समर्थन करती है — टाइप्स, ग्लोबल्स, साइडकार एनोटेशन, आर्काइव निर्यात, और व्याख्या योग्य सकारात्मक/शमन संकेतों और साक्ष्य कवरेज के साथ एक नियतिवादी Attack Surface रैंकिंग।
• चैट — सहायक, दो मोडों में से एक में:
  • कॉपायलट (डिफ़ॉल्ट): प्रति संदेश एक सीमित चरण/टूल कॉल, तदर्थ प्रश्नों के लिए।
  • स्वायत्त: एक नामित, बजट-युक्त वर्कफ़्लो आरंभ करें जो अपने आप कई सीमित चरण चलाता है और कार्य करते समय एक लाइव गतिविधि टाइमलाइन दिखाता है।

दोनों मोड एक प्रति-कार्य चरण बजट और एक कोई चरण सीमा नहीं विकल्प लेते हैं जो कार्य समाप्त होने तक चलता है (फिर भी MAX_STEP_BUDGET द्वारा सीमित ताकि एक लूपिंग मॉडल भाग न सके)। यदि कोई रन अपने बजट तक पहुँचता है, तो वह आंशिक परिणाम रिपोर्ट करता है और जारी रखें प्रदान करता है — जो पहले से प्राप्त साक्ष्य का उपयोग करके उसी वार्तालाप को फिर से शुरू करता है, बिना पूर्ण किए गए टूल कॉलों को दोहराए। लागत टूल/मॉडल कॉलों की संख्या के साथ बढ़ती है, इसलिए उच्च बजट अधिक खर्चीले होते हैं।

उपलब्ध वर्कफ़्लो:

केंद्रित उप-जाँच

प्रत्येक विश्लेषण कार्य में एक मुख्य चैट और वैकल्पिक केंद्रित उप-सूत्र होते हैं। नई उप-जाँच चुनें, एक-पंक्ति का ब्रीफिंग दर्ज करें, और उसी बाइनरी और उसी केवल-पठन टूलों पर एक नए वार्तालाप संदर्भ के साथ कार्य करें। सूत्र इतिहास अलग-थलग रहते हैं, और एक समय में केवल एक सूत्र स्ट्रीम करता है।

जब केंद्रित कार्य तैयार हो, तो मूल सूत्र को निष्कर्ष लौटाएँ चुनें। Rev·Deck केवल उस उप-सूत्र पर एक सीमित मॉडल कॉल करता है, उसके साक्ष्य उद्धरणों को सत्यापित करता है, और मूल सूत्र में एक उत्पत्ति-चिह्नित निष्कर्ष कार्ड जोड़ता है। पूर्ण शाखा फिर से खोलने योग्य रहती है, जबकि मूल सूत्र संदर्भ केवल संक्षिप्त निष्कर्ष प्राप्त करता है—शाखा प्रतिलेख नहीं। बिना सत्यापित उद्धरणों वाला लौटाया गया कार्ड स्पष्ट रूप से असत्यापित चिह्नित होता है।

सहायक उत्तर साक्ष्य को इनलाइन [function:0xADDR], [string:0xADDR], या [import:name] के रूप में उद्धृत करते हैं। उद्धरणों की जाँच उसके विरुद्ध की जाती है जो वास्तव में उस दौर के दौरान प्राप्त किया गया था; जो उद्धरण मेल नहीं खाता उसे "(unverified)" चिह्नित किया जाता है और उसे एक अपुष्ट दावे के रूप में माना जाना चाहिए, तथ्य के रूप में नहीं।

सहायक आउटपुट में Mermaid आरेख (जैसे कॉल-ग्राफ़ स्केच) बाहरी नेटवर्क पहुँच के बिना एक सैंडबॉक्स्ड फ्रेम में रेंडर होते हैं।

आर्किटेक्चर

ब्राउज़र केवल Rev·Deck वेब एप्लिकेशन से संवाद करता है। Rev·Deck कॉन्फ़िगर किए गए LLM और हेडलेस Ghidra सेवा का समन्वय करता है, फिर परिणामी साक्ष्य और एजेंट गतिविधि को एक वर्कस्पेस में प्रस्तुत करता है।

स्रोत से चलाना

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
npm ci && npm run vendor        # one-time: vendors the pinned Mermaid runtime

cp .env.example .env            # edit API_BASE / MODEL_NAME / API_KEY
set -a; source .env; set +a     # plain Python does not load .env automatically

# Start the separate Ghidra service, then:
python webui/app.py

http://127.0.0.1:5000 खोलें। Docker Compose .env को स्वचालित रूप से पढ़ता है; स्रोत निष्पादन के लिए इसे ऊपर दिखाए अनुसार निर्यात करना आवश्यक है। Flask डेवलपमेंट सर्वर स्थानीय उपयोग के लिए उपयुक्त है; Docker इमेज Gunicorn चलाती है।

सुरक्षा / केवल-स्थानीय सीमा

यह एक विश्वसनीय विश्लेषक के लिए उनकी अपनी मशीन पर डिज़ाइन किया गया है — बहु-उपयोगकर्ता या सार्वजनिक होस्टिंग के लिए नहीं। डिफ़ॉल्ट रूप से ऐप और Ghidra सेवा केवल 127.0.0.1 से बंधते हैं, डीबग मोड बंद है, अपलोड की गई बाइनरी कभी निष्पादित नहीं होतीं, और LLM प्रदाता कुंजी सर्वर-पक्ष पर ही रहती है।

परीक्षण

pip install -r requirements.txt -r requirements-dev.txt
python -m pytest
node --test "webui/static/js/tests/**/*.test.mjs"
npm ci && npm run vendor:verify   # verifies the vendored Mermaid bundle's integrity

समस्या निवारण

• "Service offline" / /readyz 503 लौटाता है — Ghidra सेवा GHIDRA_API_BASE पर अप्राप्य है, या API_BASE/MODEL_NAME सेट नहीं है।
• Types/Globals/Annotations "requires v1" दिखाते हैं — कनेक्टेड Ghidra सेवा उस क्षमता की घोषणा नहीं करती; पुरानी सेवाओं पर यह अपेक्षित है।
• चैट तुरंत त्रुटि देता है — API_BASE/API_KEY/MODEL_NAME सत्यापित करें और यह भी कि प्रदाता LLM_TIMEOUT के भीतर पहुँच योग्य है।
• अपलोड बहुत बड़ा होने पर अस्वीकृत — MAX_UPLOAD_BYTES बढ़ाएँ।
• अपलोड सादा पाठ जैसा दिखता है — Rev·Deck इसे Ghidra को भेजने से पहले पूछता है; केवल जानबूझकर होने पर ही रॉ बाइनरी के रूप में जारी रखें।
• बड़ा विश्लेषण टाइमआउट — Ghidra कंटेनर का ANALYSIS_TIMEOUT बढ़ाएँ (उदाहरण के लिए 10k+ फ़ंक्शन वाली C++/Android बाइनरी के लिए 5400) और पुनः अपलोड करें। असंबंधित है।