Python Module

Use the Sublime Python module to analyze email messages programmatically from any system.

Installation

Install the CLI:

pip3 install sublime-cli --upgrade

Analyze a message

See the Helper functions for how to load raw messages, rules, and queries. Optionally configure your free API key for unlimited requests.

Analyze raw messages (EML and MSG files)

def analyze_raw_message(self, raw_message, rules, queries, mailbox_email_address=None, message_type=None):
    """Analyze a raw message against a list of rules or queries.

    :param raw_message: Base64 encoded raw message
    :type raw_message: str
    :param rules: Rules to run
    :type rules: list
    :param queries: Queries to run
    :type queries: list
    :param mailbox_email_address: Email address of the mailbox
    :type mailbox_email_address: str
    :param message_type: The type of message from the perspective of your organization (inbound, internal, outbound)
    :type message_type: str
    :rtype: dict

    """

Sample code

import sublime

API_KEY = "" # (optional) put your API key here
sublime_client = sublime.Sublime(api_key=API_KEY)

# load raw messages (EMLs, MSGs)
raw_message_eml = sublime.util.load_eml("path/to/file.eml")
raw_message_msg = sublime.util.load_msg("path/to/file.msg")

# load rules and queries
rules, queries = sublime.util.load_yml_path("sublime-rules/")

# analyze
response = sublime_client.analyze_raw_message(raw_message_eml, rules, queries)

Analyze Message Data Models

If you already have a message data model, you can analyze it using this function:

def analyze_message(self, message_data_model, rules, queries):
    """Analyze a Message Data Model against a list of rules or queries.

    :param message_data_model: Message Data Model
    :type message_data_model: dict
    :param rules: Rules to run
    :type rules: list
    :param queries: Queries to run
    :type queries: list
    :rtype: dict

    """

Create an MDM

def create_message(self, raw_message, mailbox_email_address=None, message_type=None):
    """Create a Message Data Model from a raw message.

    :param raw_message: Base64 encoded raw message
    :type raw_message: str
    :param mailbox_email_address: Email address of the mailbox
    :type mailbox_email_address: str
    :param message_type: The type of message from the perspective of your organization (inbound, internal, outbound)
    :type message_type: str
    :rtype: dict
    
    """

Sample code

import sublime

API_KEY = "" # (optional) put your API key here
sublime_client = sublime.Sublime(api_key=API_KEY)

# load raw messages (EMLs, MSGs)
raw_message_eml = sublime.util.load_eml("path/to/file.eml")
raw_message_msg = sublime.util.load_msg("path/to/file.msg")

# create
response = sublime_client.create_message(raw_message_eml)

Helper functions

Load the helper functions:

from sublime.util import *
def load_eml(input_file):
    """Load .EML file.

    :param input_file: Path to file.
    :type input_file: str
    :returns: Base64-encoded raw content
    :rtype: string
    :raises: LoadEMLError

    """

def load_msg(input_file):
    """Load .MSG file.

    :param input_file: Path to file.
    :type input_file: str
    :returns: Base64-encoded raw content
    :rtype: string
    :raises: LoadMSGError

    """

def load_message_data_model(input_file):
    """Load Message Data Model file.

    :param input_file: Path to file.
    :type input_file: str
    :returns: Message Data Model JSON object
    :rtype: dict
    :raises: LoadMessageDataModelError

    """

def load_yml_path(files_path, ignore_errors=True):
    """Load rules and queries from a path.

    :param files_path: Path to YML files
    :type files_path: string
    :param ignore_errors: Ignore file loading errors
    :type ignore_errors: boolean
    :returns: A list of rules and a list of queries
    :rtype: list, list
    :raises: LoadRuleError

    """

def load_yml(yml_file, ignore_errors=True):
    """Load rules and queries from a file.

    :param yml_file: YML file
    :type yml_file: _io.TextIOWrapper
    :param ignore_errors: Ignore loading errors
    :type ignore_errors: boolean
    :returns: A list of rules and a list of queries
    :rtype: list, list
    :raises: LoadRuleError

    """

Updating

  1. View your current version:
sublime version
  1. Update your CLI:
pip3 install sublime-cli --upgrade
  1. Check your new version:
sublime version

Use your self-hosted Sublime deployment

๐Ÿ“˜

Early access

The Sublime Platform is currently in early access. You can request early access here.

By default, the Python module uses the Analysis API located at https://alpha.api.sublimesecurity.com. You can override this by setting the BASE_URL environment variable to the location of your Sublime deployment.

For example, for a local Docker deployment:

export BASE_URL=http://localhost:8000