{"id":13456277,"url":"https://github.com/FrenchYeti/dexcalibur","last_synced_at":"2025-03-24T09:31:56.424Z","repository":{"id":42535240,"uuid":"171117490","full_name":"FrenchYeti/dexcalibur","owner":"FrenchYeti","description":"[Official] Android reverse engineering tool focused on dynamic instrumentation automation leveraging Frida. It disassembles dex, analyzes it statically, generates hooks, discovers reflected methods, stores intercepted data and does new things from it. Its aim is to be an all-in-one Android reverse engineering platform.","archived":false,"fork":false,"pushed_at":"2023-02-02T21:46:58.000Z","size":32574,"stargazers_count":1082,"open_issues_count":30,"forks_count":126,"subscribers_count":27,"default_branch":"master","last_synced_at":"2025-03-18T03:14:01.116Z","etag":null,"topics":["analysis","android","android-security","apk","dex","frida","frida-node","gui","hook","hooking","instrumentation-automation","mobile-security","reverse","reverse-engineering","security-tools","smali"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FrenchYeti.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"FrenchYeti"}},"created_at":"2019-02-17T12:07:02.000Z","updated_at":"2025-03-17T07:49:29.000Z","dependencies_parsed_at":"2023-02-18T01:00:26.804Z","dependency_job_id":null,"html_url":"https://github.com/FrenchYeti/dexcalibur","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FrenchYeti%2Fdexcalibur","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FrenchYeti%2Fdexcalibur/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FrenchYeti%2Fdexcalibur/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FrenchYeti%2Fdexcalibur/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FrenchYeti","download_url":"https://codeload.github.com/FrenchYeti/dexcalibur/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245243377,"owners_count":20583614,"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":["analysis","android","android-security","apk","dex","frida","frida-node","gui","hook","hooking","instrumentation-automation","mobile-security","reverse","reverse-engineering","security-tools","smali"],"created_at":"2024-07-31T08:01:19.128Z","updated_at":"2025-03-24T09:31:51.407Z","avatar_url":"https://github.com/FrenchYeti.png","language":"JavaScript","funding_links":["https://github.com/sponsors/FrenchYeti"],"categories":["JavaScript","JavaScript (485)","Tools","Powered by Frida","Reverse Engineering"],"sub_categories":["Static Analysis Tools","Malware Articles and Sources"],"readme":"![npm dependencies](https://david-dm.org/frenchyeti/dexcalibur.svg)\n![npm](https://img.shields.io/npm/dm/dexcalibur)\n![npm](https://img.shields.io/npm/v/dexcalibur?color=green)\n![Docker Automated build](https://img.shields.io/docker/automated/frenchyeti/dexcalibur.svg?style=flat-square)\n[![Build Status](https://travis-ci.org/FrenchYeti/dexcalibur.svg?branch=master)](https://travis-ci.org/FrenchYeti/dexcalibur)\n![Twitter Follow](https://img.shields.io/twitter/follow/frenchyeti?style=social)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com) \n[![Maintainability](https://api.codeclimate.com/v1/badges/080688cfe119a255db70/maintainability)](https://codeclimate.com/github/FrenchYeti/dexcalibur/maintainability)\n\n\n![Dexcalibur banner](https://raw.githubusercontent.com/FrenchYeti/dexcalibur-doc/master/pictures/v1.0.0a/Dexcalibur-for-Github2.jpg)\n# Dexcalibur\n\nDexcalibur is an Android reverse engineering platform focus on instrumentation automation. Its particularity is to use dynamic analysis to improve static analysis heuristics. It aims automate boring tasks related to dynamic instrumentation, such as :\n* Decompile/disass intercepted bytecode at runtime\n* Write hook code and Manage lot of hook message\n* Search interesting pattern / things to hook\n* Process data gathered by hook (dex file, invoked method, class loader, ...)\n* and so ...\nBut not only that, because Dexcalibur has own static analysis engine and it is able to execute partial piece of smali.  \n\n\nDo you want share something or do you need some help ? Join our official chats :\n\n[Telegram](https://t.me/dexcalibur) - the quickiest way to give a response\n\n[![https://discord.gg/pfB7Ez34Ts](https://discordapp.com/api/guilds/852565889386676246/widget.png?style=banner2)](https://discord.gg/pfB7Ez34Ts)\n\n\nOfficial documentation is available [here (website - work in progress)](https://frenchyeti.github.io/dexcalibur-doc/). \n\nSee the latest news here : [http://docs.dexcalibur.org/News.html](http://docs.dexcalibur.org/News.html) \n\nShow Dexcalibur demo videos : [Demo: Less than 1 minute to hook 61 methods ? Not a problem. \\(youtube\\)](https://www.youtube.com/watch?v=2dGoolvMEpI)\n\n\n## How to support Dexcalibur ? \n\n**Contribute !**\n\nDon't hesitate ! There are several ways to contribute : \n- Make a pull request related to a fix or a new feature\n- Create an issue to help me to patch/involves tools \n- Help me to develop UI\n- Send me a mail with your feedback\n- etc ...\n\n\n## A. Installation\n\n### A.1 New install\n\nGo to [Install doc](https://frenchyeti.github.io/dexcalibur-doc/Installation-guide.html)\n\nAlternative: use Docker\n\n- on your host, install `adb` (and an Android emulator if appropriate)\n- `docker-compose build android-dexcalibur`\n- `docker run --rm -it --net=host -v /tmp/dexcalibur:/shared -p 8000:8000 dexcalibur:2023.01 /bin/bash`\n\n\n### A.2 Launch dexcalibur\n\n**For Linux and MacOS**\n\nNPM Install : If Dexcalibur has been installed globaly using NPM (`-g` option), then Dexcalibur can be launch from terminal by doing `$ dexcalibur`, else the location it can be launch by `$ node $(node root -g dexcalibur)/dexcalibur/dexcalibur.js`.\n\nInstall from source : from `dexcalibur` folder, run `$ dexcalibur` or `$ node dexcalibur.js`. \n\n**For Windows**\n\nNPM Install : Event if Dexcalibur is installed globaly using NPM (`-g` option), Dexcalibur must be launched from terminal by running the following command from a terminal `node \u003cNPM_ROOT\u003e/dexcalibur/dexcalibur.js`.\n\nInstall from source : from `dexcalibur` folder, into the terminal, run the command  `node dexcalibur.js`. \n\n### A.3 Update \n\n#### From version \u003c= 0.6.x\n\nYou are using a previous version of Dexcalibur ? \n\nFollow same steps than a new install, and when you should enter workspace path, enter your current workspace location. \n\n\n#### From version \u003e= 0.7\n\nJust by doing:\n```\n$  npm install -g dexcalibur\n``` \n\nExisting configuration and workspace will be detected automatically. \n\n\n\n\n## C. Screenshots\n\nFollowing screenshots illustrate the automatic update of *xrefs* at runtime.\n\n![Xref auto update](https://raw.githubusercontent.com/FrenchYeti/dexcalibur-doc/master/pictures/xref_after_run_white.png)\n\n\n![Features](https://raw.githubusercontent.com/FrenchYeti/dexcalibur-doc/master/pictures/aims.png)\n\n\n## D. Features and limitations\n\nActually, the biggest limitation is Dexcalibur is not able to generate source code of hook targeting native function (into JNI library). However, you can declare manually a Frida's Interceptor by editing a hook.\n\nAssuming Dexcalibur does not provide (for the moment) features to analyse native part such as JNI library or JNA, only features and limitations related to Java part have been detailled.  \n\n**Analysis accuracy depends of the completeness of the Android API image used during early steps of the analysis. That means, if you use a DEX file generated from the Android.jar file from Android SDK, some references to internal methods, fields, or classes from Android java API could be missing. Better results are obtained when the analysis start from a \"boot.oat\" file extracted directly from a real device running the expected Android version.**  \n\n### D.1 Features\n\n#### D.1.A Static analyzer\n\nTODO : write text\n\n#### D.1.B Hook manager\n\nTODO : write text\n\n#### D.1.C Dexcalibur's smali VM\n\n**Tracked behaviors**\n\nStatic analyzer involved into \"Run smali (VM)\" action is able to discover and accept but track following behaviors :\n* Out-of-bound destination register (register out of v0 - v255)\n* Out-of-bound source register (register out of v0 - v65535)\n* Detect invalid instruction throwing implicitely an internal exception\n* Detect some piece of valid bytecode non-compliant with Android specification\n* Compute length of undefined array\n* Fill undefined array  \n* and more ...\n\nActually, handlers/listeners for such invalid instruction are not supported but events are tracked and rendered.   \n\n**Dexcalibur IR**\n\nThe VM produces a custom and simplified Intermediate Representation (IR) which is displayed **only to help analyst** to perform its analysis. \n\nDepending of the value of the callstack depth and configuration, IR can include or not instruction executed into called function. If the execution enters into a try block and continues to return, but never excute catch, then the catch block will not be rendered. In fact the purpose of Dexcalibur IR is to render only \"what is executed\" or \"what  could be executed depending of some symbol's value\" into VM context. \n\nDexcalibur IR helps to read a cleaned version of bytcode by removing useless goto and opaque predicate. Dexcalibur IR can be generated by the VM with 2 simplifying levels :\n\n*1st level IR, could be used if you don't trust 2th level IR  :*\n\n - no CFG simplifying : conditions and incondtionnal jumps are rendered.\n - every move into a register are rendered\n\n\n*2th level :* \n\n- Hide assign if the register is not modified with an unknown value before its use.\n- Always TRUE/FALSE predicate are removed\n- Inconditional jump such goto are removed under certain conditions : single predecessor of targeted basic block, etc ...  \n- Resolve \u0026 replace Method.inoke() call by called method if possible. \n- Instructions into a Try block are not rendered if an exception is thrown before \n- ...\n\n**Android API mock**\n\nTODO\n\n**Details**\n\nSmali VM follows steps :\n\n1. Init VM : stack memory, heap, classloaders, method area, ...\n2. The VM load class declaring the method.\n3. (Optionnal) If the class has static blocks, clinit() is executed.  It helps to solve concrete value stored into static properties\n4. Load method metadata\n5. Execute method's instructions, if PseudoCodeMaker is enable, Dexcalibur IR is generated. \n\n\nHow VM handles invoke-* instruction ?  \n\n1. When an invoke-* happens, the local symbol table is saved, and the invoked method is loaded.\n2. If the class declaring the invoked method  has never been loaded, the class is loaded \n3. If the method has never been loaded, the method is loaded (by MethodArea) and its local symbol table initialized by importing symbols of arguments from caller's symbol table. \n4. Invoked method is push into callstack (StackMemory).\n5. Method instruction are executed.\n6. Return is push into stack memory\n7. Caller give flow control\n\n#### D.1.D Application Topology  analyzers\n\n\n**Manifest analysis (LIMITED)**\n\nBefore the first run, the Android manifest of the application is parsed. Actually, anomalies into the manifest \nsuch insecure configuration are really detected at this level. \n\nThe only purpose of Android manifest parsing is to populate other kind of analyzers.\n\n**Permission analysis**\n\nEvery permissions extracted from the Manifest are listed and identified and compared to Android specification of the target Android API version.\n\nDexcalibur provides - only in some case - a description of the permission purpose, the minimal Android API version, ... \n\n**Activities analysis**\n\n**Providers analysis**\n\n**Services analysis**\n\n**Receivers analysis**\n\n\n#### D.1.E Runtime monitoring (not implemented)\n\n**Network monitoring**\n\n**Intent monitoring**\n\n**File access monitoring**\n\n#### D.1.F Collaborating features\n\nYou cannot find multi-user menu ? Not a probleme, there is not a menu but minimalistic collaborative work can be achieve. \n\nDexcalibur runs a web server.  So, if several people are on the same network of this web server and if host firewall is well configured, you can be several to work on the same Dexcalibur instance.\n\n*Actual limitations are :*\n- **No authentication :** everybody into the network can send request to Dexcalibur instance and doing RCE the host through search engine.\n- **No identifying :** modifying are not tracked, so, if someone rename a symbol, you could not know who renamed it. Similar case : you are not able to know who created a specific hook.\n- **Single device instrumentation :** if several devices are connected to Dexcalibur's host, and even if you can choose the device to instrument, instrumentation and hook messages are linked to the last device selected. So, you cannot generate instrumention for several devices simultaneously.\n\n\n\n## E. Github Contributors\n\nA special thanks to contributors : \n\n- [ubamrein](https://github.com/ubamrein)\n- [jhscheer](https://github.com/jhscheer)\n- [eybisi](https://github.com/eybisi)\n- [monperrus](https://github.com/monperrus)\n- [cryptax](https://github.com/cryptax)\n\n## F. Troubleshoots\n\n### F.1 Dexcalibur continues to start into \"install mode\"\n\nBefore to go deeper :\n- Ensure you are connected to Internet : Apktool and target platform are downloaded during install\n- Did you have tried to reinstall it by doing `dexcalibur --reinstall` command ? If no, try it.\n\n\nFirst, check if global settings have been saved into `\u003cuser_directory\u003e/.dexcalibur/`\n```\n$ ls -la ~/.dexcalibur      \n\ntotal 8\ndrwxr-xr-x   3 test_user  staff    96 29 avr 11:41 .\ndrwxr-xr-x+ 87 test_user  staff  2784 29 avr 11:47 ..\n-rw-r--r--   1 test_user  staff   204 29 avr 11:41 config.json\n\n\n$ cat ~/.dexcalibur/config.json \n\n{\n    \"workspace\":\"/Users/test_user/dexcaliburWS3\",\n    \"registry\":\"https://github.com/FrenchYeti/dexcalibur-registry/raw/master/\",\n    \"registryAPI\":\"https://api.github.com/repos/FrenchYeti/dexcalibur-registry/contents/\"\n}\n```\n\n\nNext, check if structure of Dexcalibur workspace is as following (content of `/api` folder may differs).\n```\n$ ls -la ~/dexcaliburWS/.dxc/*\n/Users/test_user/dexcaliburWS/.dxc/api:\ntotal 0\ndrwxr-xr-x  3 test_user  staff   96 29 avr 11:41 .\ndrwxr-xr-x  7 test_user  staff  224 29 avr 11:41 ..\ndrwxr-xr-x  8 test_user  staff  256 29 avr 11:41 sdk_androidapi_29_google\n\n/Users/test_user/dexcaliburWS/.dxc/bin:\ntotal 34824\ndrwxr-xr-x   4 test_user  staff       128 29 avr 11:41 .\ndrwxr-xr-x   7 test_user  staff       224 29 avr 11:41 ..\n-rwxr-xr-x   1 test_user  staff  17661172 29 avr 11:41 apktool.jar\ndrwxr-xr-x  18 test_user  staff       576 29 avr 11:41 platform-tools\n\n/Users/test_user/dexcaliburWS/.dxc/cfg:\ntotal 8\ndrwxr-xr-x  3 test_user  staff   96 29 avr 11:41 .\ndrwxr-xr-x  7 test_user  staff  224 29 avr 11:41 ..\n-rw-r--r--  1 test_user  staff  314 29 avr 11:41 config.json\n\n/Users/test_user/dexcaliburWS/.dxc/dev:\ntotal 0\ndrwxr-xr-x  2 test_user  staff   64 29 avr 11:41 .\ndrwxr-xr-x  7 test_user  staff  224 29 avr 11:41 ..\n\n/Users/test_user/dexcaliburWS/.dxc/tmp:\ntotal 0\ndrwxr-xr-x  2 test_user  staff   64 29 avr 11:41 .\ndrwxr-xr-x  7 test_user  staff  224 29 avr 11:41 ..\n```\n\n## G. FAQ\n\n### My device not appears when into device list\n\nIf you use a physical device connected over USB, ensure *developper mode* and *USB debugging* are enabled.  \n\nIf you use a virtual device, go to `/splash.html`,  select `Device Manager`,  click `Connect over TCP ...` and follow instructions. If you don't know IP address of your device, let Dexcalibur detect it by checking box `automatic configuration`.\n\n\n### USB debugging is enabled, but my device not appears when into device list\n\n - Connect/disconnect USB and ensure your computer is allowed. \n - Select file transfert\n\n### Why enroll a new device ?\n\nYou need to enroll the target device before to be able to use it. \nDuring enrollment Dexcalibur gather device metadata and push a compatible version of Frida server.\n\nSuch metadata are used to select right frida-server and frida-gadget targets.\n\n#### My device is listed into Device Manager, but it cannot be enrolled\n\nIf a red exclamation mark `!` appears on a line into device list, then your desktop is not allowed by device. You probably need to confirm \n\nIf your device is listed into DeviceManager and the column `online` is checked, then click `enroll` \n\n\n#### G.1 My device is listed into Device Manager\n\nIf your device is listed into DeviceManager and the column `online` is checked, then click `enroll` \n\n### How to use an emulator instead of a physical device ?\n\nDexcalibur version \u003c v0.7 was not able to detect automatically emulated device and use it due to an incomplete ADB output parsing.\n\nSince version \u003e= v0.7, once your virtual device is running, go to `/splash.html` or click on `DEXCALIBUR` into navigation bar.\nClick on `Device Manager` button into left menu, and click the `Refresh` button at top of array.\n\nYou should have a row starting by the ADB ID of your virtual device.\n\n### How to use a device over TCP ?\n\nFirst, as any target device, you should enroll it.\n\nClick `Connect over TCP ...` to add a new device over TCP or to connect an enrolled device over TCP.\n\nIf the device has never been enrolled, so enrollment will be perform through TCP. \nIn some case, connection over TCP is slower than over USB. So enrollement can take additional time.\n\nIf the device has been enrolled over USB, so the new prefered transport type for this device becomes TCP.\n\n### How to contribute to the dexcalibur ?\n\nCreate a pull request on this repository or create an issue.\n\n### How to contribute to the documentation?\n\nCreate a pull request on [dexcalibur-doc](https://github.com/FrenchYeti/dexcalibur-doc) repository.\n\nDocumentation is available at [here (doc website)](https://frenchyeti.github.io/dexcalibur-doc/) and [here (wiki)](https://github.com/FrenchYeti/dexcalibur/wiki/News)\n\n## H. Sponsors\n\n| ![https://www.jetbrains.com/?from=dexcalibur](https://github.com/FrenchYeti/dexcalibur-doc/raw/master/pictures/jetbrains_logo.png) |\n| --- |\n| They offered a license for All Products \u003c3 |\n\n## I. Resources\n\nThere is actually few documentation and training resources about Dexcalibur. If you successfully used Dexcalibur to win CTF challenge or to find vulnerability, i highly encourage you to share your experience. \n\n* [THCon 2020](https://www.youtube.com/watch?v=VRVV23glm_o)\n* [SSTIC 2020](https://www.sstic.org/2020/presentation/dexcalibur_hook_it_yourself/)\n* [Slides of Pass the SALT 2019 (PDF)](https://2019.pass-the-salt.org/files/slides/02-Dexcalibur.pdf)\n* [Youtube : demonstration](https://www.youtube.com/watch?v=2dGoolvMEpI)\n* [CLI User Guide](https://github.com/FrenchYeti/dexcalibur/wiki/CLI-User-guide)\n* [User Guide](https://github.com/FrenchYeti/dexcalibur/wiki/User-guide)\n* [Troubleshoots](https://github.com/FrenchYeti/dexcalibur/wiki/Troubleshoots)\n* [Screenshots](https://github.com/FrenchYeti/dexcalibur/wiki)\n\n\n## J. They wrote something about Dexcalibur\n\n* [Awesome Frida](https://github.com/dweinstein/awesome-frida)\n* [Awesome OpenSource Security](https://github.com/CaledoniaProject/awesome-opensource-security)\n* [n0secure.org - PassTheSalt2019 J2](https://www.n0secure.org/2019/06/sstic-2019-j2.html)\n* [rootshell.be - PassTheSalt2019 Wrap Up](https://blog.rootshell.be/2019/07/04/pass-the-salt-2019-wrap-up/)\n* [PentesterLand - the 5 hacking newsletter 61](https://pentester.land/newsletter/2019/07/09/the-5-hacking-newsletter-61.html)\n* [Technology Knowledge Database](https://github.com/ikey4u/tkb/blob/d26f47bf75d8d4c1aa5a655ab6c60f876ad7d402/tkb201907.txt)\n* [Xuanwu Lab Security](https://github.com/MyKings/security-study-tutorial/blob/3a5661fb54c6320f403eefa95bcf787324a6e923/origin/Xuanwu%20Lab%20Security/2019/08/01.md)\n* [Mobile Gitbook](https://github.com/z3f1r/mobile-gitbook)\n* [274 - AppsSec Ezine](https://github.com/Simpsonpt/AppSecEzine/blob/60c530b32984921daa47164591e94bb564b0c75c/Ezines/274%20-%20AppSec%20Ezine)\n* [ysh329 / Android Reverse Engineering](https://github.com/ysh329/android-reverse-engineering)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFrenchYeti%2Fdexcalibur","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FFrenchYeti%2Fdexcalibur","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFrenchYeti%2Fdexcalibur/lists"}