code organization

Author: marpaia

osquery/__init__.py

@@ -0,0 +1,88 @@
+"""LICENSE file in the root directory of this source tree. An additional grant
+of patent rights can be found in the PATENTS file in the same directory.
+"""
+
+# pylint: disable=no-self-use
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import print_function
+from __future__ import unicode_literals
+
+from abc import ABCMeta, abstractmethod
+
+from osquery.extensions.ttypes import ExtensionResponse, ExtensionStatus
+from osquery.plugin import BasePlugin
+
+class ConfigPlugin(BasePlugin):
+    """All config plugins should inherit from ConfigPlugin"""
+    __metaclass__ = ABCMeta
+
+    def call(self, context):
+        """Internal routing for this plugin type.
+
+        Do not override this method.
+        """
+        if "action" in context:
+            if context["action"] == "genConfig":
+                return ExtensionResponse(status=ExtensionStatus(code=0,
+                                                                message="OK",),
+                                         response=self.content(),)
+
+        message = "Not a valid config plugin action"
+        return ExtensionResponse(status=ExtensionStatus(code=1,
+                                                        message=message,),
+                                 response=[],)
+
+    def registry_name(self):
+        """The name of the registry type for config plugins.
+
+        Do not override this method.
+        """
+        return "config"
+
+    @abstractmethod
+    def content(self):
+        """The implementation of your config plugin.
+
+        This should return a dictionary of the following format:
+
+            [
+                {
+                    "source_name_1": serialized_json_config_string_1,
+                    "source_name_2": serialized_json_config_string_2,
+                }
+            ]
+
+        Consider the following full example of the content method:
+
+            @osquery.register_plugin
+            class TestConfigPlugin(osquery.ConfigPlugin):
+                def name(self):
+                    return "test_config"
+
+                def content(self):
+                    return [
+                        {
+                            "source_one": json.dumps({
+                                "schedule": {
+                                    "time_1": {
+                                        "query": "select * from time",
+                                        "interval": 1,
+                                    },
+                                },
+                            }),
+                            "source_two": json.dumps({
+                                "schedule": {
+                                    "time_2": {
+                                        "query": "select * from time",
+                                        "interval": 2,
+                                    },
+                                },
+                            }),
+                        }
+                    ]
+
+        This must be implemented by your plugin.
+        """
+        raise NotImplementedError

osquery/config_plugin.py

@@ -0,0 +1,57 @@
+"""LICENSE file in the root directory of this source tree. An additional grant
+of patent rights can be found in the PATENTS file in the same directory.
+"""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import print_function
+from __future__ import unicode_literals
+
+try:
+    from thrift.transport import TSocket
+    from thrift.transport import TTransport
+    from thrift.protocol import TBinaryProtocol
+except ImportError:
+    print("Cannot import thrift: pip install thrift")
+    exit(1)
+
+from osquery.extensions.ExtensionManager import Client
+
+DEFAULT_SOCKET_PATH = "/var/osquery/osquery.em"
+"""The default path for osqueryd sockets"""
+
+class ExtensionClient(object):
+    """A client for connecting to an existing extension manager socket"""
+
+    _transport = None
+
+    def __init__(self, path=DEFAULT_SOCKET_PATH, uuid=None):
+        """
+        Keyword arguments:
+        path -- the path of the extension socket to connect to
+        uuid -- the additional UUID to use when constructing the socket path
+        """
+        self.path = path
+        if uuid:
+            self.path += ".%s" % str(uuid)
+        transport = TSocket.TSocket(unix_socket=self.path)
+        transport = TTransport.TBufferedTransport(transport)
+        self.protocol = TBinaryProtocol.TBinaryProtocol(transport)
+        self._transport = transport
+
+    def close(self):
+        """Close the extension client connection"""
+        if self._transport:
+            self._transport.close()
+
+    def open(self):
+        """Attempt to open the UNIX domain socket"""
+        self._transport.open()
+
+    def extension_manager_client(self):
+        """Return an extension manager (osquery core) client."""
+        return Client(self.protocol)
+
+    def extension_client(self):
+        """Return an extension (osquery extension) client."""
+        return Client(self.protocol)

osquery/extension_client.py

