SYNOPSIS

Enhancer is an LD_PRELOAD library that contains a number of configurable 'enhancements' that can be applied to add features to programs that lack them. It works by intercepting calls to common functions in libc or libx11 and running it's own code when called. Enhancements include setting various socket options, redirecting file opens, adding logging when a function is called, sending messages when a function is called, changing x11 fonts, adding socks4 and socks4a proxy support, etc.

Enhancements are configured in /etc/enhancer.conf (or other config file specified using an environment variable) and then the program is run using 'LD_PRELOAD=<path to enhancer.so> <progname>'

LICENSE

Enhancer is released under the GPLv3 license.

AUTHOR

Enhancer is written by Colum Paget. All patches/bugreports/requests should be sent to colums.projects@gmail.com, or handled through the project's github page.

PROGRAMS THAT DON'T WORK WITH ENHANCER

Some programs will not work with enhancer. Enhancer relies on intercepting calls to shared libraries, so if a program is statically linked then enhancer will not be able to intercept function calls. Furthermore enhancer has been seen to cause issues for some complex programs, like the Pale Moon webbrowser, and also does not play well with emulators like wine. Finally, while enhancer likely does have some use for system monitoring or hardening, the user should be aware that there are methods of avoiding triggering enhancer functions, for instance by calling kernel syscalls directly rather than going through libc. Enhancer is primarily intended to add features or fix a few common types of bug, not really as a security tool, though it still has some value in that area.

For these reasons enhancer should not be rashly applied to all programs running on a system by adding it to /etc/ld.so.preload, as this may cause major system problems. A better solution is to use 'bash alias' functions like so:

alias mpg123='LD_PRELOAD=/usr/local/lib/enhancer.so mpg123'

The 'nodescend' action can be used to prevent a process from passing enhancer.so to its child processes in those situations where those child processes might be disrupted by having a preloaded library.

CONFIG FILE

The enhancer config file contains entries of the form:

program <program list>
{
<function name> <match values> <actions>
}

for example:

program mpg123,mplayer
{
open path=*.mp3,*.ogg setbasename "track=%1" xtermtitle "$(progname) $(track)" send "unix:/tmp/nowplay.sock|$(track)"
onexit xtermtitle idle
}

Enhancer looks for its config in the following places:

1. path specified by ENHANCER_CONFIG_FILE environment variable.
2. path specified by ENHANCER_CONFIG_DIR environment variable, $(ENHANCER_CONFIG_DIR)/<progname>.conf
3. path specified by ENHANCER_CONFIG_DIR environment variable, $(ENHANCER_CONFIG_DIR)/<progname>
4. ~/.config/enhancer/<progname>.conf
5. ~/.config/enhancer/<progname>
6. ~/.enhancer/<progname>.conf
7. ~/.enhancer/<progname>
8. ~/.enhancer.conf
9. /etc/enhancer.d/<progname>.conf
10. /etc/enhancer.conf

in the case of the paths containing progname the name of the currently running program is subsitututed in before the config file is looked for.

RULE SYNTAX

Each line in a config section consists of a function name (or name that identifies a group of functions), a set of match tests that apply to data passed to the function, and a list of actions to take. These things are processed in the order that they occur in the line.

Hence:

open path=/etc/passwd redirect /etc/fakeusers

Applies to the 'open' group of functions. This includes not just open, but open64, openat and fopen too. The match test 'path=/etc/passwd' specifies that this rule only applies when that path is opened. The action 'redirect' instructs that the file /etc/fakeusers should be opened instead of /etc/passwd.

Match tests include an operator which can be one of '=', '!=', '=='

STRING QUOTING

Enhancer recognizes two styles of quoting in its config file. Firstly via use of double-quotes, and secondly via use of backslash quoting.

	open path="/home/my directory/my file.txt" log "opened file %1"
	open path=/home/my\ directory/my\ file.txt log "opened file %1"

HOOKED FUNCTIONS

Enhancer only hooks a few useful libc functions. These are:

