{"id":13438293,"url":"https://github.com/seemoo-lab/internalblue","last_synced_at":"2025-05-16T13:07:52.679Z","repository":{"id":33416814,"uuid":"147357670","full_name":"seemoo-lab/internalblue","owner":"seemoo-lab","description":"Bluetooth experimentation framework for Broadcom and Cypress chips.","archived":false,"fork":false,"pushed_at":"2024-08-21T15:45:36.000Z","size":39047,"stargazers_count":727,"open_issues_count":16,"forks_count":96,"subscribers_count":36,"default_branch":"master","last_synced_at":"2025-04-12T10:57:35.537Z","etag":null,"topics":["android","ble","bluetooth","bluez","broadcom","cypress","firmware","ios","linux","macos","security"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/seemoo-lab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2018-09-04T14:17:46.000Z","updated_at":"2025-03-29T15:25:55.000Z","dependencies_parsed_at":"2024-08-21T17:59:01.522Z","dependency_job_id":null,"html_url":"https://github.com/seemoo-lab/internalblue","commit_stats":{"total_commits":487,"total_committers":29,"mean_commits":16.79310344827586,"dds":0.7002053388090349,"last_synced_commit":"b6ccfd66dce8d08f45dc32304fb4d6fcda85d51c"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seemoo-lab%2Finternalblue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seemoo-lab%2Finternalblue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seemoo-lab%2Finternalblue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seemoo-lab%2Finternalblue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/seemoo-lab","download_url":"https://codeload.github.com/seemoo-lab/internalblue/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254535829,"owners_count":22087399,"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","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":["android","ble","bluetooth","bluez","broadcom","cypress","firmware","ios","linux","macos","security"],"created_at":"2024-07-31T03:01:04.316Z","updated_at":"2025-05-16T13:07:52.663Z","avatar_url":"https://github.com/seemoo-lab.png","language":"Python","funding_links":[],"categories":["Android Security","Python","Python (1887)","\u003ca name=\"bluetooth_security_tools\"\u003e\u003c/a\u003eBluetooth Security Tools","Wireless Protocols","\u003ca id=\"c72811e491c68f75ac2e7eb7afd3b01f\"\u003e\u003c/a\u003e工具","Tools"],"sub_categories":["Misc Tools","Firmware Analysis","Bluetooth / BLE","\u003ca id=\"3828e67170e5db714c9c16f663b42a5e\"\u003e\u003c/a\u003e新添加的"],"readme":"![InternalBlue](doc/images/internalblue_text.svg)\n\n\n*Broadcom* chips are used in approximately a billion of devices, such as\nall *iPhones*, *MacBooks*, the *Samsung Galaxy S* series, the older *Google\nNexus* series, older *Thinkpads*, *Raspberry Pis*, various IoT devices, and more.\nIn 2016, *Cypress* acquired the IoT division of *Broadcom*. Since\nthen, firmware variants slightly diverged, as *Broadcom* kept non-IoT customers like\n*Apple* and *Samsung*. However, the firmware interaction\nand update mechanism stayed the same. We reverse-engineered how the operating\nsystems patch this firmware and interact with it. Based on that we developed a\nBluetooth experimentation framework, which is able to patch the firmware.\nThis enables various features that otherwise would only be possible with\na full-stack software-defined radio implementation, such as injecting and\nmonitoring packets on the link layer.\n\n*InternalBlue* has not only been used for our own research at the Secure Mobile\nNetworking Lab ([SEEMOO](https://seemoo.de)). Also, the [KNOB](https://knobattack.com/) and [BIAS](https://francozappa.github.io/about-bias/) attack prototype \nwere implemented using *InternalBlue* LMP messages\nand the [SweynTooth](https://asset-group.github.io/disclosures/sweyntooth/) attacks also\nexperimented with *InternalBlue* for crafting LCP messages. Note that in contrast to tools like\n[btlejack](https://github.com/virtualabs/btlejack) or\n[Ubertooth](https://github.com/greatscottgadgets/ubertooth), *InternalBlue* does not\naim at performing Machine-in-the-Middle attacks. However, the device running *InternalBlue*\ncan send arbitrary packets and also inject these into existing connections. During\nmonitoring, all packets that are received by the device running *InternalBlue* are\ncaptured, and there is no packet loss. *InternalBlue* does not have any issues with analysis of encrypted connections or\nClassic Bluetooth. If you have specific feature requests for your security research,\nfeel free to open a ticket.\n\nIn addition to security research, *InternalBlue* also opens possibilities for\nfurther analysis such as Bluetooth Low Energy performance statistics and improvements.\nAnything that can be improved within a Bluetooth stack can be directly tested on\noff-the-shelf devices.\n\nOur recent research features [Frankenstein](https://github.com/seemoo-lab/frankenstein),\nwhich emulates the firmware including thread switches and virtual modem input. The\nemulated firmware can be attached to a *Linux* host. Thus, the approach is full-stack.\nWe mainly used it for fuzzing and found vulnerabilities that include host responses\nto be triggered. *Frankenstein* is in a separate repository, but depends on *InternalBlue*\nto take state snapshots etc. on a physical device.\n\nMoreover, we just published [Polypyus](https://github.com/seemoo-lab/polypyus).\nIt enables binary-only binary diffing, independent of *IDA* and *Ghidra*. However,\nit integrates into that workflow by identifying good starting points for further\nanalysis. We already tried it across various *Broadcom* Wi-Fi and Bluetooth firmware.\n\nLooking for our random number generator measurements that we did within the analysis\nof CVE-2020-6616? You can find them [here](doc/rng.md).\n\nThere are also some more dynamic hooks for HCI with [Frida on iOS and Android](doc/keychange.md).\nWe used this to study the warning behavior in the user interface upon MitM attacks.\nLikely useful for a lot of other experiments, though.\n\nDue to Spectra 👻🌈 the write and read RAM commands are disabled after driver initialization.\nWorkarounds for this are described in the according *Android* and *iOS* instructions,\nbypasses for other devices will follow if needed. \n\n\n\nTable of Contents\n-----------------\n* [Feature overview](doc/features.md)\n* [General setup and usage](doc/setup.md)\n* Operating system specific setup\n    * [Android](doc/android.md) *6—11 (rooted)*\n    * [iOS](doc/ios.md) *12—14 (jailbroken)*\n    * [macOS](doc/macos.md) *High Sierra—Big Sur*\n    * [Linux](doc/linux_bluez.md) with *BlueZ* (default) but __not__ WSL\n    * [User-space macOS, Linux, Windows](doc/btstack.md) with *BTstack* \n* [Firmware overview](doc/firmware.md)\n* [SEEMOO talks and publications](doc/publications.md)\n* [Examples](doc/examples.md)\n\n\n\n\n\n\n\n\n\n\nLicense\n-------\n\nCopyright 2018-2021 The InternalBlue Team\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of\nthis software and associated documentation files (the \"Software\"), to deal in\nthe Software without restriction, including without limitation the rights to\nuse, copy, modify, merge, publish, distribute, sublicense, and/or sell copies\nof the Software, and to permit persons to whom the Software is furnished to do\nso, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseemoo-lab%2Finternalblue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseemoo-lab%2Finternalblue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseemoo-lab%2Finternalblue/lists"}