gramfuzz is a grammar-based fuzzer that lets one define complex grammars to generate text and binary data formats.
Python Shell
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
bin fixed the error Dec 12, 2016
tests fixes #16 - __file__ is now set when loading grammars Jan 19, 2017


  • master Build Status: Master
  • develop Build Status: Develop

gramfuzz is a grammar-based fuzzer that lets one define complex grammars to model text and binary data formats.


Install via pip:

pip install gramfuzz


For detailed documentation, please view the full docs here

TLDR Example

Suppose we define a grammar for generating names and their prefixes and suffixes:

import gramfuzz
from gramfuzz.fields import *

class NRef(Ref):
    cat = "name_def"
class NDef(Def):
    cat = "name_def"

cat="name", sep=" ")
    NRef("initial") | NRef("first_name"), Opt(NRef("personal_part")),
sep=" ")
NDef("last_name", Or(
    "Blart", "Tralb"
    Or("Phd.", "CISSP", "MD.", "MBA", "NBA", "NFL", "WTF", "The Great"),
sep=" ")
NDef("seniority", Or("Sr.", "Jr."))
NDef("name_title", Or(
    "Sir", "Ms.", "Mr.", "Mrs.", "Senator", "Capt.", "Maj.", "Lt.", "President"
NDef("first_name", Or("Henry", "Susy"))
    String(min=1, max=2, charset=String.charset_alpha_upper), "."

We could then use this grammar like so:

import gramfuzz

fuzzer = gramfuzz.GramFuzzer()
names = fuzzer.gen(cat="name", num=10)

Which would output something like this:

Ms. Susy Henry Tralb
Lt. Henry Henry Tralb
L. Tralb WTF
Maj. L. W. N. Tralb
Z. Tralb
Senator C. K. Henry Blart
Henry Tralb CISSP
Lt. Henry Tralb Jr. NBA
Maj. Susy Tralb Sr. NBA
Henry C. Blart WTF

More Examples

See the examples (and example script) in the examples folder:

 lptp [ tmp ]: git clone
 lptp [ tmp ]: cd gramfuzz/examples
 lptp [ examples ]: ./ --help
usage: gramfuzz/examples/ [-h] -g GRAMMAR [-n N] [-s RAND_SEED]
                                    [--max-recursion R] [-o OUTPUT]

This script will generate N instances of the specified grammar.

optional arguments:
  -h, --help            show this help message and exit
  -g GRAMMAR, --grammar GRAMMAR
                        The grammar to load. One of: names,python27,roman_numeral,postal
  -n N, --number N      The number of times to generate top-level nodes from the specified grammar(s) (default=1)
  -s RAND_SEED, --seed RAND_SEED
                        The random seed to initialize the PRNG with (default=None)
  --max-recursion R     The maximum reference recursion depth allowed (default=10)
  -o OUTPUT, --output OUTPUT
                        The output file to output the generated data to (default=stdout)
 lptp [ examples ]: ./ -g postal -n 10 -s 1337 --max-recursion 5
Z. Tralb
69 Baker Street 8325U 
Malang, IL 64666-4973
Senator Susy Henry Blart WTF
56 Sesame Street 
Yokohama, WV 49471-3667
Henry I. Tralb Jr. CISSP
63 Spooner Street 858H 
Tehran, TX 27259-9556
Capt. Henry Susy Blart Jr. Phd.
65536 Jump Street 
Malang, ID 84108-0969
Susy Blart
0 Rainey Street 
Wuhan, FL 16712-1095
P. Blart NFL
98 Wisteria Lane 
Shenyang, NH 70126
Henry Henry Blart Phd.
30 Rainey Street 
Madras, GA 90915
Senator Henry E. Tralb
38 Spooner Street 
Tianjin, CT 37211
Maj. Henry Tralb
70 Rainey Street 458W 
HongKong, OK 40689
Mrs. Henry Blart
11 Sesame Street 
Beijing, MT 58689-7258