{"id":16712850,"url":"https://github.com/hugsy/binja-headless","last_synced_at":"2025-10-09T08:34:47.648Z","repository":{"id":146704030,"uuid":"382195048","full_name":"hugsy/binja-headless","owner":"hugsy","description":"Binja (sort of) headless","archived":false,"fork":false,"pushed_at":"2025-02-13T20:55:25.000Z","size":49,"stargazers_count":43,"open_issues_count":0,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-02T02:11:44.878Z","etag":null,"topics":["binary-ninja","binary-ninja-plugin","disassembler","python3","reverse-engineering"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hugsy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-07-02T01:09:18.000Z","updated_at":"2025-03-24T11:09:07.000Z","dependencies_parsed_at":"2024-09-06T06:14:43.192Z","dependency_job_id":"87316ac4-a45f-48c0-9b7a-b5999bc0811d","html_url":"https://github.com/hugsy/binja-headless","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/hugsy/binja-headless","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hugsy%2Fbinja-headless","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hugsy%2Fbinja-headless/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hugsy%2Fbinja-headless/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hugsy%2Fbinja-headless/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hugsy","download_url":"https://codeload.github.com/hugsy/binja-headless/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hugsy%2Fbinja-headless/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279001055,"owners_count":26082991,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["binary-ninja","binary-ninja-plugin","disassembler","python3","reverse-engineering"],"created_at":"2024-10-12T20:44:17.768Z","updated_at":"2025-10-09T08:34:47.632Z","avatar_url":"https://github.com/hugsy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# binja-headless\n\nAuthor: **@hugsy**\n\nHeadless Binary Ninja (sort of!)\n\n_Note_: A Snippet version can be copy/pasted from [here](https://gist.github.com/hugsy/714e0038d5d0b1deb7fad1907928252f)\n\n## Description\n\nThis plugin allows you to use Binary Ninja headlessly and remotely to script and control Binja remotely without the need of an entreprise license. This makes it convenient for creating scripts, or live reversing using Jupyter for instance. It works internally by simply creating an RPyc service within the Python environment, and expose it on a TCP socket. Note that this plugin is Binary Ninja specific: an equivalent for IDA was created in the repository [IDA-Headless](https://github.com/hugsy/ida-headless).\n\n**Important note**: this plugin exposes entirely the targeted Python VM over a TCP socket, in cleartext without authentication. Therefore *anyone* able to connect to it will be able to execute command on the remote system; so this plugin should never be used on a host that receive untrusted connections.\n\nThis plugin requires the installation of the [`rpyc`](https://rpyc.readthedocs.io/en/latest) package, but the service is only opened on demand. It was tested and works well under Windows and Linux but is expected to work the same on MacOS.\n\n## Installation\n\nInstall the files in the Binary Ninja plugin directory:\n\n### Linux\n\n```bash\ngit clone --depth 1 https://github.com/hugsy/binja-headless \"$HOME/.binaryninja/plugins/binja-headless\"\n```\n\n### macOS\n\n```bash\ngit clone --depth 1 https://github.com/hugsy/binja-headless \"$HOME/Library/Application Support/Binary Ninja/plugins/binja-headless\"\n```\n\n### Windows\n\n```bash\ngit clone --depth 1 https://github.com/hugsy/binja-headless \"$env:AppData/Binary Ninja/plugins/binja-headless\"\n```\n\nThen start Binary Ninja and check in the logs the plugin is correctly loaded.\n```text\nLoaded python3 plugin 'binja-headless'\n```\n\n## Settings\n\nSettings can be configured to specify a different host and port (default `0.0.0.0:18812`) to listen to by RPyC.\nYou can also enable the plugin autostart, allowing it to launch immediately in background when Binary Ninja starts.\n\n![Image](https://github.com/user-attachments/assets/bb3e30d7-cded-4bb9-b897-a07dfdff402f)\n\n## Requirements\n\nMake sure `rpyc` is installed in Binary Ninja: Palette -\u003e `Install python3 module` and enter `rpyc` with the version as mentioned in the `requirements.txt`  file, in the dialog box that appeared.\n\nAfter a few seconds, the following message should appear in the log\n\n```text\n[Default] Running pip ['C:\\\\Users\\\\User\\\\AppData\\\\Local\\\\Vector35\\\\BinaryNinja\\\\plugins\\\\python\\\\python.exe', '-m', 'pip', '--isolated', '--disable-pip-version-check', 'install', '--upgrade', '--upgrade-strategy', 'only-if-needed', '--target', 'C:\\\\Users\\\\User\\\\AppData\\\\Roaming\\\\Binary Ninja\\\\python310\\\\site-packages', 'rpyc\u003e=6.0.0']\n[Default] Successfully installed dependencies.\n```\n\nYou can now use Binja-RPyC !\n\n## Start / Stop the service manually\n\nYou can now start the service (Palette -\u003e `Binja-RPyc - Start RPyc Service`). A popup will confirm the service is running, or show the error in the logs on failure.\n\n## Usage\n\nFrom a remote Python terminal, you can now import the `rpyc` module and access your remote Binary Ninja.\n\n```python\n\u003e\u003e\u003e import rpyc\n\u003e\u003e\u003e c = rpyc.connect(\"192.168.57.2\", 18812)\n\u003e\u003e\u003e bn = c.root.binaryninja\n```\n\nIf the service was started manually with the GUI, a binaryview is automatically exposed (as `bv`) in the `root` namespace.\n\n```python\n\u003e\u003e\u003e c.root.bv\n\u003cBinaryView: '//DESKTOP-SD4TH5/Temp/ls', len 0x248e8\u003e\n\n\u003e\u003e\u003e dir(c.root.binaryninja)\n['ActionType',\n 'ActiveAnalysisInfo',\n 'AddressField',\n 'AddressRange',\n 'AdvancedFunctionAnalysisDataRequestor',\n 'AnalysisCompletionEvent',\n [...]\n```\n\nAnd then you can create some aliases to make as if you were using it locally:\n\n```python\n\u003e\u003e\u003e bv = c.root.bv\n```\n\nIf the service was started automatically, no binary view is attached, but it can be opened using normal binja API calls:\n\n```python\n# Load a binary\n\u003e\u003e\u003e bv = bn.load(\"/path/to/my/bin\")\n# Load a BNDB\n\u003e\u003e\u003e bv = bn.load(\"/path/to/file.bndb\")\n\n\u003e\u003e\u003e assert isinstance(bv, bn.binaryview.BinaryView)\n```\n\n\u003e [!NOTE]\n\u003e Before 3.5.4378 you must use `binaryninja.open_view()` to open BNDB files\n\n\u003e [!WARNING]\n\u003e By opening a BNDB file analyzed with a prior version of binja will display an error popup, and throw an `Exception`\n\u003e See the [binary ninja documentation](https://api.binary.ninja/index.html#binaryninja.load) for full details\n\nAnd then go crazy!\n\n```python\n\u003e\u003e\u003e bn.core_version()\n'4.2.5975-dev Personal'\n\n\u003e\u003e\u003e bv.file\n\u003cFileMetadata: Y:/IDBs/windows/kernel32/10.0.18362.329/kernel32.bndb\u003e\n\n\u003e\u003e\u003e bv.arch\n\u003carch: x86_64\u003e\n\n\u003e\u003e\u003e assert bn.binaryview.BinaryView.new(pathlib.Path(\"c:/temp/chall\").read_bytes()).read(0, 4) == b'\\x7fELF'\n\n\u003e\u003e\u003e bv.endianness.name\n'LittleEndian'\n\n\u003e\u003e\u003e hex(bv.entry_function.start)\n'0x1c0272010'\n\n\u003e\u003e\u003e bv.file.original_filename\n'Y:/IDBs/windows/kernel32/10.0.18362.329/kernel32.dll'\n\n\u003e\u003e\u003e bv.get_functions_by_name(\"CreateFileMappingW\")\n[\u003cfunc: x86_64@0x18001c250\u003e]\n\n\u003e\u003e\u003e for f in bv.functions:\n    print(f\"{f.name} -\u003e {f.start:#x}\")\nRtlVirtualUnwindStub -\u003e 0x180001010\nGetNumberFormatWStub -\u003e 0x180001060\nGetTimeZoneInformationForYearStub -\u003e 0x180001070\nIdnToAsciiStub -\u003e 0x180001080\nCreateWaitableTimerW -\u003e 0x180001090\n[...]\n\n\u003e\u003e\u003e for block in bv.get_functions_by_name(\"GlobalUnlock\")[0]:\n      for insn in block:\n        print(insn)\n(['mov', '     ', 'qword ', '[', 'rsp', '+', '0x8', ']', ', ', 'rbx'], 5)\n(['mov', '     ', 'qword ', '[', 'rsp', '+', '0x10', ']', ', ', 'rsi'], 5)\n(['push', '    ', 'rdi'], 1)\n[...]\n```\n\n## Demo\n\n[![binja-headless](https://i.imgur.com/1dUevj7.png)](https://youtu.be/wvQyXbYV92c)\n\n\n## Minimum Version\n\nThis plugin requires the following minimum version of Binary Ninja:\n\n * 3164\n\n\n\n## Required Dependencies\n\nThe required dependencies can be found in the `requirements.txt` file.\n\n\n## License\n\nThis plugin is released under a MIT license. See the `LICENSE` file for complete details.\n\n\n## Metadata Version\n\n2\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhugsy%2Fbinja-headless","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhugsy%2Fbinja-headless","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhugsy%2Fbinja-headless/lists"}