mentat.reports.event module

Library for generating event reports.

The implementation is based on mentat.reports.base.BaseReporter.

class mentat.reports.event.EventReporter(logger, reports_dir, templates_dir, locale, timezone, eventservice, sqlservice, mailer, thresholding=True)[source]

Bases: mentat.reports.base.BaseReporter

Implementation of reporting class providing Mentat event reports.

aggregate_events(events)[source]

Aggregate given list of events to dictionary structure that can be used to generate report message.

Parameters

events (dict) – Structure containing events as mentat.idea.internal.Idea objects.

Returns

Dictionary structure of aggregated events.

Return type

dict

static aggregate_events_by_source(events, settings)[source]

Aggregate given list of events to dictionary structure according to the IPv4 and IPv6 sources. The resulting structure contains event source addresses (value of Source.IP4 and Source.IP6 attributes) as keys and list of events with given source in no particular order. For example:

{
    '192.168.1.1': [...],
    '::1': [...],
    ...
}
Parameters

  • events (list) – List of events as mentat.idea.internal.Idea objects.

  • settings (mentat.reports.event.ReportingSettings) – Reporting settings.

Returns

Dictionary structure of aggregated events.

Return type

dict

static aggregate_events_for_extra(events)[source]

Aggregate given list of events to dictionary structure more appropriate for rendering extra reports. The resulting structure contains event classes (value of _CESNET.EventClass attribute) as keys and list of events with given class sorted in ascending order by the value of the DetectTime attribute. For example:

{
    'event-class-01': [...],
    'event-class-02': [...],
    ...
}
Parameters

events (list) – List of events as mentat.idea.internal.Idea objects.

Returns

Dictionary structure of aggregated events.

Return type

dict

static aggregate_events_for_summary(events)[source]

Aggregate given list of events to dictionary structure more appropriate for rendering summary reports. The resulting structure contains event classes (value of _CESNET.EventClass attribute) as keys and and another dictionary with sources as keys (value of Source.IP4 and Source.IP6 attributes) and list of events with given class and source sorted in ascending order by the value of the DetectTime attribute. For example:

{
    'event-class-01': {'192.168.0.1': [...]},
    'event-class-02': {'192.168.0.2': [...]},
    ...
}
Parameters

events (dict) – Structure containing events as mentat.idea.internal.Idea objects.

Returns

Dictionary structure of aggregated events.

Return type

dict

choose_attachments(ident, settings)[source]

Choose appropriate report attachments based on the reporting configuration.

cleanup(ttl)[source]

Cleanup thresholding cache and remove all records with TTL older than given value.

Parameters

time_h (datetime.datetime) – Upper cleanup time threshold.

Returns

Number of removed records.

Return type

int

fetch_severity_events(abuse_group, severity, time_l, time_h, testdata=False)[source]

Fetch events with given severity for given abuse group within given time iterval.

Parameters

  • abuse_group – Abuse group model object.

  • severity (str) – Event severity level to fetch.

  • time_l (datetime.datetime) – Lower time interval boundary.

  • time_h (datetime.datetime) – Upper time interval boundary.

  • testdata (bool) – Switch to use test data for reporting.

Returns

List of events matching search criteria.

Return type

list

filter_event(filter_rules, event)[source]

Filter given event according to given list of filtering rules.

Parameters

  • filter_rules (list) – Filters to be used.

  • mentat.idea.internal.Idea – Event to be filtered.

Returns

True in case any filter matched, False otherwise.

Return type

bool

filter_events(events, abuse_group, settings)[source]

Filter given list of IDEA events according to given abuse group settings.

Parameters

  • events (list) – List of IDEA events as mentat.idea.internal.Idea objects.

  • mentat.datatype.sqldb.GroupModel – Abuse group.

  • settings (mentat.reports.event.ReportingSettings) – Reporting settings.

Returns

Tuple with list of events that passed filtering and filtering log as a dictionary.

Return type

tuple

static j2t_idea_path_valueset(message_s, jpath_s)[source]

Calculate and return set of all values on all given jpaths in all given messages. Messages and jpaths can also be a single values.

prepare_structured_data(events_reg_aggr, events_rel_aggr, settings)[source]

Prepare structured data for report column

Parameters
Returns

Structured data that cam be used to generate report message

Return type

dict

relapse_events(abuse_group, severity, time_h)[source]

Detect IDEA event relapses for given abuse group settings.

Parameters

  • mentat.datatype.sqldb.GroupModel – Abuse group.

  • severity (str) – Severity for which to perform reporting.

  • time_h (datetime.datetime) – Upper reporting time threshold.

Returns

List of events that relapsed.

Return type

list

render_report_extra(report, source, events_reg, events_rel, settings, template_vars=None, attachment_files=None)[source]

Render extra section of the event report email.

