`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`
`AST_OPERATORS`
`AST_COMPARATORS`
`NONE_OBJECT`
`FUNCTION_WHITELIST`

flow.record.selector.HAVE_ASTOR = True¶

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: object) → bool¶

__ne__(b: object) → bool¶

__lt__(b: object) → bool¶

__gt__(b: object) → bool¶

__lte__(b: object) → bool¶

__gte__(b: object) → bool¶

__noteq__(b: object) → bool¶

__contains__(b: object) → bool¶

__len__() → int¶

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: str | Any) → str¶: Return lowercased string, otherwise s if not string type.

flow.record.selector.upper(s: str | Any) → str | Any¶: Return uppercased string, otherwise s if not string type.

flow.record.selector.names(r: flow.record.base.Record | WrappedRecord | flow.record.base.GroupedRecord) → set[str]¶: Return the available names as a set in the Record otherwise [‘UnknownRecord’].

flow.record.selector.name(r: flow.record.base.Record | WrappedRecord) → str¶: Return the name of the Record otherwise ‘UnknownRecord’.

flow.record.selector.get_type(obj: Any) → str¶: Return the type of the Object as ‘str’.

flow.record.selector.has_field(r: flow.record.base.Record, field: str) → bool¶

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: flow.record.base.Record, fields: list[str], regex: str) → bool¶

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: flow.record.base.Record, fields: list[str], strings: list[str], nocase: bool = True) → bool¶

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: flow.record.base.Record, fields: list[str], strings: list[str], nocase: bool = True, word_boundary: bool = False) → bool¶

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: ast.Call) → str¶: Resolve a node attribute to full path, eg: net.ipv4.Subnet.

class flow.record.selector.SelectorResult(expression_str: str, match_result: Any, backtrace: list[tuple[int, Any]], referenced_fields: list)¶

expresssion_str¶

result¶

backtrace_info¶

referenced_fields¶

backtrace() → str¶

class flow.record.selector.Selector(expression: str)¶

VERBOSITY_ALL = 1¶

VERBOSITY_BRANCHES = 2¶

VERBOSITY_NONE = 3¶

expression_str¶

expression¶

matcher = None¶

__str__() → str¶

__repr__() → str¶

__contains__(record: flow.record.base.Record) → bool¶

explain_selector(record: flow.record.base.Record, verbosity: int = VERBOSITY_ALL) → SelectorResult¶

match(record: flow.record.base.Record) → bool¶

class flow.record.selector.WrappedRecord(record: flow.record.base.Record)¶

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

__slots__ = ('record',)¶

record¶

__getattr__(k: str) → Any¶

__str__() → str¶

__repr__() → str¶

class flow.record.selector.CompiledSelector(expression: str)¶

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

expression¶

code = None¶

ns¶

__str__() → str¶

__repr__() → str¶

__contains__(record: flow.record.base.Record) → bool¶

match(record: flow.record.base.Record) → bool¶

class flow.record.selector.TypeMatcher(rec: flow.record.base.Record)¶

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: str) → TypeMatcherInstance | NoneObject¶

class flow.record.selector.TypeMatcherInstance(rec: flow.record.base.Record, ftypeparts: list[str] | None = None, attrs: list[str] | None = None)¶

__getattr__(attr: str) → TypeMatcherInstance | NoneObject¶

__iter__() → collections.abc.Iterator[str]¶

__eq__(other: object) → bool¶

__ne__(other: object) → bool¶

__lt__(other: object) → bool¶

__gt__(other: object) → bool¶

__lte__(other: object) → bool¶

__gte__(other: object) → bool¶

__noteq__(other: object) → bool¶

__contains__(other: object) → bool¶

class flow.record.selector.RecordContextMatcher(expr: ast.Expression, expr_str: str, backtrace_verbosity: int = Selector.VERBOSITY_NONE)¶

expression¶

expression_str¶

selector_backtrace = []¶

selector_backtrace_verbosity = 3¶

data¶

rec = None¶

matches(rec: flow.record.base.Record) → bool¶

eval(node: ast.expr) → Any¶

flow.record.selector.make_selector(selector: str | Selector | None, force_compiled: bool = False) → Selector | CompiledSelector | None¶: Return a Selector object (either CompiledSelector or Selector).

flow.record.selector¶

Module Contents¶

Classes¶

Functions¶

Attributes¶

`flow.record.selector`¶