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:
- Configure your environment variables
- Run your program with Chaos Cat enabled
- ...
- Profit!
Set environment variable CHAOSCAT_OPTS
with list of syscalls to break
delimeted by colon (:
). For example:
$ export CHAOSCAT_OPTS="read:write"
Syscall | Return value | errno |
---|---|---|
open | -1 | EINTR |
read | -1 | EINTR |
write | -1 | EINTR |
socket | -1 | ENOBUFS |
connect | -1 | EINTR |
sendto | -1 | ENOBUFS |
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.
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
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
Set environment variables:
$ export CHAOSCAT_OPTS="read:write"
And run the program to be tested:
$ LD_PRELOAD="/path/to/libchaoscat.dylib" my-awesome-binary