Parameters

  • report (mentat.datatype.sqldb.EventReportModel) – Event report.

  • source (str) – Source address.

  • events_reg (list) – List of regular IDEA events.

  • events_rel (list) – List of relapsed IDEA events.

  • locale_name (str) – Name of the locale.

  • timezone_name (str) – Name of the timezone.

  • template_file (str) – Name of the template file.

  • template_vars (dict) – Additional template variables.

  • attachment_files (list) – List of files, that will be attached to report.

Returns

Content of the extra section of report email.

Return type

str

render_report_summary(report, events, settings, template_vars=None, attachment_files=None)[source]

Render summary section of the event report email.

Parameters

  • report (mentat.datatype.sqldb.EventReportModel) – Event report.

  • events (dict) – Dictionary structure with IDEA events to be reported.

  • locale_name (str) – Name of the locale.

  • timezone_name (str) – Name of the timezone.

  • template_file (str) – Name of the template file.

  • template_vars (dict) – Additional template variables.

  • attachment_files (list) – List of files, that will be attached to report.

Returns

Content of the extra section of report email.

Return type

str

report(abuse_group, settings, severity, time_l, time_h, template_vars=None, testdata=False)[source]

Perform reporting for given abuse group, event severity and time window.

Parameters

  • abuse_group (mentat.datatype.internal.GroupModel) – Abuse group.

  • settings (mentat.reports.event.ReportingSettings) – Reporting settings.

  • severity (str) – Severity for which to perform reporting.

  • time_l (datetime.datetime) – Lower reporting time threshold.

  • time_h (datetime.datetime) – Upper reporting time threshold.

  • template_vars (dict) – Dictionary containing additional template variables.

  • testdata (bool) – Switch to use test data for reporting.

report_extra(parent_rep, result, events, abuse_group, settings, severity, time_l, time_h, template_vars=None, testdata=False)[source]

Generate extra reports from given events for given abuse group, severity and period.

Parameters

  • parent_rep (mentat.datatype.internal.EventReportModel) – Parent summary report.

  • result (dict) – Reporting result structure with various usefull metadata.

  • events (dict) – Dictionary structure with IDEA events to be reported.

  • abuse_group (mentat.datatype.internal.GroupModel) – Abuse group.

  • settings (mentat.reports.event.ReportingSettings) – Reporting settings.

  • severity (str) – Severity for which to perform reporting.

  • time_l (datetime.datetime) – Lower reporting time threshold.

  • time_h (datetime.datetime) – Upper reporting time threshold.

  • template_vars (dict) – Dictionary containing additional template variables.

  • testdata (bool) – Switch to use test data for reporting.

report_summary(result, events, abuse_group, settings, severity, time_l, time_h, template_vars=None, testdata=False)[source]

Generate summary report from given events for given abuse group, severity and period.

Parameters

  • result (dict) – Reporting result structure with various usefull metadata.

  • events (dict) – Dictionary structure with IDEA events to be reported.

  • abuse_group (mentat.datatype.internal.GroupModel) – Abuse group.

  • settings (mentat.reports.event.ReportingSettings) – Reporting settings.

  • severity (str) – Severity for which to perform reporting.

  • time_l (datetime.datetime) – Lower reporting time threshold.

  • time_h (datetime.datetime) – Upper reporting time threshold.

  • template_vars (dict) – Dictionary containing additional template variables.

  • testdata (bool) – Switch to use test data for reporting.

threshold_events(events, abuse_group, severity, time_h)[source]

Threshold given list of IDEA events according to given abuse group settings.

Parameters

  • events (list) – List of IDEA events as mentat.idea.internal.Idea objects.

  • mentat.datatype.sqldb.GroupModel – Abuse group.

  • severity (str) – Severity for which to perform reporting.

  • time_h (datetime.datetime) – Upper reporting time threshold.

Returns

List of events that passed thresholding.

Return type

list

update_thresholding_cache(events, settings, severity, time_h)[source]
Parameters

  • events (dict) – Dictionary structure with IDEA events that were reported.

  • settings (mentat.reports.event.ReportingSettings) – Reporting settings.

  • severity (str) – Severity for which to perform reporting.

  • time_h (datetime.datetime) – Upper reporting time threshold.

mentat.reports.event.REPORT_EMAIL_TEXT_WIDTH = 90

Width of the report email text.

mentat.reports.event.REPORT_SUBJECT_EXTRA = '[{:s}] {:s} - Notice about possible problems regarding host {:s}'

Subject for extra report emails.

mentat.reports.event.REPORT_SUBJECT_SUMMARY = '[{:s}] {:s} - Notice about possible problems in your network'

Subject for summary report emails.

mentat.reports.event.csv_dict(idea)[source]

Convert selected attributes of given IDEA message into flat dictionary suitable for CSV dump. This is a legacy feature from old version of Mentat system and due to its shortcomings is planned to be removed in the future. It was implemented only for the purposes of compatibility and transition from old version of Mentat system to new one.

mentat.reports.event.json_default(val)[source]

Helper function for JSON serialization of non basic data types.