--- name: "hexec" section: "1" platform: "linux" package: "hexec" version: "0.2.1-4+b1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/hexec" --- # hexec(1) a process execution hooking tool ## NAME hexec - a process execution hooking tool ## SYNOPSIS hexec \ \[expr\] \[cmd\] \[args...\] ## DESCRIPTION hexec is a tool to hook into process exececution calls (exec family of syscalls). You can define an expression that is executed against any hooked exec call. This expression may also contain a replacement exec call. ## OPTIONS SUMMARY Here is a summary of the options to hexec. ``` --help | -h Print a options/expr summary page --version | -v Print hexec version --log-out | -lo set output file for error and -print output ``` ## OPTIONS - **-h** Print a options/expr summary page - **--help** Print a options/expr summary page - **-lo** Set the output file for error and -print output. This can be required if writing to stderr could cause malfunction because some processes read from stderr and expect a well defined output. - ## EXPRESSIONS The expression is executed against all process execution calls. If the expression returns true, the original call is skipped. - **\ -and \** - **\ -a \** - **\ \** Returns true if both expressions return true. If the left returns false, the right expression is never executed. - **\ -or \** - **\ -o \** Returns true if one of both expressions returns true. If the left returns true, the right expression is never executed. - **-path \** Returns true if the path of the executable matches \. \ is a bash compatible wild card pattern. - **-ipath \** Same as -path, but case insensitive. - **-name \** Returns true if the base name of the executable matches \. \ is a bash compatible wild card pattern. - **-iname \** Same as -name, but case insensitive. - **-contains \** Returns true if the path of the executable containes the string \. - **-icontains \** Same as -contains, but case insensitive. - **-print** Print all arguments to the called process. Returns always true. - **-exec \ \[args...\] ;** Executes \ with \[args...\] as arguments. This expression must be terminated with a semicolon. You can use argument placeholders in \ and \[args...\] (see below). This expression always returns true.\ \ **NOTE**: Please be aware that you may need to escape or quote the terminating semicolon to not confuse your shell. - **-sh \** Interprets \ as a shell script by invoking /bin/sh with the arguments **-c '\'**. You can use argument placeholders inside \. Please note that -sh only expects a single argument and not a variable list of arguments (as -exec does). Using -sh is the same as using **-exec sh -c \**. ## PLACEHOLDERS FOR -exec EXPRESSION Every -exec expression can use placeholders in the argument list to obtain information from the original exec call. Each placeholder starts with { and ends with }. Use \\{ if you want to use a { in your argument list. The placeholders are replaced when the -exec expression is evaluated. Placeholder types: - **{n}** Will be replaced with the number of arguments in the original call. - **{\}** Will be replaced with the original argument at index \. Example: {1} would give the first argument. You can prepend \ with placeholder flags. - **{}** Will be replaced with all arguments from the original call. Each argument is seperated with a space. You can use placeholder flags. **NOTE**: The executable name is also considered as argument. This means that a call like "echo test" will result in two arguments, "echo" and "test". ## PLACEHOLDER FLAGS - **s** Every argument is inserted as single argument instead of concatenating all arguments.\ Consider the arguments 'a', 'b' and 'c'. Without **s**, **-exec {} \\;** would result in **-exec 'a b c' \\;**, which in many cases is not what you want. **-exec {s} \\;** howewer would result in **-exec 'a' 'b' 'c' \\;**. - **q** Quote every single argument. - **e** Escape all non alpha-numeric characters. This flag is very useful when using a "sh -c \<...\>" in the -exec expression. Examples - **-exec echo {} \\;** with the call **'a' 'b' 'c'** results in: 'echo' 'a b c' - **-exec echo {q} \\;** with the call **'a' 'b' 'c'** results in: 'echo' 'a' 'b' 'c' - **-exec sh -c 'echo {}; {}' \\;** with the call **'sh' '-c' 'gcc d.c \>\> log.txt'** results in: 'sh' '-c' 'echo sh -c gcc d.c \>\> log.txt; sh -c gcc d.c \>\> log.txt' \ Please note that this will not do what you may expect, as the \>\> is handled wrong in this case. - **-exec sh -c 'echo {e}; {}' \\;** with the call **'sh' '-c' 'gcc d.c \>\> log.txt'** results in: 'sh' '-c' 'echo sh \\-c gcc\\ d\\.c\\ \\\>\\\>\\ log\\.txt; sh -c gcc d.c \>\> log.txt' \ - ## CHANGES TO PROCESSES hexec will add some environment variables to the hooked processes. These are (may not be complete): - **LD\_PRELOAD** hexec adds libhexec-hook.so to the list of preloaded libraries. - **HEXEC\_EXPR\_SHM** Contains the name of the internal shared memory object. - **HEXEC\_LOG\_FD** Contains the file descriptor for error and -print output. Please do never modify these environment variables. Also take care when you use these variables, because the name and content of the variables may change in the future. ## EXAMPLES - **hexec -name 'gcc' -exec ccache {s} \\; make** Calls make, which will then call gcc several times. The executable name of each hooked process execution is tested against the file pattern "gcc" and "ccache {s}" is called each time a match is found. '{s}' will be replaced with the original (the hooked) call. In this example, a call to "gcc -o test.o test.c" would be replaced with "ccache gcc -o test.o test.c" ## HOW IT WORKS TODO ## BUGS I'm sure there are alot...it's still beta :) ## AUTHOR hexec was written by Alexander Block http://blocksoftware.net/ If you wish to report a problem or make a suggestion then please email ablock@blocksoftware.net hexec is released under the GNU General Public License version 2 or later. Please see the file COPYING for license details.