hcl

History

Martin Atkins 6c4344623b Unfold the "hcl" directory up into the root The main HCL package is more visible this way, and so it's easier than having to pick it out from dozens of other package directories.		2019-09-09 16:08:19 -07:00
..
config	Unfold the "hcl" directory up into the root	2019-09-09 16:08:19 -07:00
expr	Unfold the "hcl" directory up into the root	2019-09-09 16:08:19 -07:00
template	Unfold the "hcl" directory up into the root	2019-09-09 16:08:19 -07:00
traversal	Unfold the "hcl" directory up into the root	2019-09-09 16:08:19 -07:00
.gitignore	Unfold the "hcl" directory up into the root	2019-09-09 16:08:19 -07:00
Makefile	Unfold the "hcl" directory up into the root	2019-09-09 16:08:19 -07:00
README.md	Unfold the "hcl" directory up into the root	2019-09-09 16:08:19 -07:00

README.md

hclsyntax fuzzing utilities

This directory contains helper functions and corpuses that can be used to fuzz-test the hclsyntax parsers using go-fuzz.

To fuzz, first install go-fuzz and its build tool in your GOPATH:

$ make tools

Now you can fuzz one or all of the parsers:

$ make fuzz-config FUZZ_WORK_DIR=/tmp/hcl2-fuzz-config
$ make fuzz-expr  FUZZ_WORK_DIR=/tmp/hcl2-fuzz-expr
$ make fuzz-template  FUZZ_WORK_DIR=/tmp/hcl2-fuzz-template
$ make fuzz-traversal FUZZ_WORK_DIR=/tmp/hcl2-fuzz-traversal

In all cases, set FUZZ_WORK_DIR to a directory where go-fuzz can keep state as it works. This should ideally be in a ramdisk for efficiency, and should probably not be on an SSD to avoid thrashing it.

Understanding the result

A small number of subdirectories will be created in the work directory.

If you let go-fuzz run for a few minutes (the more minutes the better) it may detect "crashers", which are inputs that caused the parser to panic. Details about these are written to $FUZZ_WORK_DIR/crashers:

$ ls /tmp/hcl2-fuzz-config/crashers
7f5e9ec80c89da14b8b0b238ec88969f658f5a2d
7f5e9ec80c89da14b8b0b238ec88969f658f5a2d.output
7f5e9ec80c89da14b8b0b238ec88969f658f5a2d.quoted

The base file above (with no extension) is the input that caused a crash. The .output file contains the panic stack trace, which you can use as a clue to figure out what caused the crash.

A good first step to fixing a detected crasher is to copy the failing input into one of the unit tests in the hclsyntax package and see it crash there too. After that, it's easy to re-run the test as you try to fix it. The file with the .quoted extension contains a form of the input that is quoted in Go syntax for easy copy-paste into a test case, even if the input contains non-printable characters or other inconvenient symbols.

Rebuilding for new Upstream Code

An archive file is created for go-fuzz to use on the first run of each of the above, as a .zip file created in this directory. If upstream code is changed these will need to be deleted to cause them to be rebuilt with the latest code:

$ make clean