msiempy.DevTree

class documentation

class msiempy.DevTree(NitroList): (source)

View In Hierarchy

List-Like object. ESM device tree interface.

  • __contains__ method returns: (bool) True/None the name or IP matches the provided search term.
Exemples:
  • List Datasources
>>> from msiempy.device import DevTree
>>> devtree = DevTree()
>>> print("All Datasources")
>>> print(devtree.get_text(fields=["parent_name", "name", "ds_id"]))

The script all_dev.py can help you list all your datasources.

  • Add a Datasource
>>> from msiempy import DevTree
>>> devtree = DevTree()
>>> devtree.add({
...     "name": "Test DS",
...     "parent_id": "144116287587483648",
...     "ds_ip": "10.2.2.2",
...     "hostname": "testds.domain.ca",
...     "type_id": "65" })
{'value': 1385420} # Wait a bit for the request
>>> devtree.refresh() # Refresh the DevTree
See:
Object DataSource
Note:
Uses internal API methods such as GRP_GETVIRTUALGROUPIPSLISTDATA to assemble DevTree object.
Method __init__ Create a new list
Instance Variable data Undocumented
Method __contains__ Returns: (bool) True/None the name or IP matches the provided search term.
Method search Search a datasource in the DevTree.
Method search_ds_group Search datasources in the DevTree.
Method refresh Rebuilds the devtree
Method recs Returns: list of Receiver dict
Method build_devtree Coordinates assembly of the devtree object
Method duplicate_datasource Check for duplicate dataname name or IP address.
Method add Adds a datasource.
Method add_client Add a datasource client
Method _get_devtree Returns: ESM device tree; raw, but ordered, string.
Method _format_devtree Parse key fields from raw device strings into datasource dicts.
Method _insert_rec_info Adds parent_ids to datasources in the tree based upon the ordered list provided by the ESM. All the datasources below a Receiver row have it's id set as their parent ID.
Method _get_client_containers Filters DevTree for datasources that have client datasources.
Method _merge_clients Undocumented
Method _get_clients Get list of raw client strings.
Method _format_clients Parse key fields from _get_clients() output. Returns: list of dicts
Method _get_zonetree Retrieve zone data.
Method _insert_zone_names Arguments: - zonetree (str): Built by self._get_zonetree
Method _get_zone_map Builds a table of zone names to zone ids. Returns: dict (str: str) zone name : zone ids
Method _insert_zone_ids Undocumented
Method _get_last_times Returns: string with datasource names and last event times.
Method _format_times Formats the output of _get_last_times
Method _insert_ds_last_times Parse event times str and insert it into the _devtree
Method _filter_bogus_ds Filters objects that inaccurately show up as datasources sometimes.
Method _cast_datasources Undocumented
Method _validate_ds_params Validate parameters for new datasource.
Method _validate_ds_tz_id Validates datasource time zone id.
Static Method _normalize_bool_vals Recursively changes strings 'T', 'F' to bool

Inherited from NitroList:

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 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 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.
def __init__(self, *args, **kwargs): (source)
overrides msiempy.core.types.NitroList.__init__

Create a new list

Arguments:
  • alist: list object to wrap.
data = (source)
overrides msiempy.core.types.NitroList.data
Undocumented
(type: List)
def __contains__(self, term): (source)
Returns: (bool) True/None the name or IP matches the provided search term.
def search(self, term, zone_id="""0"""): (source)
overrides msiempy.core.types.NitroList.search

Search a datasource in the DevTree.

Arguments:
  • term (str): Datasource name, IP, hostname or ds_id. Matching the name, IPv4/IPv6 address, hostname or device ID.
  • zone_id (int): Provide zone_id to limit search to a specific zone
Returns:
Datasource object that matches the provided search term or None.
def search_ds_group(self, field, term, zone_id="""0"""): (source)

Search datasources in the DevTree.

Arguments:
  • field (str): Valid DS config field to search
  • term (str): Data to search for in specified field
Valid field options include:
  • parent_id = '144119615532826624'
  • type_id = '65'
  • vendor = 'Intersect Alliance'
  • model = 'Snare for Windows'
  • require_tls = 'T'
  • port = '514'
  • tz_id = '51'
  • tz_name = 'Darwin'
  • zone_id = '7'
Returns:
generator (list) containing any matching DataSource objects or None.
NOTE:
Result must be iterated through.
Raises:
ValueError: if field or term are None
def refresh(self): (source)
overrides msiempy.core.types.NitroList.refresh
Rebuilds the devtree
def recs(self): (source)
Returns:
list of Receiver dict
def build_devtree(self): (source)
Coordinates assembly of the devtree object
def _get_devtree(self): (source)
Returns:
ESM device tree; raw, but ordered, string.

