Jinja

Description

Event plugin for producing events using Jinja template engine.

Parameters

Parameter	Expected value	Required	Description
params	<ParamsMapping>	Yes	Parameters to pass to templates
samples	<SamplesMapping>	Yes	Samples to pass to templates
mode	all | any | chance | spin	Yes	Mode of template picking all - render all templates at a time any - render one any template chance - render one template depending on their chances spin - render one template after another in turn
templates	<TemplatesList>	Yes	Templates to render

Params mapping

Params mapping is a simple mapping of key-value type where key is parameter name and value is a value of parameter. Mapping can be nested.

Example:

param1: 1
param2: ["a", "b", "c"]
param3: "hello"

tip

In yaml files mapping can be passed as json as well:

{ "param1": 1, "param2": ["a", "b", "c"], "param3": "hello" }

Samples mapping

Each key in samples mapping is a sample alias and value is a following object:

Parameter	Expected value	Required	Description
type	csv | items	Yes	Type of sample
header	<bool>	No, applicable only with csv type, default is False	Whether the csv sample includes header
delimiter	<str>	No, applicable only with csv type, default is ,	Delimiter for csv sample
source	<str> | <list[str]>	Yes	Source data for sample For csv type is a filepath to csv file For items type is a list of sample items

Example:

users:
  type: "csv"
  source: "users.csv"

hosts:
  type: "items"
  source:
    - "host1"
    - "host2"
    - "host3"

Templates list

Each item in templates list is a mapping where key is a template alias and value is a following object:

Parameter	Expected value	Required	Description
template	<str>	Yes	Path to template
chance	<float>	Only for chance picking mode	Chance for the template to be picked

Example

- auth_failed:
    template: "auth_failed.json.jinja"
    chance: 0.05

- auth_success:
    template: "auth_success.json.jinja"
    chance: 0.95

Example

params: {"param": 1, "param2": "string"}

samples:
  users:
    type: "csv"
    source: "users.csv"

mode: "all"

templates:
  - test:
      template: "test.jinja"

Usage in templates

Predefined variables

Variable	Example value	Description
timestamp	2024-01-01T00:00:00	Original timestamp of the event
tz	+0300	Timezone of timestamp
tags	["tag1", "tag2", "tag3"]	Tags list of input plugin that triggered event rendering

Variable names can be adjusted via core settings.

State API

There are two scopes of states in templates:

• locals - individual state for each template
• shared - single shared state available across templates

To set variable to state (e.g. locals scope):

{% do locals.set("key", value) %}

To get variable from state:

{% value = locals.get("key", "default") %}

If state has no specified key when calling get, then default value passed as second argument will be returned. If second argument is omitted, then None is returned.

Params API

To use parameters in templates use params keyword and then specify parameter name:

{{ params.param_name }}

Samples API

To use samples in templates use samples keyword and then specify sample alias:

{{ samples.samples_alias }}

For type csv collection of tuples is returned even if sample has one column. For type items collection of strings is returned.

To pick random row from a sample you can for example use Jinja random filter:

{{ samples.samples_alias | random }}

Subprocess API

To run subprocess from template use subprocess keyword and call run method.

Parameters of subprocess.run method:

Parameter	Expected value	Required	Description
command	<str>	Yes	Shell command to execute
block	<bool>	No, default is False	Whether to block template rendering waiting for the result of the command. If True is provided command output is returned after its execution, otherwise subprocess runs in the background and method call immediately returns None to unblock template rendering.

Examples:

{% do subprocess.run("python3 trigger_me.py") %}

{% set result = subprocess.run("tail -n 1 /app/data/status.log", True) %}

Module API

To run some python function in template you can use module keyword. Then you have to specify module and function name to be called.

{{ module.my_module.my_function("param") }}

Modules should be placed into event_plugins/jinja_modules directory of eventum-plugins package. There are default modules listed below.

Module rand

Module provides functions to generate random values.

Function	Parameters	Returned value	Description
shuffle	items: <Sequence[T]>	<T>	Return shuffled sequence of items
choice	items: <Sequence[T]>	<T>	Return random item from non empty sequence
choices	items: <Sequence[T]> n: <int>	<list[T]>	Return n random items from non empty sequence
weighted_choice	items: <Sequence[T]> weights: <Sequence[float]>	<T>	Return random item from non empty sequence with weights probability
weighted_choices	items: <Sequence[T]> weights: <Sequence[float]> n: <int>	<list[T]>	Return n random items from non empty sequence with weights probability
number.integer	a: <int> b: <int>	<int>	Return random integer in range [a, b]
number.floating	a: <float> b: <float>	<float>	Return random floating point number in range [a, b]
number.gauss	mu: <float> sigma: <float>	<float>	Return random floating point number from Gaussian distribution
string.letters_lowercase	size: <int>	<str>	Return string of specified size that contains random ASCII lowercase letters
string.letters_uppercase	size: <int>	<str>	Return string of specified size that contains random ASCII uppercase letters
string.letters	size: <int>	<str>	Return string of specified size that contains random ASCII letters
string.digits	size: <int>	<str>	Return string of specified size that contains random digits characters
string.punctuation	size: <int>	<str>	Return string of specified size that contains random ASCII punctuation characters
string.hex	size: <int>	<str>	Return string of specified size that contains random hex characters
network.ip_v4	-	<str>	Return random IPv4 address
network.ip_v4_private_a	-	<str>	Return random private IPv4 address of Class A
network.ip_v4_private_b	-	<str>	Return random private IPv4 address of Class B
network.ip_v4_private_c	-	<str>	Return random private IPv4 address of Class C
network.ip_v4_public	-	<str>	Return random public IPv4 address
network.mac	-	<str>	Return random MAC address
crypto.uuid4	-	<str>	Return universally unique identifier of version 4
crypto.md5	-	<str>	Return random MD5 hash
crypto.sha256	-	<str>	Return random SHA-256 hash
datetime.timestamp	start: <str> end: <str>	<str>	Return random timestamp in range [start; end]

Module py

Module provides classes from python standard library.

List of classes:

• datetime
• time
• timedelta