Screenshot of Hackium and the REPL

Introducing Hackium

with shift-refactor and shift-interpreter

I’m super excited to release Hackium, shift-refactor, and shift-interpreter — three tools that I’ve been using to analyze, automate, and manipulate web sites for the past year. These projects have been a long time in the making, they incorporate techniques I started playing with 20+ years ago. Granted, those techniques were little more than a hacky HTTP proxy and dozens of regular expressions, but the spirit was there.

Hackium is a command line tool, a browser, and a framework. That’s the elevator pitch, anyway. Technically, Hackium is a nodejs library that extends puppeteer to control a bundled version of Chromium, preconfigured to disable security controls and expose more APIs. That’s less catchy. In practical terms, Hackium is a browser that stands in your way less and gives you more.

Who is Hackium for?

Do you open devtools frequently, even on sites you don’t actually work on?

Do you ever wish your browser was more useful on the command line?

Have you ever been frustrated that a website could do something that a developer API couldn’t?

Hackium may be for you.

Browser makers prioritize features for two groups of users: everyday people browsing the web and, in a distant second, web application developers. Hackium is not for those people. They can use it, sure. But it’s not for them. They have enough.

How do I use Hackium?

Install Hackium via npm…

$ npm install -g hackium

…and run it via the hackium command….

$ hackium

… and watch in a amazement as a strangely colored Chrome lookalike pops up. I know, not too exciting yet, but pop over to the terminal again and you can play with the REPL! The REPL allows you to interact with the page via Hackium and Puppeteer APIs. Try entering the following:

page.goto('https://google.com');

The bulk of the browser and page API methods come from Puppeteer, an amazing web automation library that paved the way for me to make Hackium.

See github.com/jsoverson/hackium for more info on command line options, or use hackium init to generate a basic configuration file:

Hackium’s configuration wires together what would normally be tedious boilerplate so we can cut straight to the logic we’re interested in. Interceptors jump into the middle of requests and responses and injections are in-page scripts that run before any website code runs. Hackium scripts are basic nodejs scripts (with top-level await) that have access to an already launched browser and page instance.

Shift-refactor

I gave a preview of Shift-refactor almost one year ago and we now have a v1 (v2, actually) release. Shift-refactor is a JavaScript transformation library that uses CSS-like selectors and a jQuery-like API to make it simple to cut up and twist JavaScript source.

const $script = refactor(ast);
$script('VariableDeclarationStatement').prepend(`test();`);
$script.statements().first().delete();
$script.print();

If you’ve ever used regular expressions to scrape data from or modify JavaScript, then you know how difficult it is to craft a regex for arbitrary code. Shift-refactor is what you need.

Check out more of the API at github.com/jsoverson/shift-refactor and experiment with the query syntax at the online demo here: https://jsoverson.github.io/shift-query-demo/

Shift-interpreter

Shift-interpreter is a JavaScript meta-interpreter that evaluates JavaScript piecemeal. An interpreter instance takes nodes of a JavaScript abstract syntax tree (AST), in any order, and evaluate those nodes individually while retaining awareness of the original scope. This is not common behavior but was the reason I started the project in the first place. This functionality makes it possible to carve out only the portions of source you need without actually rewriting anything.

Why in the world would anyone want to do that?

Well, imagine you have a chunk of obfuscated JavaScript, something like this:

All those encoded strings stand in the way of understanding the source. There’s a decoder method somewhere in there, we just need to find it. Once we find it we could just copy the logic and decode those strings, but what if the encoding algorithm changes? Or what if decoding is dependent on state of the application? That gets trickier.

Shift-interpreter allows you to use those methods directly. Combine the interpreter with shift-refactor to query for nodes, interpret them, and then slice them back into the JavaScript. In other words, you can use JavaScript against itself.

I built shift-interpreter specifically for deobfuscating source code but it’s proven useful for generic analysis and code flow mapping.

Shift-interpreter is not for everyone. It’s powerful but is fraught with caveats that are worth working through only if you’re crazy enough to be doing the things I’m talking about.

Check out more at github.com/jsoverson/shift-interpreter

Better together?

I built these projects as a response to holes I found in my web hacking travels, but each is an independent project that can be used just as well on its own.

Wielding them all together makes you feel like a wizard that can twist the web in any direction you choose, however. It shouldn’t be missed.

You’re a wizard, h̶a̶r̶r̶y̶ hacker

More demos!

I announced these releases last Saturday during my session at Defcon’s AppSec Village.

Original session during Defcon 28

In this session I demo how to get started, how to integrate with other services, and how to combine Hackium with shift-refactor and shift-interpreter to deobfuscate JavaScript. If you missed it, then you’re in luck! The Defcon version had the edges cut off, and I uploaded the original version here:

I’ve wanted the functionality in these projects for years. It would be nice to know I’m not the only one who uses the web this way. Reach out if you find these tools useful!