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

     1  # hclsyntax fuzzing utilities
     2  
     3  This directory contains helper functions and corpora that can be used to
     4  fuzz-test the `hclsyntax` 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 `hclsyntax` 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 FuzzParseTemplate
    19  $ go test -fuzz FuzzParseTraversalAbs
    20  $ go test -fuzz FuzzParseExpression
    21  $ go test -fuzz FuzzParseConfig
    22  ```
    23  
    24  This command will exit only when a crasher is found (see "Understanding the 
    25  result" below.)
    26  
    27  ## Seed corpus
    28  
    29  The seed corpus for each fuzz test function is stored in the corresponding
    30  directory under `hclsyntax/fuzz/testdata/fuzz/`. For example:
    31  
    32  ```
    33  $ ls hclsyntax/fuzz/testdata/fuzz/FuzzParseTemplate
    34  empty.tmpl
    35  escape-dollar.tmpl
    36  escape-newline-tmpl
    37  ...
    38  ```
    39  
    40  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:
    41  
    42  ```
    43  $ go install golang.org/x/tools/cmd/file2fuzz@latest
    44  $ file2fuzz -help
    45  ```
    46  
    47  ## Understanding the result
    48  
    49  A small number of subdirectories will be created in the work directory.
    50  
    51  If you let `go-fuzz` run for a few minutes (the more minutes the better) it
    52  may detect "crashers", which are inputs that caused the parser to panic.
    53  These are written to `hclsyntax/fuzz/testdata/fuzz/<fuzz test name>/`:
    54  
    55  ```
    56  $ ls hclsyntax/fuzz/testdata/fuzz/FuzzParseTemplate
    57  582528ddfad69eb57775199a43e0f9fd5c94bba343ce7bb6724d4ebafe311ed4
    58  ```
    59  
    60  A good first step to fixing a detected crasher is to copy the failing input
    61  into one of the unit tests in the `hclsyntax` package and see it crash there
    62  too. After that, it's easy to re-run the test as you try to fix it.