updated README and added comments to custom mutator

Author: PBetzler

.devcontainer/Dockerfile

@@ -0,0 +1,26 @@
+FROM mcr.microsoft.com/devcontainers/cpp:1-ubuntu-22.04
+
+#ARG REINSTALL_CMAKE_VERSION_FROM_SOURCE="3.22.2"
+
+# Optionally install the cmake for vcpkg
+#COPY ./reinstall-cmake.sh /tmp/
+
+#RUN if [ "${REINSTALL_CMAKE_VERSION_FROM_SOURCE}" != "none" ]; then \
+#        chmod +x /tmp/reinstall-cmake.sh && /tmp/reinstall-cmake.sh ${REINSTALL_CMAKE_VERSION_FROM_SOURCE}; \
+#    fi \
+#    && rm -f /tmp/reinstall-cmake.sh
+
+# [Optional] Uncomment this section to install additional vcpkg ports.
+# RUN su vscode -c "${VCPKG_ROOT}/vcpkg install <your-port-name-here>"
+
+# [Optional] Uncomment this section to install additional packages.
+RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
+     && apt-get -y install --no-install-recommends cmake clang llvm lcov
+RUN --mount=type=secret,id=credentials \
+    export CIFUZZ_CREDENTIALS=$(cat /run/secrets/credentials) &&\
+    sh -c "$(curl -fsSL http://downloads.code-intelligence.com/assets/install-cifuzz.sh)" $CIFUZZ_CREDENTIALS latest &&\
+    export CIFUZZ_CREDENTIALS=""
+    
+
+RUN sysctl vm.mmap_rnd_bits=30
+RUN cifuzz completion bash > /etc/bash_completion.d/cifuzz

.devcontainer/devcontainer.json

@@ -0,0 +1,39 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/cpp
+{
+	"name": "Cifuzz",
+	"build": {
+		"dockerfile": "Dockerfile",
+		"options": [
+			"--secret=id=credentials,env=CIFUZZ_CREDENTIALS"
+		]
+	},
+	"features": {
+		"ghcr.io/devcontainers-community/features/llvm:3": {}
+	},
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"ryanluker.vscode-coverage-gutters",
+				"ms-vscode.cpptools",
+				"ms-vscode.cpptools-extension-pack",
+				"jeff-hykin.better-cpp-syntax"
+			]
+		}
+	}
+
+	// Features to add to the dev container. More info: https://containers.dev/features.
+	// "features": {},
+
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+
+	// Use 'postCreateCommand' to run commands after the container is created.
+	// "postCreateCommand": "gcc -v",
+
+	// Configure tool-specific properties.
+	// "customizations": {},
+
+	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
+	// "remoteUser": "root"
+}

.devcontainer/reinstall-cmake.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+#-------------------------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See https://go.microsoft.com/fwlink/?linkid=2090316 for license information.
+#-------------------------------------------------------------------------------------------------------------
+#
+set -e
+
+CMAKE_VERSION=${1:-"none"}
+
+if [ "${CMAKE_VERSION}" = "none" ]; then
+    echo "No CMake version specified, skipping CMake reinstallation"
+    exit 0
+fi
+
+# Cleanup temporary directory and associated files when exiting the script.
+cleanup() {
+    EXIT_CODE=$?
+    set +e
+    if [[ -n "${TMP_DIR}" ]]; then
+        echo "Executing cleanup of tmp files"
+        rm -Rf "${TMP_DIR}"
+    fi
+    exit $EXIT_CODE
+}
+trap cleanup EXIT
+
+
+echo "Installing CMake..."
+apt-get -y purge --auto-remove cmake
+mkdir -p /opt/cmake
+
+architecture=$(dpkg --print-architecture)
+case "${architecture}" in
+    arm64)
+        ARCH=aarch64 ;;
+    amd64)
+        ARCH=x86_64 ;;
+    *)
+        echo "Unsupported architecture ${architecture}."
+        exit 1
+        ;;
+esac
+
+CMAKE_BINARY_NAME="cmake-${CMAKE_VERSION}-linux-${ARCH}.sh"
+CMAKE_CHECKSUM_NAME="cmake-${CMAKE_VERSION}-SHA-256.txt"
+TMP_DIR=$(mktemp -d -t cmake-XXXXXXXXXX)
+
+echo "${TMP_DIR}"
+cd "${TMP_DIR}"
+
+curl -sSL "https://github.com/Kitware/CMake/releases/download/v${CMAKE_VERSION}/${CMAKE_BINARY_NAME}" -O
+curl -sSL "https://github.com/Kitware/CMake/releases/download/v${CMAKE_VERSION}/${CMAKE_CHECKSUM_NAME}" -O
+
+sha256sum -c --ignore-missing "${CMAKE_CHECKSUM_NAME}"
+sh "${TMP_DIR}/${CMAKE_BINARY_NAME}" --prefix=/opt/cmake --skip-license
+
+ln -s /opt/cmake/bin/cmake /usr/local/bin/cmake
+ln -s /opt/cmake/bin/ctest /usr/local/bin/ctest

