API Documentation

API Documentation

• Header Files
• Debug Mode
• Ptrace Hooking

---

Header Files

BEURK provides multiple header files, sorted by utility.

Internal API (beurk.h)

This header files provides prototypes for all internal API public functions.

Corresponding functions are located in a /src/<function_name.c file.

Function Hooks (hooks.h)

This file contains hooked functions prototypes.

Corresponding function are located in a /src/hooks/<hooked_function>.c file.

Preprocessor Macros (config.h)

The config.h header file is dynamically generated by the builder.

It contains all macros corresponding to key/value pairs provided in the builder's given config file (beurk.conf).

It also contains one REAL_<hook>() macros, for each hooked function (this is done by parsing hooks.h at build time).

---

Debug Mode

The rootkit provides a debug mode, which can be enabled by defining the DEBUG_LEVEL macro at compile time.

If enabled, debug mode impacts the hooking library in some points:

• Core debug message are written to stderr.
• BEURK's uninstallation feature is enabled.
• Symbols are not stripped from evil hooking library.

Enabling debug mode

This macro enables debug mode at compile time.

Usage:

    #define DEBUG_LEVEL (1)

• if DEBUG_LEVEL == 1:

  enable basic debugging

  E.G: [BEURK_INFO]: init() constructor loaded

• if DEBUG_LEVEL == 2:

  enable debugging, providing informations about concerned file and line number.

  E.G: [BEURK_INFO<init.c:83>]: init() constructor loaded

Setting default debug output file

The DEBUG_FILE macro can be set in order to infer where debug messages will be written.

Usage:

    #define DEBUG_FILE "/tmp/beurk-rootkit.log"

• Default value: /dev/stderr

Changing debug output file at runtime

The destination file for debug messages can be overridden at runtime, through the BEURK_DEBUG_FILE environment variable.

Note that if the rootkit hasn't been compiled with DEBUG_LEVEL, this option has no effect.

Usage:

    BEURK_DEBUG_FILE="/dev/stdout" ls -la

Using the DEBUG() macro

Flavour (1st argument)

The debug macro take a flavour as first argument, which indicates what kind of debug message it provides. If D_INFO is provided as flavour, lines will start with '[BEURK_INFO', while the D_ERROR flag outputs lines starting with '[BEURK_ERROR'.

Variadic format printf

2nd and following arguments are designed to be used as for printf(3).

Usage:

    DEBUG(D_INFO, "this is an '%s' message", "info");
    DEBUG(D_ERROR, "this is an '%s' message", "error");

---

Ptrace Hooking

Enable hooking on ptrace(2) within the rootkit.

By default, ptrace hooking is enabled;

Disabling ptrace hooking

This macro disables ptrace hooking at compile time.

Usage:

    #define ENABLE_PTRACE (1)

• if ENABLE_PTRACE == 1:

  enable ptrace hooking (default value)

• if ENABLE_PTRACE == 0:

  disable ptrace hooking

Use cases

Disabling ptrace hooking is a must do while debugging the rootkit with gdb or similar tools.