McAfee SIEM API Python wrapper
Project description
McAfee SIEM API Python wrapper
This module aims to provide a basic API wrapper around the McAfee SIEM API to help make it more accessible and pythonic.
This python module is currently experimental
Main features
- ESM monitoring
- Datasource operations : add, edit, delete - including client datasources (work in progress)
- Alarm operations and querying : filter, [un]acknowledge, delete, get triggering event(s)
- Event querying and builtin workaround SIEM query
limit
- Watchlist operations : list watchlists, add values (work in progress)
- Single stable session handler and built-in asynchronous jobs
Known module implementations
- esm_healthmon : Monitors ESM operations (CLI)
- msiem : Query and manage ESM alarms (CLI)
- See samples folder for other implementation examples and scripts !
Documentation and links
- Module documentation
- Class diagram
- McAfee SIEM API documentation : https://HOST/rs/esm/help
Installation
pip install msiempy
Authentication and configuration setup
The module offers a single point of authentication against your SIEM, so you don't have to worry about authentication when writting your scripts. This means that you need to preconfigure the authentication using the configuration file.
The configuration file is located (by default) securely in your user directory since it contains credentials.
- For Windows:
%APPDATA%\.msiem\conf.ini
- For Mac :
$HOME/.msiem/conf.ini
- For Linux :
$XDG_CONFIG_HOME/.msiem/conf.ini
or :$HOME/.msiem/conf.ini
[esm]
host = HOST
user = USER
passwd = PASSWORD's BASE64
[general]
verbose = yes
quiet = no
logfile = /var/log/msiempy/log.txt
timeout = 30
ssl_verify = no
output = text
To set the password, you can edit the configuration dynamically with python.
>>> from msiempy import NitroConfig
>>> config=NitroConfig()
>>> config.iset('esm')
Enter [esm]host. Press <Enter> to keep empty: <type here>
Enter [esm]user. Press <Enter> to keep empty: <type here>
Enter [esm]passwd. Press <Enter> to skip: <type here>
>>> config.iset('general') [...]
>>> print(config)
Configuration file : /Users/username/.msiem/conf.ini
{'esm': {'host': '***', 'user': '***', 'passwd': '***=='}, 'general': {'verbose': 'no', 'quiet': 'no', 'logfile': '', 'timeout': '60', 'ssl_verify': 'no', 'output': 'text'}}
>>>config.write()
You can also directly paste the password's base64 in the config file by doing
>>> import base64
>>> passwd = 'P@assW0rd'
>>> print(base64.b64encode(passwd.encode('utf-8')).decode())
UEBhc3NXMHJk
Examples
See examples.py and all the samples folder for more detailed uses !
For further informations, please visit the module documentation ! :)
Alarm
Print all unacknowledged
alarms of the year who's name match 'IPS alarm'
and triggering event message match 'Wordpress'
. Then load the genuine Event
objects (from the query module) that triggered the alarms and print all of their JSON representations.
The number of alarms retreived is defined by the page_size
property.
from msiempy.alarm import AlarmManager
alarms=AlarmManager(
time_range='CURRENT_YEAR',
status_filter='unacknowledged',
filters=[
('alarmName', 'IPS alarm')],
event_filters=[
('ruleMessage','Wordpress')],
page_size=400)
alarms.load_data()
print(alarms.json)
See: FilteredQueryList, AlarmManager, Alarm
Event
Query events according to destination IP and hostname filters, load the data with comprensive parralel tasks working around the SIEM query limit
and printing selected data fields.
from msiempy.event import EventManager, FieldFilter
events = EventManager(
time_range='LAST_3_DAYS',
fields=['Alert.SrcIP', 'DSID'], # Alert.SrcIP is not queried by default # DSID is the event's datasource ID
filters=[
FieldFilter('DstIP', ['8.8.0.0/8',]),
FieldFilter('HostID', ['mydomain.local'], operator='CONTAINS') ],
limit=400)
events.load_data()
print(events.get_text(fields=['Alert.LastTime','Alert.SrcIP', 'Rule.msg']))
See: FilteredQueryList, EventManager, FieldFilter, Event
EventManager
__init__()
can take other parameter like order
or max_query_depth
. max_query_depth
parameter specify the number of sub-divisions the query can take at most (zero by default). The query is divided only if it hasn't completed with the current query settings.
load_data()
method accept also several parameters. It controls the query's division time range into slots of delta
duration, then the query would be divided into the specified number of slots
. Control also the number of asyncronous jobs using workers
parameter. See module documentation for more infos.
See filters list you can use to filter events.
See fields list you can request.
ESM
Print a few esm infos. This is still work in progress.
>>> import msiempy.device
>>> esm=msiempy.device.ESM()
>>> esm.version()
'11.2.1'
>>> esm.recs()
[('ERC-1', 144116287587483648)]
>>> esm.buildstamp()
'11.2.1 20190725050014'
See: ESM
Datasource
Load all datasources. This is still work in progress.
import msiempy.device
devtree = msiempy.device.DevTree()
See: DevTree, DataSource
Watchlist
Print whatchlist list. This is still work in progress.
import msiempy.watchlist
watchlists=msiempy.watchlist.WatchlistManager()
print(watchlists)
See: WatchlistManager, Watchlist
Questions ?
If you have any questions, please create a new issue.
Contribute
If you like the project and think you could help with making it better, there are many ways you can do it:
- Create new issue for new feature proposal or a bug
- Implement existing issues
- Help with improving the documentation
- Spread a word about the project to your collegues, friends, blogs or any other channels
- Any other things you could imagine
- Any contribution would be of great help and I will highly appreciate it!
Run tests
./setup.py test
Error report
Configure log file reporting in the configuration file and execute :
cat /path/to/your/log/file | cut -c 25-500 | grep -i error | sort | uniq
Disclaimer
This is an UNOFFICIAL project and is NOT sponsored or supported by McAfee, Inc. If you accidentally delete all of your datasources, don't call support (or me). Product access will always be in respect to McAfee's intellectual property.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for msiempy-0.1.20.dev0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 64320e644f0c9158a8468f99377bf9cd5d30c2fe4e173af12d229945a54ecf3e |
|
MD5 | 79b69d41bd91483215c314211c172be1 |
|
BLAKE2b-256 | 43263a8393730c0a79ef5245fb0daa5c8c9d1111074c1b96195c125f571668e6 |