Quickstart

The Session object is the center of your fuzz… session. When you create it, you’ll pass it a Target object, which will itself receive a Connection object. For example:

session = Session(
    target=Target(
        connection=TCPSocketConnection("127.0.0.1", 8021)))

Connection objects implement ITargetConnection. Available options include TCPSocketConnection and its sister classes for UDP, SSL and raw sockets, and SerialConnection.

With a Session object ready, you next need to define the messages in your protocol. Once you’ve read the requisite RFC, tutorial, etc., you should be confident enough in the format to define your protocol using the various block and primitive types.

Each message is a Request object, whose children define the structure for that message.

Here are several message definitions from the FTP protocol:

user = Request("user", children=(
    String("key", "USER"),
    Delim("space", " "),
    String("val", "anonymous"),
    Static("end", "\r\n"),
))

passw = Request("pass", children=(
    String("key", "PASS"),
    Delim("space", " "),
    String("val", "james"),
    Static("end", "\r\n"),
))

stor = Request("stor", children=(
    String("key", "STOR"),
    Delim("space", " "),
    String("val", "AAAA"),
    Static("end", "\r\n"),
))

retr = Request("retr", children=(
    String("key", "RETR"),
    Delim("space", " "),
    String("val", "AAAA"),
    Static("end", "\r\n"),
))

Once you’ve defined your message(s), you will connect them into a graph using the Session object you just created:

session.connect(user)
session.connect(user, passw)
session.connect(passw, stor)
session.connect(passw, retr)

When fuzzing, boofuzz will send user before fuzzing passw, and user and passw before fuzzing stor or retr.

Now you are ready to fuzz:

session.fuzz()

Note that at this point you have only a very basic fuzzer. Making it kick butt is up to you. There are some examples and request_definitions in the repository that might help you get started.

The log data of each run will be saved to a SQLite database located in the boofuzz-results directory in your current working directory. You can reopen the web interface on any of those databases at any time with

$ boo open <run-*.db>

To do cool stuff like checking responses, you’ll want to use post_test_case_callbacks in Session. To use data from a response in a subsequent request, see ProtocolSessionReference.

You may also be interested in Making Your Own Block/Primitive.

Remember boofuzz is all Python, and advanced use cases often require customization. If you are doing crazy cool stuff, check out the community info and consider contributing back!

Happy fuzzing, and Godspeed!

More examples

Simple FTP

Check out the ftp_simple.py example. To run it, you will need an FTP server.

Once you have compiled the FTP server, just run it with ./ftp. The server runs on port 8021 by default. Make sure to run the ftp_simple.py script against the port that the server is listening on.

Simple HTTP and HTTP with body

Good examples on how to get started with HTTP fuzzing can be found in http_simple.py and http_with_body.py. Here is an example of how to execute theses scripts.

You will need an HTTP server, you can use Python or any other webserver like Apache or NGINX for that.

$ python3 -m http.server

Then run http_simple.py or http_with_body.py against the IP and port that your server uses.