Chaos Cat - Wreaking havoc to your syscalls since 2022!

Chaos Cat brings destruction and suffering to your software. When Chaos Cat is loaded it will randomly make predefined syscalls fail. This tests your software for the the things you might have forgotten to check because operating systems usually Just Work™ and syscalls usually never fail.

Chaos Cat is a dynamic library to be loaded using LD_PRELOAD (Linux) or DYLD_INSERT_LIBRARIES (macOS) and to be configured with environment variable.

The testing is as easy as:

1. Configure your environment variables
2. Run your program with Chaos Cat enabled
3. ...
4. Profit!

Enabling Chaos Cat

Set environment variable CHAOSCAT_OPTS with list of syscalls to break delimeted by colon (:). For example:

$ export CHAOSCAT_OPTS="read:write"

Supported syscalls

The links to syscalls point to OpenBSD's manual pages. This is because of the high quality of the documentation OpenBSD provides. The syscalls are standard (e.g. conform to IEEE Std 1003.1-2008 (“POSIX.1”)) so they should function in any POSIX conforming systems.

How syscalls indicate error?

When a system call detects an error, it returns an integer value indicating failure (usually -1) and sets the variable errno accordingly. (This allows interpretation of the failure on receiving a -1 and to take action accordingly.) Successful calls never set errno; once set, it remains until another error occurs. It should only be examined after an error. Note that a number of system calls overload the meanings of these error numbers, and that the meanings must be interpreted according to the type and circumstances of the call.

Source: https://man.openbsd.org/intro.2#DIAGNOSTICS

Running in macOS

Set environment variables:

$ export DYLD_FORCE_FLAT_NAMESPACE=1
$ export CHAOSCAT_OPTS="read:write"

And run the program to be tested:

$ DYLD_INSERT_LIBRARIES="/path/to/libchaoscat.dylib" my-awesome-binary

Running in Linux

Set environment variables:

$ export CHAOSCAT_OPTS="read:write"

And run the program to be tested:

$ LD_PRELOAD="/path/to/libchaoscat.dylib" my-awesome-binary