README

Sidecar

Sidecar is a runtime hooking tool for intercepting function calls by TypeScript annotation with ease, powered by Frida.RE.

Frida Sidecar

Image source: 1920s Raleigh Box Sidecar Outfit & ShellterProject

What is a "Sidecar" Pattern?

Segregating the functionalities of an application into a separate process can be viewed as a Sidecar pattern. The Sidecar design pattern allows you to add a number of capabilities to your application without the need of additional configuration code for 3rd party components.

As a sidecar is attached to a motorcycle, similarly in software architecture a sidecar is attached to a parent application and extends/enhances its functionalities. A Sidecar is loosely coupled with the main application.

— SOURCE: Sidecar Design Pattern in your Microservices Ecosystem, Samir Behara, July 23, 2018

What is a "Hooking" Patern?

Hook: by intercepting function calls or messages or events passed between software components. — SOURCE: Hooking, Wikipedia

Features

Easy to use by TypeScript decorators/annotations
1. @Call(memoryAddress) for make a API for calling memory address from the binary
2. @Hook(memoryAddress) for emit arguments when a memory address is being called
Portable on Windows, macOS, GNU/Linux, iOS, Android, and QNX, as well as X86, Arm, Thumb, Arm64, AArch64, and Mips.
Powered by Frida.RE and can be easily extended by any agent script.

Requirements

Mac: disable System Integrity Protection

Introduction

When you are running an application on the Linux, Mac, Windows, iPhone, or Android, you might want to make it programmatic, so that your can control it automatically.

The SDK and API are designed for achieving this, if there are any. However, most of the application have very limited functionalities for providing a SDK or API to the developers, or they have neither SDK nor API at all, what we have is only the binary executable application.

How can we make a binary executable application to be able to called from our program? If we can call the function in the application process directly, then we will be able to make the application as our SDK/API, then we can make API call to control the application, or hook function inside the application to get to know what happened.

I have the above question and I want to find an universal way to solve it: Frida is for rescue. Frida is a dynamic instrumentation toolkit for developers and reverse-engineers, which can help us easily call the internal function from a process, or hook any internal function inside the process. And it has a nice Node.js binding and TypeScript support, which is nice to me because I love TypeScript much.

That's why I start build this project: Sidecar. Sidecar is a runtime hooking tool for intercepting function calls by decorate a TypeScript class with annotation.

Here's an example code example for demostration that how easy it can help you to hook a exiting application.

Talk is cheap, show me the code

@Sidecar('chatbox')
class ChatboxSidecar extends SidecarBody {

  @Call(0x11c9)
  @RetType('void')
  mo (
    @ParamType('pointer', 'Utf8String') content: string,
  ): Promise<string> { return Ret(content) }

  @Hook(0x11f4)
  mt (
    @ParamType('pointer', 'Utf8String') content: string,
  ) { return Ret(content) }

}

async function main () {
  const sidecar = new ChatboxSidecar()
  await attach(sidecar)

  sidecar.on('hook', ({ method, args }) => {
    console.log('method:', method)
    console.log('args:', args)
    sidecar.mo('Hello from Sidecar'),
  })

  process.on('SIGINT',  () => detach(sidecar))
  process.on('SIGTERM', () => detach(sidecar))
}

main().catch(console.error)

Learn more from the sidecar example: https://github.com/huan/sidecar/blob/main/examples

To-do list

Intercepter.attach() a NativeCallback() ~~ptr not work in Sidecar generated script. (it is possible by direct using the frida cli)~~ worked! (#9)
Add typing.d.ts for Sidecar Agent pre-defined variables & functions
Add @Name() support for specify parameter names in @Hook()-ed method args.
Calculate Memory.alloc() in sidecar agent scripts automatically.

Explanation

1. Sidecar Steps

When we are running a Sidecar Class, the following steps will happend:

From the sidecar class file, decorators save all configs to the class metadata.
1. @Sidecar(): <src/decorators/sidecar/sidecar.ts>, <src/decorators/sidecar/build-sidecar-metadata.ts>
2. @Call(): <src/decorators/call/call.ts>
3. @ParamType(): <src/decorators/param-type/param-type.ts>
4. @RetType(): <src/decorators/ret-type/ret-type.ts>
5. @Hook(), @Name, etc.
SidecarBody(<src/sidecar-body/sidecar-body.ts>) base class will generate agentSource:
1. getMetadataSidecar()(<src/decorators/sidecar/metadata-sidecar.ts>) for get the sidecar metadata from the class
2. buildAgentSource()(<src/agent/build-agent-source.ts>) for generate the agent source code for the whole sidecar system.
Call the attach() method to attach the sidecar to the target
Call the detach() method to detach the sidecar to the target

References

1. `@Sidecar(sidecarTarget, initAgentScript)`

sidecarTarget : SidecarTarget,
initAgentScript? : string,

The class decorator.

sidecarTarget is the executable binary name, and the initAgentScript is a Frida agent script that help you to do whatever you want to do with Frida system.

Example:

import { Sidecar } from 'sidecar'
@Sidecar('chatbox')
class ChatboxSidecar {}

It is possible to load a init agent script, for example:

const initAgentScript = 'console.log("this will be runned when the sidecar class initiating")'
@Sidecar(
  'chatbox', 
  initAgentScript,
)

sidecarTarget supports Spawn mode, by specifing the sidecarTarget as a array:

@Sidecar([
  '/bin/sleep', // command
  [10],         // args
])

To learn more about the power of initAgentScript, see also this great repo with lots of examples: Hand-crafted Frida examples

2. `class SidecarBody`

Base class for the Sidecar class. All Sidecar class need to extends from the SidecarBody, or the system will throw an error.

Example:

import { SidecarBody } from 'sidecar'
class ChatboxSidecar extends SidecarBody {}

3. `@Call(functionTarget)`

functionTarget: FunctionTarget

The native call method decorator.

functionTarget is the address (in number type) of the function which we need to call in the executable binary.

Example:

import { Call } from 'sidecar'
class ChatboxSidecar {
  @Call(0x11c9) mo () {}
}

If the functionTarget is not the type of number, then it can be string or an FunctionTarget object. See FunctionTarget section to learn more about the advanced usage of FunctionTarget.

4. `@Hook(functionTarget)`

functionTarget: FunctionTarget

The hook method decorator.

functionTarget is the address (in number type) of the function which we need to hook in the executable binary.

Example:

import { Hook } from 'sidecar'
class ChatboxSidecar {
  @Hook(0x11f4) mt () {}
}

If the functionTarget is not the type of number, then it can be string or an FunctionTarget object. See FunctionTarget section to learn more about the advanced usage of FunctionTarget.

5. `@RetType(nativeType, ...pointerTypeList)`

nativeType : NativeType
pointerTypeList : PointerType[]

import { RetType } from 'sidecar'
class ChatboxSidecar {
  @RetType('void') mo () {}

6. `@ParamType(nativeType, ...pointerTypeList)`

nativeType : NativeType
pointerTypeList : PointerType[]

import { ParamType } from 'sidecar'
class ChatboxSidecar {
  mo (
    @ParamType('pointer', 'Utf8String') content: string,
  ) {}

7. `Name(parameterName)`

TODO: to be implemented.

parameterName: string

The parameter name.

This is especially useful for Hook methods. The hook event will be emit with the method name and the arguments array. If the Name(parameterName) has been set, then the event will have additional information for the parameter names.

import { Name } from 'sidecar'
class ChatboxSidecar {
  mo (
    @Name('content') content: string,
  ) {}

8. `Ret(...args)`

args: any[]

Example:

import { Ret } from 'sidecar'
class ChatboxSidecar {
  mo () { return Ret() }

9. `FunctionTarget`

The FunctionTarget is where @Call or @Hook to be located. It can be created by the following factory helper functions:

addressTarget(address: number, module?: string): memory address. i.e. 0x369adf. Can specify a second module to call address in a specified module
agentTarget(funcName: string): the JavaScript function name in initAgentScript to be used
exportTarget(exportName: string, exportModule?: string): export name of a function. Can specify a second moduleName to load exportName from it.
objcTarget: to be added
javaTarget: to be added

For convenice, the number and string can be used as FunctionTarget as an alias of addressTarget() and agentTarget(). When we are defining the @Call(target) and @Hook(target):

if the target type is number, then it will be converted to addressTarget(target)
if the target type is string, then it will be converted to agentTarget(target)

Example:

import { 
  Call,
  addressTarget,
} from 'sidecar'
class ChatboxSidecar {
  @Call(
    addressTarget(0x11c9)
  )
  mo () {}
}

9.1 `agentTarget(funcName: string)`

agentTarget let you specify a funcName in the initAgentScript source code, and will use it directly for advanced users.

There's two type of the AgentTarget usage: @Call and @Hook.

AgentTarget with @Call: the funcName should be a JavaScript function instance in the initAgentScript. The decorated method call that function.
AgentTarget with @Hook: the funcName should be a NativeCallback instance in the initAgentScript. The decorated method hook that callback.

Notes:

The NativeFunction passed to @Call must pay attention to the Garbage Collection of the JavaScript inside Frida. You have to hold a reference to all the memory you alloced by yourself, for example, store them in a Object like const refHolder = { buf }, then make sure the refHolder will be hold unless you can free the memory that you have alloced before. (See also: Frida Best Practices)
the NativeCallback passed to @Hook is recommended to be a empty function, like () => {} because it will be replaced by Sidecar/Frida. So you should not put any code inside it,

Debug utility: `sidecar-dump`

Sidecar provide a utility named sidecar-dump for viewing the metadata of the sidecar class, or debuging the frida agent init source code.

You can run this util by the following command:

$ npx sidecar-dump --help
sidecar-dump <subcommand>
> Sidecar utility for dumping metadata/source for a sidecar class

where <subcommand> can be one of:

- metadata - Dump sidecar metadata
- source - Dump sidecar agent source

For more help, try running `sidecar-dump <subcommand> --help`

sidecar-dump support two sub commands:

metadata: dump the metadata for a sidecar class
source: dump the generated frida agent source code for a sidecar class

1. `sidecar-dump metadata`

Sidecar is using decorators heavily, for example, we are using @Call() for specifying the process target, @ParamType() for specifying the parameter data type, etc.

Internally, sidecar organize all the decorated information as metadata and save them into the class.

the sidecar-dump metadata command is to viewing this metadata information, so that we can review and debug them.

For example, the following is the metadata showed by sidecar-dump for our ChatboxSidecar class from examples/chatbox-sidecar.ts.

$ sidecar-dump metadata examples/chatbox-sidecar.ts
{
  "initAgentScript": "console.log('inited...')",
  "interceptorList": [
    {
      "agent": {
        "name": "mt",
        "paramTypeList": [
          [
            "pointer",
            "Utf8String"
          ]
        ],
        "target": "agentMt_PatchCode",
        "type": "agent"
      }
    }
  ],
  "nativeFunctionList": [
    {
      "agent": {
        "name": "mo",
        "paramTypeList": [
          [
            "pointer",
            "Utf8String"
          ],
          [
            "pointer",
            "Utf8String"
          ]
        ],
        "retType": [
          "void"
        ],
        "target": "agentMo",
        "type": "agent"
      }
    }
  ],
  "sidecarTarget": "/tmp/t/examples/chatbox/chatbox-linux"
}

2. `sidecar-dump source`

Sidecar is using Frida to connect to the program process and make communication with it.

In order to make the connection, sidecar will generate a frida agent source code, and using this agent as the bridge between the sidecar, frida, and the target program process.

the sidecar-dump source command is to viewing this frida agent source, so that we can review and debug them.

For example, the following is the source code showed by sidecar-dump for our ChatboxSidecar class from examples/chatbox-sidecar.ts.

$ sidecar-dump source  examples/chatbox-sidecar.ts
...
const __sidecar__mo_Function_wrapper = (() => {
  const nativeFunctionAddress =
    __sidecar__moduleBaseAddress
    .add(0x11e9)

  const nativeFunction = new NativeFunction(
    nativeFunctionAddress,
    'int',
    ['pointer'],
  )

  return function (...args) {
    log.verbose(
      'SidecarAgent',
      'mo(%s)',
      args.join(', '),
    )

    // pointer type for arg[0] -> Utf8String
    const mo_NativeArg_0 = Memory.alloc(1024 /*Process.pointerSize*/)
    mo_NativeArg_0.writeUtf8String(args[0])

    const ret = nativeFunction(...[mo_NativeArg_0])
    return Number(ret)
  }
})()

;(() => {
  const interceptorTarget =
    __sidecar__moduleBaseAddress
    .add(0x121f)

  Interceptor.attach(
    interceptorTarget,
    {
      onEnter: args => {
        log.verbose(
          'SidecarAgent',
          'Interceptor.attach(0x%s) onEnter()',
          Number(0x121f).toString(16),
        )

        send(__sidecar__payloadHook(
          'mt',
          [ args[0].readUtf8String() ]
        ), null)

      },
    }
  )
})()

rpc.exports = {
  mo: __sidecar__mo_Function_wrapper,
}

You can dump the sidecar agent source code to a javascript file, then using it with frida directly for debugging & testing.

$ sidecar-dump source chatbox-sidecar.ts > agent.js
$ frida chatbox -l agent.js
     ____
    / _  |   Frida 14.2.18 - A world-class dynamic instrumentation toolkit
   | (_| |
    > _  |   Commands:
   /_/ |_|       help      -> Displays the help system
   . . . .       object?   -> Display information about 'object'
   . . . .       exit/quit -> Exit
   . . . .
   . . . .   More info at https://frida.re/docs/home/
                                                                                
[Local::chatbox]-> rpc.exports.mo('hello from frida cli')

Resources

RPA Examples

Quake REST API demo

Papers

Assembly to Open Source Code Matching for Reverse Engineering and Malware Analysis

Dll

Frida

Unicode

字符编码笔记：ASCII，Unicode 和 UTF-8, 阮一峰，2007年10月28日

Assembler

Online x86 / x64 Assembler and Disassembler (0xf is not valid, use 0x0f instead)
易语言汇编代码转置入代码开源
The 32 bit x86 C Calling Convention
x86 Disassembly/Calling Conventions
How to pass parameters to a procedure in assembly?
NativeCallback doesn't seem to work on Windows, except for mscdecl #525

ObjC

Java

Tiktok data acquisition Frida tutorial, Java, Interceptor, NativePointer(Function/Callback) usage and examples

Related project: FFI Adapter

I have another NPM module named ffi-adapter, which is a Foreign Function Interface Adapter Powered by Decorator & TypeScript.

Learn more about FFI from its examples at https://github.com/huan/ffi-adapter/tree/master/tests/fixtures/library

Badge

[![Powered by Sidecar](https://img.shields.io/badge/Powered%20By-Sidecar-brightgreen.svg)](https://github.com/huan/sidecar)

Demos for Community

We have created different demos that work-out-of-box for some use cases.

You can visit them at Sidecar Demos if you are interested.

History

master v1.0 (Nov 24, 2021)

ES Modules support (#17)
TypeScript version 4.5
Breaking change: Add hook event for all hooked methods

v0.14 (Aug 13, 2021)

Publish to NPM as sidecar package name!

Enforce AgentTarget not to be decorated by neither @ParamType nor @RetType for prevent confusing.

v0.12 (Aug 5, 2021)

Refactor wrappers for include '[' and ']' in array return string
agentTarget now point to JavaScript function in initAgentScript instead of ~~NativeFunction~~
Add scripts/post-install.ts to double check frida_binding.node existance and run prebuild-install with cdn if needed (#14)

v0.9 (Jul 29, 2021)

agentTarget will use NativeFunction instead of a plain javascript function
Clean sidecar frida agent templates
1. Use closure to encapsulate variables
2. Add __sidecar__ namespace for all variable names
Enhance @Sidecar() to support spawn target. e.g. @Sidecar(['/bin/sleep', [10]])
Add .so & .DLL library example for Linux & Windows (Dynamic Library Example)
Add support for raw pointer type

v0.6 (Jul 7, 2021)

Upgrade to TypeScript 4.4-dev for supporting index signatures for symbols. (Microsoft/TypeScript#44512)
Add sidecar-dump utility: it dump the sidecar metadata and source from a class defination file now.
Add pack testing for sidecar-dump to make sure it works under Liniux, Mac, and Windows.

v0.2 (Jul 5, 2021)

Add agent type support to FunctionTarget so that both @Call and @Hookcan use a pre-defined native function ptr defined from the initAgentScript. (more types like java, objc, name, and module to be added)

v0.1 (Jul 4, 2021)

First worked version, published to NPM as sidecar.

v0.0.1 (Jun 13, 2021)

Repo created.

Troubleshooting

1. Debug `initAgentScript`

If sidecar tells you that there's some script error internally, you should use sidecar-dump utility to dump the source of the frida agent script to a agent.js file, and use frida -l agent.js to debug it to get a clearly insight.

$ sidecar-dump source your-sidecar-class.ts > agent.js
$ frida -l agent.js
# by this way, you can locate the error inside the agent.js
# for easy debug and fix.

Special thanks

Thanks to Quinton Ashley @quinton-ashley who is the previous owner of NPM name sidecar and he transfer this beautify name to me for publishing this project after I requested via email. Appreciate it! (Jun 29, 2021)

Author

Huan LI (李卓桓), Microsoft Regional Director, zixia@zixia.net

Copyright & License

Docs released under Creative Commons
Code released under the Apache-2.0 License

Usage no npm install needed!

README

Sidecar

What is a "Sidecar" Pattern?

What is a "Hooking" Patern?

Features

Requirements

Introduction

Talk is cheap, show me the code

To-do list

Explanation

1. Sidecar Steps

References

1. @Sidecar(sidecarTarget, initAgentScript)

2. class SidecarBody

3. @Call(functionTarget)

4. @Hook(functionTarget)

5. @RetType(nativeType, ...pointerTypeList)

6. @ParamType(nativeType, ...pointerTypeList)

7. Name(parameterName)

8. Ret(...args)

9. FunctionTarget

9.1 agentTarget(funcName: string)

Debug utility: sidecar-dump

1. sidecar-dump metadata

2. sidecar-dump source

Resources

RPA Examples

Papers

Dll

Frida

Unicode

Assembler

ObjC

Java

Related project: FFI Adapter

Badge

Demos for Community

History

master v1.0 (Nov 24, 2021)

v0.14 (Aug 13, 2021)

v0.12 (Aug 5, 2021)

v0.9 (Jul 29, 2021)

v0.6 (Jul 7, 2021)

v0.2 (Jul 5, 2021)

v0.1 (Jul 4, 2021)

v0.0.1 (Jun 13, 2021)

Troubleshooting

1. Debug initAgentScript

Special thanks

Author

Copyright & License

1. `@Sidecar(sidecarTarget, initAgentScript)`

2. `class SidecarBody`

3. `@Call(functionTarget)`

4. `@Hook(functionTarget)`

5. `@RetType(nativeType, ...pointerTypeList)`

6. `@ParamType(nativeType, ...pointerTypeList)`

7. `Name(parameterName)`

8. `Ret(...args)`

9. `FunctionTarget`

9.1 `agentTarget(funcName: string)`

Debug utility: `sidecar-dump`

1. `sidecar-dump metadata`

2. `sidecar-dump source`

1. Debug `initAgentScript`