fuzz.h@ 83266

Last change on this file since 83266 was 83266, checked in by vboxsync, 5 years ago
Runtime/common/fuzz: Add API to specify the range in an input corpus where mutations are allowed, global and per input. Allows fuzzing certain interesting areas which might not be reached that often otherwise
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 31.8 KB

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

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

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

Download in other formats: