https://github.com/status-im/nim-drchaos Skip to content Sign up * Product + Features + Mobile + Actions + Codespaces + Copilot + Packages + Security + Code review + Issues + Discussions + Integrations + GitHub Sponsors + Customer stories * Team * Enterprise * Explore + Explore GitHub + Learn and contribute + Topics + Collections + Trending + Skills + GitHub Sponsors + Open source guides + Connect with others + The ReadME Project + Events + Community forum + GitHub Education + GitHub Stars program * Marketplace * Pricing + Plans + Compare plans + Contact Sales + Education [ ] * # In this repository All GitHub | Jump to | * No suggested jump to results * # In this repository All GitHub | Jump to | * # In this organization All GitHub | Jump to | * # In this repository All GitHub | Jump to | Sign in Sign up {{ message }} status-im / nim-drchaos Public * Notifications * Fork 0 * Star 31 A powerful and easy-to-use fuzzing framework in Nim for C/C++/Obj-C targets 31 stars 0 forks Star Notifications * Code * Issues 5 * Pull requests 0 * Actions * Projects 0 * Security * Insights More * Code * Issues * Pull requests * Actions * Projects * Security * Insights status-im/nim-drchaos This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository. master Switch branches/tags [ ] Branches Tags Could not load branches Nothing to show {{ refName }} default View all branches Could not load tags Nothing to show {{ refName }} default View all tags 1 branch 4 tags Code * Clone HTTPS GitHub CLI [https://github.com/s] Use Git or checkout with SVN using the web URL. [gh repo clone status] Work fast with our official CLI. Learn more. * Open with GitHub Desktop * Download ZIP Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Launching Xcode If nothing happens, download Xcode and try again. Launching Visual Studio Code Your codespace will open once ready. There was a problem preparing your codespace, please try again. Latest commit @planetis-m planetis-m v0.1.3 ... 96ef0be Aug 28, 2022 v0.1.3 96ef0be Git stats * 17 commits Files Permalink Failed to load latest commit information. Type Name Latest commit message Commit time benchmarks minor Aug 27, 2022 drchaos v0.1.2 Aug 28, 2022 examples added warnings in everything that broke, minor additions Aug 26, 2022 experiments fixes #7, minor cleanups Aug 27, 2022 tests added warnings in everything that broke, minor additions Aug 26, 2022 README.md lower the required Nim version Aug 28, 2022 drchaos.nim Initial commit Aug 25, 2022 drchaos.nimble v0.1.3 Aug 28, 2022 View code [ ] Dr. Chaos Usage Example Post-processors Custom mutator User-defined mutate procs What's not supported License README.md Dr. Chaos A powerful and easy-to-use fuzzing framework in Nim for C/C++/Obj-C targets. Fuzzing is an automated bug finding technique, where randomized inputs are fed to a target program in order to get it to crash. With fuzzing, you can increase your test coverage to find edge cases and trigger bugs more effectively. Dr. Chaos extends the Nim interface to LLVM/Clang libFuzzer, an in-process, coverage-guided, evolutionary fuzzing engine. And adds support for structured fuzzing. The user should define the input type, as a parameter to the target function and the fuzzer is responsible for providing valid inputs. Behind the scenes it uses value profiling to guide the fuzzer past these comparisons much more efficiently than simply hoping to stumble on the exact sequence of bytes by chance. Usage For most cases, it is fairly trivial to define a data type and a target function that performs some operations and checks if the invariants expressed as assert conditions still hold. Then call defaultMutator with that function as parameter. That can be as basic as defining a range type and ensuring your library doesn't crash or complex as shown bellow. Example A simple but somewhat contrived example looks like this: import drchaos type ContentNodeKind = enum P, Br, Text ContentNode = object case kind: ContentNodeKind of P: pChildren: seq[ContentNode] of Br: discard of Text: textStr: string func `==`(a, b: ContentNode): bool = if a.kind != b.kind: return false case a.kind of P: return a.pChildren == b.pChildren of Br: return true of Text: return a.textStr == b.textStr func fuzzTarget(x: ContentNode) = # Convert or translate `x` to any format (JSON, HMTL, binary, etc...) # and feed it to the API you are testing. defaultMutator(fuzzTarget) Dr. Chaos will generate millions of inputs and run fuzzTarget under a few seconds. More articulate examples, such as fuzzing a graph library are in the examples/ directory. Defining a == proc for your input type is necessary. Post-processors Sometimes it is necessary to adjust the random input in order to add magic values or dependencies between some fields. This is supported with a post-processing step, which for performance and clarity reasons only runs on compound types such as object/tuple/ref/seq/ string/array/set and by exception distinct types. proc postProcess(x: var ContentNode; r: var Rand) = if x.kind == Text: x.textStr = "The man the professor the student has studies Rome." Custom mutator Besides defaultMutator there is also customMutator which allows more fine-grained control of the mutation procedure, like uncompressing a seq[byte] then calling runMutator on the raw data and compressing the output again. func myTarget(x: seq[byte]) = var data = uncompress(x) ... proc myMutator(x: var seq[byte]; sizeIncreaseHint: Natural; r: var Rand) = var data = uncompress(x) runMutator(data, sizeIncreaseHint, r) x = compress(data) customMutator(myTarget, myMutator) User-defined mutate procs It's possible to use distinct types to provide a mutate overload for fields that have interesting values, like file signatures or to limit the search space. # Fuzzed library when defined(runFuzzTests): type ClientId = distinct int proc `==`(a, b: ClientId): bool {.borrow.} else: type ClientId = int # In a test file import drchaos/mutator const idA = 0.ClientId idB = 2.ClientId idC = 4.ClientId proc mutate(value: var ClientId; sizeIncreaseHint: int; enforceChanges: bool; r: var Rand) = # use `rand()` to return a new value. repeatMutate(r.sample([idA, idB, idC])) For aiding the creation of mutate functions, mutators for every supported type are exported by drchaos/mutator. What's not supported * Polymorphic types, missing serialization support. * References with cycles. A .noFuzz custom pragma will be added soon for cursors. License Licensed and distributed under either of * MIT license: LICENSE-MIT or http://opensource.org/licenses/MIT or * Apache License, Version 2.0, (LICENSE-APACHEv2 or http:// www.apache.org/licenses/LICENSE-2.0) at your option. These files may not be copied, modified, or distributed except according to those terms. About A powerful and easy-to-use fuzzing framework in Nim for C/C++/Obj-C targets Resources Readme Stars 31 stars Watchers 14 watching Forks 0 forks Releases 4 tags Packages 0 No packages published Languages * Nim 100.0% Footer (c) 2022 GitHub, Inc. Footer navigation * Terms * Privacy * Security * Status * Docs * Contact GitHub * Pricing * API * Training * Blog * About You can't perform that action at this time. You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.