libextractor

fuzz_ec.h (16251B)

---

 /*
      This file is part of libextractor.
      Copyright (C) 2026 Christian Grothoff
 
      libextractor is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published
      by the Free Software Foundation; either version 3, or (at your
      option) any later version.
 
      libextractor is distributed in the hope that it will be useful, but
      WITHOUT ANY WARRANTY; without even the implied warranty of
      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
      General Public License for more details.
 
      You should have received a copy of the GNU General Public License
      along with libextractor; see the file COPYING.  If not, write to the
      Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
      Boston, MA 02110-1301, USA.
  */
 /**
  * @file fuzz/fuzz_ec.h
  * @brief contract-exact model of `struct EXTRACTOR_ExtractContext`
  * @author Christian Grothoff
  *
  * This is what makes the plugin harnesses find things that running
  * `extract` over a mutated file does not.  Two properties matter:
  *
  * 1. **The read window is exact.**  `plugin_env_read()` in
  *    extractor_plugin_main.c hands the plugin a pointer *into the shared
  *    memory window* and returns how many bytes are valid there -- which
  *    is at most `shm_map_size` (16 KiB by default), and at most what is
  *    left of the file.  A plugin that asks for 100 KiB and gets 16 KiB
  *    but then dereferences all 100 KiB reads memory it was never given.
  *    In production that memory is a live mmap, so nothing crashes and
  *    the bug is invisible; here every window is a fresh `malloc()` of
  *    *exactly* the returned byte count, so AddressSanitizer's redzone
  *    turns the same access into a hard error.
  *
  *    The window size is fuzzer-controlled, because "read() returned less
  *    than I asked for" is the single most productive precondition in
  *    this library and a 16 KiB default hides it for every file smaller
  *    than that.
  *
  * 2. **The window slides.**  The pointer a plugin got from `read()` stays
  *    valid only for as long as the shared memory window it points into
  *    still covers that part of the file.  A `read()` or `seek()` that
  *    needs data outside the window makes the core refill it, and the
  *    plugin's old pointer then addresses *different file bytes* than the
  *    plugin believes it holds.  The model tracks the same window as
  *    `plugin_env_read()`/`plugin_env_seek()` do -- so a `seek(0,
  *    SEEK_CUR)`, which never leaves the window, does not invalidate
  *    anything, exactly as in production -- and frees every slice handed
  *    out from a window when that window slides, so ASAN reports a
  *    retained pointer as a use-after-free.
  *
  *    Set `LE_FUZZ_STRICT_WINDOW=1` to invalidate on *every* call instead.
  *    That models the in-process implementation, whose single `ctx->buf`
  *    is overwritten by each read; it finds more, at the price of also
  *    flagging plugins that are correct under the default out-of-process
  *    policy.
  *
  * On top of that the metadata processor is an oracle.  The plugin-side
  * `transmit_reply()` writes `data_len` bytes from `data` to a pipe and
  * calls `strlen()` on the mime type, so this harness touches exactly the
  * same bytes -- an over-long `data_len` is a real out-of-bounds read in
  * production, not an artefact of the harness.
  */
 #ifndef LE_FUZZ_EC_H
 #define LE_FUZZ_EC_H 1
 
 #include "platform.h"
 #include "extractor.h"
 #include "fuzz_common.h"
 
 /**
  * Size of the shared memory window the core actually uses; must be kept
  * in sync with #DEFAULT_SHM_SIZE in src/main/extractor.c.
  */
 #define LE_FUZZ_DEFAULT_SHM (16 * 1024)
 
 /**
  * Upper bound the plugin side enforces on a single meta data item; see
  * #MAX_META_DATA in src/main/extractor_ipc.h.
  */
 #define LE_FUZZ_MAX_META_DATA (32 * 1024)
 
 /**
  * Number of configuration bytes that precede the file image in every
  * plugin-harness input.  An all-zero prefix means "no fault injection,
  * real 16 KiB window", i.e. exactly what production does, so a corpus
  * entry is just four zero bytes followed by the file.
  */
 #define LE_FUZZ_EC_PREFIX 4
 
 /**
  * Candidate read-window sizes.  Index 0 is the production value; the
  * rest deliberately include sizes that force a short read on almost
  * every call, and sizes just below/above a power of two.
  */
 static const size_t le_fuzz_windows[] = {
   LE_FUZZ_DEFAULT_SHM, 1, 2, 3, 5, 7, 15, 16, 31, 64, 127, 255, 256,
   511, 1024, 4095, 8192, 16383, 16385, 32768, 65536
 };
 
 /**
  * State behind the #EXTRACTOR_ExtractContext handed to the plugin.
  */
 struct fuzz_ec_state
 {
   /**
    * The file image.  Owned by the caller.
    */
   const uint8_t *img;
 
   /**
    * Number of bytes in #img.
    */
   size_t img_len;
 
   /**
    * Current read position, in [0, #img_len].
    */
   uint64_t pos;
 
   /**
    * Size of the shared memory window, i.e. the largest number of bytes
    * a single read() may return.  Models `shm_map_size`.
    */
   size_t window;
 
   /**
    * File offset the current window starts at.  Models `shm_off`.
    */
   uint64_t win_off;
 
   /**
    * Number of bytes of the file the current window holds.  Models
    * `shm_ready_bytes`.
    */
   size_t win_len;
 
   /**
    * Non-zero once a window has been established at all.
    */
   int win_valid;
 
   /**
    * Slices handed out from the current window.  Each is an exact-size
    * allocation, so ASAN's redzone starts right after the last byte the
    * plugin was promised; all of them are freed when the window slides.
    */
   uint8_t **slices;
 
   /**
    * Number of entries in #slices.
    */
   size_t slices_len;
 
   /**
    * Capacity of #slices.  Grown geometrically: a plugin can issue
    * millions of one-byte reads inside a single window, and a
    * grow-by-one realloc() would make the *harness* quadratic and turn
    * every such input into a bogus "slow unit".
    */
   size_t slices_cap;
 
   /**
    * Number of read() calls so far.
    */
   unsigned int reads;
 
   /**
    * Number of seek() calls so far.
    */
   unsigned int seeks;
 
   /**
    * Number of proc() calls so far.
    */
   unsigned int procs;
 
   /**
    * Fault-injection bitmask, see #LE_FUZZ_FAULT_*.
    */
   unsigned int faults;
 
   /**
    * Call index at which an injected fault fires.
    */
   unsigned int fault_at;
 
   /**
    * Set once get_size() has returned UINT64_MAX; the failure is
    * transient in production (one failed IPC round), so it only fires
    * once here too.
    */
   int size_failed;
 };
 
 #define LE_FUZZ_FAULT_SIZE     0x01
 #define LE_FUZZ_FAULT_READ     0x02
 #define LE_FUZZ_FAULT_SEEK     0x04
 #define LE_FUZZ_FAULT_STOP     0x08
 #define LE_FUZZ_RUN_TWICE      0x10
 #define LE_FUZZ_ODD_ALIGN      0x20
 
 /**
  * Cached value of $LE_FUZZ_STRICT_WINDOW.
  */
 static int le_fuzz_strict_window = -1;
 
 /**
  * Cached value of $LE_FUZZ_STRICT_PROC.
  */
 static int le_fuzz_strict_proc = -1;
 
 
 /**
  * Free every slice handed out from the window that is about to be
  * replaced.  In production those pointers keep addressing live shared
  * memory, but the bytes behind them are no longer the ones the plugin
  * read, so any use of them is a defect; freeing turns that into an ASAN
  * report.
  *
  * @param st harness state
  */
 static void
 le_fuzz_drop_slices (struct fuzz_ec_state *st)
 {
   size_t i;
 
   for (i = 0; i < st->slices_len; i++)
     free (st->slices[i]);
   free (st->slices);
   st->slices = NULL;
   st->slices_len = 0;
   st->slices_cap = 0;
 }
 
 
 /**
  * Slide the window so that it starts at @a off.
  *
  * @param st harness state
  * @param off new window start
  */
 static void
 le_fuzz_slide (struct fuzz_ec_state *st,
                uint64_t off)
 {
   le_fuzz_drop_slices (st);
   st->win_off = off;
   st->win_len = (size_t) (st->img_len - off);
   if (st->win_len > st->window)
     st->win_len = st->window;
   st->win_valid = 1;
 }
 
 
 /**
  * @return non-zero if @a off is covered by the current window
  */
 static int
 le_fuzz_in_window (const struct fuzz_ec_state *st,
                    uint64_t off)
 {
   if (! st->win_valid)
     return 0;
   if (le_fuzz_strict_window)
     return 0;
   return ( (st->win_off <= off) &&
            (off < st->win_off + st->win_len) );
 }
 
 
 /**
  * Hand out an exact-size copy of @a n bytes starting at file offset
  * @a off.  The allocation is remembered so that it can be freed when the
  * window slides.
  *
  * @param st harness state
  * @param off file offset
  * @param n number of bytes
  * @return pointer the plugin may read @a n bytes from
  */
 static uint8_t *
 le_fuzz_slice (struct fuzz_ec_state *st,
                uint64_t off,
                size_t n)
 {
   uint8_t *p = (uint8_t *) malloc ((0 == n) ? 1 : n);
 
   if (NULL == p)
     abort ();
   if (0 != n)
     memcpy (p, st->img + off, n);
   if (st->slices_len == st->slices_cap)
   {
     size_t cap = (0 == st->slices_cap) ? 64 : st->slices_cap * 2;
     uint8_t **v = (uint8_t **) realloc (st->slices,
                                         sizeof (uint8_t *) * cap);
 
     if (NULL == v)
       abort ();
     st->slices = v;
     st->slices_cap = cap;
   }
   st->slices[st->slices_len++] = p;
   return p;
 }
 
 
 /**
  * Model of `plugin_env_read()` from src/main/extractor_plugin_main.c.
  *
  * @param cls a `struct fuzz_ec_state`
  * @param[out] data set to the start of the window
  * @param count number of bytes requested
  * @return number of bytes available at @a data, -1 on error
  */
 static ssize_t
 le_fuzz_read (void *cls,
               void **data,
               size_t count)
 {
   struct fuzz_ec_state *st = cls;
 
   *data = NULL;
   st->reads++;
   if ( (0 != (st->faults & LE_FUZZ_FAULT_READ)) &&
        (st->reads == st->fault_at) )
     return -1;                  /* models a failed IPC round */
   /* clamp to what is left of the file, exactly as plugin_env_read()
      does (including its overflow guard) */
   if ( (count + st->pos > st->img_len) ||
        (count + st->pos < st->pos) )
     count = (size_t) (st->img_len - st->pos);
   /* refill the window if the read starts outside it, as
      plugin_env_read() does via its plugin_env_seek() call */
   if (! le_fuzz_in_window (st, st->pos))
     le_fuzz_slide (st, st->pos);
   /* clamp to what the window holds */
   if (st->pos + count > st->win_off + st->win_len)
     count = (size_t) (st->win_off + st->win_len - st->pos);
   *data = le_fuzz_slice (st, st->pos, count);
   st->pos += count;
   return (ssize_t) count;
 }
 
 
 /**
  * Model of `plugin_env_seek()` from src/main/extractor_plugin_main.c.
  *
  * @param cls a `struct fuzz_ec_state`
  * @param pos offset to seek to
  * @param whence SEEK_SET, SEEK_CUR or SEEK_END
  * @return new absolute position, -1 on error
  */
 static int64_t
 le_fuzz_seek (void *cls,
               int64_t pos,
               int whence)
 {
   struct fuzz_ec_state *st = cls;
   uint64_t npos;
 
   st->seeks++;
   if ( (0 != (st->faults & LE_FUZZ_FAULT_SEEK)) &&
        (st->seeks == st->fault_at) )
     return -1;
   switch (whence)
   {
   case SEEK_CUR:
     if ( (pos < 0) &&
          (st->pos < (uint64_t) (-pos)) )
       return -1;
     pos = (int64_t) (st->pos + pos);
     break;
   case SEEK_END:
     if (pos > 0)
       return -1;
     pos = (int64_t) (st->img_len + pos);
     break;
   case SEEK_SET:
     break;
   default:
     return -1;
   }
   if ( (pos < 0) ||
        ((uint64_t) pos > st->img_len) )
     return -1;
   npos = (uint64_t) pos;
   /* plugin_env_seek() returns without touching the window whenever the
      target is already inside it; otherwise the core refills it and every
      pointer into the old window goes stale */
   if (! le_fuzz_in_window (st, npos))
     le_fuzz_slide (st, npos);
   st->pos = npos;
   return (int64_t) npos;
 }
 
 
 /**
  * Model of `plugin_env_get_size()`.
  *
  * @param cls a `struct fuzz_ec_state`
  * @return file size, UINT64_MAX when the injected IPC failure fires
  */
 static uint64_t
 le_fuzz_get_size (void *cls)
 {
   struct fuzz_ec_state *st = cls;
 
   if ( (0 != (st->faults & LE_FUZZ_FAULT_SIZE)) &&
        (! st->size_failed) )
   {
     st->size_failed = 1;
     return UINT64_MAX;          /* documented "IPC failure" return */
   }
   return (uint64_t) st->img_len;
 }
 
 
 /**
  * Metadata processor used as an oracle.  Touches precisely the bytes
  * that `transmit_reply()` in extractor_plugin_main.c touches.
  *
  * @param cls a `struct fuzz_ec_state`
  * @param plugin_name name of the reporting plugin
  * @param type metadata type
  * @param format metadata format
  * @param data_mime_type mime type of @a data, may be NULL
  * @param data the metadata
  * @param data_len number of bytes in @a data
  * @return 0 to continue, 1 to abort
  */
 static int
 le_fuzz_proc (void *cls,
               const char *plugin_name,
               enum EXTRACTOR_MetaType type,
               enum EXTRACTOR_MetaFormat format,
               const char *data_mime_type,
               const char *data,
               size_t data_len)
 {
   struct fuzz_ec_state *st = cls;
   volatile unsigned int sink = 0;
   size_t i;
 
   st->procs++;
   if (NULL == plugin_name)
     fuzz_report_finding ("plugin reported a NULL plugin name");
   /* transmit_reply() does strlen() on both of these */
   sink += (unsigned int) strlen (plugin_name);
   if (NULL != data_mime_type)
     sink += (unsigned int) strlen (data_mime_type);
   if ( (NULL == data) &&
        (0 != data_len) )
     fuzz_report_finding ("plugin reported NULL data with a non-zero length");
   if (NULL != data)
   {
     /* transmit_reply() writes exactly data_len bytes starting at data;
        reading them here is what production does */
     for (i = 0; i < data_len; i++)
       sink += (unsigned char) data[i];
     if ( (le_fuzz_strict_proc) &&
          (0 != data_len) &&
          ( (EXTRACTOR_METAFORMAT_UTF8 == format) ||
            (EXTRACTOR_METAFORMAT_C_STRING == format) ) &&
          ('\0' != data[data_len - 1]) )
       fuzz_report_finding ("plugin reported a string metadata value that is "
                            "not 0-terminated");
   }
   (void) sink;
   (void) type;
   if ( (0 != (st->faults & LE_FUZZ_FAULT_STOP)) &&
        (st->procs > st->fault_at) )
     return 1;                   /* application asked us to stop */
   return 0;
 }
 
 
 /**
  * Read the harness-wide environment knobs once.
  */
 static void
 le_fuzz_ec_init_env (void)
 {
   if (-1 != le_fuzz_strict_window)
     return;
   le_fuzz_strict_window = (0 != fuzz_env_ulong ("LE_FUZZ_STRICT_WINDOW", 0));
   le_fuzz_strict_proc = (0 != fuzz_env_ulong ("LE_FUZZ_STRICT_PROC", 0));
 }
 
 
 /**
  * Set up @a ec and @a st from a fuzz input.  The first
  * #LE_FUZZ_EC_PREFIX bytes are configuration, the rest is the file
  * image.
  *
  * @param[out] ec context to fill in
  * @param[out] st state to fill in
  * @param data the fuzz input
  * @param size number of bytes in @a data
  * @return 0 if the input was too short to be usable
  */
 static int
 le_fuzz_ec_setup (struct EXTRACTOR_ExtractContext *ec,
                   struct fuzz_ec_state *st,
                   const uint8_t *data,
                   size_t size)
 {
   size_t off;
 
   le_fuzz_ec_init_env ();
   if (size < LE_FUZZ_EC_PREFIX)
     return 0;
   memset (st, 0, sizeof (*st));
   st->window = le_fuzz_windows[data[0]
                                % (sizeof (le_fuzz_windows)
                                   / sizeof (le_fuzz_windows[0]))];
   st->faults = data[1];
   st->fault_at = data[2];
   off = LE_FUZZ_EC_PREFIX;
   if ( (0 != (st->faults & LE_FUZZ_ODD_ALIGN)) &&
        (off < size) )
     off++;
   st->img = data + off;
   st->img_len = size - off;
   memset (ec, 0, sizeof (*ec));
   ec->cls = st;
   ec->config = NULL;
   ec->read = &le_fuzz_read;
   ec->seek = &le_fuzz_seek;
   ec->get_size = &le_fuzz_get_size;
   ec->proc = &le_fuzz_proc;
   return 1;
 }
 
 
 /**
  * Release everything @a st still owns.
  *
  * @param st state to clean up
  */
 static void
 le_fuzz_ec_cleanup (struct fuzz_ec_state *st)
 {
   le_fuzz_drop_slices (st);
   st->win_valid = 0;
   st->win_off = 0;
   st->win_len = 0;
 }
 
 
 /**
  * Rewind @a st so that the same context can be handed to the extract
  * method a second time.  Plugins must be stateless across files.
  *
  * @param st state to reset
  */
 static void
 le_fuzz_ec_rewind (struct fuzz_ec_state *st)
 {
   le_fuzz_ec_cleanup (st);
   st->pos = 0;
   st->reads = 0;
   st->seeks = 0;
   st->procs = 0;
   st->size_failed = 0;
 }
 
 
 #endif /* LE_FUZZ_EC_H */