{"id":18746692,"url":"https://github.com/matrixeditor/bshark","last_synced_at":"2025-11-23T23:30:17.761Z","repository":{"id":234768852,"uuid":"788013761","full_name":"MatrixEditor/bshark","owner":"MatrixEditor","description":":shark: Wireshark for Android Binder - capture and decode IPC messages from Android devices.","archived":false,"fork":false,"pushed_at":"2024-04-21T11:01:26.000Z","size":2137,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-12-28T20:45:59.862Z","etag":null,"topics":["android","android-binder","ipc"],"latest_commit_sha":null,"homepage":"https://matrixeditor.github.io/bshark/","language":"C","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/MatrixEditor.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":"2024-04-17T16:01:23.000Z","updated_at":"2024-10-20T18:45:46.000Z","dependencies_parsed_at":"2024-11-07T16:29:10.049Z","dependency_job_id":"85096d3a-715d-410a-b719-a2a066983170","html_url":"https://github.com/MatrixEditor/bshark","commit_stats":null,"previous_names":["matrixeditor/bshark"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixEditor%2Fbshark","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixEditor%2Fbshark/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixEditor%2Fbshark/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixEditor%2Fbshark/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MatrixEditor","download_url":"https://codeload.github.com/MatrixEditor/bshark/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239629292,"owners_count":19671257,"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","android-binder","ipc"],"created_at":"2024-11-07T16:26:32.783Z","updated_at":"2025-11-23T23:30:17.566Z","avatar_url":"https://github.com/MatrixEditor.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# :shark: bshark\n\n*bshark* is a Python library that provides an interface to capturing\nand processing Android Binder transactions as well as compiling AIDL\nfiles into struct definitions.\n\n## Installation\n\nCurrently, there is no python package available for *bshark*. Therefore,\nyou have to use the GIT installation candidate:\n\n```bash\npip install bshark@git+https://github.com/MatrixEditor/bshark.git\n```\n\nPlease follow the documentation on how to use this library.\n\n## Examples\n\n### Compiling an AIDL file:\n```python\nfrom bshark.compiler import BaseLoader, Compiler, ParcelableDef\n\n# More information about the Java sources are given in the\n# documentation\nloader = BaseLoader(['/path/to/android-java-root/'])\nunits  = loader.import_(\"android.accounts.Account\")\n\nc = Compiler(units[0], loader)\npdef: ParcelableDef = c.compile()\n```\n\nor using the command line interface:\n```bash\npython3 -m bshark.compiler         \\ # base command\n    -I /path/to/android-java-root/ \\ # include directories\n    compile                        \\ # action\n    -o /path/to/output/            \\ # output directory\n    android.accounts.Account       \\ # target class to compile (AIDL file required)\n```\n\n#### Batch compilation\n\nBatch compilation is supported in the same way in the command line interface.\n```bash\npython3 -m bshark.compiler        \\ # base commmand\n    -I $ANDROID_SRC               \\ # include directories (Android source required)\n    batch-compile                 \\ # action\n    -o $OUTPUT_DIR                \\ # output directory\n    [--recursive] [--force]         # options\n```\n\n### Manual Message Parsing:\n\nIn order to parse a message, we need the compiled binder interface and all necessary\nparcelable definitions involved. Consider we want to decode a message from the\n`android.app.IActivityManager` with transaction code `63`. First, we have to compile\nthe binder interface:\n```python\nfrom bshark.compiler import BaseLoader, Compiler\nfrom bshark.parcel import parse\n\nloader = BaseLoader(['/path/to/android-java-root/'])\n(unit,) = loader.import_(\"android.app.IActivityManager\")\n\n# A single call to compile is enough. It will replace the\n# cached unit and place the binder definition in it.\nc = Compiler(unit, loader)\nbdef = c.compile()\n\ndata = ...\nmsg = parse(\n    data,           # recevied data\n    63,             # transaction code\n    loader,         # loader\n    version=...,    # Android API version\n)\n```\n\nThe output would look something like this:\n```python\nIncomingMessage(\n    smp=3254779908,\n    work_suid=4294967295,\n    env=\u003cEnvironment.SYST: 1398362964\u003e,\n    descriptor='android.app.IActivityManager',\n    data={\n        'connection': {\n            'type': 1936206469,\n            'flags': 275,\n            'handle': 41,\n            'cookie': 0,\n            'status': 201326593\n        },\n        'stable': 0\n    }\n)\n```\n\n### Capturing Binder transactions:\nIn order to receive binder transactions, we have to use a custom\n`TransactionListener`, which wil be used later on by an `Agent`.\n```python\nfrom bshark.agent import TransactionListener\nfrom bshark.parcel import parse, IncomingMessage, OutgoingMessage\n\nloader = ... # the loader must store compiled Parcelable definitions\n# e.g.\nloader = BaseLoader(['/path/to/compiled-files-root/'])\nloader.import_(\"*\")\n\nclass MyListener(TransactionListener):\n    def on_transaction(self, code: int, data: bytes) -\u003e None:\n        msg: IncomingMessage = parse(\n            data,           # recevied data\n            code,           # transaction code\n            loader,         # loader\n            version=...,    # Android API version\n        )\n\n    def on_reply(self, code: int, interface: str, data: bytes):\n        msg: OutgoingMessage = parse(\n            data,           # recevied data\n            code,           # transaction code\n            loader,         # loader\n            version=...,    # Android API version\n            descriptor=interface, # target interface\n            in_=False\n        )\n```\n\nWith the listener, we can now capture transactions using an agent object:\n```python\nfrom bshark.agent import Agent\n\ndevice = ... # aquire device object from frida\nagent = Agent(\n    loader,\n    android_version=..., # Android API version\n    device=device,       # the device to use\n    listener=MyListener(),\n)\n\n# either spawn an application or attach to the pid\npid = ...\nagent.attach(pid)\n# or\nagent.spawn('com.example.app', extras=[\"/path/to/my-extra-script.js\"])\n\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrixeditor%2Fbshark","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatrixeditor%2Fbshark","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrixeditor%2Fbshark/lists"}