|
| 1 | +--- |
| 2 | +layout: default |
| 3 | +title: Integrating a Lua project |
| 4 | +parent: Setting up a new project |
| 5 | +grand_parent: Getting started |
| 6 | +nav_order: 4 |
| 7 | +permalink: /getting-started/new-project-guide/lua-lang/ |
| 8 | +--- |
| 9 | + |
| 10 | +# Integrating a Lua project |
| 11 | +{: .no_toc} |
| 12 | + |
| 13 | +- TOC |
| 14 | +{:toc} |
| 15 | +--- |
| 16 | + |
| 17 | +The process of integrating a project written in Lua with OSS-Fuzz |
| 18 | +is similar to the general [Setting up a new project]({{ site.baseurl |
| 19 | +}}/getting-started/new-project-guide/) process. The key specifics of |
| 20 | +integrating a Lua project are outlined below. |
| 21 | + |
| 22 | +## luzer |
| 23 | + |
| 24 | +Lua fuzzing in OSS-Fuzz is powered by |
| 25 | +[luzer](https://github.com/ligurio/luzer). As luzer operates |
| 26 | +directly on the Lua source code level, it can be applied to any |
| 27 | +project written in a language that can be transpiled into Lua, |
| 28 | +such as [MoonScript](https://moonscript.org/), |
| 29 | +[TypeScriptToLua](https://typescripttolua.github.io/), |
| 30 | +[Fennel](https://fennel-lang.org/), and [Urn](https://urn-lang.com/). |
| 31 | +Also, it supports fuzzing C/C++ extensions written for Lua. When |
| 32 | +fuzzing native code, luzer can be used in combination with |
| 33 | +Address Sanitizer or Undefined Behavior Sanitizer to catch extra bugs. |
| 34 | + |
| 35 | +## Project files |
| 36 | + |
| 37 | +### Example project |
| 38 | + |
| 39 | +We recommend viewing |
| 40 | +[lua-example](https://github.com/google/oss-fuzz/tree/master/projects/lua-example) |
| 41 | +as an example of a simple Lua fuzzing project. This example also |
| 42 | +demonstrates how to use luzer's Fuzzed Data Provider. |
| 43 | + |
| 44 | +### project.yaml |
| 45 | + |
| 46 | +The `language` attribute must be specified as follows: |
| 47 | + |
| 48 | +```yaml |
| 49 | +language: c |
| 50 | +``` |
| 51 | +
|
| 52 | +The only supported fuzzing engine is libFuzzer (`libfuzzer`). |
| 53 | + |
| 54 | +```yaml |
| 55 | +fuzzing_engines: |
| 56 | + - libfuzzer |
| 57 | +sanitizers: |
| 58 | + - none |
| 59 | +``` |
| 60 | + |
| 61 | +There is nothing special for sanitizer support in OSS-Fuzz |
| 62 | +infrastructure. luzer builds its own DSO with libFuzzer and |
| 63 | +sanitizer and `compile_lua_fuzzer` (also managed by project) sets |
| 64 | +it to `LD_PRELOAD` if required. |
| 65 | + |
| 66 | +### Dockerfile |
| 67 | + |
| 68 | +The Dockerfile should start by `FROM gcr.io/oss-fuzz-base/base-builder`. |
| 69 | + |
| 70 | +The OSS-Fuzz base Docker images come without any pre-installed |
| 71 | +components required for Lua fuzzing. Apart from that, you should |
| 72 | +usually need to build or install a Lua runtime, luzer module, |
| 73 | +clone the project, set a `WORKDIR`, and copy any necessary files, |
| 74 | +or install any project-specific dependencies here as you normally would. |
| 75 | + |
| 76 | +### Fuzzers |
| 77 | + |
| 78 | +In the simplest case, every fuzzer consists of a single Lua file that defines |
| 79 | +a function `TestOneInput` and executes a function named `luzer.Fuzz()`. |
| 80 | +An example fuzz target could thus be a file `fuzz_basic.lua` with contents: |
| 81 | + |
| 82 | +```lua |
| 83 | +local parser = require("src.luacheck.parser") |
| 84 | +local decoder = require("luacheck.decoder") |
| 85 | +local luzer = require("luzer") |
| 86 | +
|
| 87 | +local function TestOneInput(buf) |
| 88 | + parser.parse(decoder.decode(buf)) |
| 89 | +end |
| 90 | +
|
| 91 | +local args = { |
| 92 | + print_final_stats = 1, |
| 93 | +} |
| 94 | +luzer.Fuzz(TestOneInput, nil, args) |
| 95 | +``` |
| 96 | + |
| 97 | +### compile_lua_fuzzer |
| 98 | + |
| 99 | +Unlike projects for other languages, the base image does not |
| 100 | +include a script that generates a wrapper script that can be used |
| 101 | +as a drop-in replacement for libFuzzer. |
| 102 | + |
| 103 | +Therefore, you need to add such a script yourself. This script |
| 104 | +sets a relative path to Lua runtime that will be used for running |
| 105 | +tests and the necessary environment variables (for example, `LUA_PATH`, |
| 106 | +`LUA_CPATH` and `LD_PRELOAD`) and specifies the path directly to |
| 107 | +the `.lua` file containing the test implementation. The script |
| 108 | +`compile_lua_fuzzer` must accept the same command line flags as |
| 109 | +libFuzzer-based tests. |
| 110 | + |
| 111 | +Note, the resulting wrapper scripts must contain the word "luarocks" |
| 112 | +to pass checks by `bad_build_check` in continuous integration. |
| 113 | + |
| 114 | +Then, you can use the script `compile_lua_fuzzer` to build the fuzzers. |
| 115 | +A usage example from the `lua-example` project is |
| 116 | + |
| 117 | +```shell |
| 118 | +compile_lua_fuzzer lua fuzz_basic.lua |
| 119 | +``` |
| 120 | + |
| 121 | +Arguments are: |
| 122 | + |
| 123 | +* a relative path to a Lua runtime name |
| 124 | +* a relative path to the fuzzing test inside the OSS Fuzz project directory |
| 125 | + |
| 126 | +The `lua-example` projects includes an |
| 127 | +[example](https://github.com/google/oss-fuzz/blob/master/projects/lua-example/compile_lua_fuzzer) |
| 128 | +of such script. |
| 129 | + |
| 130 | +### build.sh |
| 131 | + |
| 132 | +The script is executed within the image built from your [Dockerfile](#Dockerfile). |
| 133 | + |
| 134 | +In general, this script should do the following: |
| 135 | + |
| 136 | +- Set up or build a Lua runtime. |
| 137 | +- Set up or build required dependencies for your tests. |
| 138 | +- Generate wrapper scripts for your tests using [compile_lua_fuzzer](#compile_lua_fuzzer). |
| 139 | + |
| 140 | +Resulting binaries, tests and their wrapper scripts, and a |
| 141 | +directory with Luarocks dependencies should be placed in `$OUT`. |
| 142 | + |
| 143 | +Beware, when installing the luzer module, you need to set the |
| 144 | +environment variable `OSS_FUZZ` to non-empty value, otherwise the |
| 145 | +build may fail. |
| 146 | + |
| 147 | +The [lua-example](https://github.com/google/oss-fuzz/blob/master/projects/lua-example/build.sh) |
| 148 | +project contains an example of a `build.sh` for a Lua projects. |
| 149 | + |
| 150 | +## FuzzedDataProvider |
| 151 | + |
| 152 | +luzer provides a Fuzzed Data Provider that is helpful for splitting |
| 153 | +a fuzz input into multiple parts of various Lua types. Its |
| 154 | +functionality is similar to |
| 155 | +[Fuzzed Data Provider](https://github.com/google/fuzzing/blob/master/docs/split-inputs.md#fuzzed-data-provider) |
| 156 | +available in LLVM. Learn about methods, provided by FDP in luzer, |
| 157 | +in [documentation](https://github.com/ligurio/luzer/blob/master/docs/api.md#structure-aware-fuzzing). |
| 158 | + |
| 159 | +A fuzz target using the `FuzzedDataProvider` would look as follows: |
| 160 | + |
| 161 | +```lua |
| 162 | +local luzer = require("luzer") |
| 163 | +
|
| 164 | +local function TestOneInput(buf) |
| 165 | + local fdp = luzer.FuzzedDataProvider(buf) |
| 166 | + local str = fdp:consume_string(4) |
| 167 | +
|
| 168 | + local b = {} |
| 169 | + str:gsub(".", function(c) table.insert(b, c) end) |
| 170 | + local count = 0 |
| 171 | + if b[1] == "o" then count = count + 1 end |
| 172 | + if b[2] == "o" then count = count + 1 end |
| 173 | + if b[3] == "p" then count = count + 1 end |
| 174 | + if b[4] == "s" then count = count + 1 end |
| 175 | +
|
| 176 | + if count == 4 then assert(nil) end |
| 177 | +end |
| 178 | +
|
| 179 | +local args = { |
| 180 | + only_ascii = 1, |
| 181 | + print_pcs = 1, |
| 182 | +} |
| 183 | +
|
| 184 | +luzer.Fuzz(TestOneInput, nil, args) |
| 185 | +``` |
0 commit comments