{"id":13827114,"url":"https://github.com/conorpp/btproxy","last_synced_at":"2025-10-09T22:33:40.415Z","repository":{"id":36764418,"uuid":"41071103","full_name":"conorpp/btproxy","owner":"conorpp","description":"Man in the Middle analysis tool for Bluetooth.","archived":false,"fork":false,"pushed_at":"2020-02-24T12:54:20.000Z","size":128,"stargazers_count":528,"open_issues_count":9,"forks_count":78,"subscribers_count":41,"default_branch":"master","last_synced_at":"2025-10-09T22:33:06.271Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/conorpp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-08-20T02:33:16.000Z","updated_at":"2025-09-21T21:21:03.000Z","dependencies_parsed_at":"2022-09-20T19:51:44.944Z","dependency_job_id":null,"html_url":"https://github.com/conorpp/btproxy","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/conorpp/btproxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/conorpp%2Fbtproxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/conorpp%2Fbtproxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/conorpp%2Fbtproxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/conorpp%2Fbtproxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/conorpp","download_url":"https://codeload.github.com/conorpp/btproxy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/conorpp%2Fbtproxy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279002107,"owners_count":26083307,"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":[],"created_at":"2024-08-04T09:01:50.378Z","updated_at":"2025-10-09T22:33:40.396Z","avatar_url":"https://github.com/conorpp.png","language":"Python","readme":"\n# Btproxy\n\n### (Unsupported)\n\n## Bluetooth Proxy tool\n\n[Walkthrough](https://conorpp.com/proxying-bluetooth-devices-for-security-analysis-using-btproxy)\n![](http://conorpp.com/assets/images/btproxy/cover.jpg.fb.jpg)\n\n### Tested Devices\n\n* Pebble Steel smart watch\n* Moto 360 smart watch\n* OBDLink OBD-II Bluetooth Dongle\n* Withings Smart Baby Monitor\n\nIf you have tried anything else, please let me know at conorpp (at) vt (dot) edu.  \n\n### Dependencies\n\n- Need at least 1 Bluetooth card (either USB or internal).\n- Need to be running Linux or another *nix.\n- BlueZ 4\n\nFor a debian system, run\n\n```bash\nsudo apt-get install bluez bluez-tools libbluetooth-dev python-dev\n```\n\n### Installation\n\n```bash\nsudo python setup.py install\n```\n\n### Running\n\nTo run a simple MiTM or proxy on two devices, run\n\n```bash\nbtproxy \u003cmaster-bt-mac-address\u003e \u003cslave-bt-mac-address\u003e\n```\n   \nRun `btproxy` to get a list of command arguments.\n\n#### Example\n\n```bash\n# This will connect to the slave 40:14:33:66:CC:FF device and \n# wait for a connection from the master F1:64:F3:31:67:88 device\nbtproxy F1:64:F3:31:67:88 40:14:33:66:CC:FF\n```\n\nWhere the master is typically the phone and the slave mac\naddress is typically the other peripherial device (smart watch, headphones, keyboard, obd2 dongle, etc).\n\nThe master is the device the sends the connection request and the slave is \nthe device listening for something to connect to it.\n\nAfter the proxy connects to the slave device and the master connects to the proxy device,\nyou will be able to see traffic and modify it.\n\n#### How to find the BT MAC Address?  \n\nWell, you can look it up in the settings usually for a phone.  The most\nrobost way is to put the device in advertising mode and scan for it.\n\nThere are two ways to scan for devices: scanning and inquiring.\nhcitool can be used to do this:\n\n```bash\nhcitool scan\nhcitool inq\n```\n\nTo get a list of services on a device:\n\n```bash\nsdptool records \u003cbt-address\u003e\n```\n\n### Usage\n\nSome devices may restrict connecting based on the name, class, or address of another bluetooth device.  \nSo the program will lookup those three properties of the target devices to be proxied,\nand then clone them onto the proxying adapter(s).\n\nThen it will first try connecting to the slave device from the\ncloned master adaptor.  It will make a socket for each service\nhosted by the slave and relay traffic for each one independently.\n\nAfter the slave is connected, the cloned slave adaptor will be set\nto be listening for a connection from the master.  At this point, the real master device\nshould connect to the adaptor.  After the master connects, the proxied connection\nis complete.\n\n#### Using only one adapter\n\nThis program uses either 1 or 2 Bluetooth adapters.  If you use one adapter, then only\nthe slave device will be cloned.  Both devices will be cloned if 2 adapters are used; this might\nbe necessary for more restrictive Bluetooth devices.\n\n\n### Advanced Usage\n\nManipulation of the traffic can be handled via python \nby passing an inline script.  Just implement the master_cb and\nslave_cb callback functions.  This are called upon receiving \ndata and the returned data is sent back out to the corresponding device.\n\n```python\n# replace.py\ndef master_cb(req):\n    \"\"\"\n        Received something from master, about to be sent to slave.\n    \"\"\"\n    print '\u003c\u003c ', repr(req)\n    open('mastermessages.log', 'a+b').write(req)\n    return req\n\ndef slave_cb(res):\n    \"\"\"\n        Same as above but it's from slave about to be sent to master\n    \"\"\"\n    print '\u003e\u003e ', repr(res)\n    open('slavemessages.log', 'a+b').write(res)\n    return res\n```\n\n\nAlso see the example functions for [manipulating Pebble watch traffic in replace.py](https://github.com/conorpp/btproxy/blob/master/libbtproxy/replace.py#L33)\n\nThis code can be edited and reloaded during runtime by entering 'r'\ninto the program console. This avoids the pains of reconnecting.  Any errors\nwill be caught and regular transmission will continue.\n\n### TODO\n\n- BLE\n- Improve the file logging of the traffic and make it more interactive for\n- replays/manipulation.\n- Indicate which service is which in the output.\n- Provide control for disconnecting/connecting services.\n- PCAP file support\n- ncurses?\n\n\n### How it works\n\nThis program starts by killing the bluetoothd process, running it again with\na LD_PRELOAD pointed to a wrapper for the bind system call to block bluetoothd\nfrom binding to L2CAP port 1 (SDP).  All SDP traffic goes over L2CAP port 1 so\nthis makes it easy to MiTM/forward between the two devices and we don't have to\nworry about mimicking the advertising.\n\nThe program first scans each device for their name and device class to make\naccurate clones.  It will append the string '_btproxy' to each name to make them\ndistinguishable from a user perspective.  Alternatively, you can specify the\nnames to use at the command line.\n\nThe program then scans the services of the slave device.  It makes a socket\nconnection to each service and open a listening port for the master device to \nconnect to.  Once the master connects, the Proxy/MiTM is complete and output will be\nsent to STDOUT.\n\n### Notes\n\nSome bluetooth devices have different methods of pairing which\nmakes this process more complicated.  Right now it supports SPP and legacy pin pairing.\n\nThis program doesn't yet have support for Bluetooth Low Energy.\nA similiar approach to BLE can be taken.\n\n### Errors\n\n#### btproxy or bluetoothd hangs\n\nIf you are using bluez 5, you should try uninstalling and installing [bluez 4](http://www.bluez.org/download/).  I've had problems with \nbluez 5 hanging.\n\n#### error accessing bluetooth device\n\nMake sure the bluetooth adaptors are plugged in and enabled.\n\nRun\n\n```bash\n    # See the list of all adaptors\n    hciconfig -a\n\n    # Enable\n    sudo hciconfig hciX up\n\n    # if you get this message\n    Can't init device hci0: Operation not possible due to RF-kill (132)\n\n    # Then try unblocking it with the rfkill command\n    sudo rfkill unblock all\n```\n\n#### UserWarning: \\\u003cpath\\\u003e/.python-eggs is writable by group/others\n\nFix\n\n```bash\nchmod g-rw,o-x \u003cpath\u003e/.python-eggs\n```\n\n\n\n\n","funding_links":[],"categories":["\u003ca id=\"42f9e068b6511bcbb47d6b2b273097da\"\u003e\u003c/a\u003e未分类","Python","Wireless Protocols","\u003ca name=\"bluetooth_security_tools\"\u003e\u003c/a\u003eBluetooth Security Tools"],"sub_categories":["\u003ca id=\"3bd67ee9f322e2c85854991c85ed6da0\"\u003e\u003c/a\u003e投毒\u0026\u0026Poisoning","Bluetooth / BLE","Man-in-the-middle \u0026 Packet Injection"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconorpp%2Fbtproxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fconorpp%2Fbtproxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconorpp%2Fbtproxy/lists"}