msiempy.EventManager

class documentation

class msiempy.EventManager(_QueryExecuteManager): (source)

View In Hierarchy

List-Like object. Interface to execute a event query.

Exemples:
  • Execute an event query

Query events according to destination IP and hostname filters, sorted by AlertID.

from  msiempy import EventManager, FieldFilter
print('Simple event query sorted by AlertID')
events = EventManager(
        time_range='CURRENT_YEAR',
        fields=['SrcIP', 'AlertID'], # SrcIP and AlertID are not queried by default
        filters=[
                FieldFilter('DstIP', ['0.0.0.0/0',]),
                FieldFilter('HostID', ['mail'], operator='CONTAINS')], # Replace "mail" by a test hostname
        order=(('ASCENDING', 'AlertID')),
        limit=10) # Should be increased to 500 or 1000 once finish testing for better performance
events.load_data()
print(events)
print(events.get_text(fields=['AlertID','LastTime','SrcIP', 'Rule.msg']))
Note:
You can dump full list of fields usable in query FieldFilter with dump_all_fields.py script.
  • Add a note to events

Set the note of some events and check if the note is well set.

from  msiempy import EventManager, Event
events = EventManager(
        time_range='CURRENT_YEAR',
        limit=2 )
events.load_data()
for event in events :
        event.set_note("Test note")
        event.refresh(use_query=False) # Event data will be loaded with ipsGetAlertData API method
        assert "Test note" in genuine_event['note'], "Error, the note hasn't been added"
See:
  • add_wpsan_note.py script for more on how to add notes to event that triggered alarms.
See:
Objects Event and FieldFilter
Class Variable POSSBILE_ROW_ORDER "ASCENDING" or "DESCENDING"
Method __init__ Create a new event query.
Instance Variable fields List of query fields
Instance Variable limit Maximum number of rows per query.
Instance Variable order The order is a tuple (direction, field). Default value is ("DESCENDING", "LastTime").
Method clear_filters Replace all filters by a non filtering rule. Acts like there is not filters.
Method load_data Load the events data into the list. Wraps around msiempy.event.EventManager._qry_load_data.
Instance Variable data Undocumented
Method get_possible_fields Return the list of possible fields that you can request in a Events query. The list is loaded from the SIEM.
Method get_possible_filters Return the list of possible fields that you can use as a filter in a query. The list is loaded from the SIEM.
Class Variable _GROUPTYPE NO_GROUP: EventManager handles only events see GroupedEventManager for grouped queries
Instance Variable _parent Undocumented
Method _get_order Undocumented
Method _set_order Undocumented
Instance Variable _order_direction Undocumented
Instance Variable _order_field Undocumented
Instance Variable _filters Undocumented
Method _qry_load_data No summary
Method _root_parent Internal method that return the first query of the query tree.

Inherited from _QueryExecuteManager:

Method add_filter Add a filter to the query.
Static Method get_field_nickname Resolve SIEM events field nickname base on Event.SIEM_FIELDS_MAP_INTERNAL_NAME_TO_NICKNAME mapping. Returns the valid query field nickname if found else the initial value.
Class Variable _TYPE EVENT: Flow queries are not implemented (yet)
Method _get_filters Returns SIEM formatted filters for the query structured from msiempy.event.GroupFilter and/or msiempy.event.FieldFilter See msiempy.core.query.FilteredQueryList.filters.
Method _close_query Close the query
Method _wait_for Wait and sleep for the query.
Method _get_events Internal method that will get the query events. Called by _qry_load_data. By default, numRows correspond to limit.

Inherited from FilteredQueryList (via _QueryExecuteManager):

Instance Variable not_completed Boolean signals the query is not completed
Instance Variable filters Query filters
Instance Variable start_time Start time of the query in the right SIEM format.
Instance Variable end_time End time of the query in the right SIEM format.
Instance Variable time_range Query time range. Defaults to "CURRENT_DAY".
Class Variable DEFAULT_TIME_RANGE Default time range : "CURRENT_DAY"
Class Variable POSSIBLE_TIME_RANGE No summary
Instance Variable _time_range Undocumented
Instance Variable _start_time Undocumented
Instance Variable _end_time Undocumented
Method _get_time_range Undocumented
Method _set_time_range Undocumented
Method _get_start_time Undocumented
Method _set_start_time Undocumented
Method _get_end_time Undocumented
Method _set_end_time Undocumented
Method _set_filters Undocumented

Inherited from NitroList (via _QueryExecuteManager, FilteredQueryList):

