fuzz.h

Last change on this file was 106061, checked in by vboxsync, 2 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-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

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: