AndKittyInjector

When injecting into apps that use emulation (cross-ISA via libhoudini or libndk_translation), you may need to use specific timing or breakpoint strategies to ensure successful injection.

Common Scenarios:

1. Wait for launch: Use --watch to wait for the process to appear.
2. Inject on first dlopen: Use --launch --bp-ld to inject as soon as the first native/emulated dlopen occurs.
3. Inject on specific symbol: Use --launch --bp-sym <binary> <symbol> to trigger injection at a specific code location.
4. Delayed injection: Use --delay <micros> to provide a buffer after launch.

# Inject as soon as the first native/emulated dlopen call happens after launch.
./AndKittyInjector --package com.target.package --libs /data/local/tmp/libtest.so --launch --bp-ld

# Inject on a breakpoint at a specific symbol in a specific binary.
./AndKittyInjector --package com.target.package --libs /data/local/tmp/libtest.so \
    --launch --bp-sym /libc.so malloc

When writing a library intended to be injected by AndKittyInjector, follow these rules to ensure stability:

1. Do NOT start threads in the library constructor.
2. Use JNI_OnLoad for initialization logic.
3. Verify the injector key: The injector passes a specific key (1337) to JNI_OnLoad. Check this key to confirm the call originated from the injector before proceeding with sensitive initialization.

Example implementation:

extern "C" jint JNIEXPORT JNI_OnLoad(JavaVM* vm, void *key)
{
    // key 1337 is passed by the injector to confirm this call came from it.
    if (key != (void*)1337)
        return JNI_VERSION_1_6;

    KITTY_LOGI("JNI_OnLoad called by injector.");

    JNIEnv *env = nullptr;
    if (vm->GetEnv((void**)&env, JNI_VERSION_1_6) == JNI_OK)
    {
        KITTY_LOGI("JavaEnv: %p.", env);
        // ...
    }

    std::thread(thread_function).detach();

    return JNI_VERSION_1_6;
}

You can integrate KittyInjector directly into your own C++ tools instead of using the CLI. This requires manual management of the KittyMemoryMgr and the injection lifecycle.

Workflow:

1. Initialize KittyMemoryMgr and its trace component.
2. seize() or attach() to the target PID.
3. Initialize the memory manager with kMgr.initialize(...).
4. Initialize the KittyInjector instance with the manager and a configuration object.
5. Validate the ELF file using injector.validateElf(...).
6. Call injector.inject(...) to perform the injection.
7. detach() the trace when finished.

Note: inject_elf_config_t provides beforeEntryPoint and afterEntryPoint callbacks which are invoked around the remote JNI_OnLoad call.

#include "Injector/KittyInjector.hpp"

inject_elf_config_t cfg{};
// init config

KittyMemoryMgr kMgr;
// manual early init of kMgr.trace to stop process then take our time to kMgr.initialize(...)
kMgr.trace = KittyTraceMgr(targetPid, 0, true);
kMgr.trace.seize();      // or .attach() on older SDKs
kMgr.trace.stop();
kMgr.initialize(targetPid, EK_MEM_OP_SYSCALL, true);

KittyInjector injector;
injector.init(&kMgr, cfg);

bool needsEmulation = false;
if (!injector.validateElf("/data/local/tmp/libtest.so", nullptr, &needsEmulation))
{
    // Failed to validate lib
}

inject_elf_info_t result = injector.inject("/data/local/tmp/libtest.so");
if (result.is_valid())
{
    // result.dl_handle, result.soinfo, result.pJvm, result.pJNI_OnLoad are populated
}

kMgr.trace.detach();

The inject_elf_config_t struct defines the behavior and parameters for the injection process. Use this struct to control how the injector targets processes, handles memory, and manages lifecycle callbacks.

Key Configuration Fields

The following flags are available for the AndKittyInjector command-line tool:

Usage: AndKittyInjector [--help] [--version] (--pid <id> | --package <name>) --libs <paths>...
                         [--launch | --watch] [--bp-ld | --bp-sym <binary> <symbol>]
                         [--delay <micros>] [--timeout <ms>] [--memfd] [--free] [--hide]

The KittyInjector class is the primary interface for managing library injection. To use it, you must first initialize it with a KittyMemoryMgr instance and an inject_elf_config_t configuration object.

Workflow

1. Initialize: Call init(kmgr, cfg) to set up the memory manager and injection parameters.
2. Inject: Call inject(elfPath) providing the path to the .so file you wish to inject. This returns an inject_elf_info_t object containing metadata about the injected library.

Important Methods

• bool init(KittyMemoryMgr *kmgr, const inject_elf_config_t &cfg): Initializes the injector. Returns true on success.
• inject_elf_info_t inject(const std::string &elfPath): Performs the injection of the specified ELF file into the target process.
• KittyMemoryMgr *KMgr(): Returns the pointer to the internal memory manager.

// Example initialization and injection
KittyMemoryMgr kmgr;
inject_elf_config_t cfg;
cfg.package = "com.example.targetapp";
cfg.watch = true;
cfg.hide = true;

KittyInjector injector;
if (injector.init(&kmgr, cfg)) {
    inject_elf_info_t info = injector.inject("/data/local/tmp/libinjected.so");
    if (info.is_valid()) {
        // Injection successful
    }
}