include/iprt/fuzz.h

   1 /** @file
   2  * IPRT - Fuzzing framework
   3  */
   4
   5 /*
   6  * Copyright (C) 2018-2024 Oracle and/or its affiliates.
   7  *
   8  * This file is part of VirtualBox base platform packages, as
   9  * available from https://www.virtualbox.org.
  10  *
  11  * This program is free software; you can redistribute it and/or
  12  * modify it under the terms of the GNU General Public License
  13  * as published by the Free Software Foundation, in version 3 of the
  14  * License.
  15  *
  16  * This program is distributed in the hope that it will be useful, but
  17  * WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19  * General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU General Public License
  22  * along with this program; if not, see <https://www.gnu.org/licenses>.
  23  *
  24  * The contents of this file may alternatively be used under the terms
  25  * of the Common Development and Distribution License Version 1.0
  26  * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
  27  * in the VirtualBox distribution, in which case the provisions of the
  28  * CDDL are applicable instead of those of the GPL.
  29  *
  30  * You may elect to license modified versions of this file under the
  31  * terms and conditions of either the GPL or the CDDL or both.
  32  *
  33  * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
  34  */
  35
  36 #ifndef IPRT_INCLUDED_fuzz_h
  37 #define IPRT_INCLUDED_fuzz_h
  38 #ifndef RT_WITHOUT_PRAGMA_ONCE
  39 # pragma once
  40 #endif
  41
  42 #include <iprt/cdefs.h>
  43 #include <iprt/process.h>
  44 #include <iprt/types.h>
  45
  46 RT_C_DECLS_BEGIN
  47
  48 /** @defgroup grp_rt_fuzz RTFuzz - Data fuzzing framework
  49  * @ingroup grp_rt
  50  * @sa grp_rt_test
  51  * @{
  52  */
  53
  54 /** A fuzzer context handle. */
  55 typedef struct RTFUZZCTXINT      *RTFUZZCTX;
  56 /** Pointer to a fuzzer context handle. */
  57 typedef RTFUZZCTX                *PRTFUZZCTX;
  58 /** NIL fuzzer context handle. */
  59 #define NIL_RTFUZZCTX            ((RTFUZZCTX)~(uintptr_t)0)
  60 /** A fuzzer input handle. */
  61 typedef struct RTFUZZINPUTINT    *RTFUZZINPUT;
  62 /** Pointer to a fuzzer input handle. */
  63 typedef RTFUZZINPUT              *PRTFUZZINPUT;
  64 /** NIL fuzzer input handle. */
  65 #define NIL_RTFUZZINPUT          ((RTFUZZINPUT)~(uintptr_t)0)
  66
  67
  68 /** A fuzzer config handle. */
  69 typedef struct RTFUZZCFGINT      *RTFUZZCFG;
  70 /** Pointer to a fuzzer config handle. */
  71 typedef RTFUZZCFG                *PRTFUZZCFG;
  72 /** NIL fuzzer config handle. */
  73 #define NIL_RTFUZZCFG            ((RTFUZZCFG)~(uintptr_t)0)
  74
  75
  76 /** A fuzzer target recorder handler. */
  77 typedef struct RTFUZZTGTRECINT   *RTFUZZTGTREC;
  78 /** Pointer to a fuzzer target recorder handle. */
  79 typedef RTFUZZTGTREC             *PRTFUZZTGTREC;
  80 /** NIL fuzzer target recorder handle. */
  81 #define NIL_RTFUZZTGTREC         ((RTFUZZTGTREC)~(uintptr_t)0)
  82 /** A fuzzed target state handle. */
  83 typedef struct RTFUZZTGTSTATEINT *RTFUZZTGTSTATE;
  84 /** Pointer to a fuzzed target state handle. */
  85 typedef RTFUZZTGTSTATE           *PRTFUZZTGTSTATE;
  86 /** NIL fuzzed target state handle. */
  87 #define NIL_RTFUZZTGTSTATE       ((RTFUZZTGTSTATE)~(uintptr_t)0)
  88
  89
  90 /** Fuzzing observer handle. */
  91 typedef struct RTFUZZOBSINT      *RTFUZZOBS;
  92 /** Pointer to a fuzzing observer handle. */
  93 typedef RTFUZZOBS                *PRTFUZZOBS;
  94 /** NIL fuzzing observer handle. */
  95 #define NIL_RTFUZZOBS             ((RTFUZZOBS)~(uintptr_t)0)
  96
  97
  98 /**
  99  * Fuzzing context type.
 100  */
 101 typedef enum RTFUZZCTXTYPE
 102 {
 103     /** Invalid type. */
 104     RTFUZZCTXTYPE_INVALID = 0,
 105     /** Original input data is a single binary large object (BLOB), from a file or similar. */
 106     RTFUZZCTXTYPE_BLOB,
 107     /** Original input data is from a data stream like a network connection. */
 108     RTFUZZCTXTYPE_STREAM,
 109     /** 32bit hack. */
 110     RTFUZZCTXTYPE_32BIT_HACK = 0x7fffffff
 111 } RTFUZZCTXTYPE;
 112
 113
 114 /**
 115  * Fuzzing context statistics.
 116  */
 117 typedef struct RTFUZZCTXSTATS
 118 {
 119     /** Amount of memory currently allocated. */
 120     size_t                      cbMemory;
 121     /** Number of mutations accumulated in the corpus. */
 122     uint64_t                    cMutations;
 123 } RTFUZZCTXSTATS;
 124 /** Pointer to fuzzing context statistics. */
 125 typedef RTFUZZCTXSTATS *PRTFUZZCTXSTATS;
 126
 127
 128 /** @name RTFUZZCTX_F_XXX - Flags for RTFuzzCtxCfgSetBehavioralFlags
 129  * @{ */
 130 /** Adds all generated inputs automatically to the input corpus for the owning context. */
 131 #define RTFUZZCTX_F_BEHAVIORAL_ADD_INPUT_AUTOMATICALLY_TO_CORPUS    RT_BIT_32(0)
 132 /** All valid behavioral modification flags. */
 133 #define RTFUZZCTX_F_BEHAVIORAL_VALID                                (RTFUZZCTX_F_BEHAVIORAL_ADD_INPUT_AUTOMATICALLY_TO_CORPUS)
 134 /** @} */
 135
 136
 137 /** @name RTFUZZOBS_SANITIZER_F_XXX - Flags for RTFuzzObsSetTestBinarySanitizers().
 138  * @{ */
 139 /** ASAN is compiled and enabled (observer needs to configure to abort on error to catch memory errors). */
 140 #define RTFUZZOBS_SANITIZER_F_ASAN                 UINT32_C(0x00000001)
 141 /** A converage sanitizer is compiled in which can be used to produce coverage reports aiding in the
 142  * fuzzing process. */
 143 #define RTFUZZOBS_SANITIZER_F_SANCOV               UINT32_C(0x00000002)
 144 /** @} */
 145
 146
 147 /** @name RTFUZZTGT_REC_STATE_F_XXX - Flags for RTFuzzTgtRecorderCreate().
 148  * @{ */
 149 /** The output from stdout is used to compare states. */
 150 #define RTFUZZTGT_REC_STATE_F_STDOUT               RT_BIT_32(0)
 151 /** The output from stderr is used to compare states. */
 152 #define RTFUZZTGT_REC_STATE_F_STDERR               RT_BIT_32(1)
 153 /** The process status is used to compare states. */
 154 #define RTFUZZTGT_REC_STATE_F_PROCSTATUS           RT_BIT_32(2)
 155 /** The coverage report is used to compare states. */
 156 #define RTFUZZTGT_REC_STATE_F_SANCOV               RT_BIT_32(3)
 157 /** Mask of all valid flags. */
 158 #define RTFUZZTGT_REC_STATE_F_VALID                UINT32_C(0x0000000f)
 159 /** @} */
 160
 161
 162 /** @name RTFUZZCFG_IMPORT_F_XXX - Flags for RTFuzzCfgImport().
 163  * @{ */
 164 /** Default flags. */
 165 #define RTFUZZCFG_IMPORT_F_DEFAULT                 0
 166 /** Adds only the inputs and doesn't set any glboal configuration flags of the fuzzing context. */
 167 #define RTFUZZCFG_IMPORT_F_ONLY_INPUT              RT_BIT_32(0)
 168 /** Mask of all valid flags. */
 169 #define RTFUZZCFG_IMPORT_F_VALID                   UINT32_C(0x00000001)
 170 /** @} */
 171
 172
 173 /**
 174  * Fuzzing context state export callback.
 175  *
 176  * @returns IPRT status code.
 177  * @param   hFuzzCtx            Handle of the fuzzing context.
 178  * @param   pvBuf               The data to write.
 179  * @param   cbWrite             Number of bytes to write.
 180  * @param   pvUser              Opaque user data passed in RTFuzzCtxStateExport().
 181  */
 182 typedef DECLCALLBACKTYPE(int, FNRTFUZZCTXEXPORT,(RTFUZZCTX hFuzzCtx, const void *pvBuf, size_t cbWrite, void *pvUser));
 183 /** Pointer to a fuzzing context state export callback. */
 184 typedef FNRTFUZZCTXEXPORT *PFNRTFUZZCTXEXPORT;
 185
 186 /**
 187  * Fuzzing context state import callback.
 188  *
 189  * @returns IPRT status code.
 190  * @param   hFuzzCtx            Handle of the fuzzing context.
 191  * @param   pvBuf               Where to store the read data.
 192  * @param   cbRead              Number of bytes to read.
 193  * @param   pcbRead             Where to store the amount of data written, optional.
 194  * @param   pvUser              Opaque user data passed in RTFuzzCtxCreateFromState().
 195  */
 196 typedef DECLCALLBACKTYPE(int, FNRTFUZZCTXIMPORT,(RTFUZZCTX hFuzzCtx, void *pvBuf, size_t cbRead, size_t *pcbRead, void *pvUser));
 197 /** Pointer to a fuzzing context state export callback. */
 198 typedef FNRTFUZZCTXIMPORT *PFNRTFUZZCTXIMPORT;
 199
 200
 201 /**
 202  * Creates a new fuzzing context.
 203  *
 204  * @returns IPRT status code.
 205  * @param   phFuzzCtx           Where to store the handle to the fuzzing context on success.
 206  * @param   enmType             Fuzzing context data type.
 207  */
 208 RTDECL(int) RTFuzzCtxCreate(PRTFUZZCTX phFuzzCtx, RTFUZZCTXTYPE enmType);
 209
 210 /**
 211  * Creates a new fuzzing context from the given state.
 212  *
 213  * @returns IPRT status code.
 214  * @param   phFuzzCtx           Where to store the handle to the fuzzing context on success.
 215  * @param   pfnImport           State import callback.
 216  * @param   pvUser              Opaque user data to pass to the callback.
 217  */
 218 RTDECL(int) RTFuzzCtxCreateFromState(PRTFUZZCTX phFuzzCtx, PFNRTFUZZCTXIMPORT pfnImport, void *pvUser);
 219
 220 /**
 221  * Creates a new fuzzing context loading the state from the given memory buffer.
 222  *
 223  * @returns IPRT status code.
 224  * @param   phFuzzCtx           Where to store the handle to the fuzzing context on success.
 225  * @param   pvState             Pointer to the memory containing the state.
 226  * @param   cbState             Size of the state buffer.
 227  */
 228 RTDECL(int) RTFuzzCtxCreateFromStateMem(PRTFUZZCTX phFuzzCtx, const void *pvState, size_t cbState);
 229
 230 /**
 231  * Creates a new fuzzing context loading the state from the given file.
 232  *
 233  * @returns IPRT status code.
 234  * @param   phFuzzCtx           Where to store the handle to the fuzzing context on success.
 235  * @param   pszFilename         File to load the fuzzing context from.
 236  */
 237 RTDECL(int) RTFuzzCtxCreateFromStateFile(PRTFUZZCTX phFuzzCtx, const char *pszFilename);
 238
 239 /**
 240  * Retains a reference to the given fuzzing context.
 241  *
 242  * @returns New reference count on success.
 243  * @param   hFuzzCtx            Handle of the fuzzing context.
 244  */
 245 RTDECL(uint32_t) RTFuzzCtxRetain(RTFUZZCTX hFuzzCtx);
 246
 247 /**
 248  * Releases a reference from the given fuzzing context, destroying it when reaching 0.
 249  *
 250  * @returns New reference count on success, 0 if the fuzzing context got destroyed.
 251  * @param   hFuzzCtx            Handle of the fuzzing context.
 252  */
 253 RTDECL(uint32_t) RTFuzzCtxRelease(RTFUZZCTX hFuzzCtx);
 254
 255 /**
 256  * Queries statistics about the given fuzzing context.
 257  *
 258  * @returns IPRT status code.
 259  * @param   hFuzzCtx            Handle of the fuzzing context.
 260  * @param   pStats              Where to store the stats on success.
 261  */
 262 RTDECL(int) RTFuzzCtxQueryStats(RTFUZZCTX hFuzzCtx, PRTFUZZCTXSTATS pStats);
 263
 264 /**
 265  * Exports the given fuzzing context state.
 266  *
 267  * @returns IPRT statuse code
 268  * @param   hFuzzCtx            The fuzzing context to export.
 269  * @param   pfnExport           Export callback.
 270  * @param   pvUser              Opaque user data to pass to the callback.
 271  */
 272 RTDECL(int) RTFuzzCtxStateExport(RTFUZZCTX hFuzzCtx, PFNRTFUZZCTXEXPORT pfnExport, void *pvUser);
 273
 274 /**
 275  * Exports the given fuzzing context state to memory allocating the buffer.
 276  *
 277  * @returns IPRT status code.
 278  * @param   hFuzzCtx            The fuzzing context to export.
 279  * @param   ppvState            Where to store the pointer to the memory containing state on success.
 280  *                              Free with RTMemFree().
 281  * @param   pcbState            Where to store the size of the state in bytes.
 282  */
 283 RTDECL(int) RTFuzzCtxStateExportToMem(RTFUZZCTX hFuzzCtx, void **ppvState, size_t *pcbState);
 284
 285 /**
 286  * Exports the given fuzzing context state to the given file.
 287  *
 288  * @returns IPRT status code.
 289  * @param   hFuzzCtx            The fuzzing context to export.
 290  * @param   pszFilename         The file to save the state to.
 291  */
 292 RTDECL(int) RTFuzzCtxStateExportToFile(RTFUZZCTX hFuzzCtx, const char *pszFilename);
 293
 294 /**
 295  * Adds a new seed to the input corpus of the given fuzzing context.
 296  *
 297  * @returns IPRT status code.
 298  * @param   hFuzzCtx            The fuzzing context handle.
 299  * @param   pvInput             The pointer to the input buffer.
 300  * @param   cbInput             Size of the input buffer.
 301  */
 302 RTDECL(int) RTFuzzCtxCorpusInputAdd(RTFUZZCTX hFuzzCtx, const void *pvInput, size_t cbInput);
 303
 304 /**
 305  * Adds a new seed to the input corpus of the given fuzzing context - extended version.
 306  *
 307  * @returns IPRT status code.
 308  * @param   hFuzzCtx            The fuzzing context handle.
 309  * @param   pvInput             The pointer to the input buffer.
 310  * @param   cbInput             Size of the input buffer.
 311  * @param   offMutStart         Start offset at which a mutation can happen.
 312  * @param   cbMutRange          Size of the range in bytes where a mutation can happen,
 313  *                              use UINT64_MAX to allow mutations till the end of the input.
 314  */
 315 RTDECL(int) RTFuzzCtxCorpusInputAddEx(RTFUZZCTX hFuzzCtx, const void *pvInput, size_t cbInput,
 316                                       uint64_t offMutStart, uint64_t cbMutRange);
 317
 318 /**
 319  * Adds a new seed to the input corpus of the given fuzzing context from the given file.
 320  *
 321  * @returns IPRT status code.
 322  * @param   hFuzzCtx            The fuzzing context handle.
 323  * @param   pszFilename         The filename to load the seed from.
 324  */
 325 RTDECL(int) RTFuzzCtxCorpusInputAddFromFile(RTFUZZCTX hFuzzCtx, const char *pszFilename);
 326
 327 /**
 328  * Adds a new seed to the input corpus of the given fuzzing context from the given file - extended version.
 329  *
 330  * @returns IPRT status code.
 331  * @param   hFuzzCtx            The fuzzing context handle.
 332  * @param   pszFilename         The filename to load the seed from.
 333  * @param   offMutStart         Start offset at which a mutation can happen.
 334  * @param   cbMutRange          Size of the range in bytes where a mutation can happen,
 335  *                              use UINT64_MAX to allow mutations till the end of the input.
 336  */
 337 RTDECL(int) RTFuzzCtxCorpusInputAddFromFileEx(RTFUZZCTX hFuzzCtx, const char *pszFilename,
 338                                               uint64_t offMutStart, uint64_t cbMutRange);
 339
 340 /**
 341  * Adds a new seed to the input corpus of the given fuzzing context from the given VFS file.
 342  *
 343  * @returns IPRT status code.
 344  * @param   hFuzzCtx            The fuzzing context handle.
 345  * @param   hVfsFile            The VFS file handle to load the seed from.
 346  */
 347 RTDECL(int) RTFuzzCtxCorpusInputAddFromVfsFile(RTFUZZCTX hFuzzCtx, RTVFSFILE hVfsFile);
 348
 349 /**
 350  * Adds a new seed to the input corpus of the given fuzzing context from the given VFS file - extended version.
 351  *
 352  * @returns IPRT status code.
 353  * @param   hFuzzCtx            The fuzzing context handle.
 354  * @param   hVfsFile            The VFS file handle to load the seed from.
 355  * @param   offMutStart         Start offset at which a mutation can happen.
 356  * @param   cbMutRange          Size of the range in bytes where a mutation can happen,
 357  *                              use UINT64_MAX to allow mutations till the end of the input.
 358  */
 359 RTDECL(int) RTFuzzCtxCorpusInputAddFromVfsFileEx(RTFUZZCTX hFuzzCtx, RTVFSFILE hVfsFile,
 360                                                  uint64_t offMutStart, uint64_t cbMutRange);
 361
 362 /**
 363  * Adds a new seed to the input corpus of the given fuzzing context from the given VFS I/O stream.
 364  *
 365  * @returns IPRT status code.
 366  * @param   hFuzzCtx            The fuzzing context handle.
 367  * @param   hVfsIos             The VFS I/O stream handle to load the seed from.
 368  */
 369 RTDECL(int) RTFuzzCtxCorpusInputAddFromVfsIoStrm(RTFUZZCTX hFuzzCtx, RTVFSIOSTREAM hVfsIos);
 370
 371 /**
 372  * Adds a new seed to the input corpus of the given fuzzing context from the given VFS I/O stream - extended version.
 373  *
 374  * @returns IPRT status code.
 375  * @param   hFuzzCtx            The fuzzing context handle.
 376  * @param   hVfsIos             The VFS I/O stream handle to load the seed from.
 377  * @param   offMutStart         Start offset at which a mutation can happen.
 378  * @param   cbMutRange          Size of the range in bytes where a mutation can happen,
 379  *                              use UINT64_MAX to allow mutations till the end of the input.
 380  */
 381 RTDECL(int) RTFuzzCtxCorpusInputAddFromVfsIoStrmEx(RTFUZZCTX hFuzzCtx, RTVFSIOSTREAM hVfsIos,
 382                                                    uint64_t offMutStart, uint64_t cbMutRange);
 383
 384 /**
 385  * Adds new seeds to the input corpus of the given fuzzing context from the given directory.
 386  *
 387  * Will only process regular files, i.e. ignores directories, symbolic links, devices, fifos
 388  * and such.
 389  *
 390  * @returns IPRT status code.
 391  * @param   hFuzzCtx            The fuzzing context handle.
 392  * @param   pszDirPath          The directory to load seeds from.
 393  */
 394 RTDECL(int) RTFuzzCtxCorpusInputAddFromDirPath(RTFUZZCTX hFuzzCtx, const char *pszDirPath);
 395
 396 /**
 397  * Restricts the maximum input size to generate by the fuzzing context.
 398  *
 399  * @returns IPRT status code
 400  * @param   hFuzzCtx            The fuzzing context handle.
 401  * @param   cbMax               Maximum input size in bytes.
 402  */
 403 RTDECL(int) RTFuzzCtxCfgSetInputSeedMaximum(RTFUZZCTX hFuzzCtx, size_t cbMax);
 404
 405 /**
 406  * Returns the maximum input size of the given fuzzing context.
 407  *
 408  * @returns Maximum input size generated in bytes.
 409  * @param   hFuzzCtx            The fuzzing context handle.
 410  */
 411 RTDECL(size_t) RTFuzzCtxCfgGetInputSeedMaximum(RTFUZZCTX hFuzzCtx);
 412
 413 /**
 414  * Sets flags controlling the behavior of the fuzzing context.
 415  *
 416  * @returns IPRT status code.
 417  * @param   hFuzzCtx            The fuzzing context handle.
 418  * @param   fFlags              Flags controlling the fuzzing context, RTFUZZCTX_F_XXX.
 419  */
 420 RTDECL(int) RTFuzzCtxCfgSetBehavioralFlags(RTFUZZCTX hFuzzCtx, uint32_t fFlags);
 421
 422 /**
 423  * Returns the current set behavioral flags for the given fuzzing context.
 424  *
 425  * @returns Behavioral flags of the given fuzzing context.
 426  * @param   hFuzzCtx            The fuzzing context handle.
 427  */
 428 RTDECL(uint32_t) RTFuzzCfgGetBehavioralFlags(RTFUZZCTX hFuzzCtx);
 429
 430 /**
 431  * Sets the temporary directory used by the fuzzing context.
 432  *
 433  * @returns IPRT status code.
 434  * @param   hFuzzCtx            The fuzzing context handle.
 435  * @param   pszPathTmp          The directory for the temporary state.
 436  */
 437 RTDECL(int) RTFuzzCtxCfgSetTmpDirectory(RTFUZZCTX hFuzzCtx, const char *pszPathTmp);
 438
 439 /**
 440  * Returns the current temporary directory.
 441  *
 442  * @returns Current temporary directory.
 443  * @param   hFuzzCtx            The fuzzing context handle.
 444  */
 445 RTDECL(const char *) RTFuzzCtxCfgGetTmpDirectory(RTFUZZCTX hFuzzCtx);
 446
 447 /**
 448  * Sets the range in which a particular input can get mutated.
 449  *
 450  * @returns IPRT status code.
 451  * @param   hFuzzCtx            The fuzzing context handle.
 452  * @param   offStart            Start offset at which a mutation can happen.
 453  * @param   cbRange             Size of the range in bytes where a mutation can happen,
 454  *                              use UINT64_MAX to allow mutations till the end of the input.
 455  */
 456 RTDECL(int) RTFuzzCtxCfgSetMutationRange(RTFUZZCTX hFuzzCtx, uint64_t offStart, uint64_t cbRange);
 457
 458 /**
 459  * Reseeds the PRNG of the given fuzzing context.
 460  *
 461  * @returns IPRT status code.
 462  * @param   hFuzzCtx            The fuzzing context handle.
 463  * @param   uSeed               The new seed.
 464  */
 465 RTDECL(int) RTFuzzCtxReseed(RTFUZZCTX hFuzzCtx, uint64_t uSeed);
 466
 467 /**
 468  * Generates a new input from the given fuzzing context and returns it.
 469  *
 470  * @returns IPRT status code.
 471  * @param   hFuzzCtx            The fuzzing context handle.
 472  * @param   phFuzzInput         Where to store the handle to the fuzzed input on success.
 473  */
 474 RTDECL(int) RTFuzzCtxInputGenerate(RTFUZZCTX hFuzzCtx, PRTFUZZINPUT phFuzzInput);
 475
 476
 477 /**
 478  * Retains a reference to the given fuzzing input handle.
 479  *
 480  * @returns New reference count on success.
 481  * @param   hFuzzInput          The fuzzing input handle.
 482  */
 483 RTDECL(uint32_t) RTFuzzInputRetain(RTFUZZINPUT hFuzzInput);
 484
 485 /**
 486  * Releases a reference from the given fuzzing input handle, destroying it when reaching 0.
 487  *
 488  * @returns New reference count on success, 0 if the fuzzing input got destroyed.
 489  * @param   hFuzzInput          The fuzzing input handle.
 490  */
 491 RTDECL(uint32_t) RTFuzzInputRelease(RTFUZZINPUT hFuzzInput);
 492
 493 /**
 494  * Queries the data pointer and size of the given fuzzed input blob.
 495  *
 496  * @returns IPRT status code
 497  * @param   hFuzzInput          The fuzzing input handle.
 498  * @param   ppv                 Where to store the pointer to the input data on success.
 499  * @param   pcb                 Where to store the size of the input data on success.
 500  */
 501 RTDECL(int) RTFuzzInputQueryBlobData(RTFUZZINPUT hFuzzInput, void **ppv, size_t *pcb);
 502
 503 /**
 504  * Processes the given data stream for a streamed fuzzing context.
 505  *
 506  * @returns IPRT status code.
 507  * @param   hFuzzInput          The fuzzing input handle.
 508  * @param   pvBuf               The data buffer.
 509  * @param   cbBuf               Size of the buffer.
 510  */
 511 RTDECL(int) RTFuzzInputMutateStreamData(RTFUZZINPUT hFuzzInput, void *pvBuf, size_t cbBuf);
 512
 513 /**
 514  * Queries the string of the MD5 digest for the given fuzzed input.
 515  *
 516  * @returns IPRT status code.
 517  * @retval  VERR_BUFFER_OVERFLOW if the size of the string buffer is not sufficient.
 518  * @param   hFuzzInput          The fuzzing input handle.
 519  * @param   pszDigest           Where to store the digest string and a closing terminator.
 520  * @param   cchDigest           Size of the string buffer in characters (including the zero terminator).
 521  */
 522 RTDECL(int) RTFuzzInputQueryDigestString(RTFUZZINPUT hFuzzInput, char *pszDigest, size_t cchDigest);
 523
 524 /**
 525  * Writes the given fuzzing input to the given file.
 526  *
 527  * @returns IPRT status code.
 528  * @param   hFuzzInput          The fuzzing input handle.
 529  * @param   pszFilename         The filename to store the input to.
 530  */
 531 RTDECL(int) RTFuzzInputWriteToFile(RTFUZZINPUT hFuzzInput, const char *pszFilename);
 532
 533 /**
 534  * Adds the given fuzzed input to the input corpus of the owning context.
 535  *
 536  * @returns IPRT status code.
 537  * @retval  VERR_ALREADY_EXISTS if the input exists already.
 538  * @param   hFuzzInput          The fuzzing input handle.
 539  */
 540 RTDECL(int) RTFuzzInputAddToCtxCorpus(RTFUZZINPUT hFuzzInput);
 541
 542 /**
 543  * Removes the given fuzzed input from the input corpus of the owning context.
 544  *
 545  * @returns IPRT status code.
 546  * @retval  VERR_NOT_FOUND if the input is not part of the corpus.
 547  * @param   hFuzzInput          The fuzzing input handle.
 548  */
 549 RTDECL(int) RTFuzzInputRemoveFromCtxCorpus(RTFUZZINPUT hFuzzInput);
 550
 551
 552 /**
 553  * Creates a fuzzing config from the given VFS file handle.
 554  *
 555  * @returns IPRT status code.
 556  * @param   phFuzzCfg           Where to store the handle to the fuzzing config on success.
 557  * @param   hVfsFile            The VFS file to use (retained).
 558  * @param   pErrInfo            Where to store extended error info. Optional.
 559  */
 560 RTDECL(int) RTFuzzCfgCreateFromVfsFile(PRTFUZZCFG phFuzzCfg, RTVFSFILE hVfsFile, PRTERRINFO pErrInfo);
 561
 562 /**
 563  * Creates a fuzzing config from the given file path.
 564  *
 565  * @returns IPRT status code.
 566  * @param   phFuzzCfg           Where to store the handle to the fuzzing config on success.
 567  * @param   pszFilename         Filename to load the config from.
 568  * @param   pErrInfo            Where to store extended error info. Optional.
 569  */
 570 RTDECL(int) RTFuzzCfgCreateFromFile(PRTFUZZCFG phFuzzCfg, const char *pszFilename, PRTERRINFO pErrInfo);
 571
 572 /**
 573  * Retains a reference to the given fuzzing config.
 574  *
 575  * @returns New reference count on success.
 576  * @param   hFuzzCfg            Handle of the fuzzing config.
 577  */
 578 RTDECL(uint32_t) RTFuzzCfgRetain(RTFUZZCFG hFuzzCfg);
 579
 580 /**
 581  * Releases a reference from the given fuzzing config, destroying it when reaching 0.
 582  *
 583  * @returns New reference count on success, 0 if the fuzzing config got destroyed.
 584  * @param   hFuzzCfg            Handle of the fuzzing config.
 585  */
 586 RTDECL(uint32_t) RTFuzzCfgRelease(RTFUZZCFG hFuzzCfg);
 587
 588 /**
 589  * Imports the given fuzzing config into a previously created fuzzing context.
 590  *
 591  * @returns IPRT status code.
 592  * @param   hFuzzCfg            Handle of the fuzzing config.
 593  * @param   hFuzzCtx            Handle of the fuzzing context.
 594  * @param   fFlags              Flags controlling what to import exactly, combination of RTFUZZCFG_IMPORT_F_XXX.
 595  */
 596 RTDECL(int) RTFuzzCfgImport(RTFUZZCFG hFuzzCfg, RTFUZZCTX hFuzzCtx, uint32_t fFlags);
 597
 598 /**
 599  * Queries the custom config for the controller of the fuzzing process.
 600  *
 601  * @returns IPRT status code.
 602  * @param   hFuzzCfg            Handle of the fuzzing config.
 603  * @param   phVfsFile           Where to store the handle of the VFS file containing the custom config.
 604  */
 605 RTDECL(int) RTFuzzCfgQueryCustomCfg(RTFUZZCFG hFuzzCfg, PRTVFSFILE phVfsFile);
 606
 607
 608 /**
 609  * Creates a new fuzzed target recorder.
 610  *
 611  * @returns IPRT status code.
 612  * @param   phFuzzTgtRec        Where to store the handle to the fuzzed target recorder on success.
 613  * @param   fRecFlags           What to take into account when checking for equal states.
 614  *                              Combination of RTFUZZTGT_REC_STATE_F_*
 615  */
 616 RTDECL(int) RTFuzzTgtRecorderCreate(PRTFUZZTGTREC phFuzzTgtRec, uint32_t fRecFlags);
 617
 618 /**
 619  * Retains a reference to the given fuzzed target recorder handle.
 620  *
 621  * @returns New reference count on success.
 622  * @param   hFuzzTgtRec         The fuzzed target recorder handle.
 623  */
 624 RTDECL(uint32_t) RTFuzzTgtRecorderRetain(RTFUZZTGTREC hFuzzTgtRec);
 625
 626 /**
 627  * Releases a reference from the given fuzzed target recorder handle, destroying it when reaching 0.
 628  *
 629  * @returns New reference count on success, 0 if the fuzzed target recorder got destroyed.
 630  * @param   hFuzzTgtRec         The fuzzed target recorder handle.
 631  */
 632 RTDECL(uint32_t) RTFuzzTgtRecorderRelease(RTFUZZTGTREC hFuzzTgtRec);
 633
 634 /**
 635  * Creates a new empty fuzzed target state.
 636  *
 637  * @returns IPRT status code.
 638  * @param   hFuzzTgtRec         The fuzzed target recorder handle.
 639  * @param   phFuzzTgtState      Where to store the handle to the fuzzed target state on success.
 640  */
 641 RTDECL(int) RTFuzzTgtRecorderCreateNewState(RTFUZZTGTREC hFuzzTgtRec, PRTFUZZTGTSTATE phFuzzTgtState);
 642
 643 /**
 644  * Retains a reference to the given fuzzed target state handle.
 645  *
 646  * @returns New reference count on success.
 647  * @param   hFuzzTgtState       The fuzzed target state handle.
 648  */
 649 RTDECL(uint32_t) RTFuzzTgtStateRetain(RTFUZZTGTSTATE hFuzzTgtState);
 650
 651 /**
 652  * Releases a reference from the given fuzzed target state handle, destroying it when reaching 0.
 653  *
 654  * @returns New reference count on success, 0 if the fuzzed target recorder got destroyed.
 655  * @param   hFuzzTgtState       The fuzzed target state handle.
 656  */
 657 RTDECL(uint32_t) RTFuzzTgtStateRelease(RTFUZZTGTSTATE hFuzzTgtState);
 658
 659 /**
 660  * Resets the given fuzzed target state to an empty state (keeping allocated memory).
 661  *
 662  * @returns IPRT status code.
 663  * @param   hFuzzTgtState       The fuzzed target state handle.
 664  *
 665  * @note Useful when the state is not added to the recorded set to avoid allocating memory.
 666  */
 667 RTDECL(int) RTFuzzTgtStateReset(RTFUZZTGTSTATE hFuzzTgtState);
 668
 669 /**
 670  * Finalizes the given fuzzed target state, making it readonly.
 671  *
 672  * @returns IPRT status code.
 673  * @param   hFuzzTgtState       The fuzzed target state handle.
 674  */
 675 RTDECL(int) RTFuzzTgtStateFinalize(RTFUZZTGTSTATE hFuzzTgtState);
 676
 677 /**
 678  * Adds the given state to the set for the owning target recorder.
 679  *
 680  * @returns IPRT status code.
 681  * @retval  VERR_ALREADY_EXISTS if the state is already existing in the recorder set.
 682  * @param   hFuzzTgtState       The fuzzed target state handle.
 683  *
 684  * @note This also finalizes the target state if not already done.
 685  */
 686 RTDECL(int) RTFuzzTgtStateAddToRecorder(RTFUZZTGTSTATE hFuzzTgtState);
 687
 688 /**
 689  * Appends the given stdout output to the given target state.
 690  *
 691  * @returns IPRT status code.
 692  * @param   hFuzzTgtState       The fuzzed target state handle.
 693  * @param   pvStdOut            Pointer to the stdout data buffer.
 694  * @param   cbStdOut            Size of the stdout data buffer in bytes.
 695  */
 696 RTDECL(int) RTFuzzTgtStateAppendStdoutFromBuf(RTFUZZTGTSTATE hFuzzTgtState, const void *pvStdOut, size_t cbStdOut);
 697
 698 /**
 699  * Appends the given stderr output to the given target state.
 700  *
 701  * @returns IPRT status code.
 702  * @param   hFuzzTgtState       The fuzzed target state handle.
 703  * @param   pvStdErr            Pointer to the stderr data buffer.
 704  * @param   cbStdErr            Size of the stderr data buffer in bytes.
 705  */
 706 RTDECL(int) RTFuzzTgtStateAppendStderrFromBuf(RTFUZZTGTSTATE hFuzzTgtState, const void *pvStdErr, size_t cbStdErr);
 707
 708 /**
 709  * Appends the given stdout output to the given target state, reading from the given pipe.
 710  *
 711  * @returns IPRT status code.
 712  * @param   hFuzzTgtState       The fuzzed target state handle.
 713  * @param   hPipe               The stdout pipe to read the data from.
 714  */
 715 RTDECL(int) RTFuzzTgtStateAppendStdoutFromPipe(RTFUZZTGTSTATE hFuzzTgtState, RTPIPE hPipe);
 716
 717 /**
 718  * Appends the given stderr output to the given target state, reading from the given pipe.
 719  *
 720  * @returns IPRT status code.
 721  * @param   hFuzzTgtState       The fuzzed target state handle.
 722  * @param   hPipe               The stdout pipe to read the data from.
 723  */
 724 RTDECL(int) RTFuzzTgtStateAppendStderrFromPipe(RTFUZZTGTSTATE hFuzzTgtState, RTPIPE hPipe);
 725
 726 /**
 727  * Adds the SanCov coverage information from the given file to the given target state.
 728  *
 729  * @returns IPRT status code.
 730  * @param   hFuzzTgtState       The fuzzed target state handle.
 731  * @param   pszFilename         Filename of the coverage report.
 732  */
 733 RTDECL(int) RTFuzzTgtStateAddSanCovReportFromFile(RTFUZZTGTSTATE hFuzzTgtState, const char *pszFilename);
 734
 735 /**
 736  * Adds the given process status to the target state.
 737  *
 738  * @returns IPRT status code.
 739  * @param   hFuzzTgtState       The fuzzed target state handle.
 740  * @param   pProcSts            The process status to add.
 741  */
 742 RTDECL(int) RTFuzzTgtStateAddProcSts(RTFUZZTGTSTATE hFuzzTgtState, PCRTPROCSTATUS pProcSts);
 743
 744 /**
 745  * Dumps the given target state to the given directory.
 746  *
 747  * @returns IPRT status code.
 748  * @param   hFuzzTgtState       The fuzzed target state handle.
 749  * @param   pszDirPath          The directory to dump to.
 750  */
 751 RTDECL(int) RTFuzzTgtStateDumpToDir(RTFUZZTGTSTATE hFuzzTgtState, const char *pszDirPath);
 752
 753
 754 /**
 755  * Fuzzed binary input channel.
 756  */
 757 typedef enum RTFUZZOBSINPUTCHAN
 758 {
 759     /** Invalid. */
 760     RTFUZZOBSINPUTCHAN_INVALID = 0,
 761     /** File input. */
 762     RTFUZZOBSINPUTCHAN_FILE,
 763     /** Input over stdin. */
 764     RTFUZZOBSINPUTCHAN_STDIN,
 765     /** The binary is a fuzzing aware client using the
 766      * specified protocol over stdin/stdout. */
 767     RTFUZZOBSINPUTCHAN_FUZZING_AWARE_CLIENT,
 768     /** TCP server. */
 769     RTFUZZOBSINPUTCHAN_TCP_SERVER,
 770     /** TCP client. */
 771     RTFUZZOBSINPUTCHAN_TCP_CLIENT,
 772     /** UDP server. */
 773     RTFUZZOBSINPUTCHAN_UDP_SERVER,
 774     /** UDP client. */
 775     RTFUZZOBSINPUTCHAN_UDP_CLIENT,
 776     /** 32bit hack. */
 777     RTFUZZOBSINPUTCHAN_32BIT_HACK = 0x7fffffff
 778 } RTFUZZOBSINPUTCHAN;
 779
 780 /**
 781  * Fuzzing observer statistics.
 782  */
 783 typedef struct RTFUZZOBSSTATS
 784 {
 785     /** Number of fuzzed inputs per second. */
 786     uint32_t                    cFuzzedInputsPerSec;
 787     /** Number of overall fuzzed inputs. */
 788     uint32_t                    cFuzzedInputs;
 789     /** Number of observed hangs. */
 790     uint32_t                    cFuzzedInputsHang;
 791     /** Number of observed crashes. */
 792     uint32_t                    cFuzzedInputsCrash;
 793 } RTFUZZOBSSTATS;
 794 /** Pointer to a fuzzing observer statistics record. */
 795 typedef RTFUZZOBSSTATS *PRTFUZZOBSSTATS;
 796
 797 /**
 798  * Creates a new fuzzing observer.
 799  *
 800  * @returns IPRT status code.
 801  * @param   phFuzzObs           Where to store the fuzzing observer handle on success.
 802  * @param   enmType             Fuzzing context data type.
 803  * @param   fTgtRecFlags        Flags to pass to the target state recorder, see RTFuzzTgtRecorderCreate().
 804  */
 805 RTDECL(int) RTFuzzObsCreate(PRTFUZZOBS phFuzzObs, RTFUZZCTXTYPE enmType, uint32_t fTgtRecFlags);
 806
 807 /**
 808  * Destroys a previously created fuzzing observer.
 809  *
 810  * @returns IPRT status code.
 811  * @param   hFuzzObs            The fuzzing observer handle.
 812  */
 813 RTDECL(int) RTFuzzObsDestroy(RTFUZZOBS hFuzzObs);
 814
 815 /**
 816  * Queries the internal fuzzing context of the given observer.
 817  *
 818  * @returns IPRT status code.
 819  * @param   hFuzzObs            The fuzzing observer handle.
 820  * @param   phFuzzCtx           Where to store the handle to the fuzzing context on success.
 821  *
 822  * @note The fuzzing context handle should be released with RTFuzzCtxRelease() when not used anymore.
 823  */
 824 RTDECL(int) RTFuzzObsQueryCtx(RTFUZZOBS hFuzzObs, PRTFUZZCTX phFuzzCtx);
 825
 826 /**
 827  * Queries the current statistics for the given fuzzing observer.
 828  *
 829  * @returns IPRT status code.
 830  * @param   hFuzzObs            The fuzzing observer handle.
 831  * @param   pStats              Where to store the statistics to.
 832  */
 833 RTDECL(int) RTFuzzObsQueryStats(RTFUZZOBS hFuzzObs, PRTFUZZOBSSTATS pStats);
 834
 835 /**
 836  * Sets the temp directory for the given fuzzing observer.
 837  *
 838  * @returns IPRT status code.
 839  * @param   hFuzzObs            The fuzzing observer handle.
 840  * @param   pszTmp              The temp directory path.
 841  */
 842 RTDECL(int) RTFuzzObsSetTmpDirectory(RTFUZZOBS hFuzzObs, const char *pszTmp);
 843
 844 /**
 845  * Sets the directory to store results to.
 846  *
 847  * @returns IPRT status code.
 848  * @param   hFuzzObs            The fuzzing observer handle.
 849  * @param   pszResults          The path to store the results.
 850  */
 851 RTDECL(int) RTFuzzObsSetResultDirectory(RTFUZZOBS hFuzzObs, const char *pszResults);
 852
 853 /**
 854  * Sets the binary to run for each fuzzed input.
 855  *
 856  * @returns IPRT status code.
 857  * @param   hFuzzObs            The fuzzing observer handle.
 858  * @param   pszBinary           The binary path.
 859  * @param   enmInputChan        The input channel to use.
 860  */
 861 RTDECL(int) RTFuzzObsSetTestBinary(RTFUZZOBS hFuzzObs, const char *pszBinary, RTFUZZOBSINPUTCHAN enmInputChan);
 862
 863 /**
 864  * Sets additional arguments to run the binary with.
 865  *
 866  * @returns IPRT status code.
 867  * @param   hFuzzObs            The fuzzing observer handle.
 868  * @param   papszArgs           Pointer to the array of arguments.
 869  * @param   cArgs               Number of arguments.
 870  */
 871 RTDECL(int) RTFuzzObsSetTestBinaryArgs(RTFUZZOBS hFuzzObs, const char * const *papszArgs, unsigned cArgs);
 872
 873 /**
 874  * Sets an environment block to run the binary in.
 875  *
 876  * @returns IPRT status code.
 877  * @param   hFuzzObs            The fuzzing observer handle.
 878  * @param   hEnv                The environment block to set for the test binary.
 879  *                              Use RTENV_DEFAULT for the default process environment or
 880  *                              NULL for an empty environment.
 881  *
 882  * @note Upon successful return of this function the observer has taken ownership over the
 883  *       environment block and can alter it in unexpected ways. It also destroys the environment
 884  *       block when the observer gets destroyed. So don't touch the environment block after
 885  *       calling this function.
 886  */
 887 RTDECL(int) RTFuzzObsSetTestBinaryEnv(RTFUZZOBS hFuzzObs, RTENV hEnv);
 888
 889 /**
 890  * Makes the observer aware of any configured sanitizers for the test binary.
 891  *
 892  * @returns IPRT status code.
 893  * @param   hFuzzObs            The fuzzing observer handle.
 894  * @param   fSanitizers         Bitmask of compiled and enabled sanitiziers in the
 895  *                              target binary.
 896  */
 897 RTDECL(int) RTFuzzObsSetTestBinarySanitizers(RTFUZZOBS hFuzzObs, uint32_t fSanitizers);
 898
 899 /**
 900  * Sets maximum timeout until a process is considered hung and killed.
 901  *
 902  * @returns IPRT status code.
 903  * @param   hFuzzObs            The fuzzing observer handle.
 904  * @param   msTimeoutMax        The maximum number of milliseconds to wait until the process
 905  *                              is considered hung.
 906  */
 907 RTDECL(int) RTFuzzObsSetTestBinaryTimeout(RTFUZZOBS hFuzzObs, RTMSINTERVAL msTimeoutMax);
 908
 909 /**
 910  * Starts fuzzing the set binary.
 911  *
 912  * @returns IPRT status code.
 913  * @param   hFuzzObs            The fuzzing observer handle.
 914  * @param   cProcs              Number of processes to run simulteanously,
 915  *                              0 will create as many processes as there are CPUs available.
 916  */
 917 RTDECL(int) RTFuzzObsExecStart(RTFUZZOBS hFuzzObs, uint32_t cProcs);
 918
 919 /**
 920  * Stops the fuzzing process.
 921  *
 922  * @returns IPRT status code.
 923  * @param   hFuzzObs            The fuzzing observer handle.
 924  */
 925 RTDECL(int) RTFuzzObsExecStop(RTFUZZOBS hFuzzObs);
 926
 927
 928 /**
 929  * A fuzzing master program.
 930  *
 931  * @returns Program exit code.
 932  *
 933  * @param   cArgs               The number of arguments.
 934  * @param   papszArgs           The argument vector.  (Note that this may be
 935  *                              reordered, so the memory must be writable.)
 936  */
 937 RTR3DECL(RTEXITCODE) RTFuzzCmdMaster(unsigned cArgs, char **papszArgs);
 938
 939
 940 /**
 941  * Client input consumption callback.
 942  *
 943  * @returns IPRT status code.
 944  * @retval  VINF_SUCCESS the fuzzed code accepted the input.
 945  * @retval  VERR_* the client rejected the input while parsing it.
 946  * @param   pvBuf               The buffer containing the input data.
 947  * @param   cbBuf               Size of the buffer in bytes.
 948  * @param   pvUser              Opaque user data.
 949  */
 950 typedef DECLCALLBACKTYPE(int, FNFUZZCLIENTCONSUME,(const void *pvBuf, size_t cbBuf, void *pvUser));
 951 /** Pointer to a client consumption callback. */
 952 typedef FNFUZZCLIENTCONSUME *PFNFUZZCLIENTCONSUME;
 953
 954 /**
 955  * A fuzzing client program for more efficient fuzzing.
 956  *
 957  * @returns Program exit code.
 958  *
 959  * @param   cArgs               The number of arguments.
 960  * @param   papszArgs           The argument vector.  (Note that this may be
 961  *                              reordered, so the memory must be writable.)
 962  * @param   pfnConsume          Input data consumption callback.
 963  * @param   pvUser              Opaque user data to pass to the callback.
 964  */
 965 RTR3DECL(RTEXITCODE) RTFuzzCmdFuzzingClient(unsigned cArgs, char **papszArgs, PFNFUZZCLIENTCONSUME pfnConsume, void *pvUser);
 966 /** @} */
 967
 968 RT_C_DECLS_END
 969
 970 #endif /* !IPRT_INCLUDED_fuzz_h */
 971