initial yara dispatcher plugins

yara_dispatcher.py

#!/usr/bin/env python3

#   Copyright 2014-2017 PUNCH Cyber Analytics Group
#
#   Licensed under the Apache License, Version 2.0 (the "License");
#   you may not use this file except in compliance with the License.
#   You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
#   Unless required by applicable law or agreed to in writing, software
#   distributed under the License is distributed on an "AS IS" BASIS,
#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#   See the License for the specific language governing permissions and
#   limitations under the License.

from configparser import ConfigParser
import os
from typing import Dict, List, Optional, Iterator

import yara

from stoq.data_classes import Payload, DispatcherResponse, RequestMeta
from stoq.plugins import DispatcherPlugin
from stoq.stoq_exception import StoqException


class YaraDispatcher(DispatcherPlugin):

    def __init__(self, config: ConfigParser,
                 plugin_opts: Optional[Dict]) -> None:
        super().__init__(config, plugin_opts)

        self.dispatch_rules = None
        if plugin_opts and "dispatch_rules" in plugin_opts:
            self.set_rules_path(plugin_opts["dispatch_rules"])
        elif config.has_option("options", "dispatch_rules"):
            self.set_rules_path(config.get("options", "dispatch_rules"))
        else:
            raise StoqException("No dispatch rules provided")

    def set_rules_path(self, filepath: str) -> None:
        filepath = os.path.realpath(filepath)
        if not os.path.isfile(filepath):
            raise StoqException(f"Failed to load dispatch rules: {filepath}")
        else:
            self.dispatch_rules = yara.compile(filepath=filepath)

    def dispatch(self, payload: Payload,
            request_meta: RequestMeta) -> Iterator[DispatcherResponse]:
        for match in self._yara_dispatch_matches(payload.content):
            if 'plugin' in match['meta']:
                plugin_str = match['meta']['plugin'].lower().strip()
                plugin_names = {
                    p.strip()
                    for p in plugin_str.split(',') if p.strip()
                }
                for name in plugin_names:
                    if name:
                        if match['meta'].get('save', '').lower().strip() == 'false':
                            payload.payload_meta.should_archive = False
                        yield DispatcherResponse(
                            plugin_name=name.strip(),
                            meta=match
                        )

    def _yara_dispatch_matches(self, content: bytes) -> List[Dict]:
        if self.dispatch_rules is None:
            return []
        matches = self.dispatch_rules.match(data=content, timeout=60)
        dict_matches = []
        for match in matches:
            dict_matches.append({
                'tags': match.tags,
                'namespace': match.namespace,
                'rule': match.rule,
                'meta': match.meta,
                'strings': match.strings,
            })
        return dict_matches

yara_dispatcher.stoq

#   Copyright 2014-2015 PUNCH Cyber Analytics Group
#
#   Licensed under the Apache License, Version 2.0 (the "License");
#   you may not use this file except in compliance with the License.
#   You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
#   Unless required by applicable law or agreed to in writing, software
#   distributed under the License is distributed on an "AS IS" BASIS,
#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#   See the License for the specific language governing permissions and
#   limitations under the License.

[Core]
Name = yara_dispatcher
Module = yara_dispatcher

[Documentation]
Author = Marcus LaFerrera
Version = 0.1
Website = https://github.com/PUNCH-Cyber/stoq-plugins-public
Description = yara stoQ dispatcher plugin

[options]
dispatch_rules = plugins/dispatcher/yara/dispatcher.yar