.github/dependabot.yml

@@ -0,0 +1,12 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for more information:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+# https://containers.dev/guide/dependabot
+
+version: 2
+updates:
+ - package-ecosystem: "devcontainers"
+   directory: "/"
+   schedule:
+     interval: weekly

.github/workflows/main.yaml

@@ -4,5 +4,6 @@ build
 cmake-build-debug
 
 /**/.cifuzz-*
-/**/*fuzzer_inputs
-/**/*fuzz_test_inputs
+/**/*fuzz*_inputs
+
+/**/lcov.info

.gitignore

@@ -13,17 +13,18 @@ they are not enough to uncover memory-corruption bugs.
 On the other hand, fuzz testing has established itself as the best practical method to find these
 issues in large code bases such as Google Chrome.
 
-In this example, we demonstrate how you can use CI Fuzz to integrate fuzz testing into your 
-C/C++ projects. The example project uses [CMake](https://cmake.org/) as the build system and contains
-the following three use cases:
-* [Simple Checks Example](src/simple_examples/explore_me.cpp#L10): 
+In this example, we demonstrate how you can use CI Fuzz to integrate fuzz testing into your C/C++ projects. The example project uses [CMake](https://cmake.org/) as the build system and contains the following use cases:
+* [Simple Checks Example](src/simple_examples/explore_me.cpp#L10):
 A simple example that triggers a buffer over when the input parameters satisfy certain criteria.
 We show that CI Fuzz can quickly generate a test case that trigger this bug.
 * [Complex Checks Example](src/simple_examples/explore_me.cpp#L22):
-A more complex example that triggers a use-after-free bug when the input parameters satisfy 
-certain criteria. In this example, the checks are more complex and involve Base64 encoding 
-and XORing with constant value, making it more challenging to find the correct combination of
-input parameters that trigger the bug.
-* [Automotive Example](src/automotive):
-An example that demonstrates the challenges of creating high-quality fuzz tests for complex 
-projects with a large public API. We demonstrate how we can automate most of this task with CI Spark.
+A more complex example that triggers a use-after-free bug when the input parameters satisfy certain criteria. In this example, the checks are more complex and involve Base64 encoding and XORing with constant value, making it more challenging to find the correct combination of input parameters that trigger the bug.
+* [Stateful Example](src/state_example):
+An example that demonstrates the challenges of creating high-quality fuzz tests for complex projects with a large public API. This fuzz test was created with an early version of Code Intelligence auto-generation features, but it is still an excellent example on how to test a large API that keeps state between the calls.
+* [Structure Aware Inputs Example](src/advanced_examples/explore_me.cpp#L8):
+An example that shows how to fuzz an API that requires structured inputs, with the use of the FuzzedDataProvider helper class.
+
+* [Custom Mutator Example](src/advanced_examples/custom_mutator_example_checks_test.cpp#L37):
+An example that is build on top of the [Structure Aware Inputs Example](src/advanced_examples/explore_me.cpp#L8) and shows how to utilize custom mutators to change how the inputs are mutated.
+
+If you want to use the devcontainer environment then export your cifuzz download token to a environment var called "CIFUZZ_CREDENTIALS" like `export CIFUZZ_CREDENTIALS=[my_token]`.

README.md

@@ -34,6 +34,11 @@ FUZZ_TEST(const uint8_t *data, size_t size) {
 }
 
 extern "C" size_t LLVMFuzzerMutate(uint8_t *Data, size_t Size, size_t MaxSize);
+
+/**
+Custom mutator example. In this case we only print out once that we are in a custom mutator and then use te regular one,
+but you can also change the Data how you like. Make sure to return the new length.
+*/
 extern "C" size_t LLVMFuzzerCustomMutator(uint8_t *Data, size_t Size,
                                           size_t MaxSize, unsigned int Seed) {
 
@@ -43,5 +48,6 @@ extern "C" size_t LLVMFuzzerCustomMutator(uint8_t *Data, size_t Size,
         Printed = true;
     }
 
+    // make sure to return the new Size (that needs to be <= MaxSize) as return value!
     return LLVMFuzzerMutate(Data, Size, MaxSize);
 }