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#

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).