{"id":13337945,"url":"https://github.com/wolfSSL/oss-fuzz-targets","last_synced_at":"2025-03-11T08:32:00.844Z","repository":{"id":142858622,"uuid":"97142637","full_name":"wolfSSL/oss-fuzz-targets","owner":"wolfSSL","description":"Fuzz targets for OSS-Fuzz","archived":false,"fork":false,"pushed_at":"2018-05-09T21:51:52.000Z","size":28,"stargazers_count":23,"open_issues_count":0,"forks_count":8,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-02-26T12:13:17.436Z","etag":null,"topics":["fuzz-testing","oss-fuzz","security","ssl","testing","tls","wolfcrypt","wolfssl"],"latest_commit_sha":null,"homepage":"https://www.wolfssl.com","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wolfSSL.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-07-13T16:13:09.000Z","updated_at":"2024-10-26T09:48:30.000Z","dependencies_parsed_at":"2023-04-08T09:18:40.694Z","dependency_job_id":null,"html_url":"https://github.com/wolfSSL/oss-fuzz-targets","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfSSL%2Foss-fuzz-targets","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfSSL%2Foss-fuzz-targets/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfSSL%2Foss-fuzz-targets/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfSSL%2Foss-fuzz-targets/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wolfSSL","download_url":"https://codeload.github.com/wolfSSL/oss-fuzz-targets/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243000812,"owners_count":20219747,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fuzz-testing","oss-fuzz","security","ssl","testing","tls","wolfcrypt","wolfssl"],"created_at":"2024-07-29T19:15:16.347Z","updated_at":"2025-03-11T08:32:00.827Z","avatar_url":"https://github.com/wolfSSL.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"Fuzz Targets\n============\n\nThe files in this repository are fuzzing targets for wolfSSL. They follow the\nLLVM libFuzzer API and have a very specific naming scheme for integration with\n[Google's OSS-Fuzz service][oss-fuzz]. For more information about these\nqualities, see [the section on making new targets](#new_target) below. To be\nrun, they must be linked against `libFuzzer.a`. For more information about\ncompilation, see [the section on compiling](#compiling_target) below.\n\n[The very last section of this README](#future) is meant to document the\nforeseeable future of this repository, including suggestions on what fuzz\ntargets should be written next. It is requested that future editors of this\ndirectory update that section to reflect their work and thoughts.\n\n\u003ca name=\"compiling_target\"\u003eCompiling Targets\u003c/a\u003e\n------------------------------------------------\n\nThe first thing to know is that you only need to compile these yourself if you\nintend to do testing outside of the OSS-Fuzz environment, which is useful, as\ngetting OSS-Fuzz up takes some time. After you have finished compiling, you may\nmove on to [the section on running fuzz targets](#run_targt) below.\n\nFor information on how to get a target running inside of OSS-Fuzz, see [the\nsection on OSS-Fuzz](#with_oss-fuzz) below.\n\nFor the entirety of this section, let \"`fuzz_target`\" be a stand-in for the\nname of your target. It will be identical to the directory name containing the\nsource code.\n\nIf you have access to the make utility, everything will be simple. Before\ncompiling any individual target, run `make deps`. If necessary, make will\nautomatically retrieve the libFuzzer library and the most recent version of\nclang, both of which are required for compilation. Neither are installed, but\nkept locally instead. `make dependencies` is synonymous.\n\nFrom there, simply execute `make fuzz_target` to compile a fuzz target.\n\nFurthermore, running `make` or `make all` will compile all fuzz targets,\nrunning `make clean` will delete the compiled fuzz targets but leave the source\nfiles intact, and running `make spotless` will act like `make clean` but also\ndelete the dependencies build by `make deps`.\n\nIf you don't have access to make, you're going to have to do it all by hand.\nWhat follows for the rest of this section are the instructions for doing what\nthe Makefile describes, but by yourself. If make is available and worked, you\nmay skip the remainder of this section.\n\nThe first thing to know is that the fuzz targets in this directory are written\nin C, yet `libFuzzer.a` is a C++ library. As such, the compilation of a target\ncomes in two fazes: compile, then link. Similarly, because of the nature of\nlibFuzzer, compilation must be done through clang rather than gcc.\n\nThe official libFuzzer documentation can be found [on the LLVM\nwebsite][libFuzzer].\n\nThe first thing to do is to get libFuzzer. To do this, run these commands from\nthe shell:\n\n```\n$ url=https://chromium.googlesource.com/chromium/llvm-project/llvm/lib/Fuzzer\n$ git clone $url Fuzzer\n$ ./Fuzzer/build.sh\n$ rm -rf Fuzzer\n```\n\nThe above clones in the libFuzzer git repository then builds it. There should\nnow be a `libFuzzer.a` in this directory.\n\nNext we need an up-to-date version of clang. To do this, we're going to clone\ndown some tools. Because of how those tools expect their directory hierarchy,\nwe're going to put that repository three directories deep. After that, we'll\nuse those tools to pull down the most up-to-date version of clang then make a\nlink for our convenience. In all, that looks like this:\n\n```\n$ url=https://chromium.googlesource.com/chromium/src/tools/clang\n$ git clone $url new_clang/clang/clang\n$ python new_clang/clang/clang/scripts/update.py\n$ ln -s -t . new_clang/third_party/llvm-build/Release+Asserts/bin/clang{,++}\n```\n\nAnd with that, you now have a recent version of clang. It has not been\ninstalled, so to use it you'll have to call clang like `./clang` from this\ndirectory.\n\nTo compile, run these commands from the shell:\n\n```\n$ CFLAGS=\"-fsanitize=address -fsanitize-coverage=trace-pc-guard\"\n$ LDFLAGS=\"-L. -lwolfssl -lFuzzer\"\n$ ./clang $CFLAGS -c fuzz_target/target.c -o fuzz_target/target.o\n$ ./clang++ $CFLAGS fuzz_target/target.o -o fuzz_target/target $LDFLAGS\n$ rm fuzz_target.o\n```\n\nAnd with that, `fuzz_target` has been compiled. This compile step is the only\n\n\u003ca name=\"run_target\"\u003eRunning Targets\u003c/a\u003e\n----------------------------------------\n\nFor the entirety of this section, let \"`fuzz_target`\" be a stand-in for the\nname of your target. It will be identical to the directory name containing\nthe source code.\n\nAfter compiling, `cd` into `fuzz_target/`, and `target` is an executable that\ncan be called like this:\n\n```\n$ ./target [OPTION ...] [CORPUS ...]\n```\nor\n```\n$ ./target [OPTION ...] [FILE ...]\n```\n\nA corpus is a directory with files containing example input data, good or bad,\nfor the fuzzer to use as a starting point. If a new file is generated, it will\nbe placed in the first corpus listed. If files are passed, they will be passed\nwithout being fuzzed. This is useful for testing if a fuzz target modification\nworked.\n\nOptions come strictly in the form `-flag=value`. Here are some useful options:\n\n* `-runs=N`: run N tests. The default (N = -1) means to run indefinitely.\n* `-max_len=N`: cap input data at at most N bytes of data\n* `-max_total_time=N`: run tests for at most N seconds. The default (N = 0)\n  means to run indefinitely.\n* `-help=1`: show help, including calling convention and all options\n\n\u003ca name=\"new_target\"\u003eWriting New Targets\u003c/a\u003e\n--------------------------------------------\n\nThere are three different things that you should make every time you make a new\nfuzz target: [source code](#target_src), [options](#target_opt), and\n[corpus](#target_corp). See their respective subsections below for more\ninformation on each.\n\nAll three parts must be placed in the same directory, but separate from any\nother fuzz target. The name of this directory will be the name of the fuzz\ntarget. There are no exceptions; failure to comply with this will prevent your\nfuzz target from being found by OSS-Fuzz.\n\nThe only required part is the source code; options files and corpora may be\nomitted, though it is recommended that you at least also include a corpus.\n\nThe fourth, extra optional part is the dictionary. You can read more about how\nto use or include them in [the OSS-Fuzz documentation][dict]. If you wish to\ninclude one, create a file ending in \".dict\" in the root directory of this\nrepository, then add a line like this to the options file for the fuzz target\nthat will use it:\n\n```\n[libfuzzer]\ndict = my_dictionary.dict\n```\n\nNote that dictionaries are found relative to the root directory of this\nrepository. Do not use relative or absolute paths, simply the name of the file.\n\n### \u003ca name=\"target_src\"\u003eSource Code\u003c/a\u003e\n\nThe source code is more or less what you'd expect: the code describing the\ntest. It must be named `target.c`. Internally, the only requirement is that it\nnot implement `main()` and instead implement a function for this prototype:\n\n```c\nint LLVMFuzzerTestOneInput(const uint8_t *data, size_t sz);\n```\n\nFor definitions of `uint8_t` and `size_t`, include `stdint.h` and `stdlib.h`\nrespectively.\n\nIn this function, `data` is a buffer of size `sz` bytes. Within this buffer is\nthe content of a file. If the target was invoked at the command line with file\nnames, the content of data will be exactly the content of the file. Otherwise,\nit will contain the fuzzed version of files in the corpus.\n\nFrom here, `data` and `sz` must become the input of another function. In many\ncases, this is as simple as using `data` and `sz` in the function call, but\nsometimes creativity must be used to expose the library to the fuzzed data.\n\n### \u003ca name=\"target_opt\"\u003eOptions\u003c/a\u003e\n\nAn options file will indicate to OSS-Fuzz which flags and values to pass to the\nfuzz target when running it. An options file must be named `target.options`.\n\nThe format seems to be similar to [the ini format][ini], though no explicit\nconfirmation of this was found. For example, a file like this is valid:\n\n```\n[libfuzzer]\nmax_len = 1024\n```\n\n### \u003ca name=\"target_corp\"\u003eCorpus\u003c/a\u003e\n\nA corpus is a directory containing \"seeds\" for the fuzzer. The fuzzer will\nintelligently generate fuzzed input from these files to feed into the fuzz\ntarget. Inside, you can include good or bad input. In general, it is\nrecommended that you include a few examples of good input. If ever fuzzing\nfinds an example of bad input, it is also recommended that you add this bad\ninput to make sure the problem that created it is not re-introduced.\n\nThe corpus must be a directory. It may have any name, though know that when\nOSS-Fuzz tries to find corpora, it will assume every directory in the target's\ndirectory is a corpus.\n\nThe contents of the corpus do not need to conform to any kind of naming scheme,\nthough libFuzzer is happiest when the file's name is the sha1 sum of the file,\nand so it is recommended that all corpus files are named accordingly.\n\n\u003ca name=\"with_oss-fuzz\"\u003eRunning Targets in OSS-Fuzz\u003c/a\u003e\n-------------------------------------------------------\n\nIf you've followed all the conventions described in [the section on writing new\ntargets](#new_target) above, you can get any target you've written to run in\nOSS-Fuzz pretty simply.\n\nBefore trying to get a target working with OSS-Fuzz, it is recommended that you\ncan confirm that it compiles and runs locally, because doing so makes the\nturn-around on fixing bugs/mistakes much shorter. For more information on\ncompiling targets locally, see [the section on compiling](#compiling_target)\nabove.\n\nThe first thing to do is to make sure that Docker is installed and running. To\ndo this, please consult [Docker's website][docker]. If you are on a Linux\nsystem, it is probable that Docker is already in your distribution's software\nrepository.\n\nTo get the OSS-Fuzz repository down onto your local machine, a git-clone like\nthis should work:\n\n```\n$ git clone https://github.com/google/oss-fuzz\n```\n\nNote that if you are going to be modifying the fuzz targets, you'll need to\nmodify where Docker will get its targets. Open\n`./oss-fuzz/projects/wolfssl/Dockerfile` and change this line:\n\n```\nRUN git clone --depth 1 https://github.com/wolfssl/wolfssl.git wolfssl\n```\n\nto something like this:\n\n```\nRUN git clone --depth 1 https://github.com/\u003cyou\u003e/wolfssl.git -b \u003cwork_branch\u003e wolfssl\n```\n\nBe sure to replace `\u003cyou\u003e` with your github user name and `\u003cwork_branch\u003e` with\nthe branch to which you are pushing your new targets.\n\nFrom the OSS-Fuzz root directory, we're going to run some Python scripts. Take\nnotice that these scripts are written in Python 2. Furthermore, you will\nprobably need to run them with root permissions. Appending `sudo` should do.\nFinally, these commands require the Docker daemon to be running. Those commands\nshould look like this:\n\n```\n# python infra/helper.py build_image wolfssl\n# python infra/helper.py build_fuzzers --sanitizer address wolfssl\n```\n\nYou may also choose to use `memory` or `undefined` for the sanitizer option.\n\nTo actually run a fuzz target, run this command:\n\n```\n# python infra/helper.py run_fuzzer wolfssl fuzz_target\n```\n\nWhere `fuzz_target` stands for the fuzz target you wish to run. The name of the\nfuzz target corresponds with the directory name containing the source code of\nthe target you wish to run.\n\n\u003ca name=\"future\"\u003eFuture Direction\u003c/a\u003e\n-------------------------------------\n\nAdd more tests for various wolfSSL and wolfCrypt APIs. Focus on APIs which\nprocess buffers containing data that plausibly could originate from some\noutside source. It is possible that a target for any given API has already been\nwritten: check the private wolfssl testing repository for targets before\nwriting them yourself.\n\n\u003c!-- References --\u003e\n[libFuzzer]: http://llvm.org/docs/LibFuzzer.html\n[libFuzzer_use]: http://llvm.org/docs/LibFuzzer.html#fuzzer-usage\n[oss-fuzz]: https://github.com/google/oss-fuzz\n[ini]: https://en.wikipedia.org/wiki/INI_file\n[dict]: https://github.com/google/oss-fuzz/blob/master/docs/new_project_guide.md#dictionaries\n[docker]: https://www.docker.com/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FwolfSSL%2Foss-fuzz-targets","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FwolfSSL%2Foss-fuzz-targets","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FwolfSSL%2Foss-fuzz-targets/lists"}