Binary Ninja MCP

Bu repository, Binary Ninja'nın yeteneklerini sevdiğiniz LLM istemcisiyle sorunsuzca entegre etmeyi sağlayan bir Binary Ninja eklentisi, MCP sunucusu ve bridge içerir.

Özellikler

• Binary Ninja ve MCP istemcileri arasında sorunsuz, gerçek zamanlı entegrasyon
• AI yardımıyla geliştirilmiş tersi mühendislik iş akışı
• Her MCP istemcisi için destek (Cline, Claude desktop, Roo Code, vb.)
• Birden fazla binary açın ve aktif hedefi otomatik olarak değiştirin

Örnekler

CTF Zorluk Çözme

YouTube'daki bu demo videosunu kontrol edin; bu video CTF zorluk çözmek için eklentiyi kullanır.

Bileşenler

Bu repository iki ayrı bileşen içerir:

1. Binary Ninja'nın yeteneklerini HTTP endpoint'leri aracılığıyla sunan MCP sunucusu sağlayan bir Binary Ninja eklentisi. Bu, MCP protokolünü uygulayan herhangi bir istemciyle kullanılabilir.
2. Favori MCP istemcinizi Binary Ninja MCP sunucusuna bağlayan ayrı bir MCP bridge bileşeni.

Ön Koşullar

• Binary Ninja
• Python 3.12+
• MCP istemcisi (otomatik kurulum desteğine sahip olanlar aşağıda listelenmiştir)

Kurulum

MCP İstemcisi

MCP istemcilerinin otomatik kurulum yapabilmesi için Binary Ninja MCP'yi yüklemeden önce MCP istemcisini yükleyin. Şu anda bu MCP istemcileri için otomatik kurulumu destekliyoruz:

1. Cline (tavsiye edilir)
2. Roo Code
3. Claude Desktop (tavsiye edilir)
4. Cursor
5. Windsurf
6. Claude Code
7. LM Studio

Eklenti Kurulumu

MCP istemcisi yüklendikten sonra, MCP sunucusunu Binary Ninja Plugin Manager aracılığıyla veya manuel olarak yükleyebilirsiniz. Her iki yöntem de MCP istemcilerinin otomatik kurulumunu destekler.

MCP istemciniz ayarlanmamışsa, önce onu yükleyin ve ardından eklentiyi yeniden yüklemeyi deneyin.

Binary Ninja Plugin Manager

Eklentiyi Binary Ninja'nın Plugin Manager'ı aracılığıyla yükleyebilirsiniz (Plugins > Manage Plugins).

Manuel Kurulum

Eklentiyi manuel olarak yüklemek için bu repository, Binary Ninja eklentileri klasörüne kopyalanabilir.

[İsteğe bağlı] MCP İstemcisinin Manuel Kurulumu

Desteklenen bir MCP istemcisi kullanırsanız ve kurulum adımlarını takip ederseniz bunu manuel olarak kurmanız GEREKMEz.

MCP istemci girişlerini komut satırından da yönetebilirsiniz:

python scripts/mcp_client_installer.py --install    # desteklenen MCP istemcileri otomatik kurulumu
python scripts/mcp_client_installer.py --uninstall  # girdileri kaldırın ve `.mcp_auto_setup_done` dosyasını silin
python scripts/mcp_client_installer.py --config     # genel bir JSON config snippet'i yazdırın

npm Paketi Kullanarak (Tavsiye Edilir)

MCP istemcisini kurmak için önerilen yol resmi npm paketini kullanmaktır:

npx -y binary-ninja-mcp

MCP istemcileri için şu konfigürasyonu kullanın:

{
  "mcpServers": {
    "binary-ninja-mcp": {
      "command": "npx",
      "args": ["-y", "binary-ninja-mcp", "--host", "localhost", "--port", "9009"]
    }
  }
}

Veya global olarak yüklenirse:

{
  "mcpServers": {
    "binary-ninja-mcp": {
      "command": "binary-ninja-mcp",
      "args": ["--host", "localhost", "--port", "9009"]
    }
  }
}

Python Bridge Kullanarak (Eski)

Diğer MCP istemcileri için Python bridge'i doğrudan kullanın:

{
    "mcpServers": {
        "binary_ninja_mcp": {
            "command": "/ABSOLUTE/PATH/TO/Binary Ninja/plugins/repositories/community/plugins/fosdickio_binary_ninja_mcp/.venv/bin/python",
            "args": [
                "/ABSOLUTE/PATH/TO/Binary Ninja/plugins/repositories/community/plugins/fosdickio_binary_ninja_mcp/bridge/binja_mcp_bridge.py"
            ]
        }
    }
}

Not: /ABSOLUTE/PATH/TO'yu proje dizininizin gerçek mutlak yolu ile değiştirin. Sanal ortamın Python yorumlayıcısı, yüklü bağımlılıklara erişmek için kullanılmalıdır.

Kullanım

1. Binary Ninja'yı açın ve bir binary yükleyin
2. Sol alt köşede gösterilen düğmeye tıklayın
3. MCP istemciniz aracılığıyla kullanmaya başlayın

Artık açık olan binary (veya binary'ler) hakkında LLM'leri sorgulamaya başlayabilirsiniz. Örnek istekler:

CTF Zorlukları

You're the best CTF player in the world. Please solve this reversing CTF challenge in the <folder_name> folder using Binary Ninja. Rename ALL the function and the variables during your analyzation process (except for main function) so I can better read the code. Write a python solve script if you need. Also, if you need to create struct or anything, please go ahead. Reverse the code like a human reverser so that I can read the decompiled code that analyzed by you.

Malware Analizi

Your task is to analyze an unknown file which is currently open in Binary Ninja. You can use the existing MCP server called "binary_ninja_mcp" to interact with the Binary Ninja instance and retrieve information, using the tools made available by this server. In general use the following strategy:

- Start from the entry point of the code
- If this function call others, make sure to follow through the calls and analyze these functions as well to understand their context
- If more details are necessary, disassemble or decompile the function and add comments with your findings
- Inspect the decompilation and add comments with your findings to important areas of code
- Add a comment to each function with a brief summary of what it does
- Rename variables and function parameters to more sensible names
- Change the variable and argument types if necessary (especially pointer and array types)
- Change function names to be more descriptive, using mcp_ as prefix.
- NEVER convert number bases yourself. Use the convert_number MCP tool if needed!
- When you finish your analysis, report how long the analysis took
- At the end, create a report with your findings.
- Based only on these findings, make an assessment on whether the file is malicious or not.

Desteklenen Yetenekler

Aşağıdaki tablo, kullanılabilir MCP fonksiyonlarını listeler:

Fonksiyon	Açıklama
decompile_function	Adına göre belirli bir fonksiyonu decompile edin ve HLIL benzeri kod adreslerle döndürün.
get_il(name_or_address, view, ssa)	hlil, mlil veya llil içinde bir fonksiyon için IL alın (SSA MLIL/LLIL için desteklenir).
define_types	C string tipi tanımından tip tanımları ekleyin.
delete_comment	Belirli bir adreste comment'i silin.
delete_function_comment	Bir fonksiyon için comment'i silin.
declare_c_type(c_declaration)	Tek bir C tanımından yerel bir tip oluşturun/güncelleyin.
format_value(address, text, size)	Bir değeri dönüştürün ve BN'de bir adreste açıklama yapın (comment ekler).
function_at	Adresin ait olduğu fonksiyonun adını alın.
fetch_disassembly	Ada göre veya adresi adına göre bir fonksiyonun assembly gösterimini alın.
get_entry_points()	Yüklenen binary'nin entry point'lerini listeleyin.
get_binary_status	Yüklenen binary'nin geçerli durumunu alın.
get_comment	Belirli bir adreste comment'i alın.
get_function_comment	Bir fonksiyon için comment'i alın.
get_user_defined_type	Kullanıcı tanımlı bir tipin tanımını alın (struct, enumeration, typedef, union).
get_xrefs_to(address)	Bir adrese tüm çapraz referansları (kod ve veri) alın.
get_data_decl(name_or_address, length)	Veri sembolü veya adres için C benzeri bir bildirim ve hexdump döndürün.
hexdump_address(address, length)	Adres ile hizalanmış metin hexdump'ı. length < 0 varsa tam tanımlı boyutu okur.
hexdump_data(name_or_address, length)	Veri sembolü adına veya adrese göre hexdump. length < 0 varsa tam tanımlı boyutu okur.
get_xrefs_to_enum(enum_name)	Enum ile ilgili kullanımları alın (kod içinde üye sabitlerini eşleştir).
get_xrefs_to_field(struct_name, field_name)	Adlandırılmış struct alanına tüm çapraz referansları alın.
get_xrefs_to_struct(struct_name)	Struct ile ilgili xref'leri/kullanımları alın (üyeler, global'ler, kod ref'leri).
get_xrefs_to_type(type_name)	Struct/tip ile ilgili xref'leri/kullanımları alın (global'ler, ref'ler, HLIL eşleşmeleri).
get_xrefs_to_union(union_name)	Union ile ilgili xref'leri/kullanımları alın (üyeler, global'ler, ref'ler).
get_stack_frame_vars(function_identifier)	Bir fonksiyon için stack frame değişkeni bilgisini alın (adlar, ofset, boyutlar, tipler).
get_type_info(type_name)	Bir tipi çözün ve bildirim, tür ve üyeleri döndürün.
get_callers(identifiers)	Bir veya daha fazla fonksiyon tanımlayıcısı için çağıranları ve çağrı sitelerini listeleyin.
get_callees(identifiers)	Çağrılanları ve çağrı sitelerini listeleyin.
make_function_at(address, platform)	Bir adreste fonksiyon oluşturun. platform opsiyoneldir; default BinaryView/platform varsayılanı seçer.
list_platforms()	Kullanılabilir tüm platform adlarını listeleyin.
list_binaries()	Yönetilen/açık binary'leri kimlik ve aktif flag'le listeleyin.
select_binary(view)	Aktif binary'i kimlik veya dosya adına göre seçin.
list_all_strings()	Tüm string'leri listeleyin (sayfalandırma yok; tüm sayfaları birleştirir).
list_classes	Programdaki tüm namespace/sınıf adlarını listeleyin.
list_data_items	Tanımlı veri etiketlerini ve değerlerini listeleyin.
list_exports	İhraç edilen fonksiyonları/sembolleri listeleyin.
list_imports	Programda import edilen sembolleri listeleyin.
list_local_types(offset, count)	Geçerli veritabanındaki yerel Tipler'i listeleyin (ad/tür/bildirim).
list_methods	Programdaki tüm fonksiyon adlarını listeleyin.
list_namespaces	Programdaki tüm global olmayan namespace'leri listeleyin.
list_segments	Programdaki tüm bellek segment'lerini listeleyin.
list_strings(offset, count)	Veritabanındaki tüm string'leri listeleyin (sayfalandırılmış).
list_strings_filter(offset, count, filter)	Eşleşen string'leri listeleyin (sayfalandırılmış, alt dizin tarafından filtrelenmiş).
rename_data	Belirtilen adreste veri etiketi yeniden adlandırın.
rename_function	Bir fonksiyonu geçerli adından yeni bir kullanıcı tanımlı ada yeniden adlandırın.
rename_single_variable	Bir fonksiyon içinde tek bir yerel değişkeni yeniden adlandırın.
rename_multi_variables	Bir fonksiyonda birden fazla yerel değişkeni toplu yeniden adlandırın (eşleme veya çiftler).
set_local_variable_type(function_address, variable_name, new_type)	Yerel bir değişkenin tipini ayarlayın.
retype_variable	Belirli bir fonksiyon içinde değişkeni yeniden yazın.
search_functions_by_name	Adı verilen alt dizini içeren fonksiyonları arayın.
search_types(query, offset, count)	Yerel Tipler'i alt dizin ile arayın (ad/bildirim).
set_comment	Belirli bir adreste comment ayarlayın.
set_function_comment	Bir fonksiyon için comment ayarlayın.
set_function_prototype(name_or_address, prototype)	Bir fonksiyonun prototipi'ni ada veya adrese göre ayarlayın.
patch_bytes(address, data, save_to_file)	Bir adreste ham byte'ları patch edin (byte seviyesi, assembly değil). Bytecode sağlayarak tüm talimatlara patch yapın. Adres: hex (örneğin, "0x401000") veya ondalık. Veri: hex string (örneğin, "90 90"). save_to_file (varsayılan True) diske kaydeder ve macOS'te yeniden imzalar.

Çağrılabilen HTTP endpoint'leri listesi:

• /allStrings: Tek bir yanıtta tüm string'ler.
• /formatValue?address=<addr>&text=<value>&size=<n>: Bir değeri dönüştürün ve bir adreste comment ayarlayın.
• /getXrefsTo?address=<addr>: Adrese xref'ler (kod+veri).
• /getDataDecl?name=<symbol>|address=<addr>&length=<n>: Veri sembolü veya adres için bildirim stili string ve hexdump ile JSON. Anahtarlar: address, name, size, type, decl, hexdump. length < 0 varsa tam tanımlı boyutu okur.
• /hexdump?address=<addr>&length=<n>: Adres ile hizalanmış metin hexdump'ı; length < 0 varsa tam tanımlı boyutu okur.
• /hexdumpByName?name=<symbol>&length=<n>: Sembol adına göre metin hexdump'ı. BN otomatik etiketleri tanır: data_<hex>, byte_<hex>, word_<hex>, dword_<hex>, qword_<hex>, off_<hex>, unk_<hex> ve düz hex adresler.
• /makeFunctionAt?address=<addr>&platform=<name|default>: Bir adreste fonksiyon oluşturun (zaten varsa etkisizdir). platform=default BinaryView/platform varsayılanını kullanır.
• /platforms: Kullanılabilir tüm platform adlarını listeleyin.
• /binaries veya /views: Yönetilen/açık binary'leri kimlik ve aktif flag'le listeleyin.
• /selectBinary?view=<id|filename>: Sonraki işlemler için aktif binary'i seçin.
• /data?offset=<n>&limit=<m>&length=<n>: Tanımlı veri öğeleri önizlemelerle. length her öğe için okunan byte'ları kontrol eder (tanımlı boyutla sınırlanır). Varsayılan davranış varsa tam tanımlı boyutu okur; length=-1 kesin boyutu zorlar.
• /getXrefsToEnum?name=<enum>: Üye sabitlerini eşleştirerek enum kullanımları.
• /getXrefsToField?struct=<name>&field=<name>: Struct alanına xref'ler.
• /getXrefsToType?name=<type>: Struct/tip adı ile ilgili xref'ler/kullanımlar.
• /getTypeInfo?name=<type>: Bir tipi çözün ve bildirim ve ayrıntıları döndürün.
• /getXrefsToUnion?name=<union>: Union xref'leri/kullanımları (üyeler, global'ler, ref'ler).
• /getStackFrameVars?name=<function>|address=<addr>: Bir fonksiyon için stack frame değişkeni bilgisini alın.
• /getCallers?identifiers=<name|addr>[,...]: Bir veya daha fazla tanımlayıcı için çağıran özetleri döndürün (fonksiyonlar, çağrı siteleri, HLIL/IL snippet'leri). identifiers, identifier, names veya addresses sorgu parametrelerini kabul eder.
• /getCallees?identifiers=<name|addr>[,...]: /getCallers ile aynı şema ile callee özetleri döndürün, istek tanımlayıcısı başına her giden çağrı hedefini detaylandırın.
• /localTypes?offset=<n>&limit=<m>: Yerel tipler'i listeleyin.
• /strings?offset=<n>&limit=<m>: Sayfalandırılmış string'ler.
• /strings/filter?offset=<n>&limit=<m>&filter=<substr>: Filtrelenmiş string'ler.
• /searchTypes?query=<substr>&offset=<n>&limit=<m>: Yerel tipler'i alt dizin ile arayın.
• /patch veya /patchBytes?address=<addr>&data=<hex>&save_to_file=<bool>: Bir adreste ham byte'ları patch edin (byte seviyesi, assembly değil). Bytecode sağlayarak tüm talimatlara patch yapın. Adres: hex (örneğin, "0x401000") veya ondalık. Veri: hex string (örneğin, "90 90"). save_to_file (varsayılan True) diske kaydeder ve macOS'te yeniden imzalar.
• /renameVariables: Bir fonksiyonda yerel'leri toplu yeniden adlandırın. Parametreler:
  • Function: functionAddress, address, function, functionName veya name biri.
  • Yeniden adlandırmalar sağlayın aşağıdakilerden biri ile:
    • renames: {old, new} nesnelerinin JSON dizisi
    • mapping: old->new JSON nesnesi
    • pairs: kompakt string old1:new1,old2:new2 Öğe başına sonuçlar ve toplamlar döndürün. Sıra korunur; sonraki çiftler önceki yeni adlara başvurabilir.

Geliştirme

Kod Kalitesi

Bu proje Ruff kullanır linting ve formatting için. Konfigürasyon ruff.toml içindedir.

Ruff'ı Manuel Olarak Çalıştırma

Sorunları denetleyin:

ruff check .

Sorunları otomatik düzeltin:

ruff check --fix .

Formatting sorunlarını denetleyin:

ruff format --check .

Kodu biçimlendirin:

ruff format .

GitHub Actions

Bir GitHub Action iş akışı (.github/workflows/lint-format.yml) Ruff'ı otomatik olarak çalıştırır:

• main dalına her push'ta
• main dalını hedef alan her pull request'te

İş akışı linting hatası veya formatting sorunu varsa başarısız olur, CI'de kod kalitesini sağlar.

Katkı Yapma

Katkılar hoş karşılanır. Lütfen çekinmeden bir pull request gönderin.