mozdef-client 1.0.8

A client library to send messages/events using MozDef

mozdef_client is a Python library for sending event information from Python software to MozDef.

This library performs functions such as message preformatting and validation, in addition to actually POSTing the events to MozDef using the provided event collection URL.

The library supports submission of the following MozDef event types, with more to be added in the future.

• Generic Events

• Compliance Events

• Vulnerability Events

• Asset Hint Events

This library was previously known as mozdef_lib, but was renamed for clarity. The previous version of the library can be found at mozdef_lib.

Installation

As a Python Module

To install mozdef_client as a module using setup.py, the following can be used.

make install

Or, to create an RPM/debian package and install that package:

make rpm
make deb
rpm -i <package.rpm>
dpkg -i <package.deb>

As a Submodule

Add to your project with:

git submodule add https://github.com/gdestuynder/mozdef_client
git commit -a

Python Dependencies

• requests_futures (Optional but recommended, otherwise events are synchronous)

• pytz

• boto3 (for AWS support)

Usage

The following is an example for submitting generic MozDef events.

import mozdef_client
msg = mozdef_client.MozDefEvent('https://127.0.0.1:8443/events')
msg.summary = 'a test message'
msg.tags = ['tag1', 'tag2']
msg.details = {'hostname': 'test', 'alert': True}
msg.send()

It is also possible to additionally send the message to syslog, in this case it will be flattened.

msg.set_send_to_syslog(True)
msg.send()

# Or optionally, if you only want to send to syslog.
msg.set_send_to_syslog(True, only_syslog=True)
msg.send()

And here’s how you send to an Sqs queue in AWS. Note that the URL is ignored for compatibility purposes.

msg.set_send_to_sqs(True)
msg.set_sqs_queue_name('my_queue')
msg.set_sqs_region('us-west-1')
# Note that unlike syslog this will NEVER send to MozDef HTTP (URL is ignored)
msg.send()

Compliance events (MozDefCompliance()) are sent the same way as generic events. Typically details and tags will be set. Details must adhere to the compliance event format or validation will fail.

Vulnerability events are submitted by setting the log attribute of the object to a dict representing the event. This dict is converted in it’s entirety to the event. The following is an example for vulnerability events.

import mozdef_client
msg = mozdef_client.MozDefVulnerability('https://127.0.0.1:8443/compliance')
msg.log = vuln_msg
msg.send()

Hint events operate like generic events, but set some default fields for you.

import mozdef_client
msg = mozdef_client.MozDefAssetHint('https://127.0.0.1:8443/events')
msg.summary = 'new host detected'
msg.details = {'hostname': 'test'}
msg.send()

With generic event messages, the summary field is the only mandatory field that must be set on the event before submission. Compliance and vulnerability events have a specific format and require a number of default fields to exist before submission. The validation functions in the library will raise a MozDefError exception if an error condition occurs (such as submission of an invalid message).

With a generic event message, the members of the object you will generally modify before calling send() include:

• .details (dict)

• .summary (string)

• .tags (list)

Also, for event messages the set_severity() and set_category() methods can be used to change the message severity and category. The category argument is a string value, the severity can be one of the following.

• MozDefEvent.SEVERITY_INFO

• MozDefEvent.SEVERITY_WARNING

• MozDefEvent.SEVERITY_CRITICAL

• MozDefEvent.SEVERITY_ERROR

• MozDefEvent.SEVERITY_DEBUG

With compliance and vulnerability events, you will generally operate on the .log member of the object, which is a dict.

Notes on Syslog Compatibility

When using the syslog compatibility mode, the JSON message is flattened into a single line. The severity associated with the message will also be converted into a syslog severity when the message is sent to syslog.

import mozdef_client
msg = mozdef_client.MozDefEvent('https://127.0.0.1:8443/events')
msg.summary = 'a test event'
msg.tags = ['generic', 'test']
msg.details = {'one': 1, 'two': 'two'}
msg.set_severity(MozDefEvent.SEVERITY_CRIT)
msg.set_send_to_syslog(True, only_syslog=True)
msg.send()

Mar  6 09:05:48 hostname mozdef_client.py: {"category": "event", "processid": 8095, "severity": "CRIT", "tags": ["generic", "test"], "timestamp": "2015-03-06T15:05:48.226939+00:00", "hostname": "hostname", "summary": "a test event", "processname": "mozdef_client.py", "details": {"two": "two", "one": 1}}

Certificate Handling

During testing with self-signed certificates, it may be useful to not validate certificates. Certificate validation should be enabled in production; this can be done by calling the set_verify() method on the event with a boolean argument.

Certificates are validated using the default certificate path on the system. If you want to specify a certificate to use, pass it with the set_verify_path() method on the event object before calling send().