{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "# Mutation-Based Fuzzing\n",
    "\n",
    "Most [randomly generated inputs](Fuzzer.ipynb) are syntactically _invalid_ and thus are quickly rejected by the processing program.  To exercise functionality beyond input processing, we must increase chances to obtain valid inputs.  One such way is so-called *mutational fuzzing* – that is, introducing small changes to existing inputs that may still keep the input valid, yet exercise new behavior.  We show how to create such mutations, and how to guide them towards yet uncovered code, applying central concepts from the popular AFL fuzzer."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.183206Z",
     "iopub.status.busy": "2024-01-18T17:14:25.182707Z",
     "iopub.status.idle": "2024-01-18T17:14:25.247203Z",
     "shell.execute_reply": "2024-01-18T17:14:25.246851Z"
    },
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "\n",
       "        <iframe\n",
       "            width=\"640\"\n",
       "            height=\"360\"\n",
       "            src=\"https://www.youtube-nocookie.com/embed/5ROhc_42jQU\"\n",
       "            frameborder=\"0\"\n",
       "            allowfullscreen\n",
       "            \n",
       "        ></iframe>\n",
       "        "
      ],
      "text/plain": [
       "<IPython.lib.display.IFrame at 0x104000b80>"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from bookutils import YouTubeVideo\n",
    "YouTubeVideo('5ROhc_42jQU')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "source": [
    "**Prerequisites**\n",
    "\n",
    "* You should know how basic fuzzing works; for instance, from the [\"Fuzzing\"](Fuzzer.ipynb) chapter.\n",
    "* You should understand the basics of [obtaining coverage](Coverage.ipynb)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "source": [
    "## Synopsis\n",
    "<!-- Automatically generated. Do not edit. -->\n",
    "\n",
    "To [use the code provided in this chapter](Importing.ipynb), write\n",
    "\n",
    "```python\n",
    ">>> from fuzzingbook.MutationFuzzer import <identifier>\n",
    "```\n",
    "\n",
    "and then make use of the following features.\n",
    "\n",
    "\n",
    "This chapter introduces a `MutationFuzzer` class that takes a list of _seed inputs_ which are then mutated:\n",
    "\n",
    "```python\n",
    ">>> seed_input = \"http://www.google.com/search?q=fuzzing\"\n",
    ">>> mutation_fuzzer = MutationFuzzer(seed=[seed_input])\n",
    ">>> [mutation_fuzzer.fuzz() for i in range(10)]\n",
    "['http://www.google.com/search?q=fuzzing',\n",
    " 'http://wwBw.google.com/searh?q=fuzzing',\n",
    " 'http8//wswgoRogle.am/secch?qU=fuzzing',\n",
    " 'ittp://www.googLe.com/serch?q=fuzzingZ',\n",
    " 'httP://wgw.google.com/seasch?Q=fuxzanmgY',\n",
    " 'http://www.google.cxcom/search?q=fuzzing',\n",
    " 'hFttp://ww.-g\\x7fog+le.com/s%arch?q=f-uzz#ing',\n",
    " 'http://www\\x0egoogle.com/seaNrch?q=fuZzing',\n",
    " 'http//www.Ygooge.comsarch?q=fuz~Ijg',\n",
    " 'http8//ww.goog5le.com/sezarc?q=fuzzing']\n",
    "```\n",
    "The `MutationCoverageFuzzer` maintains a _population_ of inputs, which are then evolved in order to maximize coverage.\n",
    "\n",
    "```python\n",
    ">>> mutation_fuzzer = MutationCoverageFuzzer(seed=[seed_input])\n",
    ">>> mutation_fuzzer.runs(http_runner, trials=10000)\n",
    ">>> mutation_fuzzer.population[:5]\n",
    "['http://www.google.com/search?q=fuzzing',\n",
    " 'http://wwv.oogle>co/search7Eq=fuzing',\n",
    " 'http://wwv\\x0eOogleb>co/seakh7Eq\\x1d;fuzing',\n",
    " 'http://wwv\\x0eoglebkooqeakh7Eq\\x1d;fuzing',\n",
    " 'http://wwv\\x0eoglekol=oekh7Eq\\x1d\\x1bf~ing']\n",
    "```\n",
    "![](PICS/MutationFuzzer-synopsis-1.svg)\n",
    "\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Fuzzing with Mutations\n",
    "\n",
    "On November 2013, the first version of [American Fuzzy Lop](http://lcamtuf.coredump.cx/afl/) (AFL) was released. Since then, AFL has become one of the most successful fuzzing tools and comes in many flavors, e.g., [AFLFast](https://github.com/mboehme/aflfast), [AFLGo](https://github.com/aflgo/aflgo), and [AFLSmart](https://github.com/aflsmart/aflsmart) (which are discussed in this book). AFL has made fuzzing a popular choice for automated vulnerability detection. It was the first to demonstrate that vulnerabilities can be detected automatically at a large scale in many security-critical, real-world applications.\n",
    "\n",
    "![American Fuzzy Lop Command Line User Interface](PICS/afl_screen.png)\n",
    "<center><b>Figure 1.</b> American Fuzzy Lop Command Line User Interface</center>\n",
    "\n",
    "In this chapter, we are going to introduce the basics of mutational fuzz testing; the next chapter will then further show how to direct fuzzing towards specific code goals."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Fuzzing a URL Parser\n",
    "\n",
    "Many programs expect their inputs to come in a very specific format before they would actually process them.  As an example, think of a program that accepts a URL (a Web address).  The URL has to be in a valid format (i.e., the URL format) such that the program can deal with it.  When fuzzing with random inputs, what are our chances to actually produce a valid URL?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "To get deeper into the problem, let us explore what URLs are made of.  A URL consists of a number of elements:\n",
    "\n",
    "    scheme://netloc/path?query#fragment\n",
    "    \n",
    "where\n",
    "\n",
    "* `scheme` is the protocol to be used, including `http`, `https`, `ftp`, `file`...\n",
    "* `netloc` is the name of the host to connect to, such as `www.google.com`\n",
    "* `path` is the path on that very host, such as `search`\n",
    "* `query` is a list of key/value pairs, such as `q=fuzzing`\n",
    "* `fragment` is a marker for a location in the retrieved document, such as `#result`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "In Python, we can use the `urlparse()` function to parse and decompose a URL into its parts."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.271452Z",
     "iopub.status.busy": "2024-01-18T17:14:25.271233Z",
     "iopub.status.idle": "2024-01-18T17:14:25.273609Z",
     "shell.execute_reply": "2024-01-18T17:14:25.273286Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "import bookutils.setup"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.275405Z",
     "iopub.status.busy": "2024-01-18T17:14:25.275282Z",
     "iopub.status.idle": "2024-01-18T17:14:25.277143Z",
     "shell.execute_reply": "2024-01-18T17:14:25.276823Z"
    },
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "from typing import Tuple, List, Callable, Set, Any"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.278816Z",
     "iopub.status.busy": "2024-01-18T17:14:25.278699Z",
     "iopub.status.idle": "2024-01-18T17:14:25.280370Z",
     "shell.execute_reply": "2024-01-18T17:14:25.280124Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "from urllib.parse import urlparse"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.281948Z",
     "iopub.status.busy": "2024-01-18T17:14:25.281846Z",
     "iopub.status.idle": "2024-01-18T17:14:25.283952Z",
     "shell.execute_reply": "2024-01-18T17:14:25.283678Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "ParseResult(scheme='http', netloc='www.google.com', path='/search', params='', query='q=fuzzing', fragment='')"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "urlparse(\"http://www.google.com/search?q=fuzzing\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "We see how the result encodes the individual parts of the URL in different attributes."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Let us now assume we have a program that takes a URL as input.  To simplify things, we won't let it do very much; we simply have it check the passed URL for validity.  If the URL is valid, it returns True; otherwise, it raises an exception."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.285835Z",
     "iopub.status.busy": "2024-01-18T17:14:25.285701Z",
     "iopub.status.idle": "2024-01-18T17:14:25.288071Z",
     "shell.execute_reply": "2024-01-18T17:14:25.287722Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "def http_program(url: str) -> bool:\n",
    "    supported_schemes = [\"http\", \"https\"]\n",
    "    result = urlparse(url)\n",
    "    if result.scheme not in supported_schemes:\n",
    "        raise ValueError(\"Scheme must be one of \" + \n",
    "                         repr(supported_schemes))\n",
    "    if result.netloc == '':\n",
    "        raise ValueError(\"Host must be non-empty\")\n",
    "\n",
    "    # Do something with the URL\n",
    "    return True"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Let us now go and fuzz `http_program()`.  To fuzz, we use the full range of printable ASCII characters, such that `:`, `/`, and lowercase letters are included."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.289766Z",
     "iopub.status.busy": "2024-01-18T17:14:25.289639Z",
     "iopub.status.idle": "2024-01-18T17:14:25.372467Z",
     "shell.execute_reply": "2024-01-18T17:14:25.372113Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "from Fuzzer import fuzzer"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.374511Z",
     "iopub.status.busy": "2024-01-18T17:14:25.374369Z",
     "iopub.status.idle": "2024-01-18T17:14:25.376771Z",
     "shell.execute_reply": "2024-01-18T17:14:25.376492Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'\"N&+slk%h\\x7fyp5o\\'@[3(rW*M5W]tMFPU4\\\\P@tz%[X?uo\\\\1?b4T;1bDeYtHx #UJ5w}pMmPodJM,_'"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "fuzzer(char_start=32, char_range=96)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Let's try to fuzz with 1000 random inputs and see whether we have some success."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.378354Z",
     "iopub.status.busy": "2024-01-18T17:14:25.378252Z",
     "iopub.status.idle": "2024-01-18T17:14:25.404657Z",
     "shell.execute_reply": "2024-01-18T17:14:25.404372Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "for i in range(1000):\n",
    "    try:\n",
    "        url = fuzzer()\n",
    "        result = http_program(url)\n",
    "        print(\"Success!\")\n",
    "    except ValueError:\n",
    "        pass"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "What are the chances of actually getting a valid URL?  We need our string to start with `\"http://\"` or `\"https://\"`.  Let's take the `\"http://\"` case first.  These are seven very specific characters we need to start with.  The chance of producing these seven characters randomly (with a character range of 96 different characters) is $1 : 96^7$, or"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.406546Z",
     "iopub.status.busy": "2024-01-18T17:14:25.406451Z",
     "iopub.status.idle": "2024-01-18T17:14:25.409149Z",
     "shell.execute_reply": "2024-01-18T17:14:25.408856Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "75144747810816"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "96 ** 7"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "The odds of producing a `\"https://\"` prefix are even worse, at $1 : 96^8$:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.411176Z",
     "iopub.status.busy": "2024-01-18T17:14:25.411009Z",
     "iopub.status.idle": "2024-01-18T17:14:25.413657Z",
     "shell.execute_reply": "2024-01-18T17:14:25.413353Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "7213895789838336"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "96 ** 8"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "which gives us a total chance of"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.415395Z",
     "iopub.status.busy": "2024-01-18T17:14:25.415279Z",
     "iopub.status.idle": "2024-01-18T17:14:25.417537Z",
     "shell.execute_reply": "2024-01-18T17:14:25.417187Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1.344627131107667e-14"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "likelihood = 1 / (96 ** 7) + 1 / (96 ** 8)\n",
    "likelihood"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "And this is the number of runs (on average) we'd need to produce a valid URL scheme:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.419292Z",
     "iopub.status.busy": "2024-01-18T17:14:25.419171Z",
     "iopub.status.idle": "2024-01-18T17:14:25.421364Z",
     "shell.execute_reply": "2024-01-18T17:14:25.421078Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "74370059689055.02"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "1 / likelihood"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Let's measure how long one run of `http_program()` takes:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.423203Z",
     "iopub.status.busy": "2024-01-18T17:14:25.423080Z",
     "iopub.status.idle": "2024-01-18T17:14:25.424818Z",
     "shell.execute_reply": "2024-01-18T17:14:25.424469Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "from Timer import Timer"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.426434Z",
     "iopub.status.busy": "2024-01-18T17:14:25.426315Z",
     "iopub.status.idle": "2024-01-18T17:14:25.453841Z",
     "shell.execute_reply": "2024-01-18T17:14:25.453550Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2.451037500577513e-05"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "trials = 1000\n",
    "with Timer() as t:\n",
    "    for i in range(trials):\n",
    "        try:\n",
    "            url = fuzzer()\n",
    "            result = http_program(url)\n",
    "            print(\"Success!\")\n",
    "        except ValueError:\n",
    "            pass\n",
    "\n",
    "duration_per_run_in_seconds = t.elapsed_time() / trials\n",
    "duration_per_run_in_seconds"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "That's pretty fast, isn't it?  Unfortunately, we have a lot of runs to cover."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.455824Z",
     "iopub.status.busy": "2024-01-18T17:14:25.455627Z",
     "iopub.status.idle": "2024-01-18T17:14:25.458517Z",
     "shell.execute_reply": "2024-01-18T17:14:25.457986Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1822838052.1806188"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "seconds_until_success = duration_per_run_in_seconds * (1 / likelihood)\n",
    "seconds_until_success"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "which translates into"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.460570Z",
     "iopub.status.busy": "2024-01-18T17:14:25.460430Z",
     "iopub.status.idle": "2024-01-18T17:14:25.463022Z",
     "shell.execute_reply": "2024-01-18T17:14:25.462730Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "57.76225226825294"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hours_until_success = seconds_until_success / 3600\n",
    "days_until_success = hours_until_success / 24\n",
    "years_until_success = days_until_success / 365.25\n",
    "years_until_success"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Even if we parallelize things a lot, we're still in for months to years of waiting.  And that's for getting _one_ successful run that will get deeper into `http_program()`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "What basic fuzzing will do well is to test `urlparse()`, and if there is an error in this parsing function, it has good chances of uncovering it.  But as long as we cannot produce a valid input, we are out of luck in reaching any deeper functionality."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Mutating Inputs\n",
    "\n",
    "The alternative to generating random strings from scratch is to start with a given _valid_ input, and then to subsequently _mutate_ it.  A _mutation_ in this context is a simple string manipulation - say, inserting a (random) character, deleting a character, or flipping a bit in a character representation.  This is called *mutational fuzzing* – in contrast to the _generational fuzzing_ techniques discussed earlier.\n",
    "\n",
    "Here are some mutations to get you started:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.464877Z",
     "iopub.status.busy": "2024-01-18T17:14:25.464630Z",
     "iopub.status.idle": "2024-01-18T17:14:25.466444Z",
     "shell.execute_reply": "2024-01-18T17:14:25.466158Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "import random"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.468342Z",
     "iopub.status.busy": "2024-01-18T17:14:25.468210Z",
     "iopub.status.idle": "2024-01-18T17:14:25.470338Z",
     "shell.execute_reply": "2024-01-18T17:14:25.470000Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [],
   "source": [
    "def delete_random_character(s: str) -> str:\n",
    "    \"\"\"Returns s with a random character deleted\"\"\"\n",
    "    if s == \"\":\n",
    "        return s\n",
    "\n",
    "    pos = random.randint(0, len(s) - 1)\n",
    "    # print(\"Deleting\", repr(s[pos]), \"at\", pos)\n",
    "    return s[:pos] + s[pos + 1:]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.472075Z",
     "iopub.status.busy": "2024-01-18T17:14:25.471964Z",
     "iopub.status.idle": "2024-01-18T17:14:25.474089Z",
     "shell.execute_reply": "2024-01-18T17:14:25.473834Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "'A uick brown fox'\n",
      "'A quic brown fox'\n",
      "'A quick brown fo'\n",
      "'A quic brown fox'\n",
      "'A quick bown fox'\n",
      "'A quick bown fox'\n",
      "'A quick brown fx'\n",
      "'A quick brown ox'\n",
      "'A quick brow fox'\n",
      "'A quic brown fox'\n"
     ]
    }
   ],
   "source": [
    "seed_input = \"A quick brown fox\"\n",
    "for i in range(10):\n",
    "    x = delete_random_character(seed_input)\n",
    "    print(repr(x))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.476522Z",
     "iopub.status.busy": "2024-01-18T17:14:25.476160Z",
     "iopub.status.idle": "2024-01-18T17:14:25.478640Z",
     "shell.execute_reply": "2024-01-18T17:14:25.478340Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [],
   "source": [
    "def insert_random_character(s: str) -> str:\n",
    "    \"\"\"Returns s with a random character inserted\"\"\"\n",
    "    pos = random.randint(0, len(s))\n",
    "    random_character = chr(random.randrange(32, 127))\n",
    "    # print(\"Inserting\", repr(random_character), \"at\", pos)\n",
    "    return s[:pos] + random_character + s[pos:]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.480288Z",
     "iopub.status.busy": "2024-01-18T17:14:25.480138Z",
     "iopub.status.idle": "2024-01-18T17:14:25.482295Z",
     "shell.execute_reply": "2024-01-18T17:14:25.481967Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "'A quick brvown fox'\n",
      "'A quwick brown fox'\n",
      "'A qBuick brown fox'\n",
      "'A quick broSwn fox'\n",
      "'A quick brown fvox'\n",
      "'A quick brown 3fox'\n",
      "'A quick brNown fox'\n",
      "'A quick brow4n fox'\n",
      "'A quick brown fox8'\n",
      "'A equick brown fox'\n"
     ]
    }
   ],
   "source": [
    "for i in range(10):\n",
    "    print(repr(insert_random_character(seed_input)))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.484112Z",
     "iopub.status.busy": "2024-01-18T17:14:25.483870Z",
     "iopub.status.idle": "2024-01-18T17:14:25.486283Z",
     "shell.execute_reply": "2024-01-18T17:14:25.485988Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [],
   "source": [
    "def flip_random_character(s):\n",
    "    \"\"\"Returns s with a random bit flipped in a random position\"\"\"\n",
    "    if s == \"\":\n",
    "        return s\n",
    "\n",
    "    pos = random.randint(0, len(s) - 1)\n",
    "    c = s[pos]\n",
    "    bit = 1 << random.randint(0, 6)\n",
    "    new_c = chr(ord(c) ^ bit)\n",
    "    # print(\"Flipping\", bit, \"in\", repr(c) + \", giving\", repr(new_c))\n",
    "    return s[:pos] + new_c + s[pos + 1:]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.487845Z",
     "iopub.status.busy": "2024-01-18T17:14:25.487736Z",
     "iopub.status.idle": "2024-01-18T17:14:25.489949Z",
     "shell.execute_reply": "2024-01-18T17:14:25.489590Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "'A quick bRown fox'\n",
      "'A quici brown fox'\n",
      "'A\"quick brown fox'\n",
      "'A quick brown$fox'\n",
      "'A quick bpown fox'\n",
      "'A quick brown!fox'\n",
      "'A 1uick brown fox'\n",
      "'@ quick brown fox'\n",
      "'A quic+ brown fox'\n",
      "'A quick bsown fox'\n"
     ]
    }
   ],
   "source": [
    "for i in range(10):\n",
    "    print(repr(flip_random_character(seed_input)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Let us now create a random mutator that randomly chooses which mutation to apply:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.492390Z",
     "iopub.status.busy": "2024-01-18T17:14:25.492221Z",
     "iopub.status.idle": "2024-01-18T17:14:25.494416Z",
     "shell.execute_reply": "2024-01-18T17:14:25.494069Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "def mutate(s: str) -> str:\n",
    "    \"\"\"Return s with a random mutation applied\"\"\"\n",
    "    mutators = [\n",
    "        delete_random_character,\n",
    "        insert_random_character,\n",
    "        flip_random_character\n",
    "    ]\n",
    "    mutator = random.choice(mutators)\n",
    "    # print(mutator)\n",
    "    return mutator(s)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.496011Z",
     "iopub.status.busy": "2024-01-18T17:14:25.495887Z",
     "iopub.status.idle": "2024-01-18T17:14:25.497895Z",
     "shell.execute_reply": "2024-01-18T17:14:25.497660Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "'A qzuick brown fox'\n",
      "' quick brown fox'\n",
      "'A quick Brown fox'\n",
      "'A qMuick brown fox'\n",
      "'A qu_ick brown fox'\n",
      "'A quick bXrown fox'\n",
      "'A quick brown fx'\n",
      "'A quick!brown fox'\n",
      "'A! quick brown fox'\n",
      "'A quick brownfox'\n"
     ]
    }
   ],
   "source": [
    "for i in range(10):\n",
    "    print(repr(mutate(\"A quick brown fox\")))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "The idea is now that _if_ we have some valid input(s) to begin with, we may create more input candidates by applying one of the above mutations.  To see how this works, let's get back to URLs."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Mutating URLs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Let us now get back to our URL parsing problem.  Let us create a function `is_valid_url()` that checks whether `http_program()` accepts the input."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.499552Z",
     "iopub.status.busy": "2024-01-18T17:14:25.499435Z",
     "iopub.status.idle": "2024-01-18T17:14:25.501301Z",
     "shell.execute_reply": "2024-01-18T17:14:25.501032Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "def is_valid_url(url: str) -> bool:\n",
    "    try:\n",
    "        result = http_program(url)\n",
    "        return True\n",
    "    except ValueError:\n",
    "        return False"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.502823Z",
     "iopub.status.busy": "2024-01-18T17:14:25.502722Z",
     "iopub.status.idle": "2024-01-18T17:14:25.504358Z",
     "shell.execute_reply": "2024-01-18T17:14:25.504076Z"
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "assert is_valid_url(\"http://www.google.com/search?q=fuzzing\")\n",
    "assert not is_valid_url(\"xyzzy\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Let us now apply the `mutate()` function on a given URL and see how many valid inputs we obtain."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.506147Z",
     "iopub.status.busy": "2024-01-18T17:14:25.506019Z",
     "iopub.status.idle": "2024-01-18T17:14:25.508305Z",
     "shell.execute_reply": "2024-01-18T17:14:25.507933Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "seed_input = \"http://www.google.com/search?q=fuzzing\"\n",
    "valid_inputs = set()\n",
    "trials = 20\n",
    "\n",
    "for i in range(trials):\n",
    "    inp = mutate(seed_input)\n",
    "    if is_valid_url(inp):\n",
    "        valid_inputs.add(inp)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "We can now observe that by _mutating_ the original input, we get a high proportion of valid inputs:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.510191Z",
     "iopub.status.busy": "2024-01-18T17:14:25.510008Z",
     "iopub.status.idle": "2024-01-18T17:14:25.512347Z",
     "shell.execute_reply": "2024-01-18T17:14:25.512058Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.8"
      ]
     },
     "execution_count": 30,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "len(valid_inputs) / trials"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "What are the odds of also producing a `https:` prefix by mutating a `http:` sample seed input?  We have to insert ($1 : 3$) the right character `'s'` ($1 : 96$) into the correct position ($1 : l$), where $l$ is the length of our seed input.  This means that on average, we need this many runs:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.513989Z",
     "iopub.status.busy": "2024-01-18T17:14:25.513874Z",
     "iopub.status.idle": "2024-01-18T17:14:25.516058Z",
     "shell.execute_reply": "2024-01-18T17:14:25.515807Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "10944"
      ]
     },
     "execution_count": 31,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "trials = 3 * 96 * len(seed_input)\n",
    "trials"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "We can actually afford this.  Let's try:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.517678Z",
     "iopub.status.busy": "2024-01-18T17:14:25.517529Z",
     "iopub.status.idle": "2024-01-18T17:14:25.519236Z",
     "shell.execute_reply": "2024-01-18T17:14:25.518972Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "from Timer import Timer"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.520757Z",
     "iopub.status.busy": "2024-01-18T17:14:25.520644Z",
     "iopub.status.idle": "2024-01-18T17:14:25.528570Z",
     "shell.execute_reply": "2024-01-18T17:14:25.528309Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Success after 3656 trials in 0.0055189170088851824 seconds\n"
     ]
    }
   ],
   "source": [
    "trials = 0\n",
    "with Timer() as t:\n",
    "    while True:\n",
    "        trials += 1\n",
    "        inp = mutate(seed_input)\n",
    "        if inp.startswith(\"https://\"):\n",
    "            print(\n",
    "                \"Success after\",\n",
    "                trials,\n",
    "                \"trials in\",\n",
    "                t.elapsed_time(),\n",
    "                \"seconds\")\n",
    "            break"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Of course, if we wanted to get, say, an `\"ftp://\"` prefix, we would need more mutations and more runs – most important, though, we would need to apply _multiple_ mutations."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Multiple Mutations\n",
    "\n",
    "So far, we have only applied one single mutation on a sample string.  However, we can also apply _multiple_ mutations, further changing it.  What happens, for instance, if we apply, say, 20 mutations on our sample string?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.530327Z",
     "iopub.status.busy": "2024-01-18T17:14:25.530203Z",
     "iopub.status.idle": "2024-01-18T17:14:25.531860Z",
     "shell.execute_reply": "2024-01-18T17:14:25.531587Z"
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [],
   "source": [
    "seed_input = \"http://www.google.com/search?q=fuzzing\"\n",
    "mutations = 50"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.533560Z",
     "iopub.status.busy": "2024-01-18T17:14:25.533236Z",
     "iopub.status.idle": "2024-01-18T17:14:25.535574Z",
     "shell.execute_reply": "2024-01-18T17:14:25.535330Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0 mutations: 'http://www.google.com/search?q=fuzzing'\n",
      "5 mutations: 'http:/L/www.googlej.com/seaRchq=fuz:ing'\n",
      "10 mutations: 'http:/L/www.ggoWglej.com/seaRchqfu:in'\n",
      "15 mutations: 'http:/L/wwggoWglej.com/seaR3hqf,u:in'\n",
      "20 mutations: 'htt://wwggoVgle\"j.som/seaR3hqf,u:in'\n",
      "25 mutations: 'htt://fwggoVgle\"j.som/eaRd3hqf,u^:in'\n",
      "30 mutations: 'htv://>fwggoVgle\"j.qom/ea0Rd3hqf,u^:i'\n",
      "35 mutations: 'htv://>fwggozVle\"Bj.qom/eapRd[3hqf,u^:i'\n",
      "40 mutations: 'htv://>fwgeo6zTle\"Bj.\\'qom/eapRd[3hqf,tu^:i'\n",
      "45 mutations: 'htv://>fwgeo]6zTle\"BjM.\\'qom/eaR[3hqf,tu^:i'\n"
     ]
    }
   ],
   "source": [
    "inp = seed_input\n",
    "for i in range(mutations):\n",
    "    if i % 5 == 0:\n",
    "        print(i, \"mutations:\", repr(inp))\n",
    "    inp = mutate(inp)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "As you see, the original seed input is hardly recognizable anymore.  By mutating the input again and again, we get a higher variety in the input."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "To implement such multiple mutations in a single package, let us introduce a `MutationFuzzer` class.  It takes a seed (a list of strings) as well as a minimum and a maximum number of mutations.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.537538Z",
     "iopub.status.busy": "2024-01-18T17:14:25.537105Z",
     "iopub.status.idle": "2024-01-18T17:14:25.538997Z",
     "shell.execute_reply": "2024-01-18T17:14:25.538720Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "from Fuzzer import Fuzzer"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.541238Z",
     "iopub.status.busy": "2024-01-18T17:14:25.541080Z",
     "iopub.status.idle": "2024-01-18T17:14:25.543516Z",
     "shell.execute_reply": "2024-01-18T17:14:25.543268Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "class MutationFuzzer(Fuzzer):\n",
    "    \"\"\"Base class for mutational fuzzing\"\"\"\n",
    "\n",
    "    def __init__(self, seed: List[str],\n",
    "                 min_mutations: int = 2,\n",
    "                 max_mutations: int = 10) -> None:\n",
    "        \"\"\"Constructor.\n",
    "        `seed` - a list of (input) strings to mutate.\n",
    "        `min_mutations` - the minimum number of mutations to apply.\n",
    "        `max_mutations` - the maximum number of mutations to apply.\n",
    "        \"\"\"\n",
    "        self.seed = seed\n",
    "        self.min_mutations = min_mutations\n",
    "        self.max_mutations = max_mutations\n",
    "        self.reset()\n",
    "\n",
    "    def reset(self) -> None:\n",
    "        \"\"\"Set population to initial seed.\n",
    "        To be overloaded in subclasses.\"\"\"\n",
    "        self.population = self.seed\n",
    "        self.seed_index = 0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "In the following, let us develop `MutationFuzzer` further by adding more methods to it.  The Python language requires us to define an entire class with all methods as a single, continuous unit; however, we would like to introduce one method after another.  To avoid this problem, we use a special hack: Whenever we want to introduce a new method to some class `C`, we use the construct\n",
    "\n",
    "```python\n",
    "class C(C):\n",
    "    def new_method(self, args):\n",
    "        pass\n",
    "```\n",
    "\n",
    "This seems to define `C` as a subclass of itself, which would make no sense – but actually, it introduces a new `C` class as a subclass of the _old_ `C` class, and then shadowing the old `C` definition.  What this gets us is a `C` class with `new_method()` as a method, which is just what we want.  (`C` objects defined earlier will retain the earlier `C` definition, though, and thus must be rebuilt.)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Using this hack, we can now add a `mutate()` method that actually invokes the above `mutate()` function.  Having `mutate()` as a method is useful when we want to extend a `MutationFuzzer` later."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.545175Z",
     "iopub.status.busy": "2024-01-18T17:14:25.545071Z",
     "iopub.status.idle": "2024-01-18T17:14:25.546830Z",
     "shell.execute_reply": "2024-01-18T17:14:25.546594Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "class MutationFuzzer(MutationFuzzer):\n",
    "    def mutate(self, inp: str) -> str:\n",
    "        return mutate(inp)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Let's get back to our strategy, maximizing _diversity in coverage_ in our population.  First, let us create a method `create_candidate()`, which randomly picks some input from our current population (`self.population`), and then applies between `min_mutations` and `max_mutations` mutation steps, returning the final result:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.548224Z",
     "iopub.status.busy": "2024-01-18T17:14:25.548131Z",
     "iopub.status.idle": "2024-01-18T17:14:25.550073Z",
     "shell.execute_reply": "2024-01-18T17:14:25.549814Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "class MutationFuzzer(MutationFuzzer):\n",
    "    def create_candidate(self) -> str:\n",
    "        \"\"\"Create a new candidate by mutating a population member\"\"\"\n",
    "        candidate = random.choice(self.population)\n",
    "        trials = random.randint(self.min_mutations, self.max_mutations)\n",
    "        for i in range(trials):\n",
    "            candidate = self.mutate(candidate)\n",
    "        return candidate"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "The `fuzz()` method is set to first pick the seeds; when these are gone, we mutate:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.551606Z",
     "iopub.status.busy": "2024-01-18T17:14:25.551504Z",
     "iopub.status.idle": "2024-01-18T17:14:25.553509Z",
     "shell.execute_reply": "2024-01-18T17:14:25.553260Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "class MutationFuzzer(MutationFuzzer):\n",
    "    def fuzz(self) -> str:\n",
    "        if self.seed_index < len(self.seed):\n",
    "            # Still seeding\n",
    "            self.inp = self.seed[self.seed_index]\n",
    "            self.seed_index += 1\n",
    "        else:\n",
    "            # Mutating\n",
    "            self.inp = self.create_candidate()\n",
    "        return self.inp"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Here is the `fuzz()` method in action. With every new invocation of `fuzz()`, we get another variant with multiple mutations applied.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.554994Z",
     "iopub.status.busy": "2024-01-18T17:14:25.554878Z",
     "iopub.status.idle": "2024-01-18T17:14:25.557250Z",
     "shell.execute_reply": "2024-01-18T17:14:25.556975Z"
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'http://www.google.com/search?q=fuzzing'"
      ]
     },
     "execution_count": 41,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "seed_input = \"http://www.google.com/search?q=fuzzing\"\n",
    "mutation_fuzzer = MutationFuzzer(seed=[seed_input])\n",
    "mutation_fuzzer.fuzz()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.559126Z",
     "iopub.status.busy": "2024-01-18T17:14:25.558988Z",
     "iopub.status.idle": "2024-01-18T17:14:25.561336Z",
     "shell.execute_reply": "2024-01-18T17:14:25.561058Z"
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'http://www.gogl9ecom/earch?qfuzzing'"
      ]
     },
     "execution_count": 42,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mutation_fuzzer.fuzz()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.562912Z",
     "iopub.status.busy": "2024-01-18T17:14:25.562790Z",
     "iopub.status.idle": "2024-01-18T17:14:25.564953Z",
     "shell.execute_reply": "2024-01-18T17:14:25.564719Z"
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'htotq:/www.googleom/yseach?q=fzzijg'"
      ]
     },
     "execution_count": 43,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mutation_fuzzer.fuzz()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "The higher variety in inputs, though, increases the risk of having an invalid input.  The key to success lies in the idea of _guiding_ these mutations – that is, _keeping those that are especially valuable._"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Guiding by Coverage\n",
    "\n",
    "To cover as much functionality as possible, one can rely on either _specified_ or _implemented_ functionality, as discussed in the [\"Coverage\"](Coverage.ipynb) chapter.  For now, we will not assume that there is a specification of program behavior (although it _definitely_ would be good to have one!).  We _will_ assume, though, that the program to be tested exists – and that we can leverage its structure to guide test generation.\n",
    "\n",
    "Since testing always executes the program at hand, one can always gather information about its execution – the least is the information needed to decide whether a test passes or fails.  Since coverage is frequently measured as well to determine test quality, let us also assume we can retrieve coverage of a test run.  The question is then: _How can we leverage coverage to guide test generation?_"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "One particularly successful idea is implemented in the popular fuzzer named [American fuzzy lop](http://lcamtuf.coredump.cx/afl/), or *AFL* for short.  Just like our examples above, AFL evolves test cases that have been successful – but for AFL, \"success\" means _finding a new path through the program execution_.  This way, AFL can keep on mutating inputs that so far have found new paths; and if an input finds another path, it will be retained as well."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Let us build such a strategy.  We start with introducing a `Runner` class that captures the coverage for a given function.  First, a `FunctionRunner` class:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 44,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.566642Z",
     "iopub.status.busy": "2024-01-18T17:14:25.566526Z",
     "iopub.status.idle": "2024-01-18T17:14:25.568091Z",
     "shell.execute_reply": "2024-01-18T17:14:25.567845Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "from Fuzzer import Runner"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 45,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.569535Z",
     "iopub.status.busy": "2024-01-18T17:14:25.569451Z",
     "iopub.status.idle": "2024-01-18T17:14:25.572019Z",
     "shell.execute_reply": "2024-01-18T17:14:25.571740Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "class FunctionRunner(Runner):\n",
    "    def __init__(self, function: Callable) -> None:\n",
    "        \"\"\"Initialize.  `function` is a function to be executed\"\"\"\n",
    "        self.function = function\n",
    "\n",
    "    def run_function(self, inp: str) -> Any:\n",
    "        return self.function(inp)\n",
    "\n",
    "    def run(self, inp: str) -> Tuple[Any, str]:\n",
    "        try:\n",
    "            result = self.run_function(inp)\n",
    "            outcome = self.PASS\n",
    "        except Exception:\n",
    "            result = None\n",
    "            outcome = self.FAIL\n",
    "\n",
    "        return result, outcome"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 46,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.573569Z",
     "iopub.status.busy": "2024-01-18T17:14:25.573451Z",
     "iopub.status.idle": "2024-01-18T17:14:25.575722Z",
     "shell.execute_reply": "2024-01-18T17:14:25.575351Z"
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(True, 'PASS')"
      ]
     },
     "execution_count": 46,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "http_runner = FunctionRunner(http_program)\n",
    "http_runner.run(\"https://foo.bar/\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "We can now extend the `FunctionRunner` class such that it also measures coverage.  After invoking `run()`, the `coverage()` method returns the coverage achieved in the last run."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 47,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.578378Z",
     "iopub.status.busy": "2024-01-18T17:14:25.578206Z",
     "iopub.status.idle": "2024-01-18T17:14:25.894243Z",
     "shell.execute_reply": "2024-01-18T17:14:25.893868Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "from Coverage import Coverage, population_coverage, Location"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 48,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.896307Z",
     "iopub.status.busy": "2024-01-18T17:14:25.896138Z",
     "iopub.status.idle": "2024-01-18T17:14:25.898669Z",
     "shell.execute_reply": "2024-01-18T17:14:25.898416Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "class FunctionCoverageRunner(FunctionRunner):\n",
    "    def run_function(self, inp: str) -> Any:\n",
    "        with Coverage() as cov:\n",
    "            try:\n",
    "                result = super().run_function(inp)\n",
    "            except Exception as exc:\n",
    "                self._coverage = cov.coverage()\n",
    "                raise exc\n",
    "\n",
    "        self._coverage = cov.coverage()\n",
    "        return result\n",
    "\n",
    "    def coverage(self) -> Set[Location]:\n",
    "        return self._coverage"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 49,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.900133Z",
     "iopub.status.busy": "2024-01-18T17:14:25.900022Z",
     "iopub.status.idle": "2024-01-18T17:14:25.902464Z",
     "shell.execute_reply": "2024-01-18T17:14:25.902197Z"
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(True, 'PASS')"
      ]
     },
     "execution_count": 49,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "http_runner = FunctionCoverageRunner(http_program)\n",
    "http_runner.run(\"https://foo.bar/\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Here are the first five locations covered: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 50,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.904288Z",
     "iopub.status.busy": "2024-01-18T17:14:25.904168Z",
     "iopub.status.idle": "2024-01-18T17:14:25.906179Z",
     "shell.execute_reply": "2024-01-18T17:14:25.905855Z"
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[('http_program', 3), ('urlparse', 394), ('urlparse', 400), ('_noop', 104), ('urlsplit', 460)]\n"
     ]
    }
   ],
   "source": [
    "print(list(http_runner.coverage())[:5])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "run_control": {},
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Now for the main class.  We maintain the population and a set of coverages already achieved (`coverages_seen`).  The `fuzz()` helper function takes an input and runs the given `function()` on it.  If its coverage is new (i.e. not in `coverages_seen`), the input is added to `population` and the coverage to `coverages_seen`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 51,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.907872Z",
     "iopub.status.busy": "2024-01-18T17:14:25.907756Z",
     "iopub.status.idle": "2024-01-18T17:14:25.910362Z",
     "shell.execute_reply": "2024-01-18T17:14:25.910102Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "class MutationCoverageFuzzer(MutationFuzzer):\n",
    "    \"\"\"Fuzz with mutated inputs based on coverage\"\"\"\n",
    "\n",
    "    def reset(self) -> None:\n",
    "        super().reset()\n",
    "        self.coverages_seen: Set[frozenset] = set()\n",
    "        # Now empty; we fill this with seed in the first fuzz runs\n",
    "        self.population = []\n",
    "\n",
    "    def run(self, runner: FunctionCoverageRunner) -> Any:  # type: ignore\n",
    "        \"\"\"Run function(inp) while tracking coverage.\n",
    "           If we reach new coverage,\n",
    "           add inp to population and its coverage to population_coverage\n",
    "        \"\"\"\n",
    "        result, outcome = super().run(runner)\n",
    "        new_coverage = frozenset(runner.coverage())\n",
    "        if outcome == Runner.PASS and new_coverage not in self.coverages_seen:\n",
    "            # We have new coverage\n",
    "            self.population.append(self.inp)\n",
    "            self.coverages_seen.add(new_coverage)\n",
    "\n",
    "        return result"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "run_control": {},
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Let us now put this to use:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 52,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:25.911859Z",
     "iopub.status.busy": "2024-01-18T17:14:25.911749Z",
     "iopub.status.idle": "2024-01-18T17:14:26.628028Z",
     "shell.execute_reply": "2024-01-18T17:14:26.627727Z"
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['http://www.google.com/search?q=fuzzing',\n",
       " 'http://www.goog.com/search;q=fuzzilng',\n",
       " 'http://ww.6goog\\x0eoomosearch;/q=f}zzilng',\n",
       " 'http://uv.Lboo.comoseakrch;q=fuzilng',\n",
       " 'http://ww.6goog\\x0eo/mosarch;/q=f}z{il~g',\n",
       " 'http://www.googme.com/sear#h?q=fuzzing',\n",
       " 'http://www.oogcom/sa3rchq=fuzlnv|',\n",
       " 'http://ww.6goog*./mosarch;/q=f}Zz{ilel~g',\n",
       " 'http://uv.Lboo.comoseakch;q=fuzilng',\n",
       " 'http://www.goom^e.2com/s?ear#h?q=fuzzing',\n",
       " 'http://hwww.coole.com+search?R=fuzzig',\n",
       " 'http://ww.6g7oog*./mosarch; #/q;f}Zz{ilel~gL',\n",
       " \"http://ww.6'oog*R./mosarcx;/q=}Zz{ilel;~g\",\n",
       " 'http://www.goofme.com/sear#h?q=fuzzi*yng',\n",
       " \"http://sw.6'oog*R/msa'rcx;/qw?}Zz{ileRl;~g\",\n",
       " \"http://sw.6'oog*R/msa'rsx;/qw?}Zz{ileRUl;~g\",\n",
       " \"http://sw.6'oog*R/msa'rsx;qw?}Zz{ileRU;~g\",\n",
       " 'http://wgw.gooBm^e.2com/s?&eir#h?q=]fuzzing',\n",
       " \"http://sw.6'ooM*R/mDa'rsx;w?}Zz{ileU+~g\",\n",
       " \"http://sw.6L'ooM*R/mKD'rwx;w?}Z~{ileU#zg\",\n",
       " 'http://ww6g7ooVg:./mosarc; #/q;f}ZzF{ielW~gL',\n",
       " \"http://Jsw.6L'oM*R/mKD'r3w;w?~{ileU#zg\",\n",
       " \"http://sw.6'oog*R/msa'rsx;/qw?}Z#z{ileRYUl;~g\",\n",
       " \"http://sw6'oog*V/msa'rsx;/w\\x7f}Z#zileRUl;~g\",\n",
       " \"http://sw6'oog*/msa'rsx;/g\\x7fp}Z#zileRUl;~g\"]"
      ]
     },
     "execution_count": 52,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "seed_input = \"http://www.google.com/search?q=fuzzing\"\n",
    "mutation_fuzzer = MutationCoverageFuzzer(seed=[seed_input])\n",
    "mutation_fuzzer.runs(http_runner, trials=10000)\n",
    "mutation_fuzzer.population"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Success!  In our population, _each and every input_ now is valid and has a different coverage, coming from various combinations of schemes, paths, queries, and fragments."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 53,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:26.629695Z",
     "iopub.status.busy": "2024-01-18T17:14:26.629584Z",
     "iopub.status.idle": "2024-01-18T17:14:26.632755Z",
     "shell.execute_reply": "2024-01-18T17:14:26.632449Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [],
   "source": [
    "all_coverage, cumulative_coverage = population_coverage(\n",
    "    mutation_fuzzer.population, http_program)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 54,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:26.634189Z",
     "iopub.status.busy": "2024-01-18T17:14:26.634104Z",
     "iopub.status.idle": "2024-01-18T17:14:26.635771Z",
     "shell.execute_reply": "2024-01-18T17:14:26.635517Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt  # type: ignore"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 55,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:26.637184Z",
     "iopub.status.busy": "2024-01-18T17:14:26.637104Z",
     "iopub.status.idle": "2024-01-18T17:14:26.746285Z",
     "shell.execute_reply": "2024-01-18T17:14:26.745920Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "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qBH69esHKysrfP/99xg7dixUKhXGjRundbzExEQMHToUY8aMwahRo9CgQQOcPXsWffr0QZMmTTBv3jwoFApcunQJ8fHxmvvpcu4PHTqE5557rtzn4+LigqCgIMTHx2PSpEmPfd7h4eFYtmwZzp49i8aNGwMADhw4AAsLCxw4cADR0dGabQDQsWPHco8zZswYpKamYvfu3fj000/L3eeLL75ATk4OxowZA0mSsHjxYrz44ou4fPlyhVohxo4dC09PT8yaNQv37t0DUNq1eejQIQwZMgS1atXClStXsHr1anTu3Bnnzp0r07I5YcIE1KhRA7Nnz8aVK1cQGxuL8ePH46uvvtLsM2vWLMyfPx+9evVCr169cPLkSXTr1g2FhYVax7px4wbatWuHvLw8REdHw93dHRs3bkS/fv2wZcsWDBgwQGv/mJgY2NnZYfr06bh06RJWrlwJa2trWFhY4O7du5gzZw6OHDmCDRs2IDAwELNmzXrqOanKeS4pKUGPHj3Qpk0bLF68GHFxcZg9ezaKi4sxb948nR7zSa//7t27MXToUHTt2hWLFi0CAJw/fx7x8fFa/ziSHgmq1rKysgQA0b9//wrtn5CQIACIkSNHam2fMmWKACB++eUXzXEVCoV46623tPZbvHixkCRJXL16VQghxJUrV4SlpaX497//rbXfH3/8IaysrLS2d+rUSQAQa9asKVNXXl5emW1jxowR9vb2Ij8/XwghREFBgXB3dxetWrUSRUVFmv02bNggAIhOnTpptn366afCwsJCHDhwQOuYa9asEQBEfHz8Y89RYWGh8PLyEo0bNxb379/XbP/hhx8EADFr1izNtvXr1wsA4rfffnvs8dSioqKEv79/me2zZ88Wj/4qAxAWFhbi7NmzZfYHIGbPnl3m/v369dPab+zYsQKAOH36tGZbeee5e/fuok6dOlrb/P39BQARFxentX3ZsmUCgLh169Zjn2dFz31RUZGQJKnMe+xh3bp1EyEhIY+9XQghbt68KQCIjz76SAghRGZmprCwsBCDBg0S3t7emv2io6OFm5ubUKlUQgghUlJSBACxfv16zT7jxo0r81o8vK+7u7u4c+eOZvt3330nAIjvv//+iTWq3ycdOnQQxcXFWreV95ocPnxYABCffPJJmWNERERonoMQQkyaNElYWlqKzMxMzfmwsbERvXv31tpv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QJIkqFQqLF68GM8//7xeizNnHFBMRERkGDp3Sy1evBhdu3bF8ePHUVhYiLfffhtnz57FnTt3EB8fb4gazU5hsQq3czmBHxERkSHo3HLTuHFjXLx4ER06dED//v1x7949vPjiizh16hSCgoIMUaPZuZGdDyEAG0sLuNnbyF0OERGRWdG55QYAXFxc8M477+i7lmpDvWCmjwsn8CMiItK3SoWbzMxMHDt2DDdv3oRKpdK6bfjw4XopzJxxMDEREZHh6Bxuvv/+ewwbNgy5ublwdnaGJD1oeZAkieGmAtI0g4kZboiIiPRN5zE3b731Fl577TXk5uYiMzMTd+/e1XzduXPHEDWaHfUcN76uvFKKiIhI33QON3/99Reio6PLneuGKib170UzfdlyQ0REpHc6h5vu3bvj+PHjhqil2lB3S/lyjhsiIiK903nMTe/evTF16lScO3cOoaGhsLa21rq9X79+eivOXD0IN2y5ISIi0jedw82oUaMAAPPmzStzmyRJKCkpqXpVZqyguOTBBH4MN0RERHqnc7h59NJv0s2NrNJgY2NlATcHTuBHRESkbzqPuaGqUc9x4+tiq3UZPREREelHhVpuVqxYgdGjR8PW1hYrVqx44r7R0dF6KcxccbwNERGRYVUo3CxbtgzDhg2Dra0tli1b9tj9JEliuHmKNK4GTkREZFAVCjcpKSnlfk+649ILREREhsUxN0aWmsnZiYmIiAypQi03kydPrvABly5dWuliqoP07NKWG64rRUREZBgVCjenTp2q0MF49c/Tpf3dcsNuKSIiIsOoULjZu3evoeuoFvKLSpBxrxAABxQTEREZCsfcGNGN7NJWG4WVBVztrZ+yNxEREVUGw40RqQcTK13t2IVHRERkIAw3RqQeTMwJ/IiIiAyH4caIUjmYmIiIyOAYboxIPYEfBxMTEREZDsONEaWr15VyZcsNERGRoTDcGJFmdmJ2SxERERkMw40RqbulfNktRUREZDAMN0aSX1SCu3lFADjmhoiIyJAYbowk7e/xNnbWlnC2q9DE0ERERFQJDDdGoumScrXlBH5EREQGxHBjJGkcTExERGQUDDdGwsHERERExsFwYyTqMTdKttwQEREZFMONkajDjQ9bboiIiAyK4cZIUjMfDCgmIiIiw5E13MyZMweSJGl9BQcHa+1z+PBhdOnSBQ4ODnB2dkbH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9uzB7t27MXbsWHzwwQfYv39/mZqIyHjYckNEFbJjxw4kJCTAx8cHn332GRISEtC4cWPExsYiISEBO3bseOx9nZ2doVQqER8fr7U9Pj4eDRs2NHTpAIAjR45ovi8uLsaJEycQEhICAPD09EROTg7u3bun2efRS75tbGxQUlJS5rh2dnbo27cvVqxYgX379uHw4cP4448/DPMkiKhC2HJDRBXi7++P9PR03LhxA/3794ckSTh79iwGDhwIX1/fp95/6tSpmD17NoKCgtCsWTOsX78eCQkJ+Pzzz41QPbBq1SrUq1cPISEhWLZsGe7evYvXXnsNABAWFgZ7e3vMnDkT0dHROHr0KDZs2KB1/4CAAKSkpCAhIQG1atWCk5MTvvzyS5SUlGju/9lnn8HOzu6Jl7ITkeGx5YaIKmzfvn1o1aoVbG1tcezYMdSqVatCwQYAoqOjMXnyZLz11lsIDQ1FXFwctm/fjnr16hm46lILFy7EwoUL0bRpUxw8eBDbt2/XjBFyc3PDZ599hh07diA0NBRffvllmUvRBw4ciB49euD555+Hp6cnvvzyS7i6umLdunVo3749mjRpgj179uD777+v0BVYRGQ4nKGYiMzalStXEBgYiFOnTj12SQciMi9suSEiIiKzwnBDREREZoXdUkRERGRW2HJDREREZoXhhoiIiMwKww0RERGZFYYbIiIiMisMN0RERGRWGG6IiIjIrDDcEBERkVlhuCEiIiKzwnBDREREZuX/Aem7iNwlxpCvAAAAAElFTkSuQmCC\n",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "plt.plot(cumulative_coverage)\n",
    "plt.title('Coverage of urlparse() with random inputs')\n",
    "plt.xlabel('# of inputs')\n",
    "plt.ylabel('lines covered');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "The nice thing about this strategy is that, applied to larger programs, it will happily explore one path after the other – covering functionality after functionality.  All that is needed is a means to capture the coverage."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Synopsis\n",
    "\n",
    "This chapter introduces a `MutationFuzzer` class that takes a list of _seed inputs_ which are then mutated:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 56,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:26.748082Z",
     "iopub.status.busy": "2024-01-18T17:14:26.747955Z",
     "iopub.status.idle": "2024-01-18T17:14:26.750813Z",
     "shell.execute_reply": "2024-01-18T17:14:26.750510Z"
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['http://www.google.com/search?q=fuzzing',\n",
       " 'http://wwBw.google.com/searh?q=fuzzing',\n",
       " 'http8//wswgoRogle.am/secch?qU=fuzzing',\n",
       " 'ittp://www.googLe.com/serch?q=fuzzingZ',\n",
       " 'httP://wgw.google.com/seasch?Q=fuxzanmgY',\n",
       " 'http://www.google.cxcom/search?q=fuzzing',\n",
       " 'hFttp://ww.-g\\x7fog+le.com/s%arch?q=f-uzz#ing',\n",
       " 'http://www\\x0egoogle.com/seaNrch?q=fuZzing',\n",
       " 'http//www.Ygooge.comsarch?q=fuz~Ijg',\n",
       " 'http8//ww.goog5le.com/sezarc?q=fuzzing']"
      ]
     },
     "execution_count": 56,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "seed_input = \"http://www.google.com/search?q=fuzzing\"\n",
    "mutation_fuzzer = MutationFuzzer(seed=[seed_input])\n",
    "[mutation_fuzzer.fuzz() for i in range(10)]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "The `MutationCoverageFuzzer` maintains a _population_ of inputs, which are then evolved in order to maximize coverage."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 57,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:26.752355Z",
     "iopub.status.busy": "2024-01-18T17:14:26.752256Z",
     "iopub.status.idle": "2024-01-18T17:14:27.465316Z",
     "shell.execute_reply": "2024-01-18T17:14:27.465029Z"
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['http://www.google.com/search?q=fuzzing',\n",
       " 'http://wwv.oogle>co/search7Eq=fuzing',\n",
       " 'http://wwv\\x0eOogleb>co/seakh7Eq\\x1d;fuzing',\n",
       " 'http://wwv\\x0eoglebkooqeakh7Eq\\x1d;fuzing',\n",
       " 'http://wwv\\x0eoglekol=oekh7Eq\\x1d\\x1bf~ing']"
      ]
     },
     "execution_count": 57,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mutation_fuzzer = MutationCoverageFuzzer(seed=[seed_input])\n",
    "mutation_fuzzer.runs(http_runner, trials=10000)\n",
    "mutation_fuzzer.population[:5]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 58,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:27.466943Z",
     "iopub.status.busy": "2024-01-18T17:14:27.466819Z",
     "iopub.status.idle": "2024-01-18T17:14:27.468395Z",
     "shell.execute_reply": "2024-01-18T17:14:27.468152Z"
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "# ignore\n",
    "from ClassDiagram import display_class_hierarchy"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 59,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:27.469926Z",
     "iopub.status.busy": "2024-01-18T17:14:27.469827Z",
     "iopub.status.idle": "2024-01-18T17:14:27.920849Z",
     "shell.execute_reply": "2024-01-18T17:14:27.920493Z"
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "data": {
      "image/svg+xml": [
       "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?>\n",
       "<!DOCTYPE svg PUBLIC \"-//W3C//DTD SVG 1.1//EN\"\n",
       " \"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd\">\n",
       "<!-- Generated by graphviz version 9.0.0 (20230911.1827)\n",
       " -->\n",
       "<!-- Pages: 1 -->\n",
       "<svg width=\"318pt\" height=\"309pt\"\n",
       " viewBox=\"0.00 0.00 318.38 308.75\" xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\">\n",
       "<g id=\"graph0\" class=\"graph\" transform=\"scale(1 1) rotate(0) translate(4 304.75)\">\n",
       "<g id=\"a_graph0\"><a xlink:title=\"MutationCoverageFuzzer class hierarchy\">\n",
       "<polygon fill=\"white\" stroke=\"none\" points=\"-4,4 -4,-304.75 314.38,-304.75 314.38,4 -4,4\"/>\n",
       "</a>\n",
       "</g>\n",
       "<!-- MutationCoverageFuzzer -->\n",
       "<g id=\"node1\" class=\"node\">\n",
       "<title>MutationCoverageFuzzer</title>\n",
       "<g id=\"a_node1\"><a xlink:href=\"#\" xlink:title=\"class MutationCoverageFuzzer:&#10;Fuzz with mutated inputs based on coverage\">\n",
       "<polygon fill=\"none\" stroke=\"black\" points=\"0,-0.5 0,-57 173.5,-57 173.5,-0.5 0,-0.5\"/>\n",
       "<text text-anchor=\"start\" x=\"8\" y=\"-40.7\" font-family=\"Patua One, Helvetica, sans-serif\" font-weight=\"bold\" font-size=\"14.00\" fill=\"#b03a2e\">MutationCoverageFuzzer</text>\n",
       "<polyline fill=\"none\" stroke=\"black\" points=\"0,-31 173.5,-31\"/>\n",
       "<g id=\"a_node1_0\"><a xlink:href=\"#\" xlink:title=\"MutationCoverageFuzzer\">\n",
       "<g id=\"a_node1_1\"><a xlink:href=\"#\" xlink:title=\"run(self, runner: FunctionCoverageRunner) &#45;&gt; Any:&#10;Run function(inp) while tracking coverage.&#10;If we reach new coverage,&#10;add inp to population and its coverage to population_coverage\">\n",
       "<text text-anchor=\"start\" x=\"65.75\" y=\"-18.5\" font-family=\"'Fira Mono', 'Source Code Pro', 'Courier', monospace\" font-weight=\"bold\" font-style=\"italic\" font-size=\"10.00\">run()</text>\n",
       "</a>\n",
       "</g>\n",
       "<g id=\"a_node1_2\"><a xlink:href=\"#\" xlink:title=\"reset(self) &#45;&gt; None:&#10;Set population to initial seed.&#10;To be overloaded in subclasses.\">\n",
       "<text text-anchor=\"start\" x=\"65.75\" y=\"-7.25\" font-family=\"'Fira Mono', 'Source Code Pro', 'Courier', monospace\" font-style=\"italic\" font-size=\"10.00\">reset()</text>\n",
       "</a>\n",
       "</g>\n",
       "</a>\n",
       "</g>\n",
       "</a>\n",
       "</g>\n",
       "</g>\n",
       "<!-- MutationFuzzer -->\n",
       "<g id=\"node2\" class=\"node\">\n",
       "<title>MutationFuzzer</title>\n",
       "<g id=\"a_node2\"><a xlink:href=\"#\" xlink:title=\"class MutationFuzzer:&#10;Base class for mutational fuzzing\">\n",
       "<polygon fill=\"none\" stroke=\"black\" points=\"24.75,-94 24.75,-184.25 148.75,-184.25 148.75,-94 24.75,-94\"/>\n",
       "<text text-anchor=\"start\" x=\"36.88\" y=\"-167.95\" font-family=\"Patua One, Helvetica, sans-serif\" font-weight=\"bold\" font-size=\"14.00\" fill=\"#b03a2e\">MutationFuzzer</text>\n",
       "<polyline fill=\"none\" stroke=\"black\" points=\"24.75,-158.25 148.75,-158.25\"/>\n",
       "<g id=\"a_node2_3\"><a xlink:href=\"#\" xlink:title=\"MutationFuzzer\">\n",
       "<g id=\"a_node2_4\"><a xlink:href=\"#\" xlink:title=\"__init__(self, seed: List[str], min_mutations: int = 2, max_mutations: int = 10) &#45;&gt; None:&#10;Constructor.&#10;`seed` &#45; a list of (input) strings to mutate.&#10;`min_mutations` &#45; the minimum number of mutations to apply.&#10;`max_mutations` &#45; the maximum number of mutations to apply.\">\n",
       "<text text-anchor=\"start\" x=\"32.75\" y=\"-145.75\" font-family=\"'Fira Mono', 'Source Code Pro', 'Courier', monospace\" font-weight=\"bold\" font-style=\"italic\" font-size=\"10.00\">__init__()</text>\n",
       "</a>\n",
       "</g>\n",
       "<g id=\"a_node2_5\"><a xlink:href=\"#\" xlink:title=\"fuzz(self) &#45;&gt; str:&#10;Return fuzz input\">\n",
       "<text text-anchor=\"start\" x=\"32.75\" y=\"-134.5\" font-family=\"'Fira Mono', 'Source Code Pro', 'Courier', monospace\" font-weight=\"bold\" font-style=\"italic\" font-size=\"10.00\">fuzz()</text>\n",
       "</a>\n",
       "</g>\n",
       "<g id=\"a_node2_6\"><a xlink:href=\"#\" xlink:title=\"create_candidate(self) &#45;&gt; str:&#10;Create a new candidate by mutating a population member\">\n",
       "<text text-anchor=\"start\" x=\"32.75\" y=\"-122.25\" font-family=\"'Fira Mono', 'Source Code Pro', 'Courier', monospace\" font-size=\"10.00\">create_candidate()</text>\n",
       "</a>\n",
       "</g>\n",
       "<g id=\"a_node2_7\"><a xlink:href=\"#\" xlink:title=\"mutate(self, inp: str) &#45;&gt; str\">\n",
       "<text text-anchor=\"start\" x=\"32.75\" y=\"-111\" font-family=\"'Fira Mono', 'Source Code Pro', 'Courier', monospace\" font-size=\"10.00\">mutate()</text>\n",
       "</a>\n",
       "</g>\n",
       "<g id=\"a_node2_8\"><a xlink:href=\"#\" xlink:title=\"reset(self) &#45;&gt; None:&#10;Set population to initial seed.&#10;To be overloaded in subclasses.\">\n",
       "<text text-anchor=\"start\" x=\"32.75\" y=\"-100.75\" font-family=\"'Fira Mono', 'Source Code Pro', 'Courier', monospace\" font-style=\"italic\" font-size=\"10.00\">reset()</text>\n",
       "</a>\n",
       "</g>\n",
       "</a>\n",
       "</g>\n",
       "</a>\n",
       "</g>\n",
       "</g>\n",
       "<!-- MutationCoverageFuzzer&#45;&gt;MutationFuzzer -->\n",
       "<g id=\"edge1\" class=\"edge\">\n",
       "<title>MutationCoverageFuzzer&#45;&gt;MutationFuzzer</title>\n",
       "<path fill=\"none\" stroke=\"black\" d=\"M86.75,-57.38C86.75,-65.05 86.75,-73.67 86.75,-82.34\"/>\n",
       "<polygon fill=\"none\" stroke=\"black\" points=\"83.25,-82.19 86.75,-92.19 90.25,-82.19 83.25,-82.19\"/>\n",
       "</g>\n",
       "<!-- Fuzzer -->\n",
       "<g id=\"node3\" class=\"node\">\n",
       "<title>Fuzzer</title>\n",
       "<g id=\"a_node3\"><a xlink:href=\"Fuzzer.ipynb\" xlink:title=\"class Fuzzer:&#10;Base class for fuzzers.\">\n",
       "<polygon fill=\"none\" stroke=\"black\" points=\"48.75,-221.25 48.75,-300.25 124.75,-300.25 124.75,-221.25 48.75,-221.25\"/>\n",
       "<text text-anchor=\"start\" x=\"66.12\" y=\"-283.95\" font-family=\"Patua One, Helvetica, sans-serif\" font-weight=\"bold\" font-size=\"14.00\" fill=\"#b03a2e\">Fuzzer</text>\n",
       "<polyline fill=\"none\" stroke=\"black\" points=\"48.75,-274.25 124.75,-274.25\"/>\n",
       "<g id=\"a_node3_9\"><a xlink:href=\"#\" xlink:title=\"Fuzzer\">\n",
       "<g id=\"a_node3_10\"><a xlink:href=\"Fuzzer.ipynb\" xlink:title=\"__init__(self) &#45;&gt; None:&#10;Constructor\">\n",
       "<text text-anchor=\"start\" x=\"56.75\" y=\"-261.75\" font-family=\"'Fira Mono', 'Source Code Pro', 'Courier', monospace\" font-weight=\"bold\" font-style=\"italic\" font-size=\"10.00\">__init__()</text>\n",
       "</a>\n",
       "</g>\n",
       "<g id=\"a_node3_11\"><a xlink:href=\"Fuzzer.ipynb\" xlink:title=\"fuzz(self) &#45;&gt; str:&#10;Return fuzz input\">\n",
       "<text text-anchor=\"start\" x=\"56.75\" y=\"-250.5\" font-family=\"'Fira Mono', 'Source Code Pro', 'Courier', monospace\" font-weight=\"bold\" font-style=\"italic\" font-size=\"10.00\">fuzz()</text>\n",
       "</a>\n",
       "</g>\n",
       "<g id=\"a_node3_12\"><a xlink:href=\"Fuzzer.ipynb\" xlink:title=\"run(self, runner: Fuzzer.Runner = &lt;Fuzzer.Runner object at 0x10451a1a0&gt;) &#45;&gt; Tuple[subprocess.CompletedProcess, str]:&#10;Run `runner` with fuzz input\">\n",
       "<text text-anchor=\"start\" x=\"56.75\" y=\"-239.25\" font-family=\"'Fira Mono', 'Source Code Pro', 'Courier', monospace\" font-weight=\"bold\" font-style=\"italic\" font-size=\"10.00\">run()</text>\n",
       "</a>\n",
       "</g>\n",
       "<g id=\"a_node3_13\"><a xlink:href=\"Fuzzer.ipynb\" xlink:title=\"runs(self, runner: Fuzzer.Runner = &lt;Fuzzer.PrintRunner object at 0x10451a1d0&gt;, trials: int = 10) &#45;&gt; List[Tuple[subprocess.CompletedProcess, str]]:&#10;Run `runner` with fuzz input, `trials` times\">\n",
       "<text text-anchor=\"start\" x=\"56.75\" y=\"-228\" font-family=\"'Fira Mono', 'Source Code Pro', 'Courier', monospace\" font-weight=\"bold\" font-size=\"10.00\">runs()</text>\n",
       "</a>\n",
       "</g>\n",
       "</a>\n",
       "</g>\n",
       "</a>\n",
       "</g>\n",
       "</g>\n",
       "<!-- MutationFuzzer&#45;&gt;Fuzzer -->\n",
       "<g id=\"edge2\" class=\"edge\">\n",
       "<title>MutationFuzzer&#45;&gt;Fuzzer</title>\n",
       "<path fill=\"none\" stroke=\"black\" d=\"M86.75,-184.67C86.75,-192.8 86.75,-201.33 86.75,-209.6\"/>\n",
       "<polygon fill=\"none\" stroke=\"black\" points=\"83.25,-209.55 86.75,-219.55 90.25,-209.55 83.25,-209.55\"/>\n",
       "</g>\n",
       "<!-- Legend -->\n",
       "<g id=\"node4\" class=\"node\">\n",
       "<title>Legend</title>\n",
       "<text text-anchor=\"start\" x=\"191.12\" y=\"-44.75\" font-family=\"Patua One, Helvetica, sans-serif\" font-weight=\"bold\" font-size=\"10.00\" fill=\"#b03a2e\">Legend</text>\n",
       "<text text-anchor=\"start\" x=\"191.12\" y=\"-34.75\" font-family=\"Patua One, Helvetica, sans-serif\" font-size=\"10.00\">• </text>\n",
       "<text text-anchor=\"start\" x=\"197.12\" y=\"-34.75\" font-family=\"'Fira Mono', 'Source Code Pro', 'Courier', monospace\" font-weight=\"bold\" font-size=\"8.00\">public_method()</text>\n",
       "<text text-anchor=\"start\" x=\"191.12\" y=\"-24.75\" font-family=\"Patua One, Helvetica, sans-serif\" font-size=\"10.00\">• </text>\n",
       "<text text-anchor=\"start\" x=\"197.12\" y=\"-24.75\" font-family=\"'Fira Mono', 'Source Code Pro', 'Courier', monospace\" font-size=\"8.00\">private_method()</text>\n",
       "<text text-anchor=\"start\" x=\"191.12\" y=\"-14.75\" font-family=\"Patua One, Helvetica, sans-serif\" font-size=\"10.00\">• </text>\n",
       "<text text-anchor=\"start\" x=\"197.12\" y=\"-14.75\" font-family=\"'Fira Mono', 'Source Code Pro', 'Courier', monospace\" font-style=\"italic\" font-size=\"8.00\">overloaded_method()</text>\n",
       "<text text-anchor=\"start\" x=\"191.12\" y=\"-5.7\" font-family=\"Helvetica,sans-Serif\" font-size=\"9.00\">Hover over names to see doc</text>\n",
       "</g>\n",
       "</g>\n",
       "</svg>\n"
      ],
      "text/plain": [
       "<graphviz.graphs.Digraph at 0x104475150>"
      ]
     },
     "execution_count": 59,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# ignore\n",
    "display_class_hierarchy(MutationCoverageFuzzer,\n",
    "                        public_methods=[\n",
    "                            Fuzzer.run,\n",
    "                            Fuzzer.__init__,\n",
    "                            Fuzzer.runs,\n",
    "                            Fuzzer.fuzz,\n",
    "                            MutationFuzzer.__init__,\n",
    "                            MutationFuzzer.fuzz,\n",
    "                            MutationCoverageFuzzer.run,\n",
    "                        ],\n",
    "                        types={'Location': Location},\n",
    "                        project='fuzzingbook')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Lessons Learned\n",
    "\n",
    "* Randomly generated inputs are frequently invalid – and thus exercise mostly input processing functionality.\n",
    "* Mutations from existing valid inputs have much higher chances to be valid, and thus to exercise functionality beyond input processing.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Next Steps\n",
    "\n",
    "In the next chapter on [greybox fuzzing](GreyboxFuzzer.ipynb), we further extend the concept of mutation-based testing with _power schedules_ that allow spending more energy on seeds that exercise \"unlikely\" paths and seeds that are \"closer\" to a target location."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Exercises\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### Exercise 1: Fuzzing CGI decode with Mutations\n",
    "\n",
    "Apply the above _guided_ mutation-based fuzzing technique on `cgi_decode()` from the [\"Coverage\"](Coverage.ipynb) chapter.  How many trials do you need until you cover all variations of `+`, `%` (valid and invalid), and regular characters?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 60,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:27.922814Z",
     "iopub.status.busy": "2024-01-18T17:14:27.922701Z",
     "iopub.status.idle": "2024-01-18T17:14:27.924667Z",
     "shell.execute_reply": "2024-01-18T17:14:27.924360Z"
    },
    "run_control": {},
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "from Coverage import cgi_decode"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 61,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:27.926143Z",
     "iopub.status.busy": "2024-01-18T17:14:27.926037Z",
     "iopub.status.idle": "2024-01-18T17:14:28.775067Z",
     "shell.execute_reply": "2024-01-18T17:14:28.774756Z"
    },
    "run_control": {},
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "seed = [\"Hello World\"]\n",
    "cgi_runner = FunctionCoverageRunner(cgi_decode)\n",
    "m = MutationCoverageFuzzer(seed)\n",
    "results = m.runs(cgi_runner, 10000)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 62,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:28.776810Z",
     "iopub.status.busy": "2024-01-18T17:14:28.776722Z",
     "iopub.status.idle": "2024-01-18T17:14:28.779577Z",
     "shell.execute_reply": "2024-01-18T17:14:28.779241Z"
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['Hello World', 'he_<+llo(or<D', 'L}eml &Wol%dD', 'L)q<}aml &cWol%d3D+']"
      ]
     },
     "execution_count": 62,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m.population"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 63,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:28.781138Z",
     "iopub.status.busy": "2024-01-18T17:14:28.781023Z",
     "iopub.status.idle": "2024-01-18T17:14:28.783301Z",
     "shell.execute_reply": "2024-01-18T17:14:28.783030Z"
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{('cgi_decode', 16),\n",
       " ('cgi_decode', 17),\n",
       " ('cgi_decode', 18),\n",
       " ('cgi_decode', 19),\n",
       " ('cgi_decode', 20),\n",
       " ('cgi_decode', 23),\n",
       " ('cgi_decode', 24),\n",
       " ('cgi_decode', 25),\n",
       " ('cgi_decode', 26),\n",
       " ('cgi_decode', 27),\n",
       " ('cgi_decode', 29),\n",
       " ('cgi_decode', 30),\n",
       " ('cgi_decode', 31),\n",
       " ('cgi_decode', 32),\n",
       " ('cgi_decode', 33),\n",
       " ('cgi_decode', 34),\n",
       " ('cgi_decode', 38),\n",
       " ('cgi_decode', 39),\n",
       " ('cgi_decode', 40),\n",
       " ('run_function', 7)}"
      ]
     },
     "execution_count": 63,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "cgi_runner.coverage()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 64,
   "metadata": {
    "button": false,
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:28.784772Z",
     "iopub.status.busy": "2024-01-18T17:14:28.784669Z",
     "iopub.status.idle": "2024-01-18T17:14:28.953499Z",
     "shell.execute_reply": "2024-01-18T17:14:28.952513Z"
    },
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "all_coverage, cumulative_coverage = population_coverage(\n",
    "    m.population, cgi_decode)\n",
    "\n",
    "import matplotlib.pyplot as plt\n",
    "plt.plot(cumulative_coverage)\n",
    "plt.title('Coverage of cgi_decode() with random inputs')\n",
    "plt.xlabel('# of inputs')\n",
    "plt.ylabel('lines covered');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "After 10,000 runs, we have managed to synthesize a `+` character and a valid `%xx` form.  We can still do better."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    },
    "solution2": "hidden",
    "solution2_first": true
   },
   "source": [
    "### Exercise 2: Fuzzing bc with Mutations\n",
    "\n",
    "Apply the above mutation-based fuzzing technique on `bc`, as in the chapter [\"Introduction to Fuzzing\"](Fuzzer.ipynb).\n",
    "\n",
    "#### Part 1: Non-Guided Mutations\n",
    "\n",
    "Start with non-guided mutations.  How many of the inputs are valid?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    },
    "solution2": "hidden"
   },
   "source": [
    "**Solution.** This is just a matter of tying a `ProgramRunner` to a `MutationFuzzer`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 65,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:28.958460Z",
     "iopub.status.busy": "2024-01-18T17:14:28.958315Z",
     "iopub.status.idle": "2024-01-18T17:14:28.962798Z",
     "shell.execute_reply": "2024-01-18T17:14:28.960917Z"
    },
    "slideshow": {
     "slide_type": "skip"
    },
    "solution2": "hidden"
   },
   "outputs": [],
   "source": [
    "from Fuzzer import ProgramRunner"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 66,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:28.967373Z",
     "iopub.status.busy": "2024-01-18T17:14:28.967244Z",
     "iopub.status.idle": "2024-01-18T17:14:29.366158Z",
     "shell.execute_reply": "2024-01-18T17:14:29.365739Z"
    },
    "slideshow": {
     "slide_type": "skip"
    },
    "solution2": "hidden"
   },
   "outputs": [],
   "source": [
    "seed = [\"1 + 1\"]\n",
    "bc = ProgramRunner(program=\"bc\")\n",
    "m = MutationFuzzer(seed)\n",
    "outcomes = m.runs(bc, trials=100)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 67,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:29.368129Z",
     "iopub.status.busy": "2024-01-18T17:14:29.367997Z",
     "iopub.status.idle": "2024-01-18T17:14:29.370572Z",
     "shell.execute_reply": "2024-01-18T17:14:29.370290Z"
    },
    "slideshow": {
     "slide_type": "skip"
    },
    "solution2": "hidden"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[(CompletedProcess(args='bc', returncode=0, stdout='2\\n', stderr=''), 'PASS'),\n",
       " (CompletedProcess(args='bc', returncode=0, stdout='5\\n', stderr=''), 'PASS'),\n",
       " (CompletedProcess(args='bc', returncode=0, stdout='1000\\n', stderr=''),\n",
       "  'PASS')]"
      ]
     },
     "execution_count": 67,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "outcomes[:3]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 68,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:29.372262Z",
     "iopub.status.busy": "2024-01-18T17:14:29.372135Z",
     "iopub.status.idle": "2024-01-18T17:14:29.374399Z",
     "shell.execute_reply": "2024-01-18T17:14:29.374140Z"
    },
    "slideshow": {
     "slide_type": "skip"
    },
    "solution2": "hidden"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "20"
      ]
     },
     "execution_count": 68,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sum(1 for completed_process, outcome in outcomes if completed_process.stderr == \"\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "#### Part 2: Guided Mutations\n",
    "\n",
    "Continue with _guided_ mutations.  To this end, you will have to find a way to extract coverage from a C program such as `bc`.  Proceed in these steps:\n",
    "\n",
    "First, get [GNU bc](https://www.gnu.org/software/bc/); download, say, `bc-1.07.1.tar.gz` and unpack it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 69,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:29.376031Z",
     "iopub.status.busy": "2024-01-18T17:14:29.375926Z",
     "iopub.status.idle": "2024-01-18T17:14:30.691587Z",
     "shell.execute_reply": "2024-01-18T17:14:30.689809Z"
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\r\n",
      "                                 Dload  Upload   Total   Spent    Left  Speed\r\n",
      "100  410k  100  410k    0     0   347k      0  0:00:01  0:00:01 --:--:--  348k\r\n"
     ]
    }
   ],
   "source": [
    "!curl -O mirrors.kernel.org/gnu/bc/bc-1.07.1.tar.gz"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 70,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:30.700558Z",
     "iopub.status.busy": "2024-01-18T17:14:30.700023Z",
     "iopub.status.idle": "2024-01-18T17:14:30.866414Z",
     "shell.execute_reply": "2024-01-18T17:14:30.865180Z"
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "!tar xfz bc-1.07.1.tar.gz"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Second, configure the package:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 71,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:30.872311Z",
     "iopub.status.busy": "2024-01-18T17:14:30.871884Z",
     "iopub.status.idle": "2024-01-18T17:14:35.218008Z",
     "shell.execute_reply": "2024-01-18T17:14:35.217472Z"
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "checking for a BSD-compatible install... /opt/homebrew/bin/ginstall -c\r\n",
      "checking whether build environment is sane... yes\r\n",
      "checking for a thread-safe mkdir -p... /opt/homebrew/bin/gmkdir -p\r\n",
      "checking for gawk... no\r\n",
      "checking for mawk... no\r\n",
      "checking for nawk... no\r\n",
      "checking for awk... awk\r\n",
      "checking whether make sets $(MAKE)... yes\r\n",
      "checking whether make supports nested variables... yes\r\n",
      "checking for gcc... gcc\r\n",
      "checking whether the C compiler works... yes\r\n",
      "checking for C compiler default output file name... a.out\r\n",
      "checking for suffix of executables... \r\n",
      "checking whether we are cross compiling... no\r\n",
      "checking for suffix of object files... o\r\n",
      "checking whether we are using the GNU C compiler... yes\r\n",
      "checking whether gcc accepts -g... yes\r\n",
      "checking for gcc option to accept ISO C89... none needed\r\n",
      "checking whether gcc understands -c and -o together... yes\r\n",
      "checking for style of include used by make... GNU\r\n",
      "checking dependency style of gcc... gcc3\r\n",
      "checking how to run the C preprocessor... gcc -E\r\n",
      "checking for grep that handles long lines and -e... /usr/bin/grep\r\n",
      "checking for egrep... /usr/bin/grep -E\r\n",
      "checking for ANSI C header files... yes\r\n",
      "checking for sys/types.h... yes\r\n",
      "checking for sys/stat.h... yes\r\n",
      "checking for stdlib.h... yes\r\n",
      "checking for string.h... yes\r\n",
      "checking for memory.h... yes\r\n",
      "checking for strings.h... yes\r\n",
      "checking for inttypes.h... yes\r\n",
      "checking for stdint.h... yes\r\n",
      "checking for unistd.h... yes\r\n",
      "checking minix/config.h usability... no\r\n",
      "checking minix/config.h presence... no\r\n",
      "checking for minix/config.h... no\r\n",
      "checking whether it is safe to define __EXTENSIONS__... yes\r\n",
      "checking for flex... flex\r\n",
      "checking lex output file root... lex.yy\r\n",
      "checking lex library... -ll\r\n",
      "checking whether yytext is a pointer... yes\r\n",
      "checking for ar... ar\r\n",
      "checking the archiver (ar) interface... ar\r\n",
      "checking for bison... bison -y\r\n",
      "checking for ranlib... ranlib\r\n",
      "checking whether make sets $(MAKE)... (cached) yes\r\n",
      "checking for stdarg.h... yes\r\n",
      "checking for stddef.h... yes\r\n",
      "checking for stdlib.h... (cached) yes\r\n",
      "checking for string.h... (cached) yes\r\n",
      "checking for errno.h... yes\r\n",
      "checking for limits.h... yes\r\n",
      "checking for unistd.h... (cached) yes\r\n",
      "checking for lib.h... no\r\n",
      "checking for an ANSI C-conforming const... yes\r\n",
      "checking for size_t... yes\r\n",
      "checking for ptrdiff_t... yes\r\n",
      "checking for vprintf... yes\r\n",
      "checking for _doprnt... no\r\n",
      "checking for isgraph... yes\r\n",
      "checking for setvbuf... yes\r\n",
      "checking for fstat... yes\r\n",
      "checking for strtol... yes\r\n",
      "Adding GCC specific compile flags.\r\n",
      "checking that generated files are newer than configure... done\r\n",
      "configure: creating ./config.status\r\n",
      "config.status: creating Makefile\r\n",
      "config.status: creating bc/Makefile\r\n",
      "config.status: creating dc/Makefile\r\n",
      "config.status: creating lib/Makefile\r\n",
      "config.status: creating doc/Makefile\r\n",
      "config.status: creating doc/texi-ver.incl\r\n",
      "config.status: creating config.h\r\n",
      "config.status: executing depfiles commands\r\n"
     ]
    }
   ],
   "source": [
    "!cd bc-1.07.1; ./configure"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Third, compile the package with special flags:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 72,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:35.220818Z",
     "iopub.status.busy": "2024-01-18T17:14:35.220601Z",
     "iopub.status.idle": "2024-01-18T17:14:37.508290Z",
     "shell.execute_reply": "2024-01-18T17:14:37.507873Z"
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "/Applications/Xcode.app/Contents/Developer/usr/bin/make  all-recursive\r\n",
      "Making all in lib\r\n",
      "gcc -DHAVE_CONFIG_H  -I. -I..  -I. -I.. -I./../h  -g -O2 -Wall -funsigned-char --coverage -MT getopt.o -MD -MP -MF .deps/getopt.Tpo -c -o getopt.o getopt.c\r\n",
      "\u001b[1mgetopt.c:348:28: \u001b[0m\u001b[0;1;35mwarning: \u001b[0m\u001b[1mpassing arguments to 'getenv'\r\n",
      "      without a prototype is deprecated in all versions of C and is not\r\n",
      "      supported in C2x [-Wdeprecated-non-prototype]\u001b[0m\r\n",
      "  posixly_correct = getenv (\"POSIXLY_CORRECT\");\r\n",
      "\u001b[0;1;32m                           ^\r\n",
      "\u001b[0mIn file included from getopt.c:106:\r\n",
      "\u001b[1m./../h/getopt.h:144:12: \u001b[0m\u001b[0;1;35mwarning: \u001b[0m\u001b[1ma function declaration\r\n",
      "      without a prototype is deprecated in all versions of C and is treated as a\r\n",
      "      zero-parameter prototype in C2x, conflicting with a subsequent definition\r\n",
      "      [-Wdeprecated-non-prototype]\u001b[0m\r\n",
      "extern int getopt ();\r\n",
      "\u001b[0;1;32m           ^\r\n",
      "\u001b[0m\u001b[1mgetopt.c:1135:1: \u001b[0m\u001b[0;1;30mnote: \u001b[0mconflicting prototype is here\u001b[0m\r\n",
      "getopt (int argc, char *const *argv, const char *optstring)\r\n",
      "\u001b[0;1;32m^\r\n",
      "\u001b[0m2 warnings generated.\r\n",
      "mv -f .deps/getopt.Tpo .deps/getopt.Po\r\n",
      "gcc -DHAVE_CONFIG_H  -I. -I..  -I. -I.. -I./../h  -g -O2 -Wall -funsigned-char --coverage -MT getopt1.o -MD -MP -MF .deps/getopt1.Tpo -c -o getopt1.o getopt1.c\r\n",
      "mv -f .deps/getopt1.Tpo .deps/getopt1.Po\r\n",
      "gcc -DHAVE_CONFIG_H  -I. -I..  -I. -I.. -I./../h  -g -O2 -Wall -funsigned-char --coverage -MT vfprintf.o -MD -MP -MF .deps/vfprintf.Tpo -c -o vfprintf.o vfprintf.c\r\n",
      "mv -f .deps/vfprintf.Tpo .deps/vfprintf.Po\r\n",
      "gcc -DHAVE_CONFIG_H  -I. -I..  -I. -I.. -I./../h  -g -O2 -Wall -funsigned-char --coverage -MT number.o -MD -MP -MF .deps/number.Tpo -c -o number.o number.c\r\n",
      "mv -f .deps/number.Tpo .deps/number.Po\r\n",
      "rm -f libbc.a\r\n",
      "ar cru libbc.a getopt.o getopt1.o vfprintf.o number.o \r\n",
      "ranlib libbc.a\r\n",
      "Making all in bc\r\n",
      "gcc -DHAVE_CONFIG_H -I. -I..  -I. -I./../h  -g -O2 -Wall -funsigned-char --coverage -MT main.o -MD -MP -MF .deps/main.Tpo -c -o main.o main.c\r\n",
      "In file included from main.c:34:\r\n",
      "\u001b[1m./../h/getopt.h:144:12: \u001b[0m\u001b[0;1;35mwarning: \u001b[0m\u001b[1ma function declaration\r\n",
      "      without a prototype is deprecated in all versions of C and is treated as a\r\n",
      "      zero-parameter prototype in C2x, conflicting with a previous declaration\r\n",
      "      [-Wdeprecated-non-prototype]\u001b[0m\r\n",
      "extern int getopt ();\r\n",
      "\u001b[0;1;32m           ^\r\n",
      "\u001b[0m\u001b[1m/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/unistd.h:509:6: \u001b[0m\u001b[0;1;30mnote: \u001b[0m\r\n",
      "      conflicting prototype is here\u001b[0m\r\n",
      "int      getopt(int, char * const [], const char *) __DARWIN_ALIAS(getopt);\r\n",
      "\u001b[0;1;32m         ^\r\n",
      "\u001b[0m1 warning generated.\r\n",
      "mv -f .deps/main.Tpo .deps/main.Po\r\n",
      "gcc -DHAVE_CONFIG_H -I. -I..  -I. -I./../h  -g -O2 -Wall -funsigned-char --coverage -MT bc.o -MD -MP -MF .deps/bc.Tpo -c -o bc.o bc.c\r\n",
      "mv -f .deps/bc.Tpo .deps/bc.Po\r\n",
      "gcc -DHAVE_CONFIG_H -I. -I..  -I. -I./../h  -g -O2 -Wall -funsigned-char --coverage -MT scan.o -MD -MP -MF .deps/scan.Tpo -c -o scan.o scan.c\r\n",
      "mv -f .deps/scan.Tpo .deps/scan.Po\r\n",
      "gcc -DHAVE_CONFIG_H -I. -I..  -I. -I./../h  -g -O2 -Wall -funsigned-char --coverage -MT execute.o -MD -MP -MF .deps/execute.Tpo -c -o execute.o execute.c\r\n",
      "mv -f .deps/execute.Tpo .deps/execute.Po\r\n",
      "gcc -DHAVE_CONFIG_H -I. -I..  -I. -I./../h  -g -O2 -Wall -funsigned-char --coverage -MT load.o -MD -MP -MF .deps/load.Tpo -c -o load.o load.c\r\n",
      "mv -f .deps/load.Tpo .deps/load.Po\r\n",
      "gcc -DHAVE_CONFIG_H -I. -I..  -I. -I./../h  -g -O2 -Wall -funsigned-char --coverage -MT storage.o -MD -MP -MF .deps/storage.Tpo -c -o storage.o storage.c\r\n",
      "mv -f .deps/storage.Tpo .deps/storage.Po\r\n",
      "gcc -DHAVE_CONFIG_H -I. -I..  -I. -I./../h  -g -O2 -Wall -funsigned-char --coverage -MT util.o -MD -MP -MF .deps/util.Tpo -c -o util.o util.c\r\n",
      "mv -f .deps/util.Tpo .deps/util.Po\r\n",
      "gcc -DHAVE_CONFIG_H -I. -I..  -I. -I./../h  -g -O2 -Wall -funsigned-char --coverage -MT warranty.o -MD -MP -MF .deps/warranty.Tpo -c -o warranty.o warranty.c\r\n",
      "\u001b[1mwarranty.c:56:1: \u001b[0m\u001b[0;1;35mwarning: \u001b[0m\u001b[1ma function definition without a\r\n",
      "      prototype is deprecated in all versions of C and is not supported in C2x\r\n",
      "      [-Wdeprecated-non-prototype]\u001b[0m\r\n",
      "warranty(prefix)\r\n",
      "\u001b[0;1;32m^\r\n",
      "\u001b[0m1 warning generated.\r\n",
      "mv -f .deps/warranty.Tpo .deps/warranty.Po\r\n",
      "echo '{0}' > libmath.h\r\n",
      "/Applications/Xcode.app/Contents/Developer/usr/bin/make global.o\r\n",
      "gcc -DHAVE_CONFIG_H -I. -I..  -I. -I./../h  -g -O2 -Wall -funsigned-char --coverage -MT global.o -MD -MP -MF .deps/global.Tpo -c -o global.o global.c\r\n",
      "mv -f .deps/global.Tpo .deps/global.Po\r\n",
      "gcc -g -O2 -Wall -funsigned-char --coverage   -o libmath.h -o fbc main.o bc.o scan.o execute.o load.o storage.o util.o warranty.o global.o ../lib/libbc.a -ll  \r\n",
      "./fbc -c ./libmath.b </dev/null >libmath.h\r\n",
      "./fix-libmath_h\r\n",
      "2655\r\n",
      "2793\r\n",
      "rm -f ./fbc ./global.o\r\n",
      "gcc -DHAVE_CONFIG_H -I. -I..  -I. -I./../h  -g -O2 -Wall -funsigned-char --coverage -MT global.o -MD -MP -MF .deps/global.Tpo -c -o global.o global.c\r\n",
      "mv -f .deps/global.Tpo .deps/global.Po\r\n",
      "gcc -g -O2 -Wall -funsigned-char --coverage   -o bc main.o bc.o scan.o execute.o load.o storage.o util.o global.o warranty.o ../lib/libbc.a -ll  \r\n",
      "Making all in dc\r\n",
      "gcc -DHAVE_CONFIG_H -I. -I..  -I./.. -I./../h  -g -O2 -Wall -funsigned-char --coverage -MT dc.o -MD -MP -MF .deps/dc.Tpo -c -o dc.o dc.c\r\n",
      "mv -f .deps/dc.Tpo .deps/dc.Po\r\n",
      "gcc -DHAVE_CONFIG_H -I. -I..  -I./.. -I./../h  -g -O2 -Wall -funsigned-char --coverage -MT misc.o -MD -MP -MF .deps/misc.Tpo -c -o misc.o misc.c\r\n",
      "mv -f .deps/misc.Tpo .deps/misc.Po\r\n",
      "gcc -DHAVE_CONFIG_H -I. -I..  -I./.. -I./../h  -g -O2 -Wall -funsigned-char --coverage -MT eval.o -MD -MP -MF .deps/eval.Tpo -c -o eval.o eval.c\r\n",
      "mv -f .deps/eval.Tpo .deps/eval.Po\r\n",
      "gcc -DHAVE_CONFIG_H -I. -I..  -I./.. -I./../h  -g -O2 -Wall -funsigned-char --coverage -MT stack.o -MD -MP -MF .deps/stack.Tpo -c -o stack.o stack.c\r\n",
      "mv -f .deps/stack.Tpo .deps/stack.Po\r\n",
      "gcc -DHAVE_CONFIG_H -I. -I..  -I./.. -I./../h  -g -O2 -Wall -funsigned-char --coverage -MT array.o -MD -MP -MF .deps/array.Tpo -c -o array.o array.c\r\n",
      "mv -f .deps/array.Tpo .deps/array.Po\r\n",
      "gcc -DHAVE_CONFIG_H -I. -I..  -I./.. -I./../h  -g -O2 -Wall -funsigned-char --coverage -MT numeric.o -MD -MP -MF .deps/numeric.Tpo -c -o numeric.o numeric.c\r\n",
      "\u001b[1mnumeric.c:576:1: \u001b[0m\u001b[0;1;35mwarning: \u001b[0m\u001b[1ma function definition without a\r\n",
      "      prototype is deprecated in all versions of C and is not supported in C2x\r\n",
      "      [-Wdeprecated-non-prototype]\u001b[0m\r\n",
      "out_char (ch)\r\n",
      "\u001b[0;1;32m^\r\n",
      "\u001b[0m1 warning generated.\r\n",
      "mv -f .deps/numeric.Tpo .deps/numeric.Po\r\n",
      "gcc -DHAVE_CONFIG_H -I. -I..  -I./.. -I./../h  -g -O2 -Wall -funsigned-char --coverage -MT string.o -MD -MP -MF .deps/string.Tpo -c -o string.o string.c\r\n",
      "mv -f .deps/string.Tpo .deps/string.Po\r\n",
      "gcc -g -O2 -Wall -funsigned-char --coverage   -o dc dc.o misc.o eval.o stack.o array.o numeric.o string.o ../lib/libbc.a \r\n",
      "Making all in doc\r\n",
      "restore=: && backupdir=\".am$$\" && \\\r\n",
      "\tam__cwd=`pwd` && CDPATH=\"${ZSH_VERSION+.}:\" && cd . && \\\r\n",
      "\trm -rf $backupdir && mkdir $backupdir && \\\r\n",
      "\tif (makeinfo --no-split --version) >/dev/null 2>&1; then \\\r\n",
      "\t  for f in bc.info bc.info-[0-9] bc.info-[0-9][0-9] bc.i[0-9] bc.i[0-9][0-9]; do \\\r\n",
      "\t    if test -f $f; then mv $f $backupdir; restore=mv; else :; fi; \\\r\n",
      "\t  done; \\\r\n",
      "\telse :; fi && \\\r\n",
      "\tcd \"$am__cwd\"; \\\r\n",
      "\tif makeinfo --no-split   -I . \\\r\n",
      "\t -o bc.info bc.texi; \\\r\n",
      "\tthen \\\r\n",
      "\t  rc=0; \\\r\n",
      "\t  CDPATH=\"${ZSH_VERSION+.}:\" && cd .; \\\r\n",
      "\telse \\\r\n",
      "\t  rc=$?; \\\r\n",
      "\t  CDPATH=\"${ZSH_VERSION+.}:\" && cd . && \\\r\n",
      "\t  $restore $backupdir/* `echo \"./bc.info\" | sed 's|[^/]*$||'`; \\\r\n",
      "\tfi; \\\r\n",
      "\trm -rf $backupdir; exit $rc\r\n",
      "/bin/sh: makeinfo: command not found\r\n",
      "make[3]: *** [bc.info] Error 127\r\n",
      "make[2]: *** [all-recursive] Error 1\r\n",
      "make[1]: *** [all] Error 2\r\n"
     ]
    }
   ],
   "source": [
    "!cd bc-1.07.1; make CFLAGS=\"--coverage\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "The file `bc/bc` should now be executable..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 73,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:37.510452Z",
     "iopub.status.busy": "2024-01-18T17:14:37.510307Z",
     "iopub.status.idle": "2024-01-18T17:14:37.789361Z",
     "shell.execute_reply": "2024-01-18T17:14:37.786774Z"
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "4\r\n"
     ]
    }
   ],
   "source": [
    "!cd bc-1.07.1/bc; echo 2 + 2 | ./bc"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "...and you should be able to run the `gcov` program to retrieve coverage information."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 74,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:37.800332Z",
     "iopub.status.busy": "2024-01-18T17:14:37.799848Z",
     "iopub.status.idle": "2024-01-18T17:14:37.953766Z",
     "shell.execute_reply": "2024-01-18T17:14:37.952407Z"
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "File 'main.c'\r\n",
      "Lines executed:52.55% of 137\r\n",
      "Creating 'main.c.gcov'\r\n",
      "\r\n"
     ]
    }
   ],
   "source": [
    "!cd bc-1.07.1/bc; gcov main.c"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "As sketched in the [\"Coverage\" chapter](Coverage.ipynb), the file [bc-1.07.1/bc/main.c.gcov](bc-1.07.1/bc/main.c.gcov) now holds the coverage information for `bc.c`.  Each line is prefixed with the number of times it was executed. `#####` means zero times; `-` means non-executable line."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Parse the GCOV file for `bc` and create a `coverage` set, as in `FunctionCoverageRunner`.  Make this a `ProgramCoverageRunner` class that would be constructed with a list of source files (`bc.c`, `main.c`, `load.c`) to run `gcov` on."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "When you're done, don't forget to clean up:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 75,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-01-18T17:14:37.969918Z",
     "iopub.status.busy": "2024-01-18T17:14:37.969645Z",
     "iopub.status.idle": "2024-01-18T17:14:38.129284Z",
     "shell.execute_reply": "2024-01-18T17:14:38.128087Z"
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "!rm -fr bc-1.07.1 bc-1.07.1.tar.gz"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### Exercise 3\n",
    "\n",
    "In this [blog post](https://lcamtuf.blogspot.com/2014/08/binary-fuzzing-strategies-what-works.html), the author of _American Fuzzy Lop_ (AFL), a very popular mutation-based fuzzer discusses the efficiency of various mutation operators.  Implement four of them and evaluate their efficiency as in the examples above."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### Exercise 4\n",
    "\n",
    "When adding a new element to the list of candidates, AFL does actually not compare the _coverage_, but adds an element if it exercises a new _branch_.  Using branch coverage from the exercises of the [\"Coverage\"](Coverage.ipynb) chapter, implement this \"branch\" strategy and compare it against the \"coverage\" strategy, above."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### Exercise 5\n",
    "\n",
    "Design and implement a system that will gather a population of URLs from the Web.  Can you achieve a higher coverage with these samples?  What if you use them as initial population for further mutation?"
   ]
  }
 ],
 "metadata": {
  "ipub": {
   "bibliography": "fuzzingbook.bib",
   "toc": true
  },
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.2"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": true,
   "title_cell": "",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": true
  },
  "toc-autonumbering": false
 },
 "nbformat": 4,
 "nbformat_minor": 4
}