Katana: An ELF/DWARF Manipulation Tool with Hotpatching Capabilities

The Katana shell syntax is very simple. There are no control flow structures, only commands and variables. A line is terminated by a semicolon (;) or a newline character. Each line may be either blank, contain exactly one COMMAND, or contain an ASSIGNMENT.

A COMMAND is of the form COMMAND_IDENTIFIER PARAM PARAM PARAM …., where tokens are seperated by spaces and the number of PARAMs depends on the command.

An ASSIGNMENT is currently of the form VARIABLE=COMMAND although in the future it may be possible to write other sorts of assignments.

A VARIABLE reference consists of a dollar-sign ($) followed by a letter or underscore followed by any number of letters, underscores, or digits.

A COMMAND_IDENTIFIER is one or more words which identify a COMMAND. In many cases a command is identified by only one word, but sometimes similar commands are grouped by sharing the first word in their identifier.

A PARAM is a VARIABLE reference, STRING, or NUMBER

A STRING is any literal beginning and ending with the character ".

A NUMBER is a decimal, hex, or float literal.

• Data Types
  The following types of variables exist
  • string
  • elf
  • elf section
  • raw data
  • array

• load
  Usage: load FILENAME
  Params: FILENAME must a string literal or variable that can be interpreted as a string.
  Function: Loads the data in the given file as an ELF object if possible. If not, loads it as raw data.
• save
  Usage: save VAR FILENAME
  Params: VAR must be a variable that can be interpreted as an ELF object or that can be interpreted as raw data. FILENAME must be a literal or variable that can be interpreted as a string.
  Function: Saves VAR to FILENAME.
• dwarfscript
  
  • dwarfscript emit
    Usage: dwarfscript emit [SECTION] ELF OUTFILE
    Params: SECTION must be the name (string) of the section to write as Dwarfscript. If not specified it defaults to ".eh_frame". ELF must be an ELF object. OUTFILE must be a string with the name of a file to write the resulting Dwarfscript to.
    Function: Writes the Dwarfscript representation of the given SECTION from the given ELF to OUTFILE.
  • dwarfscript compile
    Usage: dwarfscript compile INFILE
    Params: INFILE must be a string containing the name of a file.
    Function: Interprets the contents of the file named by INFILE as Dwarfscript and compiles the Dwarfscript into beinary form. Returns an array with 3 items 0: raw data for .eh_frame 1: raw data for .eh_framehdr 2: raw data for .gcc_excepttable.
• replace
  
  • replace section
    Usage: replace section ELF SECTION_NAME NEW_SECTION Params: ELF must be an ELF object. SECTION_NAME must be a string. NEW_SECTION must be either an ELF section or raw data. Function: Replaces the section with the name SECTION_NAME in the oject ELF with the data from NEW_SECTION. Section headers are replaced if NEW_SECTION is able to provide them, but not if it is only raw data.
  • replace raw
    Usage: replace raw ELF OFFSET NEW_DATA Params: ELF must be an ELF object. ADDRESS must be an integer. NEW_DATA must be raw data. Function: Replaces the raw data at OFFSET in the ELF object with NEW_DATA. OFFSET must refer to a location in an existing section.
• info
  
  • info eh
    Usage: info eh ELF [OUTFILE] Params: ELF must be an ELF object. OUTFILE, if present, must be the name of a writable file (which may or may not exist yet). Function: Prints out information about the exception-handling structures in ELF. If OUTFILE is present, this information is written to it.
• hash
  
  • hash elf
    Usage: hash elf STR Params: STR must be a string. Function: Prints the result of running elf_hash (from libelf) on the string.
• patch
  
  • gen
    Usage: patch gen OLD_OBJECTS_DIR NEW_OBJECTS_DIR EXECUTABLE Params: All three params are strings. The first two are the old and new object file directories respectively. The last is the name of the executable that can be found in both directories. Function: Generates (and returns) a patch object ELF.
  • apply
    Usage: patch apply PO PID Params: The PO parameter should be an ELF patch object. PID should be the (integer) pid of the process that PO is to be applied to. Function: Applies the patch object PO to the running process described by PID.
• ! (shell command)
  The rest of the line following by ! is executed in a shell.

Command history is saved using libreadline in $HOME/.katana_history.

Katana aims to be much less invasive than other hot-patching system and require minimal work to be used with any project. It does, however, have some requirements.

Katana does not look at the source code, therefore unlike several other hotpatching systems, it does not require any annotation in the source code. There are, however, some best practices to follow.

• Avoid the use of void* at least for global variables (since Katana does not currently patch local variables, preferring to wait until any functions using changed variables are no longer on the stack). Since it is typeless and opaque, it is very hard to analyze and patch.
• Avoid unnamed types. i.e., instead of typedef struct {...} Foo; use typedef struct Foo_ {...} Foo;.
• Avoid accessing structure members by offsets instead of by the member names. As long as you keep all the code where you do this up to date, it should not be a problem, but katana cannot detect when you do this.

Required CFLAGS:

• -g

Recommended CFLAGS:

• -ffunction-sections
• -fdata-sections

Recommended LDFLAGS:

• –emit-relocs

Let the location of your project be /project. You must have two versions of your software available: the version identical to the running software which must be hotpatched, call it v0, and the version to which you wish to hotpatch the running software, call it v1. Let foo be the name of your program. Then /project/v0/foo must exist and /project/v0 must also contain (possibly in subdirectories) all of the object files which contributed to /project/v0/foo. The source code itself is immaterial, as Katana does not parse it. Similarly, /project/v1/foo must exist and /project/v1 contain all of the object files contributing to /project/v1/foo. Katana is then invoked as

katana [OPTIONS] -g [-o OUTPUT_FILE] /project/v0 /project/v1 foo

or more formally

katana [OPTIONS] -g [-o OUTUT_FILE] OLD_OBJECTS_DIR NEW_OBJECTS_DIR EXECUTABLE_NAME

If -o OUTPUT_FILE is not specified, the output file will be OLD_OBJECTS_DIR/EXECUTABLE_NAME.po

The process to be patched is running with a pid of PID. It can be patched from its current version to a more recent version by the Patch Object (PO) file PATCH. Katana is then invoked as

katana [OPTIONS] -p [-s] PATCH PID

If all goes well, the patcher will run, print out some status messages, and leave your program in better state than it found it. The optional -s flag tells Katana to stop the target program after patching it and detaching from it. This is mostly of use for debugging Katana.

One of the goals of Katana and its Patch Object (PO) format is to increase the transparency of patches: a user about to apply a patch should know what it will do. This goal is not yet fully realized, but it is possible to view some information about a patch with

katana [OPTIONS] -l PATCH

The following options may be passed to katana regardless of whether one is generating, applying, or viewing a patch:

• -c CONFIG where CONFIG is the name of a configuration file to load

Katana loads configuration files as follows. Configuration files loaded later in the sequence may overwrite settings from files earlier in the sequence.

• etc/katana + ~.katana
• ~/.config/katana
• ./katana
• any file specified with -c

Configuration files are written in JSON. The JSON requirement that strings be quoted is relaxed (i.e. anything is assumed to be a string unless it can be interpreted otherwise). The following properties are recognized:

• maxWaitForPatching <INTEGER> This value specifies the maximum number of seconds to wait for the target to enter a safe state.
• flags <OBJECT> The value of flags should be an object which may contain the following properties, all of which should be bool-valued:
  • checkPtraceWrites Whenever something is written into the target memory, read the value back out and verify that it was written correctly. This has a performance penalty, but does provide some more robust error checking, although it should not be necessary.

the katana manpage (although the information in this document is considerably more extensive than in the manpage)