Metadata-Version: 2.1
Name: c42eventextractor
Version: 0.1.3
Summary: Utilities to extract and record Code42 security events
Home-page: UNKNOWN
License: MIT
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Python: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, <4
Description-Content-Type: text/markdown
Requires-Dist: py42 (==0.4.4)
Provides-Extra: dev
Requires-Dist: pre-commit ; extra == 'dev'
Requires-Dist: pytest (==4.6.5) ; extra == 'dev'
Requires-Dist: pytest-cov (==2.8.1) ; extra == 'dev'
Requires-Dist: pytest-mock (==2.0.0) ; extra == 'dev'
Requires-Dist: tox (==3.14.3) ; extra == 'dev'

# c42eventextractor - Utilities to extract and record Code42 security events

[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

The `c42eventextractor` package provides modules that assist in the retrieval and logging of Code42 security events.
This is done by exposing handlers that allow developers to supply custom behaviors to occur when events are retrieved.
By default, the extractors will simply print their results to stdout, but these handlers can be extended to allow developers
to record the event info to whatever location or format they desire.

## Requirements

- Python 2.7.x or 3.5.0+
- Code42 Server 6.8.x+

## Installation

Once you've done that, install `c42eventextractor` using:

```bash
$ python setup.py install
```

## Usage - AED

To get all security events within the last default look-back days (60 days):

```python
from c42eventextractor.extractors import AEDEventExtractor
from c42eventextractor.common import FileEventHandlers
from py42.sdk import SDK

code42 = SDK.create_using_local_account(
    "https://example.authority.com",
    "admin@example.com",
    "password",
)

handlers = FileEventHandlers()

# Add implementations for customizing handling response and getting/setting insertion timestamp cursors:
def handle_response(response):
    pass

def record_cursor_position(cursor):
    pass

def get_cursor_position():
    pass

handlers.handle_response = handle_response
handlers.record_cursor_position = record_cursor_position
handlers.get_cursor_position = get_cursor_position

aed_extractor = AEDEventExtractor(code42, handlers)
aed_extractor.extract()

# To get all security events in a particular time range, provide an `initial_min_timestamp` and optionally a `max_timestamp`.
# Note that the `initial_min_timestamp` is only for the initial run if you implement `record_cursor_position` and `get_cursor_position`.
# The extractor uses a default min timestamp from 60 days ago if nothing is passed in.
# The max timestamp defaults to the present time if you do not supply a `max_timestamp`.

aed_extractor.extract(1564694804)
aed_extractor.extract(initial_min_timestamp=1564694804, max_timestamp=1564699999)

# Pass in an iterable to specify the exposure types you seek.
# Choices are "SharedViaLink", "SharedToDomain", "ApplicationRead", "CloudStorage", "RemovableMedia", and "IsPublic".

aed_extractor.extract(exposure_types=["CloudStorage", "RemovableMedia"])
```

`c42eventextractor` provides some common logging and formatting implementations that you may find useful for reporting on this data.
For example, to submit each event to a syslog server in CEF format, try using the below as your `handle_response` implementation:

```python
import json
import logging
from c42eventextractor.logging.handlers import NoPrioritySysLogHandler
from c42secevents.logging.formatters import AEDDictToCEFFormatter

my_logger = logging.getLogger("MY_LOGGER")
handler = NoPrioritySysLogHandler("examplehostname.com")
handler.setFormatter((AEDDictToCEFFormatter()))
my_logger.addHandler(handler)
my_logger.setLevel(logging.INFO)

def handle_response(response):
    events = json.loads(response.text)["fileEvents"]
    for event in events:
        my_logger.info(event)
```


