Python Bindings

Python bindings provide easy and comfortable way how to use yaramod in your Python scripts. You should be able to do most of the things that are available in C++ but you can run into few limitations of these bindings.

yaramod python bindings follow the same principles as C++ interface so you should first read about parsing and construction of YARA rules.

General information

• Names of classes are the same as in C++.
• Methods use snake_case instead of camelCase.
• Usually method which begin with get, set and is are transformed into class properties.
• Nested enums are no longer nested but they are still prefixed with the parent name (Rule::Modifier is RuleModifier in Python).
• Enums which contain value None are replaced with value Empty to prevent name clash with python keyword.
• Modifying lists or dictionaries returned by methods/properties do not directly modify the contents of object which it comes from. Use dedicated methods for it.
• Methods which expect std::vector as parameter can be given list object in Python.
• Methods which expect std::istream as parameter can be given str object in Python.
• Methods which expect variadic arguments can be given variadic arguments in Python too.
• Methods which expect pointer/reference to the object can be given the instance of that class in Python. However, be advised that there is much more copying going on when using Python bindings. This is most noticeable when using YaraFileBuilder.with_rule(). This method would not copy in C++, it would move the given Rule but in Python it is being copied. So even if you end up with valid Rule instance after calling with_rule(), you should no longer use it because any modification to it would not be reflected in the YaraFileBuilder.

Bindings tables

Parser bindings

C++	Python
parseFile()	parse_file()
parseStream()	parse_string()

Types bindings

YaraFile

C++	Python
YaraFile::getText()	YaraFile.text
YaraFile::getRules()	YaraFile.rules
YaraFile::getImports()	YaraFile.imports
YaraFile::findSymbol()	YaraFile.find_symbol()
YaraFile::insertRule()	YaraFile.add_rule()
YaraFile::insertRule()	YaraFile.insert_rule()
YaraFile::removeRules()	YaraFile.remove_rules()
YaraFile::removeImports()	YaraFile.remove_imports()
YaraFile::getTokenStream()	YaraFile.tokenstream()

Rule

C++	Python
Rule::getText()	Rule.text
Rule::getName()	Rule.name
Rule::getMetas()	Rule.metas
Rule::getStrings()	Rule.strings
Rule::getTags()	Rule.tags
Rule::getModifier()	Rule.modifier
Rule::isPrivate()	Rule.is_private
Rule::isGlobal()	Rule.is_global
Rule::getLocation()	Rule.location
Rule::getSymbol()	Rule.symbol
Rule::getCondition()	Rule.condition
Rule::setCondition()	Rule.condition
Rule::removeString()	Rule.remove_string()
Rule::getMetaWithName()	Rule.get_meta_with_name()

Rule::Location

C++	Python
Rule::Location::filePath	RuleLocation.file_path
Rule::Location::lineNumber	RuleLocation.line_number

Module

C++	Python
Module::getName()	Module.name

String

C++	Python
String::getText()	String.text
String::getPureText()	String.pure_text
String::getType()	String.type
String::getIdentifier()	String.identifier
String::isPlain()	String.is_plain
String::isHex()	String.is_hex
String::isRegexp()	String.is_regexp
String::isAscii()	String.is_ascii
String::isWide()	String.is_wide
String::isFullword()	String.is_fullword
String::isNocase()	String.is_nocase
String::getModifiersText()	String.modifiers_text

Regexp

C++	Python
Regexp::getSuffixModifiers()	Regexp.suffix_modifiers

Symbol

C++	Python
Symbol::getName()	Symbol.name
Symbol::getDataType()	Symbol.data_type
Symbol::isValue()	Symbol.is_value
Symbol::isArray()	Symbol.is_array
Symbol::isDictionary()	Symbol.is_dictionary
Symbol::isFunction()	Symbol.is_function
Symbol::isStructure()	Symbol.is_structure

StructureSymbol

C++	Python
StructureSymbol::getAttribute()	StructureSymbol.get_attribute()

Expression

C++	Python
Expression::accept()	Expression.accept()
Expression::getText()	Expression.text
Expression::getText()	Expression.get_text()

StringExpression

C++	Python
StringExpression::getId()	StringExpression.id
StringExpression::setId()	StringExpression.id

StringWildcardExpression

C++	Python
StringWildcardExpression::getId()	StringWildcardExpression.id
StringWildcardExpression::setId()	StringWildcardExpression.id

StringAtExpression

C++	Python
StringAtExpression::getId()	StringAtExpression.id
StringAtExpression::setId()	StringAtExpression.id
StringAtExpression::getAtExpression()	StringAtExpression.at_expr
StringAtExpression::setAtExpression()	StringAtExpression.at_expr

StringInRangeExpression

C++	Python
StringInRangeExpression::getId()	StringInRangeExpression.id
StringInRangeExpression::setId()	StringInRangeExpression.id
StringInRangeExpression::getRangeExpression()	StringInRangeExpression.range_expr
StringInRangeExpression::setRangeExpression()	StringInRangeExpression.range_expr

StringOffsetExpression

C++	Python
StringOffsetExpression::getId()	StringOffsetExpression.id
StringOffsetExpression::setId()	StringOffsetExpression.id
StringOffsetExpression::getIndexExpression()	StringOffsetExpression.index_expr
StringOffsetExpression::setIndexExpression()	StringOffsetExpression.index_expr

StringLengthExpression

C++	Python
StringLengthExpression::getId()	StringLengthExpression.id
StringLengthExpression::setId()	StringLengthExpression.id
StringLengthExpression::getIndexExpression()	StringLengthExpression.index_expr
StringLengthExpression::setIndexExpression()	StringLengthExpression.index_expr

UnaryOpExpression

C++	Python
UnaryOpExpression::getOperand()	UnaryOpExpression.operand
UnaryOpExpression::setOperand()	UnaryOpExpression.operand

BinaryOpExpression

C++	Python
BinaryOpExpression::getLeftOperand()	BinaryOpExpression.left_operand
BinaryOpExpression::setLeftOperand()	BinaryOpExpression.left_operand
BinaryOpExpression::getRightOperand()	BinaryOpExpression.right_operand
BinaryOpExpression::setRightOperand()	BinaryOpExpression.right_operand

SetExpression

C++	Python
SetExpression::getElements()	SetExpression.elements
SetExpression::setElements()	SetExpression.elements

RangeExpression

C++	Python
RangeExpression::getLow()	RangeExpression.low
RangeExpression::getHigh()	RangeExpression.high

IdExpression

C++	Python
IdExpression::getSymbol()	IdExpression.symbol
IdExpression::setSymbol()	IdExpression.symbol

StructAccessExpression

C++	Python
StructAccessExpression::getStructure()	StructAccessExpression.structure
StructAccessExpression::setStructure()	StructAccessExpression.structure

ArrayAccessExpression

C++	Python
ArrayAccessExpression::getArray()	ArrayAccessExpression.array
ArrayAccessExpression::setArray()	ArrayAccessExpression.array
ArrayAccessExpression::getAccessor()	ArrayAccessExpression.acessor
ArrayAccessExpression::setAccessor()	ArrayAccessExpression.acessor

FunctionCallExpression

C++	Python
FunctionCallExpression::getFunction()	FunctionCallExpression.function
FunctionCallExpression::setFunction()	FunctionCallExpression.function
FunctionCallExpression::getArguments()	FunctionCallExpression.arguments
FunctionCallExpression::setArguments()	FunctionCallExpression.arguments

LiteralExpression

C++	Python
LiteralExpression::getValue()	LiteralExpression.value

ParenthesesExpression

C++	Python
ParenthesesExpression::getEnclosedExpression()	ParenthesesExpression.enclosed_expr
ParenthesesExpression::setEnclosedExpression()	ParenthesesExpression.enclosed_expr

IntFunctionExpression

C++	Python
IntFunctionExpression::getFunction()	IntFunctionExpression.function
IntFunctionExpression::setFunction()	IntFunctionExpression.function
IntFunctionExpression::getArguments()	IntFunctionExpression.arguments
IntFunctionExpression::setArguments()	IntFunctionExpression.arguments

RegexpExpression

C++	Python
RegexpExpression::getRegexpString()	RegexpExpression.regexp_string
RegexpExpression::setRegexpString()	RegexpExpression.regexp_string

Builder bindings

YaraFileBuilder

C++	Python
YaraFileBuilder::get()	YaraFileBuilder.get()
YaraFileBuilder::withModule()	YaraFileBuilder.with_module()
YaraFileBuilder::withRule()	YaraFileBuilder.with_rule()

YaraRuleBuilder

C++	Python
YaraRuleBuilder::get()	YaraRuleBuilder.get()
YaraRuleBuilder::withName()	YaraRuleBuilder.with_name()
YaraRuleBuilder::withModifier()	YaraRuleBuilder.with_modifier()
YaraRuleBuilder::withTag()	YaraRuleBuilder.with_tag()
YaraRuleBuilder::withStringMeta()	YaraRuleBuilder.with_string_meta()
YaraRuleBuilder::withIntMeta()	YaraRuleBuilder.with_int_meta()
YaraRuleBuilder::withUIntMeta()	YaraRuleBuilder.with_uint_meta()
YaraRuleBuilder::withHexIntMeta()	YaraRuleBuilder.with_hex_int_meta()
YaraRuleBuilder::withBoolMeta()	YaraRuleBuilder.with_bool_meta()
YaraRuleBuilder::withPlainString()	YaraRuleBuilder.with_plain_string()
YaraRuleBuilder::withHexString()	YaraRuleBuilder.with_hex_string()
YaraRuleBuilder::withRegexp()	YaraRuleBuilder.with_regexp()
YaraRuleBuilder::withCondition()	YaraRuleBuilder.with_condition()

YaraExpressionBuilder

C++	Python
YaraExpressionBuilder::get()	YaraExpressionBuilder.get()
YaraExpressionBuilder::operator~()	YaraExpressionBuilder.__invert__()
YaraExpressionBuilder::operator-()	YaraExpressionBuilder.__neg__()
YaraExpressionBuilder::operator==()	YaraExpressionBuilder.__eq__()
YaraExpressionBuilder::operator!=()	YaraExpressionBuilder.__ne__()
YaraExpressionBuilder::operator<()	YaraExpressionBuilder.__lt__()
YaraExpressionBuilder::operator>()	YaraExpressionBuilder.__gt__()
YaraExpressionBuilder::operator<=()	YaraExpressionBuilder.__le__()
YaraExpressionBuilder::operator>=()	YaraExpressionBuilder.__ge__()
YaraExpressionBuilder::operator+()	YaraExpressionBuilder.__add__()
YaraExpressionBuilder::operator-()	YaraExpressionBuilder.__sub__()
YaraExpressionBuilder::operator*()	YaraExpressionBuilder.__mul__()
YaraExpressionBuilder::operator/()	YaraExpressionBuilder.__truediv__()
YaraExpressionBuilder::operator%()	YaraExpressionBuilder.__mod__()
YaraExpressionBuilder::operator^()	YaraExpressionBuilder.__xor__()
YaraExpressionBuilder::operator&()	YaraExpressionBuilder.__and__()
YaraExpressionBuilder::operator|()	YaraExpressionBuilder.__or__()
YaraExpressionBuilder::operator<<()	YaraExpressionBuilder.__lshift__()
YaraExpressionBuilder::operator>>()	YaraExpressionBuilder.__rshift__()
YaraExpressionBuilder::operator()()	YaraExpressionBuilder.__call__()
YaraExpressionBuilder::operator[]()	YaraExpressionBuilder.__getitem__()
YaraExpressionBuilder::access()	YaraExpressionBuilder.access()
YaraExpressionBuilder::contains()	YaraExpressionBuilder.contains()
YaraExpressionBuilder::matches()	YaraExpressionBuilder.matches()
YaraExpressionBuilder::readInt8()	YaraExpressionBuilder.read_int8()
YaraExpressionBuilder::readInt16()	YaraExpressionBuilder.read_int16()
YaraExpressionBuilder::readInt32()	YaraExpressionBuilder.read_int32()
YaraExpressionBuilder::readUInt8()	YaraExpressionBuilder.read_uint8()
YaraExpressionBuilder::readUInt16()	YaraExpressionBuilder.read_uint16()
YaraExpressionBuilder::readUInt32()	YaraExpressionBuilder.read_uint32()
YaraExpressionBuilder::operator!()	not_()

Expression builder functions

C++	Python
set()	set()
range()	range()
conjunction()	conjunction()
disjunction()	disjunction()
filesize()	filesize()
entrypoint()	entrypoint()
all()	all()
any()	any()
them()	them()
regexp()	regexp()

YaraHexStringBuilder

C++	Python
YaraHexStringBuilder::get()	YaraHexStringBuilder.get()
YaraExpressionBuilder::add()	YaraHexStringBuilder.add()

Hex string builder functions

C++	Python
wildcard()	wildcard()
wildcardLow()	wildcard_low()
wildcardHigh()	wildcard_high()
jumpVarying()	jump_varying()
jumpFixed()	jump_fixed()
jumpVaryingRange()	jump_varying_range()
jumpRange()	jump_range()
alt()	alt()

TokenStream

C++	Python
empty()	empty
size()	size
front()	front
back()	back
getTokens()	tokens
getTokensAsText()	tokens_as_text
begin()	begin
end()	end
find()	find()

TokenIt

C++	Python
*self	value
++self	increment()
--self	decrement()
return ++self	next()
return --self	previous()

Visitor bindings

Since Python does not support function overloading and library pybind11 which we used has its limitations too, we applied unconventional measures in order to make the visitor interface work in Python. visit() from C++ becomes visit_XYZ() where XYZ is the name of the type that is being visited (for example visit_FunctionCallExpression()). This should keep your Python code as much similar as its C++ counterpart.

This is an example of FunctionCallDumper which we introduced in the parsing of YARA files.

import yaramod

class FunctionCallDumper(yaramod.ObservingVisitor):
    def visit_FunctionCallExpression(self, expr):
        print('Function call: {}'.format(expr.function.text))
        for arg in expr.arguments:
            arg.accept(self)