pip3 install kharma

Installation    >    Usage    >    Templates    >    Contact

Kharma is a state-of-the-art grammar fuzzer. It can generate many random documents based on a grammar, which can be used to improve your testing corpus by increasing code coverage and to find bugs/vulnerabilities in many kinds of applications (interpreters, files parsers, etc...).

Requirements

Python 3

Installation

Install with pip (recommended)

pip3 install kharma

Install with Docker

/bin/bash ./scripts/docker_install.sh

Or build from source

Recommended for developers. It automatically clones the main branch from the kharma repo, and installs from source.

# Automatically clone the Kharma repository and install Kharma from source
bash <(wget -q https://raw.githubusercontent.com/Rog3rSm1th/Kharma/main/scripts/autoinstall.sh -O -)

Usage

usage: kharma [-h] [-v] -t TEMPLATE -c COUNT [-s] {output} ...

positional arguments:
  {output}              sub-command help
    output              output help

options:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit
  -t TEMPLATE, --template TEMPLATE
                        template path, e.g. ./path/to/file.kg
  -c COUNT, --count COUNT
                        number of documents to generate
  -s, --safe-mode       disallow call statements

Basic usage

For example if you want to generate 10 documents based on the javascript.kg template:

kharma -t ./javascript.kg -c 10

The documents will then be printed on stdout.

Generate files documents

Otherwise, if you want to save the documents into files you should use the output option.

usage: kharma output [-h] -d DIRECTORY
                     [-e EXTENSION]

For example if you want to output the documents in a js_documents folder with the .js extension:

kharma -t ./javascript.kg -c 10 output -d ./js_documents -e js

Templates

Kharma generates random documents based on grammars defined in templates, those templates are based on the YAML format and are divided into different sections.

Comments

# This is a comment

# This is a 
# Multi-line comment

Imports (optional section)

It is possible to import variables, constants and functions defined in other templates using the imports section.

imports:
    # You must specify the import name as well as the relative path of the template
    import: "import.kg"

Functions (optional section)

The function section allows you to define python functions inside your template.

functions:
    # Here we define the "multiply" function.
    multiply: |
                <%python (factor_1, factor_2)
                    factor_1_int = int(factor_1)
                    factor_2_int = int(factor_2)
                    product = factor_1_int*factor_2_int
                    return product
                %>

Constants (optional section)

The consts section allows to define values with only one possible value. Constants can use references to variables and vice versa.

consts:
    const_0: "This is a constant"
    const_1: |
             Multiple lines
             constant
    const_2: "++import:int8++"
    const_3: "++variable_0++"
    const_4: "++const_0++"
    const_5: "@@element_@@"
    const_6: "[%%range%%](0, 1337)"
    const_7: "[%%regexp:[A-Za-z0-9]+%%]"
    const_8: "[%%call~multiply%%](3, 4)"
    const_9: "[##repeat:1:5:dup:##]{%looped string%}"

Variables (optional section)

The variables section allows you to define values with several possible values.

variables:
    # A variable can have several possible values
    variable_0: 
        - "double quoted variable"
        - 'single quoted variable'
        - "Unicode string: \u0398\u039f\u03b4"
        - "Hexadecimal string: \x49\x4a\x4b"
        - |
            variable can be written 
            on multiples
            lines !
    
    # An anchor is a reference to another variable
    variable_anchor:
        # The anchor will be replaced by one of the possibles values of the variable
        - "++variable_0++"
    
    # Variable can use references to constants
    variable_const_anchor:
        - "++const_0++"
        - "++const_1++"
        - "++const_2++"
        - "++const_3++"
        - "++const_4++"
        - "++const_5++"
        - "++const_6++"
        - "++const_7++"
        - "++const_8++"
        - "++const_9++"
    
    # You can access variables/consts defined in imported files
    variable_import_anchor:
        - "++import:int8++"
        - "++import:uint8++"
        - "++import:int16++"
        - "++import:uint16++"
        - "++import:int32++"
        - "++import:uint32++"
        - "++import:int32++"
        - "++import:uint32++"
    
    # An element has a name and a counter.
    variable_element:
        # The first time we call it, the result will be "element_0", the next time
        # "element_1", and so on
        - "@@element_@@"
        # You can use id parameter to reuse same element value
        # element_id_0 element_id_1 element_id_0 element_id_2
        - "@@element_id_@@#id=test @@element_id_@@ @@element_id_@@#id=test @@element_id_@@"
    
    # Selection of a random value within the range
    variable_range:
        - "[%%range%%](0, 1337)"
        - "[%%range%%](-100, 100)"
        - "[%%range%%](-infinity, infinity)"
        
    # Generate a random valid input for the regular expression
    variable_regexp:
        - "[%%regexp:[A-Za-z0-9]+%%]"
    
    # Calls a function defined within the template and gets the return value
    variable_call:
        - "[%%call~multiply%%](3, 4)"
        - "[%%call~multiply%%](++import:int8++, ++import:int8++)"
        - "[%%call~multiply%%]([%%range%%](-100, 100), [%%range%%](-infinity, infinity))"

    # Calls a function defined in an imported template and gets the return value
    variable_import_call:
        - "[%%call~import:sum%%](3, 4)"
        - "[%%call~import:sum%%](++import:int8++, ++import:int8++)"
        - "[%%call~import:sum%%]([%%range%%](-100, 100), [%%range%%](-infinity, infinity))"

    # Loop a string
    variable_loop:
        # Repeat a string between 1 and 5 times
        - "[##repeat:1:5:dup:##]{%looped string%}"
        # Use a custom separator
        - "[##repeat:1:5:dup:, ##]{%looped string%}"
        # Repeat an anchor
        - "[##repeat:1:5:dup:##]{%++variable_anchor++%}"
        # Remove duplicates
        - "[##repeat:1:5:nodup:##]{%++variable_anchor++%}"
        # Repeat an imported anchor
        - "[##repeat:1:5:dup:##]{%++variable_import_anchor++%}"
        # Repeat an element reference
        - "[##repeat:1:5:dup:##]{%++variable_element++%}"
        # Repeat a range statement
        - "[##repeat:1:5:dup:##]{%[%%range%%](-100, 100)%}"
        # Repeat a regexp statement
        - "[##repeat:1:5:dup:##]{%++variable_regexp++%}"
        
    # It is possible to define a static variable by giving it a name starting 
    # with "static_"
    # A static variable will be evaluated only once and will take the
    # same value at each call
    static_variable:
        - "this is a static value"
        - "++import:int8++"
        - "@@element_@@"
        - "[%%range%%](0, 1337)"
        - "[%%regexp:[A-Za-z0-9]+%%]"
        - "[%%call~multiply%%](3, 4)"
        - "[##repeat:1:5:dup:##]{%looped string%}"
    
    # It is possible to use several statements/references
    several_statements_variables:
        - "++variable_0++ ++import:int8++ @@element_@@ [%%range%%](0, 1337) [%%regexp:[A-Za-z0-9]+%%] [%%call~multiply%%](3, 4) [##repeat:1:5:dup:##]{%looped string%}"

Variance (optional section)

The variance section contains the main variable which is the entry point of the template.

variance:
    # Main is the entry point of the template
    # it works like a regular variable
    main:
        # Happy template generating ! ヽ(o＾▽＾o)ノ
        - "++several_statements_variables++"

IMPORTANT: The order in which the sections are defined is not important and all sections are optionals.

You can find a demo template here.

Contact

for any remark, suggestion, bug report, or if you found a bug using Kharma, you can contact me at [email protected] or on twitter @Rog3rSm1th