{"id":13498335,"url":"https://github.com/foundryzero/binder-trace","last_synced_at":"2025-03-29T01:30:38.115Z","repository":{"id":172067340,"uuid":"648667006","full_name":"foundryzero/binder-trace","owner":"foundryzero","description":"Binder Trace is a tool for intercepting and parsing Android Binder messages. Think of it as \"Wireshark for Binder\".","archived":false,"fork":false,"pushed_at":"2024-08-01T08:03:46.000Z","size":13240,"stargazers_count":535,"open_issues_count":6,"forks_count":50,"subscribers_count":21,"default_branch":"main","last_synced_at":"2024-08-23T10:24:17.233Z","etag":null,"topics":["android","binder","ipc","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/foundryzero.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}},"created_at":"2023-06-02T14:02:31.000Z","updated_at":"2024-08-22T03:44:49.000Z","dependencies_parsed_at":"2024-04-07T02:53:51.760Z","dependency_job_id":null,"html_url":"https://github.com/foundryzero/binder-trace","commit_stats":{"total_commits":20,"total_committers":8,"mean_commits":2.5,"dds":0.65,"last_synced_commit":"c0b9664c450148136c1f0bb1978abcb7aeb5fb5d"},"previous_names":["foundryzero/binder-trace"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foundryzero%2Fbinder-trace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foundryzero%2Fbinder-trace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foundryzero%2Fbinder-trace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foundryzero%2Fbinder-trace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/foundryzero","download_url":"https://codeload.github.com/foundryzero/binder-trace/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222435793,"owners_count":16984192,"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","binder","ipc","reverse-engineering"],"created_at":"2024-07-31T21:00:22.575Z","updated_at":"2024-10-31T15:32:03.729Z","avatar_url":"https://github.com/foundryzero.png","language":"Python","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/foundryzero/binder-trace/raw/main/binder-trace.png\" alt=\"binder-trace logo\"/\u003e\n\u003c/p\u003e\n\n# Binder Trace\n\nBinder Trace is a tool for intercepting and parsing Android Binder messages. Think of it as \"Wireshark for Binder\".\n\n![binder-trace demo](https://github.com/foundryzero/binder-trace/raw/main/binder-trace.gif)\n\n\n\n\n# Requirements\n\npython version \u003e= 3.9\n\n\n# ⚙️ Installation\n\nYou'll need a rooted Android device or emulator.\n\n* (Linux only) - install xclip or xsel for \"copy to clipboard\" functionality\n    \u003e `sudo apt-get install xclip`\n    \u003e\n    \u003e `sudo apt-get install xsel`\n\n* Install from PyPi \n    \u003e `pip install binder-trace`\n\n* Check which version of frida is installed (make sure you've pip installed the requirements)\n    \u003e `pip list | grep frida`\n* Download the matching version of frida-server from the [frida releases page](https://github.com/frida/frida/releases)\n* Make sure adb is running as root, push frida-server to your device and run it\n    \u003e `adb root`\n    \u003e \n    \u003e `adb push frida-server /data/local/tmp`\n    \u003e\n    \u003e `adb shell`\n    \u003e\n    \u003e `chmod u+x /data/local/tmp/frida-server`\n    \u003e\n    \u003e `adb shell /data/local/tmp/frida-server`\n \n\n# Arguments\n\n| Argument             | Description                                                                                                                            |\n|----------------------|----------------------------------------------------------------------------------------------------------------------------------------|\n| -h                   | Prints the argument help.                                                                                                              |\n| -d\u0026nbsp;DEVICE       | The device to attach to e.g. \"emulator-5554\". Use `adb devices` to list available devices. If not provided defaults to the USB device. |\n| -p\u0026nbsp;PID          | The pid of the process on DEVICE to attach to.                                                                                         |\n| -n\u0026nbsp;NAME         | The name of the process on DEVICE to attach to e.g. \"Messaging\".                                                                       |\n| -a\u0026nbsp;[9, 10, 11, 12, 13]   | The target device android version. If no struct path is supplied, default structs are used.             |\n| -s\u0026nbsp;STRUCTPATH   | The path to the directory of structure files.             |\n| -c\u0026nbsp;CONFIG   | The path to the config file to filter.             |\n| --spawn\u0026nbsp;    | Spawn process before attaching. -n option **must** be present and contain a valid process identifier.|\n\n# ▶️ Starting binder trace\n\nTo start binder trace we need to pick a device and process to attach to. \nIn the following example we use `adb` and `frida-ps` to identify a process to attach to on a local emulator. As it's an Android 11 emulator we choose the Android 11 structs directory. Pick the struct directory that most closely matches your version of Android. If you would like structures for a different version of Android, please let us know. Once it's running start using the target app to generate some binder transactions. \n\n```\n\u003e adb devices\nList of devices attached\nemulator-5554   device\n\n\u003e frida-ps -Ua\n PID  Name           Identifier\n----  -------------  ----------------------------\n8334  Messaging      com.android.messaging\n7941  Phone          com.android.dialer\n9607  Settings       com.android.settings\n\n\u003e cd binder_trace\n\u003e binder-trace -d emulator-5554 -n Messaging -a 11\n```\n\n# ⌨️ Controls\n\n## 🌐 Global \n| Key              | Action                                 |\n|------------------|----------------------------------------|\n| `up`             | Move up                                |\n| `down`           | Move down                              |\n| `shift + up`     | Page up                                |\n| `shift + down`   | Page down                              |\n| `home`           | Go to top                              |\n| `end`            | Go to bottom                           |\n| `tab`            | Next pane                              |\n| `shift + tab`    | Previous pane                          |\n| `ctrl + c`       | Copy pane to clipboard                 |\n| `space`          | Pause/Unpause transaction recording    |\n| `c`              | Clear                                  |\n| `h`              | Open help                              |\n| `r`              | Reload config file                     |\n| `q`              | Quit                                   |\n\n## 📈 Frequency pane\n| Key              | Action                                 |\n|------------------|----------------------------------------|\n| `p`           |   Toggle order asc/desc                   |\n| `w`           |   Jump to next interface                  |\n| `s`           |   Jump to previous interface              |\n| `a`           |   Toggle all filters on                   |\n| `n`           |   Toggle all filters off                  |\n| `enter`       |   Toggle Filter                           |\n\n# 🔎 Config File\nTo filter define any or all of the interface, method, type and inclusive options. To not use an option leave it blank `\"\"`\n\n## Without -c argument\n\n```\n\u003e binder-trace -d emulator-5554 -n Contacts -a 13\n```\n![Before Config](https://github.com/foundryzero/binder-trace/raw/main/binder-trace-before-config.png)\n\n## With -c argument\n### config.json\n```py\n{\n    \"filters\": [\n        {\n            \"interface\": \"android.gui.IDisplayEventConnection\",\n            \"method\": \"requestNextVsync\",\n            \"type\": \"\",\n            \"inclusive\": false\n        },\n        {\n            \"interface\": \"android.content.IContentProvider\",\n            \"method\": \"\",\n            \"type\": \"call\",\n            \"inclusive\": false\n        }\n    ]\n}\n```\n\n```\n\u003e binder-trace -d emulator-5554 -n Contacts -a 13 -c .\\binder_trace\\binder_trace\\config.json\n```\n\n`android.gui.IDisplayEventConnection`-\u003e`requestNextVsync`-\u003e`\"\"` and `android.content.IContentProvider`-\u003e`\"\"` -\u003e`call` have been filtered out\n\n![After Config](https://github.com/foundryzero/binder-trace/raw/main/binder-trace-after-config.png)\n\n# 📦 Structure Compatibility\n\nInternal binder interfaces can change around between minor versions, and since it's effectively all compiled together with no runtime version information it's hard to provide 100% accurate structure information for every release across Android's highly fragmented ecosystem.\n\nMore details on structures can be found in the [structures page](STRUCTURES.md)","funding_links":[],"categories":["Python","Tools"],"sub_categories":["Dynamic Analysis Tools"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoundryzero%2Fbinder-trace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffoundryzero%2Fbinder-trace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoundryzero%2Fbinder-trace/lists"}