main       the 'main' function that's the entry point to the program. This is program start-up.
onexit     triggers on program exit
arg        not a function, triggers on every argument to the program
open       'open group' which includes open, open64, openat, fopen
close
uname
unlink     'unlink group' which includes unlink, unlintat
rename     'rename group' which includes rename, renameat and renameat2
time       applies to both time and gettime of day
settime
setuid
setgid
connect
bind
listen
accept
fork       applies to fork and vfork
exec       applies to all 'exec' family functions
system
sysexec    applies to both system and exec
gethostip  applies to 'gethostbyname' and 'getaddrinfo'
chown
chmod
chdir
chroot
time
settime
select     applies to both select and poll
fsync
fdatasync
dlopen
dlclose

X11 Hooked Functions

if X11 support is compiled in, the following functions can be hooked

XMapWindow 
XRaiseWindow
XLowerWindow
XSendEvent
XNextEvent
XLoadFont
XChangeProperty

MATCHES

You can specify 'match modifiers' for a function. The config line will only be used if a function call matches these modifiers. Available modifiers are:

path          perform match against first arg of the function. This is usually a file path, but for 'connect' and 'bind' it can be a URL
basename      peform a match against the basename (leading directory removed) of the first arg of the function
family        for 'connect', 'bind' and 'accept' this is the url type. It can be 'ip4', 'ip6', 'net', or 'unix'. 'net' matches both 'ip4' and 'ip6'
peer          for 'connect' and 'accept' this is the remote host ip, extracted from 'path' which will be url
port          for 'connect' and 'bind' this will be the port to bind or connect to
user          match against username current process is running as
group         match against primary groupname current process is running as
arg           match if any arg in the programs arguments matches

The 'arg' match is a special case. You can use it to match against command-line arguments of the program. e.g.

bind arg=-local localnet

ACTIONS

The following actions can be booked against a function, to be carried out when it is called.

deny            do not perform the function, return and error code indicating failure
pretend         do not perform the function, return and error code indicating success
allow           perform the function as expected
die             cause the program to exit
die-on-fail     cause the program to exit if function call fails
abort           raise abort signal, causing program to exit
collect         collect child processes (i.e. calls 'waitpid(-1)')
deny-symlinks   for file functions: do not operate on symlinks
setvar          set a variable. Takes an argument of the form 'name=value'
setenv          set environment variable. Takes an argument of the form 'name=value'
setbasename     set a variable with the basename of the value part of a 'name=value' argument. So 'setbasename file=/home/user1/myfile.txt' would set a variable called 'file' to 'myfile.txt'
log             log to default logfile. Takes string argument.
syslog          log to syslog. Takes string argument.
syslogcrit      log a critical event to syslog. Takes string argument.
echo            write to standard out. Takes string argument.
debug           write to standard error. Takes string argument.
send            send to a url. Takes string argument in the form 'url|message'.
xtermtitle      set title of xterm compatible terminal. Takes a string argument.
exec            execute a program/command. Takes string argument.
sleep           sleep for seconds, takes numeric argument
usleep          sleep for nanoseconds, takes numeric argument
mlockall        lock process memory pages, and all future pages, so they are never swapped out
mlockcurr       lock process current memory pages so they are never swapped out
redirect        redirect main argument to a different value. Usually used to change file paths.
fallback        list of fallback arguments. Used with X11 fonts to specify fallbacks if font doesn't load.
searchpath      only for 'open'. List of directories to search for a file.
fdcache         only for 'open'. Use cached file descriptor for this file if one is already open
cmod            only for 'open'. Set file permissions for file create, takes octal 'permissions' argument
create          only for 'open'. Create file if it doesn't exist.
lock            only for 'open'. Lock file.
nosync          only for 'open'. Don't fsync this file.
fadv_seq        only for 'open'. Specify this file will be read sequentially (increases readahead)
fadv_rand       only for 'open'. Specify this file will be random access (no readahead)
fadv_nocache    only for 'close'. Don't cache this file (useful for logfiles etc)
qlen            only for 'listen'. Alter queue len, takes numeric argument.
sanitise        only for 'exec' and 'system'. Remove shell metacharacters from command string.
die-on-taint    only for 'exec' and 'system'. Exit program if shell metacharacters found in command string. 
deny-on-taint   only for 'exec' and 'system'. Refuse to launch program if shell metacharacters