{"id":20990760,"url":"https://github.com/zerochaos-/blue_hydra","last_synced_at":"2025-04-07T05:10:03.624Z","repository":{"id":37850405,"uuid":"118789956","full_name":"ZeroChaos-/blue_hydra","owner":"ZeroChaos-","description":"Blue Hydra","archived":false,"fork":false,"pushed_at":"2024-12-04T20:21:35.000Z","size":949,"stargazers_count":71,"open_issues_count":3,"forks_count":18,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-07T04:41:27.942Z","etag":null,"topics":["bluetooth","bluetooth-le","bluetooth-low-energy","bluez","security","security-tools"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ZeroChaos-.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":"2018-01-24T16:18:14.000Z","updated_at":"2025-03-31T04:45:48.000Z","dependencies_parsed_at":"2024-05-03T18:08:12.624Z","dependency_job_id":"e37eb2df-4e4b-4c96-ae2a-47fe53866f61","html_url":"https://github.com/ZeroChaos-/blue_hydra","commit_stats":null,"previous_names":[],"tags_count":68,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZeroChaos-%2Fblue_hydra","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZeroChaos-%2Fblue_hydra/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZeroChaos-%2Fblue_hydra/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZeroChaos-%2Fblue_hydra/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ZeroChaos-","download_url":"https://codeload.github.com/ZeroChaos-/blue_hydra/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247595334,"owners_count":20963943,"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":["bluetooth","bluetooth-le","bluetooth-low-energy","bluez","security","security-tools"],"created_at":"2024-11-19T06:35:26.553Z","updated_at":"2025-04-07T05:10:03.603Z","avatar_url":"https://github.com/ZeroChaos-.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BlueHydra\n\nBlueHydra is a Bluetooth device discovery service built on top of the `bluez` \nlibrary. BlueHydra makes use of ubertooth where available and attempts to track\nboth classic and low energy (LE) bluetooth devices over time. \n\n## Installation\n\nThe files in this repository can be run directly.\n\nEnsure that the following packages are installed: \n\n```\nbluez\nbluez-test-scripts\npython3-bluez\npython3-dbus\nubertooth # where applicable\nsqlite3\nlibsqlite3-dev\n```\n\nIf your chosen distro is still on bluez 4 please choose a more up to date distro.  Bluez 5 was released in 2012 and is required.\n\nOn Debian-based systems, these packages can be installed with the following command line:\n\n```sudo apt-get install bluez bluez-test-scripts python3-bluez python3-dbus libsqlite3-dev ubertooth```\n\nTo install the needed gems it may be helpful (but not required) to use bundler:\n\n```\nsudo apt-get install ruby-dev bundler\n(from inside the blue_hydra directory)\nbundle install\n```\n\nIn addition to the Bluetooth packages listed above you will need to have Ruby\nversion 2.1 or higher installed, as well as Ruby development headers for gem compilation (on\nDebian based systems, this is the `ruby-dev` package). With ruby installed add the `bundler` gem and\nthen run `bundle install` inside the checkout directory. \n\nOnce all dependencies are met simply run `./bin/blue_hydra` to start discovery.\nIf you experience gem inconsistency try running `bundle exec ./bin/blue_hydra` instead.\n\nThere are a few flags that can be passed to this script: \n\n* `-d` or `--daemonize`: suppress CLI output and run in background\n* `-z` or `--demo`: run with CLI output but mask displayed macs for demo purposes\n* `-p` or `--pulse`: attempt to send data to Pwn Pulse\n\n\n## Recommended Hardware\nBlueHydra should function with most internal bluetooth cards but we recommend \nusing the Sena UD100 adapter.\n\nAdditionally you can make use of Ubertooth One hardware to detect active devices\nnot in discoverable mode.\n\n**Note:** using an Ubertooth One is _not_ a replacement for a conventional\nbluetooth dongle. \n\n## Configuring Options\n\nThe config file `blue_hydra.yml` is located in the install directory, unless /etc/blue_hydra exists,\nthen it is in /etc/blue_hydra. The config file is located in `/opt/pwnix/data/blue_hydra/blue_hydra.yml` on\nPwnie devices.\n\nThe following options can be set:\n\n* `log_level`: defaults to info level, can be set to debug for much more verbosity. If set to `false` no log or rssi log will be created.\n* `bt_device`: specify device to use as main bluetooth interface, defaults to `hci0`\n* `info_scan_rate`: rate at which to run info scan in seconds, defaults to 240.  Values too small will be set to 45.  Value of 0 disables info scanning.\n* `status_sync_rate`: rate at which to sync device status to Pulse in seconds\n* `btmon_log`: `true|false`, if set to true will log filtered btmon output\n* `btmon_rawlog`: `true|false`, if set to true will log unfiltered btmon output\n* `file`: if set to a filepath that file will be read in rather than doing live device interactions\n* `rssi_log`: `true|false`, if set will log serialized RSSI values\n* `aggressive_rssi`: `true|false`, if set will agressively send RSSIs to Pulse\n* `ui_inc_filter_mode`: `:disabled|:hilight|:exclusive`, set ui filtering to this mode by default\n* `ui_inc_filter_mac`: `- FF:FF:00:00:59:25`, set inclusive filter on this mac, each goes on a newline proceeded by hiphon and space\n* `ui_inc_filter_prox`: `- 669a0c20-0008-9191-e411-1b11d05d7707-9001-3364`, set inclusive filter on this proximity_uuid-major_number-minor_number, each goes on a newline proceeded by hiphon and space\n* `ui_exc_filter_mac`: same syntax as ui_inc_filter_mac, but exclude instead\n* `ui_exc_filter_prox`: same syntax as ui_inc_filter_prox, but exclude instead\n* `ignore_mac`: same syntax as ui_inc_filter mac, but entirely ignore device, both db and ui\n\n## Usage\n\nIt may also be useful to check blue_hydra --help for additional command line options.  At this time it looks like this:\n\n```\nUsage: blue_hydra [options]\n    -d, --daemonize                  Suppress output and run in daemon mode\n    -z, --demo                       Hide mac addresses in CLI UI\n    -p, --pulse                      Send results to hermes\n        --pulse-debug                Store results in a file for review\n        --no-db                      Keep db in ram only\n        --rssi-api                   Open 127.0.0.1:1124 to allow other processes to poll for seen devices and rssi\n        --no-info                    For the purposes for fox hunting, don't info scan.  Some info may be missing, but there will be less gaps during tracking\n\n    -h, --help                       Show this message\n```\n\n## Logging\n\nAll data is logged to an sqlite database (unless --no-db) is passed at the command line.  The database `blue_hydra.db` is located in the blue_hydra\ndirectory, unless /etc/blue_hydra exists, and then it is placed in /etc/blue_hydra. On Pwnie Express sensors, it will be in /opt/pwnix/data.\n\nThe database will automatically be cleaned of older devices to ensure performance.  If you want to keep information about devices which haven't been seen in more than a week it is your responsibility to offload data using one of the available options (`--pulse`, `--pulse-debug`) or manually back up the database once a week.\n\nAn example for a script wrapping blue_hydra and creating a csv output after run is available here:\nhttps://github.com/pwnieexpress/pwn_pad_sources/blob/develop/scripts/blue_hydra.sh\nThis script will simply take a timestamp before blue_hydra starts, and then again after it exits, then grab a few interesting values from the db and output in csv format.\n\n## Helping with Development\n\nPR's should be targeted against the \"develop\" branch.\nDevelop branch gets merged to master branch and tagged during the release process.\n\n## Troubleshooting\n\n### `Parser thread \"\\xC3\" on US-ASCII` \n\nIf you encounter an error like `Parser Thread \"\\xC3\" on US-ASCII` it may be due\nto an encoding misconfiguration on your system. \n\nOn Debian like systems, this can be resolved by setting locale encodings as follows:\n\n```\nsudo locale-gen en_US.UTF-8 \nsudo locale-gen en en_US en_US.UTF-8\nsudo dpkg-reconfigure locales\nexport LC_ALL=\"en_US.UTF-8\"\n```\n\nThis issue and solution brought up by [llazzaro](https://github.com/llazzaro)\n[here](https://github.com/pwnieexpress/blue_hydra/issues/65).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzerochaos-%2Fblue_hydra","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzerochaos-%2Fblue_hydra","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzerochaos-%2Fblue_hydra/lists"}