Method __str__ str(obj) -> return text string.
Method keys List items keys. Every items should have the same set of keys.
Method get_text Return a csv or table string representation of the list
Method text Defaut table string, a shorcut to get_text() with no arguments.
Method json JSON list of dicts representing the list.
Method search Search elements in the list with a regex pattern
Method refresh Execute refresh function on all items.
Method perform Wrapper to execute a function on the list of elements
Static Method _confirm_func Ask user inut to confirm the calling of func on elements.

Inherited from NitroObject (via _QueryExecuteManager, FilteredQueryList, NitroList):

Class NitroJSONEncoder Custom JSON encoder that will use the approprtiate propertie depending of the type of NitroObject. TODO support json json dumping of QueryFilers, may be by making them inherits from NitroDict.
Instance Variable nitro msiempy.core.session.NitroSession object. Interface to the SIEM.
_GROUPTYPE = (source)
NO_GROUP: EventManager handles only events see GroupedEventManager for grouped queries
(type: str)
POSSBILE_ROW_ORDER = (source)
"ASCENDING" or "DESCENDING"
(type: List[str])
def __init__(self, *args, **kwargs): (source)
overrides msiempy.event._QueryExecuteManager.__init__

Create a new event query.

Arguments:
  • fields (list[str]): Query fields
  • order (tuple(direction, field)): Query order direction and field. Direction can be "ASCENDING" or "DESCENDING".
  • limit (int): Max number of rows per query result.
  • filters (list[tuple(field, [values]) or FieldFilter or GroupFilter]): Query filters
  • time_range (str): Query time range. No need to specify "CUSTOM" if start_time and end_time are set.
  • start_time (str or datetime): Query start time
  • end_time (str or datetime): Query end time
Note:
Some minimal fields will always be present. Get the list of possible fields with EventManager.get_possible_fields
See:
Event
_parent = (source)
Undocumented
fields = (source)
List of query fields
limit = (source)
Maximum number of rows per query.
order = (source)
The order is a tuple (direction, field). Default value is ("DESCENDING", "LastTime").
def _get_order(self): (source)
Undocumented
def _set_order(self, order): (source)
Undocumented
_order_direction = (source)
Undocumented
(type: str)
_order_field = (source)
Undocumented
(type: str)
def clear_filters(self): (source)
overrides msiempy.core.query.FilteredQueryList.clear_filters
Replace all filters by a non filtering rule. Acts like there is not filters.
_filters = (source)
overrides msiempy.event._QueryExecuteManager._filters
Undocumented
(type: List[Dict])
def _qry_load_data(self, retry=1, wait_timeout_sec=120): (source)
overrides msiempy.core.query.FilteredQueryList._qry_load_data
Internal helper method to execute the query and load the data:
  • Submit the query
  • Wait the query to be executed
  • Get and parse the events
Arguments:
  • retry (int): number of time the query can be failed and retried. (Default value = 1)
  • wait_timeout_sec (int): wait timeout in seconds. (Default value = 120)
Returns:
tuple: ( msiempy.event.EventManager, Query completed? bool )
Raises:
def load_data(self, workers=10, slots=10, delta=None, max_query_depth=0, **kwargs): (source)
overrides msiempy.core.query.FilteredQueryList.load_data

Load the events data into the list. Wraps around msiempy.event.EventManager._qry_load_data.

Arguments:
  • max_query_depth (int): Maximum number of reccursive divisions load_data method can apply to the query in order to load all events. Splits the query in differents time slots if the query apprears not to be completed. Only works with custom times and some time ranges.
    If EventManager.limit=500, slots=10 and max_query_depth=2, then the maximum capacity of the list is (500*10)*(500*10) = 25000000 (instead of 500 with max_query_depth=0).
  • slots (int): number of time slots the query can be divided. Loading bar is divided according to the number of slots. Applicable if max_query_depth>0.
  • delta (str): exemple : '2h', the query will be firstly divided in chuncks according to the time delta read with dateutil. Applicable if max_query_depth>0.
  • workers (int): numbre of parrallels tasks, should be equal or less than the number of slots. Applicable if max_query_depth>0.
  • retry (int): number of time the query can be failed and retried. (Default value = 1)
  • wait_timeout_sec (int): wait timeout in seconds. (Default value = 120)
Returns:
msiempy.event.EventManager
Note:
Only the first query is loaded asynchronously.
data = (source)
overrides msiempy.core.types.NitroList.data
Undocumented
@property
def _root_parent(self): (source)
Internal method that return the first query of the query tree.
def get_possible_fields(self): (source)
Return the list of possible fields that you can request in a Events query. The list is loaded from the SIEM.
def get_possible_filters(self): (source)
Return the list of possible fields that you can use as a filter in a query. The list is loaded from the SIEM.
API Documentation for msiempy, generated by pydoctor 20.7.1 at 2020-11-18 14:02:21.