VirtualBox

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

Last change on this file since 72454 was 72454, checked in by vboxsync, 6 years ago

iprt/fuzz: Some delinting. bugref:9006

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 13.2 KB
Line 
1/** @file
2 * IPRT - Fuzzing framework
3 */
4
5/*
6 * Copyright (C) 2018 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_fuzz_h
27#define ___iprt_fuzz_h
28
29#include <iprt/cdefs.h>
30#include <iprt/types.h>
31
32RT_C_DECLS_BEGIN
33
34/** @defgroup grp_rt_fuzz RTFuzz - Data fuzzing framework
35 * @ingroup grp_rt
36 * @sa grp_rt_test
37 * @{
38 */
39
40/** A fuzzer context handle. */
41typedef struct RTFUZZCTXINT *RTFUZZCTX;
42/** Pointer to a fuzzer context handle. */
43typedef RTFUZZCTX *PRTFUZZCTX;
44/** NIL fuzzer context handle. */
45#define NIL_RTFUZZCTX ((RTFUZZCTX)~(uintptr_t)0)
46/** A fuzzer input handle. */
47typedef struct RTFUZZINPUTINT *RTFUZZINPUT;
48/** Pointer to a fuzzer input handle. */
49typedef RTFUZZINPUT *PRTFUZZINPUT;
50/** NIL fuzzer input handle. */
51#define NIL_RTFUZZINPUT ((RTFUZZINPUT)~(uintptr_t)0)
52
53
54/** Fuzzing observer handle. */
55typedef struct RTFUZZOBSINT *RTFUZZOBS;
56/** Pointer to a fuzzing observer handle. */
57typedef RTFUZZOBS *PRTFUZZOBS;
58/** NIL fuzzing observer handle. */
59#define NIL_RTFUZZOBS ((RTFUZZOBS)~(uintptr_t)0)
60
61
62/** @name RTFUZZCTX_F_XXX - Flags for RTFuzzCtxCfgSetBehavioralFlags
63 * @{ */
64/** Adds all generated inputs automatically to the input corpus for the owning context. */
65#define RTFUZZCTX_F_BEHAVIORAL_ADD_INPUT_AUTOMATICALLY_TO_CORPUS RT_BIT_32(0)
66/** All valid behavioral modification flags. */
67#define RTFUZZCTX_F_BEHAVIORAL_VALID (RTFUZZCTX_F_BEHAVIORAL_ADD_INPUT_AUTOMATICALLY_TO_CORPUS)
68/** @} */
69
70/**
71 * Creates a new fuzzing context.
72 *
73 * @returns IPRT status code.
74 * @param phFuzzCtx Where to store the handle to the fuzzing context on success.
75 */
76RTDECL(int) RTFuzzCtxCreate(PRTFUZZCTX phFuzzCtx);
77
78/**
79 * Creates a new fuzzing context from the given state.
80 *
81 * @returns IPRT status code.
82 * @param phFuzzCtx Where to store the handle to the fuzzing context on success.
83 * @param pvState The pointer to the fuzzing state.
84 * @param cbState Size of the state buffer in bytes.
85 */
86RTDECL(int) RTFuzzCtxCreateFromState(PRTFUZZCTX phFuzzCtx, const void *pvState, size_t cbState);
87
88/**
89 * Creates a new fuzzing context loading the state from the given file.
90 *
91 * @returns IPRT status code.
92 * @param phFuzzCtx Where to store the handle to the fuzzing context on success.
93 * @param pszFilename File to load the fuzzing context from.
94 */
95RTDECL(int) RTFuzzCtxCreateFromStateFile(PRTFUZZCTX phFuzzCtx, const char *pszFilename);
96
97/**
98 * Retains a reference to the given fuzzing context.
99 *
100 * @returns New reference count on success.
101 * @param hFuzzCtx Handle of the fuzzing context.
102 */
103RTDECL(uint32_t) RTFuzzCtxRetain(RTFUZZCTX hFuzzCtx);
104
105/**
106 * Releases a reference from the given fuzzing context, destroying it when reaching 0.
107 *
108 * @returns New reference count on success, 0 if the fuzzing context got destroyed.
109 * @param hFuzzCtx Handle of the fuzzing context.
110 */
111RTDECL(uint32_t) RTFuzzCtxRelease(RTFUZZCTX hFuzzCtx);
112
113/**
114 * Exports the given fuzzing context state.
115 *
116 * @returns IPRT statuse code
117 * @param hFuzzCtx The fuzzing context to export.
118 * @param ppvState Where to store the buffer of the state on success, free with RTMemFree().
119 * @param pcbState Where to store the size of the context on success.
120 */
121RTDECL(int) RTFuzzCtxStateExport(RTFUZZCTX hFuzzCtx, void **ppvState, size_t *pcbState);
122
123/**
124 * Exports the given fuzzing context state to the given file.
125 *
126 * @returns IPRT status code.
127 * @param hFuzzCtx The fuzzing context to export.
128 * @param pszFilename The file to save the state to.
129 */
130RTDECL(int) RTFuzzCtxStateExportToFile(RTFUZZCTX hFuzzCtx, const char *pszFilename);
131
132/**
133 * Adds a new seed to the input corpus of the given fuzzing context.
134 *
135 * @returns IPRT status code.
136 * @param hFuzzCtx The fuzzing context handle.
137 * @param pvInput The pointer to the input buffer.
138 * @param cbInput Size of the input buffer.
139 */
140RTDECL(int) RTFuzzCtxCorpusInputAdd(RTFUZZCTX hFuzzCtx, const void *pvInput, size_t cbInput);
141
142/**
143 * Adds a new seed to the input corpus of the given fuzzing context from the given file.
144 *
145 * @returns IPRT status code.
146 * @param hFuzzCtx The fuzzing context handle.
147 * @param pszFilename The filename to load the seed from.
148 */
149RTDECL(int) RTFuzzCtxCorpusInputAddFromFile(RTFUZZCTX hFuzzCtx, const char *pszFilename);
150
151/**
152 * Adds new seeds to the input corpus of the given fuzzing context from the given directory.
153 *
154 * Will only process regular files, i.e. ignores directories, symbolic links, devices, fifos
155 * and such.
156 *
157 * @returns IPRT status code.
158 * @param hFuzzCtx The fuzzing context handle.
159 * @param pszDirPath The directory to load seeds from.
160 */
161RTDECL(int) RTFuzzCtxCorpusInputAddFromDirPath(RTFUZZCTX hFuzzCtx, const char *pszDirPath);
162
163/**
164 * Restricts the maximum input size to generate by the fuzzing context.
165 *
166 * @returns IPRT status code
167 * @param hFuzzCtx The fuzzing context handle.
168 * @param cbMax Maximum input size in bytes.
169 */
170RTDECL(int) RTFuzzCtxCfgSetInputSeedMaximum(RTFUZZCTX hFuzzCtx, size_t cbMax);
171
172/**
173 * Returns the maximum input size of the given fuzzing context.
174 *
175 * @returns Maximum input size generated in bytes.
176 * @param hFuzzCtx The fuzzing context handle.
177 */
178RTDECL(size_t) RTFuzzCtxCfgGetInputSeedMaximum(RTFUZZCTX hFuzzCtx);
179
180/**
181 * Sets flags controlling the behavior of the fuzzing context.
182 *
183 * @returns IPRT status code.
184 * @param hFuzzCtx The fuzzing context handle.
185 * @param fFlags Flags controlling the fuzzing context, RTFUZZCTX_F_XXX.
186 */
187RTDECL(int) RTFuzzCtxCfgSetBehavioralFlags(RTFUZZCTX hFuzzCtx, uint32_t fFlags);
188
189/**
190 * Returns the current set behavioral flags for the given fuzzing context.
191 *
192 * @returns Behavioral flags of the given fuzzing context.
193 * @param hFuzzCtx The fuzzing context handle.
194 */
195RTDECL(uint32_t) RTFuzzCfgGetBehavioralFlags(RTFUZZCTX hFuzzCtx);
196
197/**
198 * Sets the temporary directory used by the fuzzing context.
199 *
200 * @returns IPRT status code.
201 * @param hFuzzCtx The fuzzing context handle.
202 * @param pszPathTmp The directory for the temporary state.
203 */
204RTDECL(int) RTFuzzCtxCfgSetTmpDirectory(RTFUZZCTX hFuzzCtx, const char *pszPathTmp);
205
206/**
207 * Returns the current temporary directory.
208 *
209 * @returns Current temporary directory.
210 * @param hFuzzCtx The fuzzing context handle.
211 */
212RTDECL(const char *) RTFuzzCtxCfgGetTmpDirectory(RTFUZZCTX hFuzzCtx);
213
214/**
215 * Generates a new input from the given fuzzing context and returns it.
216 *
217 * @returns IPRT status code.
218 * @param hFuzzCtx The fuzzing context handle.
219 * @param phFuzzInput Where to store the handle to the fuzzed input on success.
220 */
221RTDECL(int) RTFuzzCtxInputGenerate(RTFUZZCTX hFuzzCtx, PRTFUZZINPUT phFuzzInput);
222
223
224
225/**
226 * Retains a reference to the given fuzzing input handle.
227 *
228 * @returns New reference count on success.
229 * @param hFuzzInput The fuzzing input handle.
230 */
231RTDECL(uint32_t) RTFuzzInputRetain(RTFUZZINPUT hFuzzInput);
232
233/**
234 * Releases a reference from the given fuzzing input handle, destroying it when reaaching 0.
235 *
236 * @returns New reference count on success, 0 if the fuzzing input got destroyed.
237 * @param hFuzzInput The fuzzing input handle.
238 */
239RTDECL(uint32_t) RTFuzzInputRelease(RTFUZZINPUT hFuzzInput);
240
241/**
242 * Queries the data pointer and size of the given fuzzing input.
243 *
244 * @returns IPRT status code
245 * @param hFuzzInput The fuzzing input handle.
246 * @param ppv Where to store the pointer to the input data on success.
247 * @param pcb Where to store the size of the input data on success.
248 */
249RTDECL(int) RTFuzzInputQueryData(RTFUZZINPUT hFuzzInput, void **ppv, size_t *pcb);
250
251/**
252 * Queries the string of the MD5 digest for the given fuzzed input.
253 *
254 * @returns IPRT status code.
255 * @retval VERR_BUFFER_OVERFLOW if the size of the string buffer is not sufficient.
256 * @param hFuzzInput The fuzzing input handle.
257 * @param pszDigest Where to store the digest string and a closing terminator.
258 * @param cchDigest Size of the string buffer in characters (including the zero terminator).
259 */
260RTDECL(int) RTFuzzInputQueryDigestString(RTFUZZINPUT hFuzzInput, char *pszDigest, size_t cchDigest);
261
262/**
263 * Writes the given fuzzing input to the given file.
264 *
265 * @returns IPRT status code.
266 * @param hFuzzInput The fuzzing input handle.
267 * @param pszFilename The filename to store the input to.
268 */
269RTDECL(int) RTFuzzInputWriteToFile(RTFUZZINPUT hFuzzInput, const char *pszFilename);
270
271/**
272 * Adds the given fuzzed input to the input corpus of the owning context.
273 *
274 * @returns IPRT status code.
275 * @retval VERR_ALREADY_EXISTS if the input exists already.
276 * @param hFuzzInput The fuzzing input handle.
277 */
278RTDECL(int) RTFuzzInputAddToCtxCorpus(RTFUZZINPUT hFuzzInput);
279
280/**
281 * Removes the given fuzzed input from the input corpus of the owning context.
282 *
283 * @returns IPRT status code.
284 * @retval VERR_NOT_FOUND if the input is not part of the corpus.
285 * @param hFuzzInput The fuzzing input handle.
286 */
287RTDECL(int) RTFuzzInputRemoveFromCtxCorpus(RTFUZZINPUT hFuzzInput);
288
289
290
291/**
292 * Creates a new fuzzing observer.
293 *
294 * @returns IPRT status code.
295 * @param phFuzzObs Where to store the fuzzing observer handle on success.
296 */
297RTDECL(int) RTFuzzObsCreate(PRTFUZZOBS phFuzzObs);
298
299/**
300 * Destroys a previously created fuzzing observer.
301 *
302 * @returns IPRT status code.
303 * @param hFuzzObs The fuzzing observer handle.
304 */
305RTDECL(int) RTFuzzObsDestroy(RTFUZZOBS hFuzzObs);
306
307/**
308 * Queries the internal fuzzing context of the given observer.
309 *
310 * @returns IPRT status code.
311 * @param hFuzzObs The fuzzing observer handle.
312 * @param phFuzzCtx Where to store the handle to the fuzzing context on success.
313 *
314 * @note The fuzzing context handle should be released with RTFuzzCtxRelease() when not used anymore.
315 */
316RTDECL(int) RTFuzzObsQueryCtx(RTFUZZOBS hFuzzObs, PRTFUZZCTX phFuzzCtx);
317
318/**
319 * Sets the temp directory for the given fuzzing observer.
320 *
321 * @returns IPRT status code.
322 * @param hFuzzObs The fuzzing observer handle.
323 * @param pszTmp The temp directory path.
324 */
325RTDECL(int) RTFuzzObsSetTmpDirectory(RTFUZZOBS hFuzzObs, const char *pszTmp);
326
327/**
328 * Sets the binary to run for each fuzzed input.
329 *
330 * @returns IPRT status code.
331 * @param hFuzzObs The fuzzing observer handle.
332 * @param pszBinary The binary path.
333 * @param fFlags Flags controlling execution of the binary, RTFUZZ_OBS_BINARY_F_XXX.
334 */
335RTDECL(int) RTFuzzObsSetTestBinary(RTFUZZOBS hFuzzObs, const char *pszBinary, uint32_t fFlags);
336
337/** @name RTFUZZ_OBS_BINARY_F_XXX
338 * @{ */
339/** The tested binary requires a real file to read from and doesn't support stdin. */
340#define RTFUZZ_OBS_BINARY_F_INPUT_FILE RT_BIT_32(0)
341/** @} */
342
343/**
344 * Sets additional arguments to run the binary with.
345 *
346 * @returns IPRT status code.
347 * @param hFuzzObs The fuzzing observer handle.
348 * @param papszArgs Pointer to the array of arguments.
349 * @param cArgs Number of arguments.
350 */
351RTDECL(int) RTFuzzObsSetTestBinaryArgs(RTFUZZOBS hFuzzObs, const char * const *papszArgs, unsigned cArgs);
352
353/**
354 * Starts fuzzing the set binary.
355 *
356 * @returns IPRT status code.
357 * @param hFuzzObs The fuzzing observer handle.
358 * @param cProcs Number of processes to run simulteanously,
359 * 0 will create as manny processes as there are CPUs available.
360 */
361RTDECL(int) RTFuzzObsExecStart(RTFUZZOBS hFuzzObs, uint32_t cProcs);
362
363/**
364 * Stops the fuzzing process.
365 *
366 * @returns IPRT status code.
367 * @param hFuzzObs The fuzzing observer handle.
368 */
369RTDECL(int) RTFuzzObsExecStop(RTFUZZOBS hFuzzObs);
370
371
372/**
373 * A fuzzing master program.
374 *
375 * @returns Program exit code.
376 *
377 * @param cArgs The number of arguments.
378 * @param papszArgs The argument vector. (Note that this may be
379 * reordered, so the memory must be writable.)
380 */
381RTR3DECL(RTEXITCODE) RTFuzzCmdMaster(unsigned cArgs, char **papszArgs);
382
383/** @} */
384
385RT_C_DECLS_END
386
387#endif
388
Note: See TracBrowser for help on using the repository browser.

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