Metadata-Version: 1.1
Name: mozdef-client
Version: 1.0.4
Summary: A client library to send messages/events using MozDef
Home-page: https://github.com/gdestuynder/mozdef_client
Author: Guillaume Destuynder
Author-email: gdestuynder@mozilla.com
License: MPL
Description: mozdef_client
        =============
        
        mozdef_client is a Python library for sending event information from Python
        software to `MozDef`_.
        
        .. _MozDef: https://github.com/jeffbryner/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`_.
        
        .. _mozdef_lib: https://github.com/gdestuynder/mozdef_lib/
        
        Installation
        ------------
        
        As a Python Module
        ~~~~~~~~~~~~~~~~~~
        
        To install mozdef_client as a module using setup.py, the following
        can be used.
        
        .. code::
        
            make install
        
        Or, to create an RPM/debian package and install that package:
        
        .. code::
        
           make rpm
           make deb
           rpm -i <package.rpm>
           dpkg -i <package.deb>
        
        As a Submodule
        ~~~~~~~~~~~~~~
        
        Add to your project with:
        
        .. code::
        
           git submodule add https://github.com/gdestuynder/mozdef_client
           git commit -a
        
        Python Dependencies
        ~~~~~~~~~~~~~~~~~~~
        
        - requests_futures (Optional but recommended, otherwise events are synchronous)
        - pytz
        
        Usage
        -----
        
        The following is an example for submitting generic MozDef events.
        
        .. code::
        
           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.
        
        .. code::
        
           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()
        
        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.
        
        .. code::
        
           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.
        
        .. code::
        
           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.
        
        .. code::
        
           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().
        
        
Keywords: mozdef client library
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Topic :: System :: Logging
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Requires: requests_futures
Requires: pytz
