971 lines
36 KiB
C
971 lines
36 KiB
C
/** @file
|
|
* IPRT - Fuzzing framework
|
|
*/
|
|
|
|
/*
|
|
* Copyright (C) 2018-2023 Oracle and/or its affiliates.
|
|
*
|
|
* This file is part of VirtualBox base platform packages, as
|
|
* available from https://www.virtualbox.org.
|
|
*
|
|
* This program 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, in version 3 of the
|
|
* License.
|
|
*
|
|
* This program 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 this program; if not, see <https://www.gnu.org/licenses>.
|
|
*
|
|
* The contents of this file may alternatively be used under the terms
|
|
* of the Common Development and Distribution License Version 1.0
|
|
* (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
|
|
* in the VirtualBox distribution, in which case the provisions of the
|
|
* CDDL are applicable instead of those of the GPL.
|
|
*
|
|
* You may elect to license modified versions of this file under the
|
|
* terms and conditions of either the GPL or the CDDL or both.
|
|
*
|
|
* SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
|
|
*/
|
|
|
|
#ifndef IPRT_INCLUDED_fuzz_h
|
|
#define IPRT_INCLUDED_fuzz_h
|
|
#ifndef RT_WITHOUT_PRAGMA_ONCE
|
|
# pragma once
|
|
#endif
|
|
|
|
#include <iprt/cdefs.h>
|
|
#include <iprt/process.h>
|
|
#include <iprt/types.h>
|
|
|
|
RT_C_DECLS_BEGIN
|
|
|
|
/** @defgroup grp_rt_fuzz RTFuzz - Data fuzzing framework
|
|
* @ingroup grp_rt
|
|
* @sa grp_rt_test
|
|
* @{
|
|
*/
|
|
|
|
/** A fuzzer context handle. */
|
|
typedef struct RTFUZZCTXINT *RTFUZZCTX;
|
|
/** Pointer to a fuzzer context handle. */
|
|
typedef RTFUZZCTX *PRTFUZZCTX;
|
|
/** NIL fuzzer context handle. */
|
|
#define NIL_RTFUZZCTX ((RTFUZZCTX)~(uintptr_t)0)
|
|
/** A fuzzer input handle. */
|
|
typedef struct RTFUZZINPUTINT *RTFUZZINPUT;
|
|
/** Pointer to a fuzzer input handle. */
|
|
typedef RTFUZZINPUT *PRTFUZZINPUT;
|
|
/** NIL fuzzer input handle. */
|
|
#define NIL_RTFUZZINPUT ((RTFUZZINPUT)~(uintptr_t)0)
|
|
|
|
|
|
/** A fuzzer config handle. */
|
|
typedef struct RTFUZZCFGINT *RTFUZZCFG;
|
|
/** Pointer to a fuzzer config handle. */
|
|
typedef RTFUZZCFG *PRTFUZZCFG;
|
|
/** NIL fuzzer config handle. */
|
|
#define NIL_RTFUZZCFG ((RTFUZZCFG)~(uintptr_t)0)
|
|
|
|
|
|
/** A fuzzer target recorder handler. */
|
|
typedef struct RTFUZZTGTRECINT *RTFUZZTGTREC;
|
|
/** Pointer to a fuzzer target recorder handle. */
|
|
typedef RTFUZZTGTREC *PRTFUZZTGTREC;
|
|
/** NIL fuzzer target recorder handle. */
|
|
#define NIL_RTFUZZTGTREC ((RTFUZZTGTREC)~(uintptr_t)0)
|
|
/** A fuzzed target state handle. */
|
|
typedef struct RTFUZZTGTSTATEINT *RTFUZZTGTSTATE;
|
|
/** Pointer to a fuzzed target state handle. */
|
|
typedef RTFUZZTGTSTATE *PRTFUZZTGTSTATE;
|
|
/** NIL fuzzed target state handle. */
|
|
#define NIL_RTFUZZTGTSTATE ((RTFUZZTGTSTATE)~(uintptr_t)0)
|
|
|
|
|
|
/** Fuzzing observer handle. */
|
|
typedef struct RTFUZZOBSINT *RTFUZZOBS;
|
|
/** Pointer to a fuzzing observer handle. */
|
|
typedef RTFUZZOBS *PRTFUZZOBS;
|
|
/** NIL fuzzing observer handle. */
|
|
#define NIL_RTFUZZOBS ((RTFUZZOBS)~(uintptr_t)0)
|
|
|
|
|
|
/**
|
|
* Fuzzing context type.
|
|
*/
|
|
typedef enum RTFUZZCTXTYPE
|
|
{
|
|
/** Invalid type. */
|
|
RTFUZZCTXTYPE_INVALID = 0,
|
|
/** Original input data is a single binary large object (BLOB), from a file or similar. */
|
|
RTFUZZCTXTYPE_BLOB,
|
|
/** Original input data is from a data stream like a network connection. */
|
|
RTFUZZCTXTYPE_STREAM,
|
|
/** 32bit hack. */
|
|
RTFUZZCTXTYPE_32BIT_HACK = 0x7fffffff
|
|
} RTFUZZCTXTYPE;
|
|
|
|
|
|
/**
|
|
* Fuzzing context statistics.
|
|
*/
|
|
typedef struct RTFUZZCTXSTATS
|
|
{
|
|
/** Amount of memory currently allocated. */
|
|
size_t cbMemory;
|
|
/** Number of mutations accumulated in the corpus. */
|
|
uint64_t cMutations;
|
|
} RTFUZZCTXSTATS;
|
|
/** Pointer to fuzzing context statistics. */
|
|
typedef RTFUZZCTXSTATS *PRTFUZZCTXSTATS;
|
|
|
|
|
|
/** @name RTFUZZCTX_F_XXX - Flags for RTFuzzCtxCfgSetBehavioralFlags
|
|
* @{ */
|
|
/** Adds all generated inputs automatically to the input corpus for the owning context. */
|
|
#define RTFUZZCTX_F_BEHAVIORAL_ADD_INPUT_AUTOMATICALLY_TO_CORPUS RT_BIT_32(0)
|
|
/** All valid behavioral modification flags. */
|
|
#define RTFUZZCTX_F_BEHAVIORAL_VALID (RTFUZZCTX_F_BEHAVIORAL_ADD_INPUT_AUTOMATICALLY_TO_CORPUS)
|
|
/** @} */
|
|
|
|
|
|
/** @name RTFUZZOBS_SANITIZER_F_XXX - Flags for RTFuzzObsSetTestBinarySanitizers().
|
|
* @{ */
|
|
/** ASAN is compiled and enabled (observer needs to configure to abort on error to catch memory errors). */
|
|
#define RTFUZZOBS_SANITIZER_F_ASAN UINT32_C(0x00000001)
|
|
/** A converage sanitizer is compiled in which can be used to produce coverage reports aiding in the
|
|
* fuzzing process. */
|
|
#define RTFUZZOBS_SANITIZER_F_SANCOV UINT32_C(0x00000002)
|
|
/** @} */
|
|
|
|
|
|
/** @name RTFUZZTGT_REC_STATE_F_XXX - Flags for RTFuzzTgtRecorderCreate().
|
|
* @{ */
|
|
/** The output from stdout is used to compare states. */
|
|
#define RTFUZZTGT_REC_STATE_F_STDOUT RT_BIT_32(0)
|
|
/** The output from stderr is used to compare states. */
|
|
#define RTFUZZTGT_REC_STATE_F_STDERR RT_BIT_32(1)
|
|
/** The process status is used to compare states. */
|
|
#define RTFUZZTGT_REC_STATE_F_PROCSTATUS RT_BIT_32(2)
|
|
/** The coverage report is used to compare states. */
|
|
#define RTFUZZTGT_REC_STATE_F_SANCOV RT_BIT_32(3)
|
|
/** Mask of all valid flags. */
|
|
#define RTFUZZTGT_REC_STATE_F_VALID UINT32_C(0x0000000f)
|
|
/** @} */
|
|
|
|
|
|
/** @name RTFUZZCFG_IMPORT_F_XXX - Flags for RTFuzzCfgImport().
|
|
* @{ */
|
|
/** Default flags. */
|
|
#define RTFUZZCFG_IMPORT_F_DEFAULT 0
|
|
/** Adds only the inputs and doesn't set any glboal configuration flags of the fuzzing context. */
|
|
#define RTFUZZCFG_IMPORT_F_ONLY_INPUT RT_BIT_32(0)
|
|
/** Mask of all valid flags. */
|
|
#define RTFUZZCFG_IMPORT_F_VALID UINT32_C(0x00000001)
|
|
/** @} */
|
|
|
|
|
|
/**
|
|
* Fuzzing context state export callback.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzCtx Handle of the fuzzing context.
|
|
* @param pvBuf The data to write.
|
|
* @param cbWrite Number of bytes to write.
|
|
* @param pvUser Opaque user data passed in RTFuzzCtxStateExport().
|
|
*/
|
|
typedef DECLCALLBACKTYPE(int, FNRTFUZZCTXEXPORT,(RTFUZZCTX hFuzzCtx, const void *pvBuf, size_t cbWrite, void *pvUser));
|
|
/** Pointer to a fuzzing context state export callback. */
|
|
typedef FNRTFUZZCTXEXPORT *PFNRTFUZZCTXEXPORT;
|
|
|
|
/**
|
|
* Fuzzing context state import callback.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzCtx Handle of the fuzzing context.
|
|
* @param pvBuf Where to store the read data.
|
|
* @param cbRead Number of bytes to read.
|
|
* @param pcbRead Where to store the amount of data written, optional.
|
|
* @param pvUser Opaque user data passed in RTFuzzCtxCreateFromState().
|
|
*/
|
|
typedef DECLCALLBACKTYPE(int, FNRTFUZZCTXIMPORT,(RTFUZZCTX hFuzzCtx, void *pvBuf, size_t cbRead, size_t *pcbRead, void *pvUser));
|
|
/** Pointer to a fuzzing context state export callback. */
|
|
typedef FNRTFUZZCTXIMPORT *PFNRTFUZZCTXIMPORT;
|
|
|
|
|
|
/**
|
|
* Creates a new fuzzing context.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param phFuzzCtx Where to store the handle to the fuzzing context on success.
|
|
* @param enmType Fuzzing context data type.
|
|
*/
|
|
RTDECL(int) RTFuzzCtxCreate(PRTFUZZCTX phFuzzCtx, RTFUZZCTXTYPE enmType);
|
|
|
|
/**
|
|
* Creates a new fuzzing context from the given state.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param phFuzzCtx Where to store the handle to the fuzzing context on success.
|
|
* @param pfnImport State import callback.
|
|
* @param pvUser Opaque user data to pass to the callback.
|
|
*/
|
|
RTDECL(int) RTFuzzCtxCreateFromState(PRTFUZZCTX phFuzzCtx, PFNRTFUZZCTXIMPORT pfnImport, void *pvUser);
|
|
|
|
/**
|
|
* Creates a new fuzzing context loading the state from the given memory buffer.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param phFuzzCtx Where to store the handle to the fuzzing context on success.
|
|
* @param pvState Pointer to the memory containing the state.
|
|
* @param cbState Size of the state buffer.
|
|
*/
|
|
RTDECL(int) RTFuzzCtxCreateFromStateMem(PRTFUZZCTX phFuzzCtx, const void *pvState, size_t cbState);
|
|
|
|
/**
|
|
* Creates a new fuzzing context loading the state from the given file.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param phFuzzCtx Where to store the handle to the fuzzing context on success.
|
|
* @param pszFilename File to load the fuzzing context from.
|
|
*/
|
|
RTDECL(int) RTFuzzCtxCreateFromStateFile(PRTFUZZCTX phFuzzCtx, const char *pszFilename);
|
|
|
|
/**
|
|
* Retains a reference to the given fuzzing context.
|
|
*
|
|
* @returns New reference count on success.
|
|
* @param hFuzzCtx Handle of the fuzzing context.
|
|
*/
|
|
RTDECL(uint32_t) RTFuzzCtxRetain(RTFUZZCTX hFuzzCtx);
|
|
|
|
/**
|
|
* Releases a reference from the given fuzzing context, destroying it when reaching 0.
|
|
*
|
|
* @returns New reference count on success, 0 if the fuzzing context got destroyed.
|
|
* @param hFuzzCtx Handle of the fuzzing context.
|
|
*/
|
|
RTDECL(uint32_t) RTFuzzCtxRelease(RTFUZZCTX hFuzzCtx);
|
|
|
|
/**
|
|
* Queries statistics about the given fuzzing context.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzCtx Handle of the fuzzing context.
|
|
* @param pStats Where to store the stats on success.
|
|
*/
|
|
RTDECL(int) RTFuzzCtxQueryStats(RTFUZZCTX hFuzzCtx, PRTFUZZCTXSTATS pStats);
|
|
|
|
/**
|
|
* Exports the given fuzzing context state.
|
|
*
|
|
* @returns IPRT statuse code
|
|
* @param hFuzzCtx The fuzzing context to export.
|
|
* @param pfnExport Export callback.
|
|
* @param pvUser Opaque user data to pass to the callback.
|
|
*/
|
|
RTDECL(int) RTFuzzCtxStateExport(RTFUZZCTX hFuzzCtx, PFNRTFUZZCTXEXPORT pfnExport, void *pvUser);
|
|
|
|
/**
|
|
* Exports the given fuzzing context state to memory allocating the buffer.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzCtx The fuzzing context to export.
|
|
* @param ppvState Where to store the pointer to the memory containing state on success.
|
|
* Free with RTMemFree().
|
|
* @param pcbState Where to store the size of the state in bytes.
|
|
*/
|
|
RTDECL(int) RTFuzzCtxStateExportToMem(RTFUZZCTX hFuzzCtx, void **ppvState, size_t *pcbState);
|
|
|
|
/**
|
|
* Exports the given fuzzing context state to the given file.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzCtx The fuzzing context to export.
|
|
* @param pszFilename The file to save the state to.
|
|
*/
|
|
RTDECL(int) RTFuzzCtxStateExportToFile(RTFUZZCTX hFuzzCtx, const char *pszFilename);
|
|
|
|
/**
|
|
* Adds a new seed to the input corpus of the given fuzzing context.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzCtx The fuzzing context handle.
|
|
* @param pvInput The pointer to the input buffer.
|
|
* @param cbInput Size of the input buffer.
|
|
*/
|
|
RTDECL(int) RTFuzzCtxCorpusInputAdd(RTFUZZCTX hFuzzCtx, const void *pvInput, size_t cbInput);
|
|
|
|
/**
|
|
* Adds a new seed to the input corpus of the given fuzzing context - extended version.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzCtx The fuzzing context handle.
|
|
* @param pvInput The pointer to the input buffer.
|
|
* @param cbInput Size of the input buffer.
|
|
* @param offMutStart Start offset at which a mutation can happen.
|
|
* @param cbMutRange Size of the range in bytes where a mutation can happen,
|
|
* use UINT64_MAX to allow mutations till the end of the input.
|
|
*/
|
|
RTDECL(int) RTFuzzCtxCorpusInputAddEx(RTFUZZCTX hFuzzCtx, const void *pvInput, size_t cbInput,
|
|
uint64_t offMutStart, uint64_t cbMutRange);
|
|
|
|
/**
|
|
* Adds a new seed to the input corpus of the given fuzzing context from the given file.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzCtx The fuzzing context handle.
|
|
* @param pszFilename The filename to load the seed from.
|
|
*/
|
|
RTDECL(int) RTFuzzCtxCorpusInputAddFromFile(RTFUZZCTX hFuzzCtx, const char *pszFilename);
|
|
|
|
/**
|
|
* Adds a new seed to the input corpus of the given fuzzing context from the given file - extended version.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzCtx The fuzzing context handle.
|
|
* @param pszFilename The filename to load the seed from.
|
|
* @param offMutStart Start offset at which a mutation can happen.
|
|
* @param cbMutRange Size of the range in bytes where a mutation can happen,
|
|
* use UINT64_MAX to allow mutations till the end of the input.
|
|
*/
|
|
RTDECL(int) RTFuzzCtxCorpusInputAddFromFileEx(RTFUZZCTX hFuzzCtx, const char *pszFilename,
|
|
uint64_t offMutStart, uint64_t cbMutRange);
|
|
|
|
/**
|
|
* Adds a new seed to the input corpus of the given fuzzing context from the given VFS file.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzCtx The fuzzing context handle.
|
|
* @param hVfsFile The VFS file handle to load the seed from.
|
|
*/
|
|
RTDECL(int) RTFuzzCtxCorpusInputAddFromVfsFile(RTFUZZCTX hFuzzCtx, RTVFSFILE hVfsFile);
|
|
|
|
/**
|
|
* Adds a new seed to the input corpus of the given fuzzing context from the given VFS file - extended version.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzCtx The fuzzing context handle.
|
|
* @param hVfsFile The VFS file handle to load the seed from.
|
|
* @param offMutStart Start offset at which a mutation can happen.
|
|
* @param cbMutRange Size of the range in bytes where a mutation can happen,
|
|
* use UINT64_MAX to allow mutations till the end of the input.
|
|
*/
|
|
RTDECL(int) RTFuzzCtxCorpusInputAddFromVfsFileEx(RTFUZZCTX hFuzzCtx, RTVFSFILE hVfsFile,
|
|
uint64_t offMutStart, uint64_t cbMutRange);
|
|
|
|
/**
|
|
* Adds a new seed to the input corpus of the given fuzzing context from the given VFS I/O stream.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzCtx The fuzzing context handle.
|
|
* @param hVfsIos The VFS I/O stream handle to load the seed from.
|
|
*/
|
|
RTDECL(int) RTFuzzCtxCorpusInputAddFromVfsIoStrm(RTFUZZCTX hFuzzCtx, RTVFSIOSTREAM hVfsIos);
|
|
|
|
/**
|
|
* Adds a new seed to the input corpus of the given fuzzing context from the given VFS I/O stream - extended version.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzCtx The fuzzing context handle.
|
|
* @param hVfsIos The VFS I/O stream handle to load the seed from.
|
|
* @param offMutStart Start offset at which a mutation can happen.
|
|
* @param cbMutRange Size of the range in bytes where a mutation can happen,
|
|
* use UINT64_MAX to allow mutations till the end of the input.
|
|
*/
|
|
RTDECL(int) RTFuzzCtxCorpusInputAddFromVfsIoStrmEx(RTFUZZCTX hFuzzCtx, RTVFSIOSTREAM hVfsIos,
|
|
uint64_t offMutStart, uint64_t cbMutRange);
|
|
|
|
/**
|
|
* Adds new seeds to the input corpus of the given fuzzing context from the given directory.
|
|
*
|
|
* Will only process regular files, i.e. ignores directories, symbolic links, devices, fifos
|
|
* and such.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzCtx The fuzzing context handle.
|
|
* @param pszDirPath The directory to load seeds from.
|
|
*/
|
|
RTDECL(int) RTFuzzCtxCorpusInputAddFromDirPath(RTFUZZCTX hFuzzCtx, const char *pszDirPath);
|
|
|
|
/**
|
|
* Restricts the maximum input size to generate by the fuzzing context.
|
|
*
|
|
* @returns IPRT status code
|
|
* @param hFuzzCtx The fuzzing context handle.
|
|
* @param cbMax Maximum input size in bytes.
|
|
*/
|
|
RTDECL(int) RTFuzzCtxCfgSetInputSeedMaximum(RTFUZZCTX hFuzzCtx, size_t cbMax);
|
|
|
|
/**
|
|
* Returns the maximum input size of the given fuzzing context.
|
|
*
|
|
* @returns Maximum input size generated in bytes.
|
|
* @param hFuzzCtx The fuzzing context handle.
|
|
*/
|
|
RTDECL(size_t) RTFuzzCtxCfgGetInputSeedMaximum(RTFUZZCTX hFuzzCtx);
|
|
|
|
/**
|
|
* Sets flags controlling the behavior of the fuzzing context.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzCtx The fuzzing context handle.
|
|
* @param fFlags Flags controlling the fuzzing context, RTFUZZCTX_F_XXX.
|
|
*/
|
|
RTDECL(int) RTFuzzCtxCfgSetBehavioralFlags(RTFUZZCTX hFuzzCtx, uint32_t fFlags);
|
|
|
|
/**
|
|
* Returns the current set behavioral flags for the given fuzzing context.
|
|
*
|
|
* @returns Behavioral flags of the given fuzzing context.
|
|
* @param hFuzzCtx The fuzzing context handle.
|
|
*/
|
|
RTDECL(uint32_t) RTFuzzCfgGetBehavioralFlags(RTFUZZCTX hFuzzCtx);
|
|
|
|
/**
|
|
* Sets the temporary directory used by the fuzzing context.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzCtx The fuzzing context handle.
|
|
* @param pszPathTmp The directory for the temporary state.
|
|
*/
|
|
RTDECL(int) RTFuzzCtxCfgSetTmpDirectory(RTFUZZCTX hFuzzCtx, const char *pszPathTmp);
|
|
|
|
/**
|
|
* Returns the current temporary directory.
|
|
*
|
|
* @returns Current temporary directory.
|
|
* @param hFuzzCtx The fuzzing context handle.
|
|
*/
|
|
RTDECL(const char *) RTFuzzCtxCfgGetTmpDirectory(RTFUZZCTX hFuzzCtx);
|
|
|
|
/**
|
|
* Sets the range in which a particular input can get mutated.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzCtx The fuzzing context handle.
|
|
* @param offStart Start offset at which a mutation can happen.
|
|
* @param cbRange Size of the range in bytes where a mutation can happen,
|
|
* use UINT64_MAX to allow mutations till the end of the input.
|
|
*/
|
|
RTDECL(int) RTFuzzCtxCfgSetMutationRange(RTFUZZCTX hFuzzCtx, uint64_t offStart, uint64_t cbRange);
|
|
|
|
/**
|
|
* Reseeds the PRNG of the given fuzzing context.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzCtx The fuzzing context handle.
|
|
* @param uSeed The new seed.
|
|
*/
|
|
RTDECL(int) RTFuzzCtxReseed(RTFUZZCTX hFuzzCtx, uint64_t uSeed);
|
|
|
|
/**
|
|
* Generates a new input from the given fuzzing context and returns it.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzCtx The fuzzing context handle.
|
|
* @param phFuzzInput Where to store the handle to the fuzzed input on success.
|
|
*/
|
|
RTDECL(int) RTFuzzCtxInputGenerate(RTFUZZCTX hFuzzCtx, PRTFUZZINPUT phFuzzInput);
|
|
|
|
|
|
/**
|
|
* Retains a reference to the given fuzzing input handle.
|
|
*
|
|
* @returns New reference count on success.
|
|
* @param hFuzzInput The fuzzing input handle.
|
|
*/
|
|
RTDECL(uint32_t) RTFuzzInputRetain(RTFUZZINPUT hFuzzInput);
|
|
|
|
/**
|
|
* Releases a reference from the given fuzzing input handle, destroying it when reaching 0.
|
|
*
|
|
* @returns New reference count on success, 0 if the fuzzing input got destroyed.
|
|
* @param hFuzzInput The fuzzing input handle.
|
|
*/
|
|
RTDECL(uint32_t) RTFuzzInputRelease(RTFUZZINPUT hFuzzInput);
|
|
|
|
/**
|
|
* Queries the data pointer and size of the given fuzzed input blob.
|
|
*
|
|
* @returns IPRT status code
|
|
* @param hFuzzInput The fuzzing input handle.
|
|
* @param ppv Where to store the pointer to the input data on success.
|
|
* @param pcb Where to store the size of the input data on success.
|
|
*/
|
|
RTDECL(int) RTFuzzInputQueryBlobData(RTFUZZINPUT hFuzzInput, void **ppv, size_t *pcb);
|
|
|
|
/**
|
|
* Processes the given data stream for a streamed fuzzing context.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzInput The fuzzing input handle.
|
|
* @param pvBuf The data buffer.
|
|
* @param cbBuf Size of the buffer.
|
|
*/
|
|
RTDECL(int) RTFuzzInputMutateStreamData(RTFUZZINPUT hFuzzInput, void *pvBuf, size_t cbBuf);
|
|
|
|
/**
|
|
* Queries the string of the MD5 digest for the given fuzzed input.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @retval VERR_BUFFER_OVERFLOW if the size of the string buffer is not sufficient.
|
|
* @param hFuzzInput The fuzzing input handle.
|
|
* @param pszDigest Where to store the digest string and a closing terminator.
|
|
* @param cchDigest Size of the string buffer in characters (including the zero terminator).
|
|
*/
|
|
RTDECL(int) RTFuzzInputQueryDigestString(RTFUZZINPUT hFuzzInput, char *pszDigest, size_t cchDigest);
|
|
|
|
/**
|
|
* Writes the given fuzzing input to the given file.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzInput The fuzzing input handle.
|
|
* @param pszFilename The filename to store the input to.
|
|
*/
|
|
RTDECL(int) RTFuzzInputWriteToFile(RTFUZZINPUT hFuzzInput, const char *pszFilename);
|
|
|
|
/**
|
|
* Adds the given fuzzed input to the input corpus of the owning context.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @retval VERR_ALREADY_EXISTS if the input exists already.
|
|
* @param hFuzzInput The fuzzing input handle.
|
|
*/
|
|
RTDECL(int) RTFuzzInputAddToCtxCorpus(RTFUZZINPUT hFuzzInput);
|
|
|
|
/**
|
|
* Removes the given fuzzed input from the input corpus of the owning context.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @retval VERR_NOT_FOUND if the input is not part of the corpus.
|
|
* @param hFuzzInput The fuzzing input handle.
|
|
*/
|
|
RTDECL(int) RTFuzzInputRemoveFromCtxCorpus(RTFUZZINPUT hFuzzInput);
|
|
|
|
|
|
/**
|
|
* Creates a fuzzing config from the given VFS file handle.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param phFuzzCfg Where to store the handle to the fuzzing config on success.
|
|
* @param hVfsFile The VFS file to use (retained).
|
|
* @param pErrInfo Where to store extended error info. Optional.
|
|
*/
|
|
RTDECL(int) RTFuzzCfgCreateFromVfsFile(PRTFUZZCFG phFuzzCfg, RTVFSFILE hVfsFile, PRTERRINFO pErrInfo);
|
|
|
|
/**
|
|
* Creates a fuzzing config from the given file path.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param phFuzzCfg Where to store the handle to the fuzzing config on success.
|
|
* @param pszFilename Filename to load the config from.
|
|
* @param pErrInfo Where to store extended error info. Optional.
|
|
*/
|
|
RTDECL(int) RTFuzzCfgCreateFromFile(PRTFUZZCFG phFuzzCfg, const char *pszFilename, PRTERRINFO pErrInfo);
|
|
|
|
/**
|
|
* Retains a reference to the given fuzzing config.
|
|
*
|
|
* @returns New reference count on success.
|
|
* @param hFuzzCfg Handle of the fuzzing config.
|
|
*/
|
|
RTDECL(uint32_t) RTFuzzCfgRetain(RTFUZZCFG hFuzzCfg);
|
|
|
|
/**
|
|
* Releases a reference from the given fuzzing config, destroying it when reaching 0.
|
|
*
|
|
* @returns New reference count on success, 0 if the fuzzing config got destroyed.
|
|
* @param hFuzzCfg Handle of the fuzzing config.
|
|
*/
|
|
RTDECL(uint32_t) RTFuzzCfgRelease(RTFUZZCFG hFuzzCfg);
|
|
|
|
/**
|
|
* Imports the given fuzzing config into a previously created fuzzing context.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzCfg Handle of the fuzzing config.
|
|
* @param hFuzzCtx Handle of the fuzzing context.
|
|
* @param fFlags Flags controlling what to import exactly, combination of RTFUZZCFG_IMPORT_F_XXX.
|
|
*/
|
|
RTDECL(int) RTFuzzCfgImport(RTFUZZCFG hFuzzCfg, RTFUZZCTX hFuzzCtx, uint32_t fFlags);
|
|
|
|
/**
|
|
* Queries the custom config for the controller of the fuzzing process.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzCfg Handle of the fuzzing config.
|
|
* @param phVfsFile Where to store the handle of the VFS file containing the custom config.
|
|
*/
|
|
RTDECL(int) RTFuzzCfgQueryCustomCfg(RTFUZZCFG hFuzzCfg, PRTVFSFILE phVfsFile);
|
|
|
|
|
|
/**
|
|
* Creates a new fuzzed target recorder.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param phFuzzTgtRec Where to store the handle to the fuzzed target recorder on success.
|
|
* @param fRecFlags What to take into account when checking for equal states.
|
|
* Combination of RTFUZZTGT_REC_STATE_F_*
|
|
*/
|
|
RTDECL(int) RTFuzzTgtRecorderCreate(PRTFUZZTGTREC phFuzzTgtRec, uint32_t fRecFlags);
|
|
|
|
/**
|
|
* Retains a reference to the given fuzzed target recorder handle.
|
|
*
|
|
* @returns New reference count on success.
|
|
* @param hFuzzTgtRec The fuzzed target recorder handle.
|
|
*/
|
|
RTDECL(uint32_t) RTFuzzTgtRecorderRetain(RTFUZZTGTREC hFuzzTgtRec);
|
|
|
|
/**
|
|
* Releases a reference from the given fuzzed target recorder handle, destroying it when reaching 0.
|
|
*
|
|
* @returns New reference count on success, 0 if the fuzzed target recorder got destroyed.
|
|
* @param hFuzzTgtRec The fuzzed target recorder handle.
|
|
*/
|
|
RTDECL(uint32_t) RTFuzzTgtRecorderRelease(RTFUZZTGTREC hFuzzTgtRec);
|
|
|
|
/**
|
|
* Creates a new empty fuzzed target state.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzTgtRec The fuzzed target recorder handle.
|
|
* @param phFuzzTgtState Where to store the handle to the fuzzed target state on success.
|
|
*/
|
|
RTDECL(int) RTFuzzTgtRecorderCreateNewState(RTFUZZTGTREC hFuzzTgtRec, PRTFUZZTGTSTATE phFuzzTgtState);
|
|
|
|
/**
|
|
* Retains a reference to the given fuzzed target state handle.
|
|
*
|
|
* @returns New reference count on success.
|
|
* @param hFuzzTgtState The fuzzed target state handle.
|
|
*/
|
|
RTDECL(uint32_t) RTFuzzTgtStateRetain(RTFUZZTGTSTATE hFuzzTgtState);
|
|
|
|
/**
|
|
* Releases a reference from the given fuzzed target state handle, destroying it when reaching 0.
|
|
*
|
|
* @returns New reference count on success, 0 if the fuzzed target recorder got destroyed.
|
|
* @param hFuzzTgtState The fuzzed target state handle.
|
|
*/
|
|
RTDECL(uint32_t) RTFuzzTgtStateRelease(RTFUZZTGTSTATE hFuzzTgtState);
|
|
|
|
/**
|
|
* Resets the given fuzzed target state to an empty state (keeping allocated memory).
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzTgtState The fuzzed target state handle.
|
|
*
|
|
* @note Useful when the state is not added to the recorded set to avoid allocating memory.
|
|
*/
|
|
RTDECL(int) RTFuzzTgtStateReset(RTFUZZTGTSTATE hFuzzTgtState);
|
|
|
|
/**
|
|
* Finalizes the given fuzzed target state, making it readonly.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzTgtState The fuzzed target state handle.
|
|
*/
|
|
RTDECL(int) RTFuzzTgtStateFinalize(RTFUZZTGTSTATE hFuzzTgtState);
|
|
|
|
/**
|
|
* Adds the given state to the set for the owning target recorder.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @retval VERR_ALREADY_EXISTS if the state is already existing in the recorder set.
|
|
* @param hFuzzTgtState The fuzzed target state handle.
|
|
*
|
|
* @note This also finalizes the target state if not already done.
|
|
*/
|
|
RTDECL(int) RTFuzzTgtStateAddToRecorder(RTFUZZTGTSTATE hFuzzTgtState);
|
|
|
|
/**
|
|
* Appends the given stdout output to the given target state.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzTgtState The fuzzed target state handle.
|
|
* @param pvStdOut Pointer to the stdout data buffer.
|
|
* @param cbStdOut Size of the stdout data buffer in bytes.
|
|
*/
|
|
RTDECL(int) RTFuzzTgtStateAppendStdoutFromBuf(RTFUZZTGTSTATE hFuzzTgtState, const void *pvStdOut, size_t cbStdOut);
|
|
|
|
/**
|
|
* Appends the given stderr output to the given target state.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzTgtState The fuzzed target state handle.
|
|
* @param pvStdErr Pointer to the stderr data buffer.
|
|
* @param cbStdErr Size of the stderr data buffer in bytes.
|
|
*/
|
|
RTDECL(int) RTFuzzTgtStateAppendStderrFromBuf(RTFUZZTGTSTATE hFuzzTgtState, const void *pvStdErr, size_t cbStdErr);
|
|
|
|
/**
|
|
* Appends the given stdout output to the given target state, reading from the given pipe.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzTgtState The fuzzed target state handle.
|
|
* @param hPipe The stdout pipe to read the data from.
|
|
*/
|
|
RTDECL(int) RTFuzzTgtStateAppendStdoutFromPipe(RTFUZZTGTSTATE hFuzzTgtState, RTPIPE hPipe);
|
|
|
|
/**
|
|
* Appends the given stderr output to the given target state, reading from the given pipe.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzTgtState The fuzzed target state handle.
|
|
* @param hPipe The stdout pipe to read the data from.
|
|
*/
|
|
RTDECL(int) RTFuzzTgtStateAppendStderrFromPipe(RTFUZZTGTSTATE hFuzzTgtState, RTPIPE hPipe);
|
|
|
|
/**
|
|
* Adds the SanCov coverage information from the given file to the given target state.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzTgtState The fuzzed target state handle.
|
|
* @param pszFilename Filename of the coverage report.
|
|
*/
|
|
RTDECL(int) RTFuzzTgtStateAddSanCovReportFromFile(RTFUZZTGTSTATE hFuzzTgtState, const char *pszFilename);
|
|
|
|
/**
|
|
* Adds the given process status to the target state.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzTgtState The fuzzed target state handle.
|
|
* @param pProcSts The process status to add.
|
|
*/
|
|
RTDECL(int) RTFuzzTgtStateAddProcSts(RTFUZZTGTSTATE hFuzzTgtState, PCRTPROCSTATUS pProcSts);
|
|
|
|
/**
|
|
* Dumps the given target state to the given directory.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzTgtState The fuzzed target state handle.
|
|
* @param pszDirPath The directory to dump to.
|
|
*/
|
|
RTDECL(int) RTFuzzTgtStateDumpToDir(RTFUZZTGTSTATE hFuzzTgtState, const char *pszDirPath);
|
|
|
|
|
|
/**
|
|
* Fuzzed binary input channel.
|
|
*/
|
|
typedef enum RTFUZZOBSINPUTCHAN
|
|
{
|
|
/** Invalid. */
|
|
RTFUZZOBSINPUTCHAN_INVALID = 0,
|
|
/** File input. */
|
|
RTFUZZOBSINPUTCHAN_FILE,
|
|
/** Input over stdin. */
|
|
RTFUZZOBSINPUTCHAN_STDIN,
|
|
/** The binary is a fuzzing aware client using the
|
|
* specified protocol over stdin/stdout. */
|
|
RTFUZZOBSINPUTCHAN_FUZZING_AWARE_CLIENT,
|
|
/** TCP server. */
|
|
RTFUZZOBSINPUTCHAN_TCP_SERVER,
|
|
/** TCP client. */
|
|
RTFUZZOBSINPUTCHAN_TCP_CLIENT,
|
|
/** UDP server. */
|
|
RTFUZZOBSINPUTCHAN_UDP_SERVER,
|
|
/** UDP client. */
|
|
RTFUZZOBSINPUTCHAN_UDP_CLIENT,
|
|
/** 32bit hack. */
|
|
RTFUZZOBSINPUTCHAN_32BIT_HACK = 0x7fffffff
|
|
} RTFUZZOBSINPUTCHAN;
|
|
|
|
/**
|
|
* Fuzzing observer statistics.
|
|
*/
|
|
typedef struct RTFUZZOBSSTATS
|
|
{
|
|
/** Number of fuzzed inputs per second. */
|
|
uint32_t cFuzzedInputsPerSec;
|
|
/** Number of overall fuzzed inputs. */
|
|
uint32_t cFuzzedInputs;
|
|
/** Number of observed hangs. */
|
|
uint32_t cFuzzedInputsHang;
|
|
/** Number of observed crashes. */
|
|
uint32_t cFuzzedInputsCrash;
|
|
} RTFUZZOBSSTATS;
|
|
/** Pointer to a fuzzing observer statistics record. */
|
|
typedef RTFUZZOBSSTATS *PRTFUZZOBSSTATS;
|
|
|
|
/**
|
|
* Creates a new fuzzing observer.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param phFuzzObs Where to store the fuzzing observer handle on success.
|
|
* @param enmType Fuzzing context data type.
|
|
* @param fTgtRecFlags Flags to pass to the target state recorder, see RTFuzzTgtRecorderCreate().
|
|
*/
|
|
RTDECL(int) RTFuzzObsCreate(PRTFUZZOBS phFuzzObs, RTFUZZCTXTYPE enmType, uint32_t fTgtRecFlags);
|
|
|
|
/**
|
|
* Destroys a previously created fuzzing observer.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzObs The fuzzing observer handle.
|
|
*/
|
|
RTDECL(int) RTFuzzObsDestroy(RTFUZZOBS hFuzzObs);
|
|
|
|
/**
|
|
* Queries the internal fuzzing context of the given observer.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzObs The fuzzing observer handle.
|
|
* @param phFuzzCtx Where to store the handle to the fuzzing context on success.
|
|
*
|
|
* @note The fuzzing context handle should be released with RTFuzzCtxRelease() when not used anymore.
|
|
*/
|
|
RTDECL(int) RTFuzzObsQueryCtx(RTFUZZOBS hFuzzObs, PRTFUZZCTX phFuzzCtx);
|
|
|
|
/**
|
|
* Queries the current statistics for the given fuzzing observer.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzObs The fuzzing observer handle.
|
|
* @param pStats Where to store the statistics to.
|
|
*/
|
|
RTDECL(int) RTFuzzObsQueryStats(RTFUZZOBS hFuzzObs, PRTFUZZOBSSTATS pStats);
|
|
|
|
/**
|
|
* Sets the temp directory for the given fuzzing observer.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzObs The fuzzing observer handle.
|
|
* @param pszTmp The temp directory path.
|
|
*/
|
|
RTDECL(int) RTFuzzObsSetTmpDirectory(RTFUZZOBS hFuzzObs, const char *pszTmp);
|
|
|
|
/**
|
|
* Sets the directory to store results to.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzObs The fuzzing observer handle.
|
|
* @param pszResults The path to store the results.
|
|
*/
|
|
RTDECL(int) RTFuzzObsSetResultDirectory(RTFUZZOBS hFuzzObs, const char *pszResults);
|
|
|
|
/**
|
|
* Sets the binary to run for each fuzzed input.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzObs The fuzzing observer handle.
|
|
* @param pszBinary The binary path.
|
|
* @param enmInputChan The input channel to use.
|
|
*/
|
|
RTDECL(int) RTFuzzObsSetTestBinary(RTFUZZOBS hFuzzObs, const char *pszBinary, RTFUZZOBSINPUTCHAN enmInputChan);
|
|
|
|
/**
|
|
* Sets additional arguments to run the binary with.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzObs The fuzzing observer handle.
|
|
* @param papszArgs Pointer to the array of arguments.
|
|
* @param cArgs Number of arguments.
|
|
*/
|
|
RTDECL(int) RTFuzzObsSetTestBinaryArgs(RTFUZZOBS hFuzzObs, const char * const *papszArgs, unsigned cArgs);
|
|
|
|
/**
|
|
* Sets an environment block to run the binary in.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzObs The fuzzing observer handle.
|
|
* @param hEnv The environment block to set for the test binary.
|
|
* Use RTENV_DEFAULT for the default process environment or
|
|
* NULL for an empty environment.
|
|
*
|
|
* @note Upon successful return of this function the observer has taken ownership over the
|
|
* environment block and can alter it in unexpected ways. It also destroys the environment
|
|
* block when the observer gets destroyed. So don't touch the environment block after
|
|
* calling this function.
|
|
*/
|
|
RTDECL(int) RTFuzzObsSetTestBinaryEnv(RTFUZZOBS hFuzzObs, RTENV hEnv);
|
|
|
|
/**
|
|
* Makes the observer aware of any configured sanitizers for the test binary.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzObs The fuzzing observer handle.
|
|
* @param fSanitizers Bitmask of compiled and enabled sanitiziers in the
|
|
* target binary.
|
|
*/
|
|
RTDECL(int) RTFuzzObsSetTestBinarySanitizers(RTFUZZOBS hFuzzObs, uint32_t fSanitizers);
|
|
|
|
/**
|
|
* Sets maximum timeout until a process is considered hung and killed.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzObs The fuzzing observer handle.
|
|
* @param msTimeoutMax The maximum number of milliseconds to wait until the process
|
|
* is considered hung.
|
|
*/
|
|
RTDECL(int) RTFuzzObsSetTestBinaryTimeout(RTFUZZOBS hFuzzObs, RTMSINTERVAL msTimeoutMax);
|
|
|
|
/**
|
|
* Starts fuzzing the set binary.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzObs The fuzzing observer handle.
|
|
* @param cProcs Number of processes to run simulteanously,
|
|
* 0 will create as many processes as there are CPUs available.
|
|
*/
|
|
RTDECL(int) RTFuzzObsExecStart(RTFUZZOBS hFuzzObs, uint32_t cProcs);
|
|
|
|
/**
|
|
* Stops the fuzzing process.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hFuzzObs The fuzzing observer handle.
|
|
*/
|
|
RTDECL(int) RTFuzzObsExecStop(RTFUZZOBS hFuzzObs);
|
|
|
|
|
|
/**
|
|
* A fuzzing master program.
|
|
*
|
|
* @returns Program exit code.
|
|
*
|
|
* @param cArgs The number of arguments.
|
|
* @param papszArgs The argument vector. (Note that this may be
|
|
* reordered, so the memory must be writable.)
|
|
*/
|
|
RTR3DECL(RTEXITCODE) RTFuzzCmdMaster(unsigned cArgs, char **papszArgs);
|
|
|
|
|
|
/**
|
|
* Client input consumption callback.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @retval VINF_SUCCESS the fuzzed code accepted the input.
|
|
* @retval VERR_* the client rejected the input while parsing it.
|
|
* @param pvBuf The buffer containing the input data.
|
|
* @param cbBuf Size of the buffer in bytes.
|
|
* @param pvUser Opaque user data.
|
|
*/
|
|
typedef DECLCALLBACKTYPE(int, FNFUZZCLIENTCONSUME,(const void *pvBuf, size_t cbBuf, void *pvUser));
|
|
/** Pointer to a client consumption callback. */
|
|
typedef FNFUZZCLIENTCONSUME *PFNFUZZCLIENTCONSUME;
|
|
|
|
/**
|
|
* A fuzzing client program for more efficient fuzzing.
|
|
*
|
|
* @returns Program exit code.
|
|
*
|
|
* @param cArgs The number of arguments.
|
|
* @param papszArgs The argument vector. (Note that this may be
|
|
* reordered, so the memory must be writable.)
|
|
* @param pfnConsume Input data consumption callback.
|
|
* @param pvUser Opaque user data to pass to the callback.
|
|
*/
|
|
RTR3DECL(RTEXITCODE) RTFuzzCmdFuzzingClient(unsigned cArgs, char **papszArgs, PFNFUZZCLIENTCONSUME pfnConsume, void *pvUser);
|
|
/** @} */
|
|
|
|
RT_C_DECLS_END
|
|
|
|
#endif /* !IPRT_INCLUDED_fuzz_h */
|
|
|