github.com/hashicorp/hcl/v2@v2.20.0/hclwrite/fuzz/README.md (about)

     1  # hclwrite fuzzing utilities
     2  
     3  This directory contains helper functions and corpora that can be used to
     4  fuzz-test the `hclwrite` parsers using Go's native fuzz testing capabilities.
     5  
     6  Please see https://go.dev/doc/fuzz/ for more information on fuzzing.
     7  
     8  ## Prerequisites
     9  * Go 1.18
    10  
    11  ## Running the fuzzer
    12  
    13  Each exported function in the `hclwrite` package has a corresponding fuzz test.
    14  These can be run one at a time via `go test`:
    15  
    16  ```
    17  $ cd fuzz
    18  $ go test -fuzz FuzzParseConfig
    19  ```
    20  
    21  This command will exit only when a crasher is found (see "Understanding the 
    22  result" below.)
    23  
    24  ## Seed corpus
    25  
    26  The seed corpus for each fuzz test function is stored in the corresponding
    27  directory under `hclwrite/fuzz/testdata/fuzz/FuzzTest`. For example:
    28  
    29  ```
    30  $ ls hclwrite/fuzz/testdata/fuzz/FuzzParseConfig
    31  attr-expr.hcl
    32  attr.hcl
    33  attr-literal.hcl
    34  ...
    35  ```
    36  
    37  Additional seed inputs can be added to this corpus. Each file must be in the Go 1.18 corpus file format. Files can be converted to this format using the `file2fuzz` tool. To install it:
    38  
    39  ```
    40  $ go install golang.org/x/tools/cmd/file2fuzz@latest
    41  $ file2fuzz -help
    42  ```
    43  
    44  ## Understanding the result
    45  
    46  A small number of subdirectories will be created in the work directory.
    47  
    48  If you let `go-fuzz` run for a few minutes (the more minutes the better) it
    49  may detect "crashers", which are inputs that caused the parser to panic.
    50  These are written to `hclwrite/fuzz/testdata/fuzz/<fuzz test name>/`:
    51  
    52  ```
    53  $ ls hclwrite/fuzz/testdata/fuzz/FuzzParseConfig
    54  582528ddfad69eb57775199a43e0f9fd5c94bba343ce7bb6724d4ebafe311ed4
    55  ```
    56  
    57  A good first step to fixing a detected crasher is to copy the failing input
    58  into one of the unit tests in the `hclwrite` package and see it crash there
    59  too. After that, it's easy to re-run the test as you try to fix it.