From 8acf5563ee0808dd1721544413118c70307abb6c Mon Sep 17 00:00:00 2001 From: dergoegge Date: Wed, 21 Aug 2024 14:56:41 +0100 Subject: [PATCH] Document custom comparators in the readme --- README.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index b625e30..11becb4 100644 --- a/README.md +++ b/README.md @@ -136,11 +136,30 @@ Options: By default SemSan will check for equality when comparing the observed output values but that is configurable with the `--comparator` option. Currently, the only supported comparators are `not-equal`, `equal`, `less-than`, -`less-than-or-equal`, `greater-than` and `greater-than-or-equal`. +`less-than-or-equal`, `greater-than`, `greater-than-or-equal` and `custom`. Using comparators other than `equal` can be useful when the harnesses under test are allowed to behave differently to some extend. +Custom comparators allow the user to provide their own comparison function by +`LD_PRELOAD`ing a library. The custom comparator function should be defined as +a function called `semsan_custom_comparator` which should return `false` if the +output values indicate a solution. + +```C +bool semsan_custom_comparator(const uint8_t *o1, size_t o1_len, + const uint8_t *o2, size_t o2_len) { + // Custom comparator logic ... +} +``` + +Example usage: + +``` +LD_PRELOAD=$PWD/custom_comp.so semsan --comparator custom fuzz \ + --seeds --solutions +``` + ### Ensembling with other engines SemSan is not meant to be used in isolation as it is quite a primitive fuzzer