fuzz.h@ 82968

Last change on this file since 82968 was 82968, checked in by vboxsync, 5 years ago
Copyright year updates by scm.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 29.1 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 from the given file.
277	*
278	* @returns IPRT status code.
279	* @param hFuzzCtx The fuzzing context handle.
280	* @param pszFilename The filename to load the seed from.
281	*/
282	RTDECL(int) RTFuzzCtxCorpusInputAddFromFile(RTFUZZCTX hFuzzCtx, const char *pszFilename);
283
284	/**
285	* Adds a new seed to the input corpus of the given fuzzing context from the given VFS file.
286	*
287	* @returns IPRT status code.
288	* @param hFuzzCtx The fuzzing context handle.
289	* @param hVfsFile The VFS file handle to load the seed from.
290	*/
291	RTDECL(int) RTFuzzCtxCorpusInputAddFromVfsFile(RTFUZZCTX hFuzzCtx, RTVFSFILE hVfsFile);
292
293	/**
294	* Adds new seeds to the input corpus of the given fuzzing context from the given directory.
295	*
296	* Will only process regular files, i.e. ignores directories, symbolic links, devices, fifos
297	* and such.
298	*
299	* @returns IPRT status code.
300	* @param hFuzzCtx The fuzzing context handle.
301	* @param pszDirPath The directory to load seeds from.
302	*/
303	RTDECL(int) RTFuzzCtxCorpusInputAddFromDirPath(RTFUZZCTX hFuzzCtx, const char *pszDirPath);
304
305	/**
306	* Restricts the maximum input size to generate by the fuzzing context.
307	*
308	* @returns IPRT status code
309	* @param hFuzzCtx The fuzzing context handle.
310	* @param cbMax Maximum input size in bytes.
311	*/
312	RTDECL(int) RTFuzzCtxCfgSetInputSeedMaximum(RTFUZZCTX hFuzzCtx, size_t cbMax);
313
314	/**
315	* Returns the maximum input size of the given fuzzing context.
316	*
317	* @returns Maximum input size generated in bytes.
318	* @param hFuzzCtx The fuzzing context handle.
319	*/
320	RTDECL(size_t) RTFuzzCtxCfgGetInputSeedMaximum(RTFUZZCTX hFuzzCtx);
321
322	/**
323	* Sets flags controlling the behavior of the fuzzing context.
324	*
325	* @returns IPRT status code.
326	* @param hFuzzCtx The fuzzing context handle.
327	* @param fFlags Flags controlling the fuzzing context, RTFUZZCTX_F_XXX.
328	*/
329	RTDECL(int) RTFuzzCtxCfgSetBehavioralFlags(RTFUZZCTX hFuzzCtx, uint32_t fFlags);
330
331	/**
332	* Returns the current set behavioral flags for the given fuzzing context.
333	*
334	* @returns Behavioral flags of the given fuzzing context.
335	* @param hFuzzCtx The fuzzing context handle.
336	*/
337	RTDECL(uint32_t) RTFuzzCfgGetBehavioralFlags(RTFUZZCTX hFuzzCtx);
338
339	/**
340	* Sets the temporary directory used by the fuzzing context.
341	*
342	* @returns IPRT status code.
343	* @param hFuzzCtx The fuzzing context handle.
344	* @param pszPathTmp The directory for the temporary state.
345	*/
346	RTDECL(int) RTFuzzCtxCfgSetTmpDirectory(RTFUZZCTX hFuzzCtx, const char *pszPathTmp);
347
348	/**
349	* Returns the current temporary directory.
350	*
351	* @returns Current temporary directory.
352	* @param hFuzzCtx The fuzzing context handle.
353	*/
354	RTDECL(const char *) RTFuzzCtxCfgGetTmpDirectory(RTFUZZCTX hFuzzCtx);
355
356	/**
357	* Reseeds the PRNG of the given fuzzing context.
358	*
359	* @returns IPRT status code.
360	* @param hFuzzCtx The fuzzing context handle.
361	* @param uSeed The new seed.
362	*/
363	RTDECL(int) RTFuzzCtxReseed(RTFUZZCTX hFuzzCtx, uint64_t uSeed);
364
365	/**
366	* Generates a new input from the given fuzzing context and returns it.
367	*
368	* @returns IPRT status code.
369	* @param hFuzzCtx The fuzzing context handle.
370	* @param phFuzzInput Where to store the handle to the fuzzed input on success.
371	*/
372	RTDECL(int) RTFuzzCtxInputGenerate(RTFUZZCTX hFuzzCtx, PRTFUZZINPUT phFuzzInput);
373
374
375	/**
376	* Retains a reference to the given fuzzing input handle.
377	*
378	* @returns New reference count on success.
379	* @param hFuzzInput The fuzzing input handle.
380	*/
381	RTDECL(uint32_t) RTFuzzInputRetain(RTFUZZINPUT hFuzzInput);
382
383	/**
384	* Releases a reference from the given fuzzing input handle, destroying it when reaching 0.
385	*
386	* @returns New reference count on success, 0 if the fuzzing input got destroyed.
387	* @param hFuzzInput The fuzzing input handle.
388	*/
389	RTDECL(uint32_t) RTFuzzInputRelease(RTFUZZINPUT hFuzzInput);
390
391	/**
392	* Queries the data pointer and size of the given fuzzed input blob.
393	*
394	* @returns IPRT status code
395	* @param hFuzzInput The fuzzing input handle.
396	* @param ppv Where to store the pointer to the input data on success.
397	* @param pcb Where to store the size of the input data on success.
398	*/
399	RTDECL(int) RTFuzzInputQueryBlobData(RTFUZZINPUT hFuzzInput, void *ppv, size_t pcb);
400
401	/**
402	* Processes the given data stream for a streamed fuzzing context.
403	*
404	* @returns IPRT status code.
405	* @param hFuzzInput The fuzzing input handle.
406	* @param pvBuf The data buffer.
407	* @param cbBuf Size of the buffer.
408	*/
409	RTDECL(int) RTFuzzInputMutateStreamData(RTFUZZINPUT hFuzzInput, void *pvBuf, size_t cbBuf);
410
411	/**
412	* Queries the string of the MD5 digest for the given fuzzed input.
413	*
414	* @returns IPRT status code.
415	* @retval VERR_BUFFER_OVERFLOW if the size of the string buffer is not sufficient.
416	* @param hFuzzInput The fuzzing input handle.
417	* @param pszDigest Where to store the digest string and a closing terminator.
418	* @param cchDigest Size of the string buffer in characters (including the zero terminator).
419	*/
420	RTDECL(int) RTFuzzInputQueryDigestString(RTFUZZINPUT hFuzzInput, char *pszDigest, size_t cchDigest);
421
422	/**
423	* Writes the given fuzzing input to the given file.
424	*
425	* @returns IPRT status code.
426	* @param hFuzzInput The fuzzing input handle.
427	* @param pszFilename The filename to store the input to.
428	*/
429	RTDECL(int) RTFuzzInputWriteToFile(RTFUZZINPUT hFuzzInput, const char *pszFilename);
430
431	/**
432	* Adds the given fuzzed input to the input corpus of the owning context.
433	*
434	* @returns IPRT status code.
435	* @retval VERR_ALREADY_EXISTS if the input exists already.
436	* @param hFuzzInput The fuzzing input handle.
437	*/
438	RTDECL(int) RTFuzzInputAddToCtxCorpus(RTFUZZINPUT hFuzzInput);
439
440	/**
441	* Removes the given fuzzed input from the input corpus of the owning context.
442	*
443	* @returns IPRT status code.
444	* @retval VERR_NOT_FOUND if the input is not part of the corpus.
445	* @param hFuzzInput The fuzzing input handle.
446	*/
447	RTDECL(int) RTFuzzInputRemoveFromCtxCorpus(RTFUZZINPUT hFuzzInput);
448
449
450	/**
451	* Creates a new fuzzed target recorder.
452	*
453	* @returns IPRT status code.
454	* @param phFuzzTgtRec Where to store the handle to the fuzzed target recorder on success.
455	* @param fRecFlags What to take into account when checking for equal states.
456	* Combination of RTFUZZTGT_REC_STATE_F_*
457	*/
458	RTDECL(int) RTFuzzTgtRecorderCreate(PRTFUZZTGTREC phFuzzTgtRec, uint32_t fRecFlags);
459
460	/**
461	* Retains a reference to the given fuzzed target recorder handle.
462	*
463	* @returns New reference count on success.
464	* @param hFuzzTgtRec The fuzzed target recorder handle.
465	*/
466	RTDECL(uint32_t) RTFuzzTgtRecorderRetain(RTFUZZTGTREC hFuzzTgtRec);
467
468	/**
469	* Releases a reference from the given fuzzed target recorder handle, destroying it when reaching 0.
470	*
471	* @returns New reference count on success, 0 if the fuzzed target recorder got destroyed.
472	* @param hFuzzTgtRec The fuzzed target recorder handle.
473	*/
474	RTDECL(uint32_t) RTFuzzTgtRecorderRelease(RTFUZZTGTREC hFuzzTgtRec);
475
476	/**
477	* Creates a new empty fuzzed target state.
478	*
479	* @returns IPRT status code.
480	* @param hFuzzTgtRec The fuzzed target recorder handle.
481	* @param phFuzzTgtState Where to store the handle to the fuzzed target state on success.
482	*/
483	RTDECL(int) RTFuzzTgtRecorderCreateNewState(RTFUZZTGTREC hFuzzTgtRec, PRTFUZZTGTSTATE phFuzzTgtState);
484
485	/**
486	* Retains a reference to the given fuzzed target state handle.
487	*
488	* @returns New reference count on success.
489	* @param hFuzzTgtState The fuzzed target state handle.
490	*/
491	RTDECL(uint32_t) RTFuzzTgtStateRetain(RTFUZZTGTSTATE hFuzzTgtState);
492
493	/**
494	* Releases a reference from the given fuzzed target state handle, destroying it when reaching 0.
495	*
496	* @returns New reference count on success, 0 if the fuzzed target recorder got destroyed.
497	* @param hFuzzTgtState The fuzzed target state handle.
498	*/
499	RTDECL(uint32_t) RTFuzzTgtStateRelease(RTFUZZTGTSTATE hFuzzTgtState);
500
501	/**
502	* Resets the given fuzzed target state to an empty state (keeping allocated memory).
503	*
504	* @returns IPRT status code.
505	* @param hFuzzTgtState The fuzzed target state handle.
506	*
507	* @note Useful when the state is not added to the recorded set to avoid allocating memory.
508	*/
509	RTDECL(int) RTFuzzTgtStateReset(RTFUZZTGTSTATE hFuzzTgtState);
510
511	/**
512	* Finalizes the given fuzzed target state, making it readonly.
513	*
514	* @returns IPRT status code.
515	* @param hFuzzTgtState The fuzzed target state handle.
516	*/
517	RTDECL(int) RTFuzzTgtStateFinalize(RTFUZZTGTSTATE hFuzzTgtState);
518
519	/**
520	* Adds the given state to the set for the owning target recorder.
521	*
522	* @returns IPRT status code.
523	* @retval VERR_ALREADY_EXISTS if the state is already existing in the recorder set.
524	* @param hFuzzTgtState The fuzzed target state handle.
525	*
526	* @note This also finalizes the target state if not already done.
527	*/
528	RTDECL(int) RTFuzzTgtStateAddToRecorder(RTFUZZTGTSTATE hFuzzTgtState);
529
530	/**
531	* Appends the given stdout output to the given target state.
532	*
533	* @returns IPRT status code.
534	* @param hFuzzTgtState The fuzzed target state handle.
535	* @param pvStdOut Pointer to the stdout data buffer.
536	* @param cbStdOut Size of the stdout data buffer in bytes.
537	*/
538	RTDECL(int) RTFuzzTgtStateAppendStdoutFromBuf(RTFUZZTGTSTATE hFuzzTgtState, const void *pvStdOut, size_t cbStdOut);
539
540	/**
541	* Appends the given stderr output to the given target state.
542	*
543	* @returns IPRT status code.
544	* @param hFuzzTgtState The fuzzed target state handle.
545	* @param pvStdErr Pointer to the stderr data buffer.
546	* @param cbStdErr Size of the stderr data buffer in bytes.
547	*/
548	RTDECL(int) RTFuzzTgtStateAppendStderrFromBuf(RTFUZZTGTSTATE hFuzzTgtState, const void *pvStdErr, size_t cbStdErr);
549
550	/**
551	* Appends the given stdout output to the given target state, reading from the given pipe.
552	*
553	* @returns IPRT status code.
554	* @param hFuzzTgtState The fuzzed target state handle.
555	* @param hPipe The stdout pipe to read the data from.
556	*/
557	RTDECL(int) RTFuzzTgtStateAppendStdoutFromPipe(RTFUZZTGTSTATE hFuzzTgtState, RTPIPE hPipe);
558
559	/**
560	* Appends the given stderr output to the given target state, reading from the given pipe.
561	*
562	* @returns IPRT status code.
563	* @param hFuzzTgtState The fuzzed target state handle.
564	* @param hPipe The stdout pipe to read the data from.
565	*/
566	RTDECL(int) RTFuzzTgtStateAppendStderrFromPipe(RTFUZZTGTSTATE hFuzzTgtState, RTPIPE hPipe);
567
568	/**
569	* Adds the SanCov coverage information from the given file to the given target state.
570	*
571	* @returns IPRT status code.
572	* @param hFuzzTgtState The fuzzed target state handle.
573	* @param pszFilename Filename of the coverage report.
574	*/
575	RTDECL(int) RTFuzzTgtStateAddSanCovReportFromFile(RTFUZZTGTSTATE hFuzzTgtState, const char *pszFilename);
576
577	/**
578	* Adds the given process status to the target state.
579	*
580	* @returns IPRT status code.
581	* @param hFuzzTgtState The fuzzed target state handle.
582	* @param pProcSts The process status to add.
583	*/
584	RTDECL(int) RTFuzzTgtStateAddProcSts(RTFUZZTGTSTATE hFuzzTgtState, PCRTPROCSTATUS pProcSts);
585
586	/**
587	* Dumps the given target state to the given directory.
588	*
589	* @returns IPRT status code.
590	* @param hFuzzTgtState The fuzzed target state handle.
591	* @param pszDirPath The directory to dump to.
592	*/
593	RTDECL(int) RTFuzzTgtStateDumpToDir(RTFUZZTGTSTATE hFuzzTgtState, const char *pszDirPath);
594
595
596	/**
597	* Fuzzed binary input channel.
598	*/
599	typedef enum RTFUZZOBSINPUTCHAN
600	{
601	/** Invalid. */
602	RTFUZZOBSINPUTCHAN_INVALID = 0,
603	/** File input. */
604	RTFUZZOBSINPUTCHAN_FILE,
605	/** Input over stdin. */
606	RTFUZZOBSINPUTCHAN_STDIN,
607	/** The binary is a fuzzing aware client using the
608	* specified protocol over stdin/stdout. */
609	RTFUZZOBSINPUTCHAN_FUZZING_AWARE_CLIENT,
610	/** TCP server. */
611	RTFUZZOBSINPUTCHAN_TCP_SERVER,
612	/** TCP client. */
613	RTFUZZOBSINPUTCHAN_TCP_CLIENT,
614	/** UDP server. */
615	RTFUZZOBSINPUTCHAN_UDP_SERVER,
616	/** UDP client. */
617	RTFUZZOBSINPUTCHAN_UDP_CLIENT,
618	/** 32bit hack. */
619	RTFUZZOBSINPUTCHAN_32BIT_HACK = 0x7fffffff
620	} RTFUZZOBSINPUTCHAN;
621
622	/**
623	* Fuzzing observer statistics.
624	*/
625	typedef struct RTFUZZOBSSTATS
626	{
627	/** Number of fuzzed inputs per second. */
628	uint32_t cFuzzedInputsPerSec;
629	/** Number of overall fuzzed inputs. */
630	uint32_t cFuzzedInputs;
631	/** Number of observed hangs. */
632	uint32_t cFuzzedInputsHang;
633	/** Number of observed crashes. */
634	uint32_t cFuzzedInputsCrash;
635	} RTFUZZOBSSTATS;
636	/** Pointer to a fuzzing observer statistics record. */
637	typedef RTFUZZOBSSTATS *PRTFUZZOBSSTATS;
638
639	/**
640	* Creates a new fuzzing observer.
641	*
642	* @returns IPRT status code.
643	* @param phFuzzObs Where to store the fuzzing observer handle on success.
644	* @param enmType Fuzzing context data type.
645	* @param fTgtRecFlags Flags to pass to the target state recorder, see RTFuzzTgtRecorderCreate().
646	*/
647	RTDECL(int) RTFuzzObsCreate(PRTFUZZOBS phFuzzObs, RTFUZZCTXTYPE enmType, uint32_t fTgtRecFlags);
648
649	/**
650	* Destroys a previously created fuzzing observer.
651	*
652	* @returns IPRT status code.
653	* @param hFuzzObs The fuzzing observer handle.
654	*/
655	RTDECL(int) RTFuzzObsDestroy(RTFUZZOBS hFuzzObs);
656
657	/**
658	* Queries the internal fuzzing context of the given observer.
659	*
660	* @returns IPRT status code.
661	* @param hFuzzObs The fuzzing observer handle.
662	* @param phFuzzCtx Where to store the handle to the fuzzing context on success.
663	*
664	* @note The fuzzing context handle should be released with RTFuzzCtxRelease() when not used anymore.
665	*/
666	RTDECL(int) RTFuzzObsQueryCtx(RTFUZZOBS hFuzzObs, PRTFUZZCTX phFuzzCtx);
667
668	/**
669	* Queries the current statistics for the given fuzzing observer.
670	*
671	* @returns IPRT status code.
672	* @param hFuzzObs The fuzzing observer handle.
673	* @param pStats Where to store the statistics to.
674	*/
675	RTDECL(int) RTFuzzObsQueryStats(RTFUZZOBS hFuzzObs, PRTFUZZOBSSTATS pStats);
676
677	/**
678	* Sets the temp directory for the given fuzzing observer.
679	*
680	* @returns IPRT status code.
681	* @param hFuzzObs The fuzzing observer handle.
682	* @param pszTmp The temp directory path.
683	*/
684	RTDECL(int) RTFuzzObsSetTmpDirectory(RTFUZZOBS hFuzzObs, const char *pszTmp);
685
686	/**
687	* Sets the directory to store results to.
688	*
689	* @returns IPRT status code.
690	* @param hFuzzObs The fuzzing observer handle.
691	* @param pszResults The path to store the results.
692	*/
693	RTDECL(int) RTFuzzObsSetResultDirectory(RTFUZZOBS hFuzzObs, const char *pszResults);
694
695	/**
696	* Sets the binary to run for each fuzzed input.
697	*
698	* @returns IPRT status code.
699	* @param hFuzzObs The fuzzing observer handle.
700	* @param pszBinary The binary path.
701	* @param enmInputChan The input channel to use.
702	*/
703	RTDECL(int) RTFuzzObsSetTestBinary(RTFUZZOBS hFuzzObs, const char *pszBinary, RTFUZZOBSINPUTCHAN enmInputChan);
704
705	/**
706	* Sets additional arguments to run the binary with.
707	*
708	* @returns IPRT status code.
709	* @param hFuzzObs The fuzzing observer handle.
710	* @param papszArgs Pointer to the array of arguments.
711	* @param cArgs Number of arguments.
712	*/
713	RTDECL(int) RTFuzzObsSetTestBinaryArgs(RTFUZZOBS hFuzzObs, const char * const *papszArgs, unsigned cArgs);
714
715	/**
716	* Sets an environment block to run the binary in.
717	*
718	* @returns IPRT status code.
719	* @param hFuzzObs The fuzzing observer handle.
720	* @param hEnv The environment block to set for the test binary.
721	* Use RTENV_DEFAULT for the default process environment or
722	* NULL for an empty environment.
723	*
724	* @note Upon successful return of this function the observer has taken ownership over the
725	* environment block and can alter it in unexpected ways. It also destroys the environment
726	* block when the observer gets destroyed. So don't touch the environment block after
727	* calling this function.
728	*/
729	RTDECL(int) RTFuzzObsSetTestBinaryEnv(RTFUZZOBS hFuzzObs, RTENV hEnv);
730
731	/**
732	* Makes the observer aware of any configured sanitizers for the test binary.
733	*
734	* @returns IPRT status code.
735	* @param hFuzzObs The fuzzing observer handle.
736	* @param fSanitizers Bitmask of compiled and enabled sanitiziers in the
737	* target binary.
738	*/
739	RTDECL(int) RTFuzzObsSetTestBinarySanitizers(RTFUZZOBS hFuzzObs, uint32_t fSanitizers);
740
741	/**
742	* Sets maximum timeout until a process is considered hung and killed.
743	*
744	* @returns IPRT status code.
745	* @param hFuzzObs The fuzzing observer handle.
746	* @param msTimeoutMax The maximum number of milliseconds to wait until the process
747	* is considered hung.
748	*/
749	RTDECL(int) RTFuzzObsSetTestBinaryTimeout(RTFUZZOBS hFuzzObs, RTMSINTERVAL msTimeoutMax);
750
751	/**
752	* Starts fuzzing the set binary.
753	*
754	* @returns IPRT status code.
755	* @param hFuzzObs The fuzzing observer handle.
756	* @param cProcs Number of processes to run simulteanously,
757	* 0 will create as many processes as there are CPUs available.
758	*/
759	RTDECL(int) RTFuzzObsExecStart(RTFUZZOBS hFuzzObs, uint32_t cProcs);
760
761	/**
762	* Stops the fuzzing process.
763	*
764	* @returns IPRT status code.
765	* @param hFuzzObs The fuzzing observer handle.
766	*/
767	RTDECL(int) RTFuzzObsExecStop(RTFUZZOBS hFuzzObs);
768
769
770	/**
771	* A fuzzing master program.
772	*
773	* @returns Program exit code.
774	*
775	* @param cArgs The number of arguments.
776	* @param papszArgs The argument vector. (Note that this may be
777	* reordered, so the memory must be writable.)
778	*/
779	RTR3DECL(RTEXITCODE) RTFuzzCmdMaster(unsigned cArgs, char **papszArgs);
780
781
782	/**
783	* Client input consumption callback.
784	*
785	* @returns IPRT status code.
786	* @retval VINF_SUCCESS the fuzzed code accepted the input.
787	* @retval VERR_* the client rejected the input while parsing it.
788	* @param pvBuf The buffer containing the input data.
789	* @param cbBuf Size of the buffer in bytes.
790	* @param pvUser Opaque user data.
791	*/
792	typedef DECLCALLBACK(int) FNFUZZCLIENTCONSUME(const void pvBuf, size_t cbBuf, void pvUser);
793	/** Pointer to a client consumption callback. */
794	typedef FNFUZZCLIENTCONSUME *PFNFUZZCLIENTCONSUME;
795
796	/**
797	* A fuzzing client program for more efficient fuzzing.
798	*
799	* @returns Program exit code.
800	*
801	* @param cArgs The number of arguments.
802	* @param papszArgs The argument vector. (Note that this may be
803	* reordered, so the memory must be writable.)
804	* @param pfnConsume Input data consumption callback.
805	* @param pvUser Opaque user data to pass to the callback.
806	*/
807	RTR3DECL(RTEXITCODE) RTFuzzCmdFuzzingClient(unsigned cArgs, char *papszArgs, PFNFUZZCLIENTCONSUME pfnConsume, void pvUser);
808	/** @} */
809
810	RT_C_DECLS_END
811
812	#endif /* !IPRT_INCLUDED_fuzz_h */
813

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

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

Download in other formats: