flow.record.selector

Module Contents

Classes

NoneObject	Returned in the Selector matching if a field does not exist on the Record.
SelectorResult
Selector
WrappedRecord	WrappedRecord wraps a Record but will return a NoneObject for non existing attributes.
CompiledSelector	CompiledSelector is faster than Selector but unsafe if you don't trust the query.
TypeMatcher	Helper to get and check fields of a certain type.
TypeMatcherInstance
RecordContextMatcher

Functions

lower	Return lowercased string, otherwise s if not string type.
upper	Return uppercased string, otherwise s if not string type.
names	Return the available names as a set in the Record otherwise ['UnknownRecord'].
name	Return the name of the Record otherwise 'UnknownRecord'.
get_type	Return the type of the Object as 'str'.
has_field	Check if field exists on Record object.
field_regex	Check a regex against fields of a Record object.
field_equals	Check for exact string matches on fields of a Record object.
field_contains	Check if the string matches on fields of a Record object.
resolve_attr_path	Resolve a node attribute to full path, eg: net.ipv4.Subnet.
make_selector	Return a Selector object (either CompiledSelector or Selector).

Attributes

HAVE_ASTOR
string_types
AST_NODE_S_TYPES
AST_NODE_VALUE_TYPES
AST_OPERATORS
AST_COMPARATORS
NONE_OBJECT
FUNCTION_WHITELIST

flow.record.selector.HAVE_ASTOR = True

flow.record.selector.string_types = ()

flow.record.selector.AST_NODE_S_TYPES

flow.record.selector.AST_NODE_VALUE_TYPES

flow.record.selector.AST_OPERATORS

flow.record.selector.AST_COMPARATORS

class flow.record.selector.NoneObject

Returned in the Selector matching if a field does not exist on the Record.

NoneObject is used to override some comparators like __contains__.

__eq__(b)

Return self==value.

__ne__(b)

Return self!=value.

__lt__(b)

Return self<value.

__gt__(b)

Return self>value.

__lte__(b)

__gte__(b)

__noteq__(b)

__contains__(b)

__len__()

flow.record.selector.NONE_OBJECT

exception flow.record.selector.InvalidSelectorError

Bases: Exception

Common base class for all non-exit exceptions.

exception flow.record.selector.InvalidOperation

Bases: Exception

Common base class for all non-exit exceptions.

flow.record.selector.lower(s)

Return lowercased string, otherwise s if not string type.

flow.record.selector.upper(s)

Return uppercased string, otherwise s if not string type.

flow.record.selector.names(r)

Return the available names as a set in the Record otherwise [‘UnknownRecord’].

flow.record.selector.name(r)

Return the name of the Record otherwise ‘UnknownRecord’.

flow.record.selector.get_type(obj)

Return the type of the Object as ‘str’.

flow.record.selector.has_field(r, field)

Check if field exists on Record object.

Parameters:

• r – Record to match on.

• field_name – Field name

Returns:

True if field exists, otherwise False

Return type:

(bool)

flow.record.selector.field_regex(r, fields, regex)

Check a regex against fields of a Record object.

Parameters:

• r – The record to match on.

• fields – The fields in the Record to match.

• regex – The regex pattern to search for.

Returns:

True or False

Return type:

(bool)

flow.record.selector.field_equals(r, fields, strings, nocase=True)

Check for exact string matches on fields of a Record object.

Parameters:

• r – The record to match on.

• fields – The fields in the Record to match.

• strings – The strings to search for.

• nocase – Should the matching be case insensitive.

Returns:

True or False

Return type:

(bool)

flow.record.selector.field_contains(r, fields, strings, nocase=True, word_boundary=False)

Check if the string matches on fields of a Record object.

Only supports strings for now and partial matches using the __contains__ operator.

• fields is a list of field names to check

• strings is a list of strings to check on the fields

• word_boundary is a boolean. True if matching required only word boundary matches.

• Non existing fields on the Record object are skipped.

• Defaults to case-insensitive matching, use nocase=False if you want to be case sensitive.

flow.record.selector.FUNCTION_WHITELIST

flow.record.selector.resolve_attr_path(node)

Resolve a node attribute to full path, eg: net.ipv4.Subnet.

class flow.record.selector.SelectorResult(expression_str, match_result, backtrace, referenced_fields)

backtrace()

class flow.record.selector.Selector(expression)

VERBOSITY_ALL = 1

VERBOSITY_BRANCHES = 2

VERBOSITY_NONE = 3

__str__()

Return str(self).

__repr__()

Return repr(self).

__contains__(record)

explain_selector(record, verbosity=VERBOSITY_ALL)

match(record)

class flow.record.selector.WrappedRecord(record)

WrappedRecord wraps a Record but will return a NoneObject for non existing attributes.

__slots__ = ('record',)

__getattr__(k)

__str__() → str

Return str(self).

__repr__() → str

Return repr(self).

class flow.record.selector.CompiledSelector(expression)

CompiledSelector is faster than Selector but unsafe if you don’t trust the query.

__str__()

Return str(self).

__repr__()

Return repr(self).

__contains__(record)

match(record)

class flow.record.selector.TypeMatcher(rec)

Helper to get and check fields of a certain type.

Types can be selected using Type.<typename>. Attributes can be selected using Type.<typename>.<attribute>.

For example Type.uri.filename will retrieve all the filenames from all uri’s in a record.

These selectors can also still be used in other helper functions, as they will unwrap to resulting fieldnames. So for example, you can still do field_contains(r, Type.string, [‘something’]), which will check all string fields.

Membership tests also work. ‘something’ in Type.string will perform a membership test in each string value and return True if there are any.

Reverse membership tests are trickier, and only work with a non-compiled Selector. For example, Type.net.ipv4.Address in net.ipv4.Subnet(‘10.0.0.0/8’) requires the TypeMatcher to unroll its values, which is only possible when overriding this behaviour.

__getattr__(attr)

class flow.record.selector.TypeMatcherInstance(rec, ftypeparts=None, attrs=None)

__getattr__(attr)

__iter__()

__eq__(other)

Return self==value.

__ne__(other)

Return self!=value.

__lt__(other)

Return self<value.

__gt__(other)

Return self>value.

__lte__(other)

__gte__(other)

__noteq__(other)

__contains__(other)

class flow.record.selector.RecordContextMatcher(expr, expr_str, backtrace_verbosity=Selector.VERBOSITY_NONE)

matches(rec)

eval(node)

flow.record.selector.make_selector(selector, force_compiled=False)

Return a Selector object (either CompiledSelector or Selector).