Merge pull request #2106 from a-shvedov/stable

feature: Added (generate_libtoken_dict.sh) script for simplified work with `libtokencap`

utils/libtokencap/README.md

@@ -69,3 +69,21 @@ need to be changed for other OSes.
 
 Current supported OSes are: Linux, Darwin, FreeBSD (thanks to @devnexen)
 
+Also, the following example (generate_libtoken_dict.sh) shows how to use a script to capture tokens from the 
+files in the target output directory, 
+and then generate a dictionary file from those tokens.
+
+#### usage:
+```bash
+./generate_libtoken_dict.sh -p /path/to/libtokencap.so -b /path/to/target/program -o /path/to/target/output -t 5 -- [-program_args]
+```
+#### description opts:
+- ```-o``` : Path to target output directory ;
+- ```-b``` : Path to target program binary ;
+- ```-p``` : Path to LD_PRELOAD library ;
+- ```-t``` : Timeout in seconds ;
+- ```-- [-program_args]```: Any additional arguments required by the target binary can be specified after ```--```.
+ 
+#### output:
+A sorted and unique token dictionary file with the extension ``*.dict`` 
+is created in the same directory as the target output containing tokens captured during the execution of the target binary.

utils/libtokencap/generate_libtoken_dict.sh

@@ -0,0 +1,55 @@
+#help
+usage() {
+    echo "Usage: $0 -o <target_output> -b <target_bin> -p <LD_PRELOAD_PATH> [-t <timeout_sec>] -- [target_args]"
+    echo "Options:"
+    echo "  -o  Path to target output directory"
+    echo "  -b  Path to target program binary"
+    echo "  -p  Path to LD_PRELOAD library"
+    echo "  -t  Timeout in seconds"
+    exit 1
+}
+
+#parse cli options
+while getopts ":o:b:p:t:" opt; do
+    case $opt in
+        o) target_output="$OPTARG" ;;
+        b) target_bin="$OPTARG" ;;
+        p) LD_PRELOAD_PATH="$OPTARG" ;;
+        t) timeout_sec="$OPTARG" ;;
+        \?) echo "Invalid option: -$OPTARG" >&2; usage ;;
+        :) echo "Option -$OPTARG requires an argument." >&2; usage ;;
+    esac
+done
+
+#shift away the parsed opts
+shift $((OPTIND - 1))
+
+#check options
+if [ -z "$target_output" ] || [ -z "$target_bin" ] || [ -z "$LD_PRELOAD_PATH" ]; then
+    echo "Error: Missing mandatory opts" >&2
+    usage
+fi
+
+# initialize vars
+AFL_TOKEN_FILE="${PWD}/temp_output.txt"
+AFL_DICT_FILE="${PWD}/$(basename "$target_bin")_tokens.dict"
+
+#generate token-file
+{
+    touch "$AFL_TOKEN_FILE"
+    for i in $(find "$target_output" -type f -name "id*"); do
+        LD_PRELOAD="$LD_PRELOAD_PATH" \
+        timeout -s SIGKILL "$timeout_sec" \
+        "$target_bin" "$@" "$i"
+    done
+} >"$AFL_TOKEN_FILE"
+
+# sort & remove duplicates
+sort -u "$AFL_TOKEN_FILE" >"$AFL_DICT_FILE"
+
+# delete temp-file
+rm "$AFL_TOKEN_FILE"
+
+# print done-message
+echo "Token dictionary created: $AFL_DICT_FILE"
+echo "Script completed successfully"