stuartpb / tbnl

TBNL: Rule your Android, as the Root, fully programmable, in Clojure

Table of Contents generated with DocToc

• TBNL: Rule your Android, as the Root, fully programmable, in Clojure
  • see it in action
  • try it
  • [annotated source in Marginalia](#annotated-source-in-marginaliahttpsgithubcomgdeer81marginalia)
  • permission
  • thanks

TBNL: Rule your Android, as the Root, fully programmable, in Clojure

Copyright © Wei Peng

The tag line above says it all.

If you are a hacker, who wants to own your rooted Android 4.3/SDK18+ devices in something nicer than Android's native tongue (i.e., Java) or the command-line power tools (e.g., am and pm), say, Clojure...

This is my gift to you.

TBNL (To Be Named Later) is a pun on the framework's open & exploratory nature, inspired by Edi Weitz's TBNL.

see it in action

Video demos.

try it

First, make sure to satisfy the build/runtime dependencies.

You may first want to try the Figurehead Android app in Google Play Store on your rooted "SDK 18/Android 4.3"+ smartphones/tablets/emulators. For emulator, Genymotion is recommended.

To try out the full TBNL, you have 2 options:

• download & install it without the source code: Easy and quick to get started; but may not have the latest version; does not support further development.
• build & install it with the source code: Longer to set up the first time; but easy to build against the latest version; support further development.

In both case, ensure that:

• Have a sole (in the sense that adb can unambiguously find it) Android device/emulator with Android SDK 18 running.

Then, you can run the tools.

All tested on Arch Linux.

annotated source in Marginalia

The ultimate truth lies in the code.

This is probably what you are looking for.

• figurehead: Clojure REPL on your rooted Android device plus more.
• messenger: Unix-style command-line interface to your Figurehead REPL.

The other components.

• core: the shared underlying framework.
• mastermind: a single central server that brokers figureheads and C&Cs communication (and more).
• C&C: C&C controls figurehead through mastermind.

See also the project Wiki.

permission

I am no legal expert, and I am confused by the plethora of Open Source licenses, so let me explain what I have in mind in plain words.

You are free to use and adapt this work in any way you want, with 2 overall principles:

• Do not hold me or any contributors liable for your actions of using this software.
• Please do the courtesy of fair acknowledgments if you derive works from it.

Please consider:

• Improving the core framework and contributing plug-ins;
• Contributing constructive criticisms: What is working, and what could be improved;
• Reporting issues and sending in patches;
• Staring this project on GitHub;
• Citing this work if you publish a paper using it;
• Letting me know if you use or extend it: I'd love to hear about your work and your use cases.

thanks

• Dr. Feng Li and Dr. Xukai Zou, who advise and support my research into Android system security that begets TBNL.
• The Clojure community.
  • In particular, Alexander Yakushev and others in the small but welcoming family of Clojure on Android.
• In choosing an icon for the Figurehead app, I come across the wonderful The Digital Michelangelo Project. I take the liberty of using a meshed（figure)head of David as the icon of Figurehead, in homage of their work. I hope the authors would not mind.