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
Installation
Install with pip (recommended)
pip3 install kharmaInstall with Docker
/bin/bash ./scripts/docker_install.shOr 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 10The 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 jsTemplates
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 commentImports (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 r0g3r5@protonmail.com or on twitter @Rog3rSm1th
