dinkel

README

The Powerful and Adaptable Cypher Fuzzer

Table of Contents

• 📖 Overview
• ⚙ Installation
• 🔎 Fuzzing with Dinkel
  • Prometheus Exporter
• 💻 Contributing
• 🐛 Bugs found by Dinkel

INFO FOR REVIEWER

System disclaimer

Dinkel was tested on amd64 systems running linux. It is possible that some features may not work on others, though the fuzzing process itself should be unaffected.

Downloading dinkel

To download dinkel, refer to the releases and download an appropriate version. If you are using an amd64/linux machine, download the assets of release v0.1.0, whereas if you are using something else, download them from the v0.1.1 release.
Due to the bisection library used only supporting amd64/linux, v0.1.1 does not support bisection. It is available in the v0.1.0 version however

Testing dinkel

Before running dinkel, ensure that there is a bugreports directory present in your PWD, otherwise dinkel will not write out bugreports.

In order to quickly see the effectiveness of dinkel, we recommend running it against an older version of Neo4j, before dinkel was used to find bugs within Neo4j. An easy way to do so is by spinning up a Neo4j 5.6.0 docker container, and running dinkel against it:

docker run --rm -it -p 7687:7687 \
  -e NEO4J_PLUGINS=\[\"apoc\"\] \
  -e NEO4J_AUTH=none \
  -e NEO4J_ACCEPT_LICENSE_AGREEMENT=yes \
  -e NEO4J_server+default_listen_address=0.0.0.0 \
  neo4j:5.6.0

./dinkel fuzz neo4j

Evaluation data

The data used for the evaluation section of the paper is in the /data directory:

Subdirectory	Description
error_bugs	Holds the data used to analyze different aspects of the bugs found, such as size, dependencies, target. Used to generate Figures 10 and 12 in the paper. The data is in the .csv file, while the data processing can be analyzed in the jupyter-notebook file.
feature_distribution	Holds the data used to analyze the distribution of Cypher features within the bugs, creates Figure 9 in the paper. The data is held within the .csv file, while the data processing happens within the jupyter-notebook file within the directory.
runtime_testing	Holds the data used for the sensitivity analysis. Within the directory is a small bash script, which spins up a prometheus docker container, with which the data can be inspected. Simply run the bash script with the -h flag for help.

---

📖 Overview

Dinkel is a state of the art Cypher fuzzer.
It employs on-the-fly state manipulation and self-generating ASTs to generate complex and valid queries with countless data dependencies.

For more detailed information on how dinkel works and performs, please refer to its paper.

⚙ Installation

Requirements:

• Go 1.22.0 or higher

Install dinkel:

$ go install github.com/Anon10214/dinkel@latest

You should now be able to run dinkel from the command line using dinkel.
If you encounter an error, ensure that the GOBIN environment variable is set and in your path.

Alternatively, you may clone this repository and build dinkel locally

$ git clone git@github.com:Anon10214/dinkel.git
$ cd dinkel
$ go build

You should now have a binary which you can run via ./dinkel.

🔎 Fuzzing with Dinkel

⚠ Never run dinkel against a database holding data you don't want to lose, as it will get deleted. ⚠ ️

If you need more info about a certain command, run

dinkel help [command]

Ensure you have a config in your present working directory.
If you cloned the repository, this config will already be in the project's root directory.
Otherwise, you can generate the config by running

dinkel config

Before you start fuzzing a target, spin up an instance of said target. For this, you may want to use the already provided dockerfiles contained in this project's dockerfiles directory. To then fuzz the target, run

dinkel fuzz target [strategy]

You can list available targets and strategies using dinkel help fuzz.

Once a bug was found and a bug report got generated, run

dinkel reduce path/to/bugreport.yml

to reduce the generated query. Note that the reduction is not perfect and you might still have to further reduce the query manually.

To make sure dinkel doesn't report the same bug again, add a regex matching the error message to the targets config.
The entry should be added to the list <the target>.reportedErrors in the config.

You can check that the regex correctly matches the error message by rerunning the bugreport and making sure dinkel now recognizes the query as a REPORTED_BUG.

If you found multiple bugs and thus have a lot of bugreports, you might find use in the command

dinkel bugreports

With this command you can easily rerun, regenerate, reduce, rename and delete your bug reports.

Prometheus Exporter

If you wish to run the fuzzer for a prolonged time you might want to monitor its performance.
You can do this by enabling the builtin prometheus exporter with the --prometheus-exporter port flag in the fuzz command.
Setting this flag exposes the /metrics HTTP endpoint on the specified port, exposing prometheus metrics. These metrics include:

1. query counts
2. statement counts
3. generation latencies
4. query latencies
5. count of query result types

💻 Contributing

Please don't hesitate to create issues if you find a bug in dinkel or wish to share an idea to improve the tool.
Feel free to open a pull request if you have made any improvements to dinkel!

Please refer to the contributing guidelines for more information about how to contribute.

You might have an easier time getting started with developing dinkel after reading its paper.

🐛 Bugs found by Dinkel

If you find a bug using dinkel, remember to responsibly disclose it to the respective developers.
Once the bug is fixed, you may (TODO: maybe add a mailing list?).

So far, dinkel has found over x bugs in four GDBMSs:

Neo4j

1. A
2. B
3. C

RedisGraph

1. A
2. B
3. C

FalkorDB

1. A
2. B
3. C

Apache AGE

1. A
2. B
3. C

Memgraph

1. A
2. B
3. C

Documentation

Overview

A cypher fuzzer generating complex, semantically and syntactically valid queries.

Dinkel provides an easily expandable framework for targeting all possible cypher implementations. Additionally, dinkel supports different fuzzing techniques, targeting exception and logic bugs.

This allows for easy and thorough testing of any cypher implementation with little setup required.

Dinkel achieves query complexity and validity by keeping track of the query context and database state during generation. This information then gets used within the stateful generation of a query's clauses, allowing for complex data dependencies within a query.