Downloads and Installation

Downloads and Installation#

This notebook has instructions on how to use the fuzzingbook code in your own programs.

In short, there are three ways:

  1. Simply run the notebooks in your browser, using the “mybinder” environment. Choose “Binder” from the menus at the top; this will lead you to a preconfigured Jupyter Notebook environment where you can toy around at your leisure.

  2. Import the code for your own Python programs. Using pip install fuzzingbook, you can install all code and start using it from your own code. See “Installing Fuzzingbook Code for your own Python projects”, below.

  3. Download or check out the code and/or the notebooks from the project site. This allows you to edit and run all things locally. However, be sure to also install the required packages; see below for details.

import bookutils.setup

from bookutils import YouTubeVideo
YouTubeVideo("fGu3uwHcTRc")

Installing Fuzzingbook Code for your own Python projects#

We provide a fuzzingbook Python package that you can install using the pip package manager:

$ pip install fuzzingbook

This is set up such that almost all additional required packages are also installed.

Once pip is complete, you can import individual fuzzingbook classes, constants, or functions into your Python code (also in notebooks) using

>>> from fuzzingbook.<notebook> import <identifier>

where <identifier> is the name of the class, constant, or function to use, and <notebook> is the name of the respective notebook. (If you read this at fuzzingbook.org, then the notebook name is the identifier preceding ".html" in the URL).

Here is an example importing RandomFuzzer from the chapter on fuzzers, whose notebook name is Fuzzer:

>>> from fuzzingbook.Fuzzer import RandomFuzzer
>>> f = RandomFuzzer()
>>> f.fuzz()
'!7#%"*#0=)$;%6*;>638:*>80"=</>(/*:-(2<4 !:5*6856&?""11<7+%<%7,4.8,*+&,,$,."5%<%76< -5'

The “Synopsis” section at the beginning of a chapter gives a short survey on useful code features you can use.

Downloading the Notebooks#

Another way to use the code is to import the notebooks directly. Download the notebooks using this link:

https://www.fuzzingbook.org/dist/fuzzingbook-notebooks.zip

Then, add your own notebooks into the same folder. After importing bookutils.setup, you can then simply import the code from other notebooks, just as our own notebooks do.

Here is again the above example, importing RandomFuzzer from the chapter on fuzzers – but now from a notebook:

import bookutils.setup

from Fuzzer import RandomFuzzer

f = RandomFuzzer()
f.fuzz()

'!7#%"*#0=)$;%6*;>638:*>80"=</>(/*:-(2<4 !:5*6856&?""11<7+%<%7,4.8,*+&,,$,."5%<%76< -5'

If you’d like to share your notebook, let us know; we can integrate it in the repository or even in the book.

Downloading the Code#

If you want to work with code samples, you can download all the Python code here:

https://www.fuzzingbook.org/dist/fuzzingbook-code.zip

The code files can also be edited if you wish, but (a) they are very obviously generated from notebooks, (b) therefore not much fun to work with, and © if you fix any errors, you’ll have to back-propagate them to the notebook before you can make a pull request.

If you only want to use the Python code, install the code package (see above).

Getting the Code from GitHub#

You can also check out the latest and greatest from GitHub. After cloning the repository from the project page and installing the additional packages (see below), you can cd into notebooks and start jupyter right away!

There also is a Makefile provided with literally hundreds of targets; most important are the ones we also use in continuous integration:

  • make check-imports checks whether your code is free of syntax errors

  • make check-style checks whether your code is free of type errors

  • make check-code runs all derived code, testing it

  • make check-notebooks runs all notebooks, testing them

If you want to contribute to the project, ensure that the above tests run through.

The Makefile has many more, often experimental, targets. make markdown creates a .md variant in markdown/, and there’s also make word and make epub, which are set to create Word and EPUB variants (with mixed results). Try make help for commonly used targets.

Installing Supplemental Packages#

After downloaded fuzzingbook code, installing the fuzzingbook package, or checking out fuzzingbook from the repository, here’s what to do to obtain a complete set of packages.

Step 1: Install Required Python Packages#

The pyproject.toml file within the project root folder lists all Python packages required.

You can do

$ pip install .

to install all required packages (but using pipenv is preferred; see below).

Step 2: Install Additional Non-Python Packages#

The apt.txt file in the binder/ folder lists all Linux packages required.

In most cases, however, it suffices to install the dot graph drawing program (part of the graphviz package). Here are some instructions:

Installing Graphviz on Linux#

Use

$ sudo apt-get install graphviz libgraphviz-dev

to install dot.

Installing Graphviz on macOS#

On macOS, if you use conda, run

$ conda install graphviz

If you use HomeBrew, run

$ brew install graphviz

Installing Fuzzingbook Code in an Isolated Environment#

If you wish to install the fuzzingbook code in an environment that is isolated from your system interpreter, we recommend using Pipenv, which can automatically create a so called virtual environment hosting all required packages.

To accomplish this, please follow these steps:

Step 1: Install PyEnv#

Optionally install pyenv following the official instructions if you are on a Unix operating system. If you are on Windows, consider using pyenv-win instead. This will allow you to seamlessly install any version of Python.

Step 2: Install PipEnv#

Install Pipenv following the official installation instructions. If you have pyenv installed, Pipenv can automatically download and install the appropriate version of the Python distribution. Otherwise, Pipenv will use your system interpreter, which may or may not be the right version.

Step 3: Install Python Packages#

In the fuzzingbook root directory, run

$ pipenv install .

Step 4: Install Additional Non-Python Packages#

See above for instructions on how to install additional non-python packages.

Step 5: Enter the Environment#

Enter the environment with

$ pipenv shell

where you can now execute

$ make -k check-code

to run the tests.

Using Docker#

As another alternative, you can also use our Docker images (experimental). Install Docker and then run

    $ docker pull zeller24/fuzzingbook
    $ docker run -it --rm -p 8888:8888 zeller24/fuzzingbook

and then in your Web browser, open the URL (http://127.0.0.1/... or http://localhost/...) given in the console output. This should kick off the same Jupyter environment as in mybinder.org.

If you want to create your own Docker images, use our Dockerfile as a starting point.

Contents