Does not include client datasources.

def _format_devtree(self, devtree): (source)

Parse key fields from raw device strings into datasource dicts.

Returns:
List of datasource dicts
def _insert_rec_info(self, devtree): (source)

Adds parent_ids to datasources in the tree based upon the ordered list provided by the ESM. All the datasources below a Receiver row have it's id set as their parent ID.

Returns:
List of datasource dicts
def _get_client_containers(self, devtree): (source)

Filters DevTree for datasources that have client datasources.

Returns:
List of datasource dicts that have clients
def _merge_clients(self, containers, devtree): (source)
Undocumented
def _get_clients(self, ds_id): (source)

Get list of raw client strings.

Arguments:
  • ds_id (str): Parent ds_id(s) are collected on init
  • ftoken (str): Set and used after requesting clients for ds_id
Returns:
List of strings representing unparsed client datasources
def _format_clients(self, clients): (source)
Parse key fields from _get_clients() output. Returns: list of dicts
def _get_zonetree(self): (source)

Retrieve zone data.

Returns:
str device tree string sorted by zones
def _insert_zone_names(self, zonetree, devtree): (source)
Arguments:
  • zonetree (str): Built by self._get_zonetree

Returns: List of dicts (str: str) devices by zone

def _get_zone_map(self): (source)
Builds a table of zone names to zone ids. Returns: dict (str: str) zone name : zone ids
def _insert_zone_ids(self, zone_map, devtree): (source)
Undocumented
def _get_last_times(self): (source)
Returns:
string with datasource names and last event times.
def _format_times(self, last_times): (source)

Formats the output of _get_last_times

Arguments:
  • last_times (str): string output from _get_last_times()
Returns:
list[dict]: [{'name', 'model', 'last_time'}]
def _insert_ds_last_times(self, last_times, devtree): (source)

Parse event times str and insert it into the _devtree

Returns:
List of datasource dicts - the devtree
def _filter_bogus_ds(self, devtree): (source)

Filters objects that inaccurately show up as datasources sometimes.

Arguments:
  • devtree (list): the devtree
def _cast_datasources(self): (source)
Undocumented
def duplicate_datasource(self, ds_params): (source)

Check for duplicate dataname name or IP address.

Arguments:
  • ds_params (dict) : datasource params
ds_params should contain following keys :
  • name (str): datasource name
  • ds_ip (str): datasource IP
  • zone_id (str): optional zone_id
def add(self, attr): (source)

Adds a datasource.

Arguments:
  • attr (dict): datasource attributes
attr can contain following keys :
  • client (bool): designate a client datasource (not child)
  • name (str): name of datasource (required)
  • parent_id (str): id of parent device (required)
  • ds_ip (str): ip of datasource (ip or hostname required)
  • hostname (str): hostname of datasource
  • type_id (str): type of datasource (required)
  • enabled (bool): enabled or not (default: True)
  • tz_id (str): timezone of datasource (default UTC: 8)
  • zone_id (str): numberic ESM id for zone (default: 0) Examples (tz_id only): PST: 27, MST: 12, CST: 11, EST: 32
  • require_tls (bool): datasource uses syslog tls
Returns:
result id (str): id of the result. Not the ds_id as of 11.2.1 or None on Error
Note:
DevTree.add do not ensure the Datasource is well added. There is place for improvment: #82.
def add_client(self, attr): (source)

Add a datasource client

Arguments:
  • attr (dict) : datasource attributes
attr can contain following keys :
  • parent_id (str): datasource id of the client group datasource (required)
  • name (str): name of the client (required)
  • enabled (bool): enabled or not (default: True)
  • ds_ip (str): IP address for client (ip or hostname required)
  • hostname (str): hostname for client
  • type_id (str): numeric ESM type-id (required)
  • tz_id (str): numeric ESM timezone id or GMT
  • dorder (str): Date order
  • maskflag (str):
  • port (str): IP port to use
  • require_tls (bool): use syslog-TLS (default: False)
Returns:
result id (str) or None on Error
def _validate_ds_params(self, p): (source)

Validate parameters for new datasource.

Arguments:
  • p (dict) : datasource parameters
Returns:
datasource dict with normalized values or False if something is invalid.
def _validate_ds_tz_id(self, p): (source)

Validates datasource time zone id.

Arguments:
  • p (dict): datasource param
Returns:
dict of datasource params or None if invalid
@staticmethod
def _normalize_bool_vals(d): (source)

Recursively changes strings 'T', 'F' to bool

Arguments:
  • d (dict) : nested dicts and lists okay
API Documentation for msiempy, generated by pydoctor 20.7.1 at 2020-11-18 14:02:21.