@@ -0,0 +1,105 @@
+"""LICENSE file in the root directory of this source tree. An additional grant
+of patent rights can be found in the PATENTS file in the same directory.
+"""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import print_function
+from __future__ import unicode_literals
+
+from osquery.extensions.Extension import Iface
+from osquery.extensions.ttypes import ExtensionResponse, ExtensionStatus
+from osquery.singleton import Singleton
+
+class ExtensionManager(Singleton, Iface):
+    """The thrift server for handling extension requests
+
+    An extension's manager is responsible for maintaining the state of
+    registered plugins, broadcasting the registry of those plugins to the
+    core's extension manager and fielding requests that come in on the
+    extension's socket.
+    """
+    _plugins = {}
+    _registry = {}
+
+    uuid = None
+
+    def add_plugin(self, plugin):
+        """Register a plugin with the extension manager. In order for the
+        extension manager to broadcast a plugin, it must be added using this
+        interface.
+
+        Keyword arguments:
+        plugin -- the plugin class to register
+        """
+
+        # First, we create an instance of the plugin. All plugins are
+        # singletons, so this instance will be long-lived.
+        obj = plugin()
+
+
+        # When the extension manager broadcasts it's registry to core's
+        # extension manager, the data structure should follow a specific
+        # format. Whenever we add a plugin, we need to update the internal
+        # _registry instance variable, which will be sent to core's extension
+        # manager once the extension has been started
+        if obj.registry_name() not in self._registry:
+            self._registry[obj.registry_name()] = {}
+        if obj.name() not in self._registry[obj.registry_name()]:
+            self._registry[obj.registry_name()][obj.name()] = obj.routes()
+
+        # The extension manager needs a way to route calls to the appropriate
+        # implementation class. We maintain references to the plugin's
+        # singleton instantiation in the _plugins instance variable. The
+        # _plugins member has the same general structure as _registry, but
+        # instead of pointing to the plugin's routes, it points to the plugin
+        # implementation object
+        if obj.registry_name() not in self._plugins:
+            self._plugins[obj.registry_name()] = {}
+        if obj.name() not in self._plugins[obj.registry_name()]:
+            self._plugins[obj.registry_name()][obj.name()] = obj
+
+    def registry(self):
+        """Accessor for the internal _registry member variable"""
+        return self._registry
+
+    def ping(self):
+        """Lightweight health verification
+
+        The core osquery extension manager will periodically "ping" each
+        extension that has connected to it to ensure that the extension is
+        still active and can field requests, if necessary.
+        """
+        return ExtensionStatus(code=0, message="OK")
+
+    def call(self, registry, item, request):
+        """The entry-point for plugin requests
+
+        When a plugin is accessed from another process, osquery core's
+        extension manager will send a thrift request to the implementing
+        extension manager's call method.
+
+        Arguments:
+        registry -- a string representing what registry is being accessed.
+            for config plugins this is "config", for table plugins this is
+            "table", etc.
+        item -- the registry item that is being requested. this is the "name"
+            of your plugin. for example, this would be the exact name of the
+            SQL table, if the plugin was a table plugin.
+        """
+
+        # this API only support plugins of the following types:
+        # - table
+        # - config
+        # - logger
+        if registry not in ["table", "config", "logger"]:
+            message = "A registry of an unknown type was called: %s" % registry
+            return ExtensionResponse(status=ExtensionStatus(code=1, message=message,),
+                                     response=[],)
+
+        try:
+            return self._plugins[registry][item].call(request)
+        except KeyError:
+            message = "Extension registry does not contain requested plugin"
+            return ExtensionResponse(status=ExtensionStatus(code=1, message=message,),
+                                     response=[],)

osquery/extension_manager.py

@@ -0,0 +1,93 @@
+"""LICENSE file in the root directory of this source tree. An additional grant
+of patent rights can be found in the PATENTS file in the same directory.
+"""
+
+# pylint: disable=no-self-use
+# pylint: disable=unused-argument
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import print_function
+from __future__ import unicode_literals
+
+from abc import ABCMeta, abstractmethod
+
+from osquery.extensions.ttypes import ExtensionResponse, ExtensionStatus
+from osquery.plugin import BasePlugin
+
+class LoggerPlugin(BasePlugin):
+    """All logger plugins should inherit from LoggerPlugin"""
+    __metaclass__ = ABCMeta
+
+    _use_glog_message = "Use Glog for status logging"
+    _invalid_action_message = "Not a valid logger plugin action"
+
+    def call(self, context):
+        """Internal routing for this plugin type.
+
+        Do not override this method.
+        """
+        if "string" in context:
+            return ExtensionResponse(status=self.log_string(context["string"]),
+                                     response=[],)
+        elif "snapshot" in context:
+            return ExtensionResponse(
+                status=self.log_snapshot(context["snapshot"]),
+                response=[],)
+        elif "health" in context:
+            return ExtensionResponse(status=self.log_health(context["health"]),
+                                     response=[],)
+        elif "init" in context:
+            return ExtensionResponse(
+                status=ExtensionStatus(code=1,
+                                       message=self._use_glog_message,),
+                response=[],)
+        elif "status" in context:
+            return ExtensionResponse(
+                status=ExtensionStatus(code=1,
+                                       message=self._use_glog_message,),
+                response=[],)
+        else:
+            return ExtensionResponse(
+                status=ExtensionStatus(code=1,
+                                       message=self._invalid_action_message,),
+                response=[],)
+
+    def registry_name(self):
+        """The name of the registry type for logger plugins.
+
+        Do not override this method."""
+        return "logger"
+
+    @abstractmethod
+    def log_string(self, value):
+        """The implementation of your logger plugin.
+
+        This must be implemented by your plugin.
+
+        This must return an ExtensionStatus
+
+        Arguments:
+        value -- the string to log
+        """
+        raise NotImplementedError
+
+    def log_health(self, value):
+        """If you'd like the log health statistics about osquery's performance,
+        override this method in your logger plugin.
+
+        By default, this action is a noop.
+
+        This must return an ExtensionStatus
+        """
+        return ExtensionStatus(code=0, message="OK",)
+
+    def log_snapshot(self, value):
+        """If you'd like to log snapshot queries in a special way, override
+        this method.
+
+        By default, this action is just hands off the string to log_string.
+
+        This must return an ExtensionStatus
+        """
+        return self.log_string(value)