{"id":21644461,"url":"https://github.com/samsung/utopia","last_synced_at":"2025-04-04T14:04:07.026Z","repository":{"id":38110738,"uuid":"488085437","full_name":"Samsung/UTopia","owner":"Samsung","description":"UT based automated fuzz driver generation","archived":false,"fork":false,"pushed_at":"2024-12-31T06:53:38.000Z","size":1305,"stargazers_count":166,"open_issues_count":2,"forks_count":26,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-28T13:05:33.277Z","etag":null,"topics":["code-generation","fuzzing"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Samsung.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-03T05:14:26.000Z","updated_at":"2025-03-14T16:28:03.000Z","dependencies_parsed_at":"2024-05-02T04:48:49.791Z","dependency_job_id":"bf104d3c-5ec3-4ebe-85e8-c90d9b44cc5e","html_url":"https://github.com/Samsung/UTopia","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Samsung%2FUTopia","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Samsung%2FUTopia/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Samsung%2FUTopia/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Samsung%2FUTopia/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Samsung","download_url":"https://codeload.github.com/Samsung/UTopia/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247186275,"owners_count":20898126,"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":["code-generation","fuzzing"],"created_at":"2024-11-25T05:40:19.670Z","updated_at":"2025-04-04T14:04:06.992Z","avatar_url":"https://github.com/Samsung.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"res/UTopia.png\"\u003e\n\u003c/p\u003e\n\n# Introduction\n\n*UTopia* is a tool for automatically generating fuzz drivers from unit tests.\n\n*UTopia* will let developers perform fuzz testing without special knowledge about writing fuzzers. Even developers\nfamiliar with fuzzing can save significant time by generating fuzz drivers automatically.\n\n*UTopia* supports C/C++ libraries which have unit tests with GoogleTest, Boost.Test or Tizen TCT.\n\n# Trophy\n\nTo see bugs found by *UTopia*, visit [Trophy](Trophy.md) page. You can also see some *UTopia*-based fuzzers there.\n\n# Docker\n\nFor easy set up, we provide docker image for running *UTopia*.\nYou can build *UTopia* and generate/run fuzzers inside docker container.\n\nBuild docker image with command below.\n\n```shell\ndocker buildx build -f docker/Dockerfile -t utopia . #llvm-10\ndocker buildx build --build-arg LLVM_VERSION=12 -f docker/Dockerfile -t utopia . #llvm-12\n```\n\n*UTopia* is designed to work best with LLVM version 10. And, it has been confirmed to pass unit tests on LLVM version 12. So that we recommened you to use LLVM 10, but if you want you can try LLVM version 12.\n\n# Build\n\n*UTopia* depends on LLVM, Protobuf and GoogleTest. You can install dependencies manually, but we recommend to use given\ndocker image.\n\nTo build *UTopia*, follow cmake process below.\n\n```shell\ncd $UTOPIA_HOME_DIR\ncmake -B build -S .\ncmake --build build -j$(nproc)\n```\n\n# Run\nFor some selected projects, you can use helper script to run our tool without further effort. Please\nrefer [helper/README.md](helper/README.md).\nFor other projects, please check following manual.\n\n## target_analyzer\n\nTarget Analyzer analyzes target library code and generates a result as json file.\nMandatory command line options are below.\n\n```shell\ntarget_analyzer --db ${builddb_path} --extern ${extern_path} --public ${api_json_path} --out ${output_path}\n```\n\n### builddb_path\n\nBuild db is a json file that contains paths of AST and IR files of target library code.\nIts format looks like below.\n\n```json\n{\n  \"bc\": \"/root/fuzz-test-generation/exp/sample/output/bc/libcommon.a.bc\",\n  \"ast\": [\n    \"/root/fuzz-test-generation/exp/sample/libcommon.a_ast/codec/common/src/ast1.o.ast\",\n    \"/root/fuzz-test-generation/exp/sample/libcommon.a_ast/codec/common/src/ast2.o.ast\"\n  ],\n  \"project_dir\": \"/root/fuzz-test-generation/exp/sample\"\n}\n```\n\nLLVM bitcode file path of a specific library should be specified using **\"bc\"** keyword.\nWe only accept one bitcode file so far, thus you may use `llvm-link` to link several bit code files\nto one bit code file.\n\nAST file paths of a specific library should be specified using **\"ast\"** keyword.\nNote that a specified bitcode file and ast files are generated from same source codes for a specific library.\n\n### extern_path\n\nTarget Analyzer accepts target analyzer report of other libraries for an accurate result.\nThis path should be a directory path where other reports stored, which means more than one library reports are allowed.\n\n### api_json_path\n\nAPI function names to be analyzed. It should be json file formatted as below.\n\n```json\n{\n  \"libcommon.a\": [\n    \"API1\",\n    \"API2\",\n    \"API3\"\n  ]\n}\n```\n\nYou can get API list from a specific library using command below.\n\n```shell\nnm --no-demangle --defined-only -g ${librarypath} | awk '$2==\"T\" {k=\"\"; for(i=3;i\u003c=NF;i++) k=k $i\"\"; print k}'\n```\n\n### Report\n\n#### Direction\n\nThe Direction property is an essential parameter that the target analyzer utilizes. It signifies whether a parameter is employed for reading (**Dir_In**), writing (**Dir_Out**), or both reading and writing (**Dir_In** | **Dir_Out**) within a function. The target analyzer delineates this property through an enumeration type comprising the following elements:\n\n```c++\nenum Dir {\n  Dir_NoOp = 0x000,        // No operation\n  Dir_In = 0x100,          // Input direction\n  Dir_Out = 0x010,         // Output direction\n  Dir_Unidentified = 0x001 // Unidentified direction\n};\n```\nFor instance, in the provided JSON file snippet:\n\n```json\n{\n  \"Direction\": {\n    \"BF_crypt(0)\": 256,\n    \"BF_crypt(1)\": 272,\n    \"BF_crypt(2)\": 272,\n    \"BF_decode(1)\": 272\n  }\n}\n```\n- The entry **\"BF_crypt(0)\": 256** indicates that the direction of the first parameter in the BF_crypt function is set to 256 (0x100), signifying an **In** direction, meaning it is used for input.\n- Similarly, **\"BF_crypt(1)\": 272** reveals that the direction of the second parameter in the BF_crypt function is 272 (0x110), indicating it has both **In** and **Out** directions, meaning it is utilized for both input and output.\n\nThis notation helps in understanding how each parameter within a function is used, whether for input, output, or both, providing clear insights into the data flow and operations performed by the function.\n\n## ut_analyzer\n\nUT Analyzer analyzes unit test code for a target library and generates a result as json file.\nMandatory command line options are below.\n\n```shell\nut_analyzer --entry ${entry_path} --extern ${extern_path} --ut ${ut_type} --name ${lib_name} --public ${api_json_path} --out ${output_path}\n```\n\nMost options are same as the [target_analyzer](#target_analyzer).\nNote that, *entry_path* should specify AST/IR files for a unit test executable, not library.\n\n### ut_type\n\nFramework used by the target project, could be `tct`, `gtest`, or `boost`.\n\n## fuzz_generator\n\nfuzz_generator generates fuzz drivers using report files of [target_anlayzer](#target_analyzer)\nand [ut_analyzer](#ut_analyzer).\nMandatory command line options are below.\n\n```shell\nfuzz_generator --src ${src_path} --target ${target_analyzer_report_path} --ut ${ut_analyzer_report_path} --public ${api_json_path} --out ${output_dir}\n```\n\n### src_path\n\nsrc_path is the directory path where unit test source code is stored. fuzz_generator copy this directory and\ngenerates fuzz driver by modifying these copied files.\n\nOther options are same as the [target_analyzer](#target_analyzer) options.\n\n### How fuzz driver works\n\nThis section describes the functionality and implementation details of the generated fuzz driver, which is crucial for understanding how fuzz testing is integrated with the target source code.\n\n**fuzz_entry.cc** (Auto-Generated File)\n```c++\nDEFINE_PROTO_FUZZER(const AutoFuzz::FuzzArgsProfile \u0026autofuzz_mutation) {\n  ... /* Values are assigned from autofuzz_mutation */\n  enterAutofuzz();\n}\n```\nThis function serves as the entry point for the generated fuzz driver. It takes values generated by the fuzzer and assigns them to variables that are subsequently used to invoke library functions. Finally, the function calls **enterAutofuzz();** to proceed with the fuzz testing process.\n\n**Source Code Defining the Target Test Case**\n```c++\n#ifdef __cplusplus\nextern \"C\" {\n#endif\nvoid enterAutofuzz() {\n  class AutofuzzTest : public ::Parser_TestArray_Test {\n  public:\n    void runTest() {\n      try {\n        SetUpTestCase();\n      } catch (std::exception \u0026E) {}\n      try {\n        SetUp();\n      } catch (std::exception \u0026E) {}\n      try {\n        TestBody();\n      } catch (std::exception \u0026E) {}\n      try {\n        TearDown();\n      } catch (std::exception \u0026E) {}\n      try {\n        TearDownTestCase();\n      } catch (std::exception \u0026E) {}\n    }\n  };\n  AutofuzzTest Fuzzer;\n  Fuzzer.runTest();\n}\n#ifdef __cplusplus\n}\n#endif\n```\nIn the final part of the source code that defines the target test case, UTopia injects the **enterAutofuzz** function. Within this function, the **AutofuzzTest** class is declared, inheriting from **::Parser_TestArray_Test**. This parent class is defined by the GoogleTest framework and is specific to the test case being addressed, as shown below:\n\n```c++\nTEST(Parser, TestArray)\n{\n  ...\n}\n```\nThe **runTest()** method executes the test case independently of GoogleTest, invoking five functions that GoogleTest typically calls for each test case. This approach allows for direct test execution without relying on the GoogleTest framework.\n\n## Build generated fuzz drivers\n\nFuzz drivers are generated in `${output_dir}` passed to fuzz_generator as command line option.\nYou can build them using same compiler command for unit test executable.\nNote that, you should include `fuzz_entry.cc`, `FuzzArgsProto.pb.cc` files that are generated by fuzz_generator.\nYou can find those files in `${output_dir}`.\n\n# Reproduce Evaluation\n\n## Generate Fuzzer\n```bash\npython3 -m helper.make {library name}\npython3 -m helper.build {library name}\n```\nYou can find every outputs from the whole pipeline of 'UTopia' under following two directories:\n- `exp/{library name}/output`,\n- `result/test/{library name}`","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamsung%2Futopia","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamsung%2Futopia","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamsung%2Futopia/lists"}