VirtualBox

source: vbox/trunk/include/iprt/fuzz.h@ 103224

Last change on this file since 103224 was 98103, checked in by vboxsync, 21 months ago

Copyright year updates by scm.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 36.0 KB
Line 
1/** @file
2 * IPRT - Fuzzing framework
3 */
4
5/*
6 * Copyright (C) 2018-2023 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
46RT_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. */
55typedef struct RTFUZZCTXINT *RTFUZZCTX;
56/** Pointer to a fuzzer context handle. */
57typedef RTFUZZCTX *PRTFUZZCTX;
58/** NIL fuzzer context handle. */
59#define NIL_RTFUZZCTX ((RTFUZZCTX)~(uintptr_t)0)
60/** A fuzzer input handle. */
61typedef struct RTFUZZINPUTINT *RTFUZZINPUT;
62/** Pointer to a fuzzer input handle. */
63typedef RTFUZZINPUT *PRTFUZZINPUT;
64/** NIL fuzzer input handle. */
65#define NIL_RTFUZZINPUT ((RTFUZZINPUT)~(uintptr_t)0)
66
67
68/** A fuzzer config handle. */
69typedef struct RTFUZZCFGINT *RTFUZZCFG;
70/** Pointer to a fuzzer config handle. */
71typedef RTFUZZCFG *PRTFUZZCFG;
72/** NIL fuzzer config handle. */
73#define NIL_RTFUZZCFG ((RTFUZZCFG)~(uintptr_t)0)
74
75
76/** A fuzzer target recorder handler. */
77typedef struct RTFUZZTGTRECINT *RTFUZZTGTREC;
78/** Pointer to a fuzzer target recorder handle. */
79typedef RTFUZZTGTREC *PRTFUZZTGTREC;
80/** NIL fuzzer target recorder handle. */
81#define NIL_RTFUZZTGTREC ((RTFUZZTGTREC)~(uintptr_t)0)
82/** A fuzzed target state handle. */
83typedef struct RTFUZZTGTSTATEINT *RTFUZZTGTSTATE;
84/** Pointer to a fuzzed target state handle. */
85typedef RTFUZZTGTSTATE *PRTFUZZTGTSTATE;
86/** NIL fuzzed target state handle. */
87#define NIL_RTFUZZTGTSTATE ((RTFUZZTGTSTATE)~(uintptr_t)0)
88
89
90/** Fuzzing observer handle. */
91typedef struct RTFUZZOBSINT *RTFUZZOBS;
92/** Pointer to a fuzzing observer handle. */
93typedef RTFUZZOBS *PRTFUZZOBS;
94/** NIL fuzzing observer handle. */
95#define NIL_RTFUZZOBS ((RTFUZZOBS)~(uintptr_t)0)
96
97
98/**
99 * Fuzzing context type.
100 */
101typedef 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 */
117typedef 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. */
125typedef 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 */
182typedef DECLCALLBACKTYPE(int, FNRTFUZZCTXEXPORT,(RTFUZZCTX hFuzzCtx, const void *pvBuf, size_t cbWrite, void *pvUser));
183/** Pointer to a fuzzing context state export callback. */
184typedef 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 */
196typedef DECLCALLBACKTYPE(int, FNRTFUZZCTXIMPORT,(RTFUZZCTX hFuzzCtx, void *pvBuf, size_t cbRead, size_t *pcbRead, void *pvUser));
197/** Pointer to a fuzzing context state export callback. */
198typedef 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 */
208RTDECL(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 */
218RTDECL(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 */
228RTDECL(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 */
237RTDECL(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 */
245RTDECL(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 */
253RTDECL(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 */
262RTDECL(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 */
272RTDECL(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 */
283RTDECL(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 */
292RTDECL(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 */
302RTDECL(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 */
315RTDECL(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 */
325RTDECL(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 */
337RTDECL(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 */
347RTDECL(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 */
359RTDECL(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 */
369RTDECL(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 */
381RTDECL(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 */
394RTDECL(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 */
403RTDECL(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 */
411RTDECL(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 */
420RTDECL(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 */
428RTDECL(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 */
437RTDECL(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 */
445RTDECL(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 */
456RTDECL(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 */
465RTDECL(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 */
474RTDECL(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 */
483RTDECL(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 */
491RTDECL(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 */
501RTDECL(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 */
511RTDECL(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 */
522RTDECL(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 */
531RTDECL(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 */
540RTDECL(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 */
549RTDECL(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 */
560RTDECL(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 */
570RTDECL(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 */
578RTDECL(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 */
586RTDECL(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 */
596RTDECL(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 */
605RTDECL(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 */
616RTDECL(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 */
624RTDECL(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 */
632RTDECL(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 */
641RTDECL(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 */
649RTDECL(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 */
657RTDECL(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 */
667RTDECL(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 */
675RTDECL(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 */
686RTDECL(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 */
696RTDECL(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 */
706RTDECL(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 */
715RTDECL(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 */
724RTDECL(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 */
733RTDECL(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 */
742RTDECL(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 */
751RTDECL(int) RTFuzzTgtStateDumpToDir(RTFUZZTGTSTATE hFuzzTgtState, const char *pszDirPath);
752
753
754/**
755 * Fuzzed binary input channel.
756 */
757typedef 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 */
783typedef 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. */
795typedef 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 */
805RTDECL(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 */
813RTDECL(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 */
824RTDECL(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 */
833RTDECL(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 */
842RTDECL(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 */
851RTDECL(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 */
861RTDECL(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 */
871RTDECL(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 */
887RTDECL(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 */
897RTDECL(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 */
907RTDECL(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 */
917RTDECL(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 */
925RTDECL(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 */
937RTR3DECL(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 */
950typedef DECLCALLBACKTYPE(int, FNFUZZCLIENTCONSUME,(const void *pvBuf, size_t cbBuf, void *pvUser));
951/** Pointer to a client consumption callback. */
952typedef 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 */
965RTR3DECL(RTEXITCODE) RTFuzzCmdFuzzingClient(unsigned cArgs, char **papszArgs, PFNFUZZCLIENTCONSUME pfnConsume, void *pvUser);
966/** @} */
967
968RT_C_DECLS_END
969
970#endif /* !IPRT_INCLUDED_fuzz_h */
971
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette