# # ZeekControl Plugin API. # from __future__ import print_function import logging from ZeekControl import config from ZeekControl import doc class Plugin(object): """The class ``Plugin`` is the base class for all ZeekControl plugins. The class has a number of methods for plugins to override, and every plugin must at least override ``name()`` and ``pluginVersion()``. For each ZeekControl command ``foo``, there are two methods, ``cmd_foo_pre`` and ``cmd_foo_post``, that are called just before the command is executed and just after it has finished, respectively. The arguments these methods receive correspond to their command-line parameters, and are further documented below. The ``cmd__pre`` methods have the ability to prevent the command's execution, either completely or partially for those commands that take nodes as parameters. In the latter case, the method receives a list of nodes that the command is to be run on, and it can filter that list and returns modified version of nodes to actually use. The standard case would be returning simply the unmodified ``nodes`` parameter. To completely block the command's execution, return an empty list. To just not execute the command for a subset, remove the affected ones. For commands that do not receive nodes as arguments, the return value is interpreted as boolean indicating whether command execution should proceed (True) or not (False). The ``cmd__post`` methods likewise receive the commands arguments as their parameter, as documented below. For commands taking nodes, the list corresponds to those nodes for which the command was actually executed (i.e., after any ``cmd__pre`` filtering). Note that if a plugin prevents a command from executing either completely or partially, it should report its reason via the ``message()`` or ``error()`` methods. If multiple plugins hook into the same command, all their ``cmd__{pre,post}`` are executed in undefined order. The command is executed on the intersection of all ``cmd__pre`` results. Finally, note that the ``restart`` command is just a combination of other commands and thus their callbacks are run in addition to the callbacks for ``restart``. """ def __init__(self, apiversion): """Must be called by the plugin with the plugin API version it expects to use. The version currently documented here is 1.""" self._apiversion = apiversion self.activated = False def apiVersion(self): """Returns the plugin API that the plugin expects to use.""" return self._apiversion @doc.api def getGlobalOption(self, name): """Returns the value of the global ZeekControl option *name*. See the output of ``zeekctl config`` for a complete list.""" val = config.Config.get_option(name) if val is None: raise KeyError("plugin %s lookup of unknown config option %s" % (self.name(), name)) return val @doc.api def getOption(self, name): """Returns the value of one of the plugin's options, *name*. An option has a default value (see *options()*), which can be overridden by a user in ``zeekctl.cfg``. An option's value cannot be changed by the plugin. """ name = "%s.%s" % (self.prefix(), name) val = config.Config.get_option(name) if val is None: raise KeyError("plugin %s lookup of unknown plugin option %s" % (self.name(), name)) return val @doc.api def getState(self, name): """Returns the current value of one of the plugin's state variables, *name*. If it has not yet been set, an empty string will be returned. Different from options, state variables can be set by the plugin. They are persistent across restarts. Note that a plugin cannot query any global ZeekControl state variables. """ name = "%s.state.%s" % (self.prefix(), name) return config.Config.get_state(name, "") @doc.api def setState(self, name, value): """Sets one of the plugin's state variables, *name*, to *value*. The change is permanent and will be recorded to disk. Note that a plugin cannot change any global ZeekControl state variables. """ if "." in name or " " in name: self.error('plugin %s state variable name "%s" must not contain dots or spaces' % (self.name(), name)) return name = "%s.state.%s" % (self.prefix(), name) config.Config.set_state(name, value) @doc.api def parseNodes(self, names): """Returns a tuple which contains two lists. The first list is a list of `Node`_ objects for a string of space-separated node names. If a name does not correspond to a known node, then the name is added to the second list in the returned tuple. """ nodes = [] notnodes = [] for arg in names.split(): nodelist = config.Config.nodes(arg) if nodelist: nodes += nodelist else: notnodes.append(arg) # Sort the list so that it doesn't depend on initial order of arguments nodes.sort(key=lambda n: (n.type, n.name)) return (nodes, notnodes) @doc.api def message(self, msg): """Reports a message to the user.""" print("%s" % msg) @doc.api def debug(self, msg): """Logs a debug message in ZeekControl's debug log if enabled.""" logging.debug("%s: %s", self.prefix(), msg) @doc.api def error(self, msg): """Reports an error to the user.""" print("error: %s" % msg) @doc.api def execute(self, node, cmd): """Executes a command on the host for the given *node* of type `Node`_. Returns a tuple ``(success, output)`` in which ``success`` is True if the command ran successfully, and ``output`` is a string which contains the combined stdout/stderr output.""" resultlist = self.executor.run_shell_cmds([(node, cmd)]) if resultlist: _, success, output = resultlist[0] else: success = False output = "" return (success, output) @doc.api def nodes(self): """Returns a list of all configured `Node`_ objects.""" return config.Config.nodes() @doc.api def hosts(self, nodes=[]): """Returns a list of Node_ objects which is a subset of the list in *nodes*, such that only one node per host will be chosen. If *nodes* is empty, then the returned list will be a subset of the entire list of configured nodes.""" if not nodes: return [n for n in config.Config.hosts()] result = [] h = {} for n in nodes: if n.host not in h: h[n.host] = 1 result.append(n) return result @doc.api def executeParallel(self, cmds): """Executes a set of commands in parallel on multiple hosts. ``cmds`` is a list of tuples ``(node, cmd)``, in which the *node* is a `Node`_ instance and *cmd* is a string with the command to execute for it. The method returns a list of tuples ``(node, success, output)``, in which ``success`` is True if the command ran successfully, and ``output`` is a string containing the combined stdout/stderr output for the corresponding ``node``.""" return self.executor.run_shell_cmds(cmds) ### Methods that must be overridden by plugins. @doc.api("override") def name(self): """Returns a string with a descriptive name for the plugin (e.g., ``"TestPlugin"``). The name must not contain any whitespace. This method must be overridden by derived classes. The implementation must not call the parent class' implementation. """ raise NotImplementedError @doc.api("override") def pluginVersion(self): """ Returns an integer with a version number for the plugin. Plugins should increase their version number with any significant change. This method must be overridden by derived classes. The implementation must not call the parent class' implementation. """ raise NotImplementedError ### Methods that can be overridden by plugins. @doc.api("override") def prefix(self): """Returns a string with a prefix for the plugin's options and commands names (e.g., "myplugin"). The prefix cannot contain any whitespace or dots (because dots are used as separators when forming the plugin's option names, state variable names, and command names). Note that ZeekControl will refuse to load a plugin if its prefix matches the prefix of another loaded plugin (this comparison is not case-sensitive). This method can be overridden by derived classes. The implementation must not call the parent class' implementation. The default implementation returns a lower-cased version of *name()*. """ return self.name().lower() @doc.api("override") def options(self): """Returns a set of local configuration options provided by the plugin. The return value is a list of 4-tuples each having the following elements: ``name`` A string with name of the option (e.g., ``Path``). Option names are not case-sensitive. Note that the option name exposed to the user will be prefixed with your plugin's prefix as returned by *prefix()* (e.g., ``myplugin.Path``). ``type`` A string with type of the option, which must be one of ``"bool"``, ``"string"``, or ``"int"``. ``default`` The option's default value. Note that this value must be enclosed in quotes if the type is "string", and must not be enclosed in quotes if the type is not "string". ``description`` A string with a description of the option semantics. This method can be overridden by derived classes. The implementation must not call the parent class' implementation. The default implementation returns an empty list. """ return [] @doc.api("override") def commands(self): """Returns a set of custom commands provided by the plugin. The return value is a list of 3-tuples each having the following elements: ``command`` A string with the command's name. Note that the command name exposed to the user will be prefixed with the plugin's prefix as returned by *prefix()* (e.g., ``myplugin.mycommand``, or just ``myplugin`` if the command name is an empty string). ``arguments`` A string describing the command's arguments in a textual form suitable for use in the ``help`` command summary (e.g., ``[]`` for a command taking an optional list of nodes). Empty if no arguments are expected. ``description`` A string with a description of the command's semantics suitable for use in the ``help`` command summary. This method can be overridden by derived classes. The implementation must not call the parent class' implementation. The default implementation returns an empty list. """ return [] @doc.api("override") def nodeKeys(self): """Returns a list of names of custom keys for nodes (the value of a key can be specified in ``node.cfg`` for any node defined there). Node key names are not case-sensitive. The value for a key will be available from the `Node`_ object as attribute ``_`` (e.g., ``node.myplugin_mykey``). If not set, the attribute will be set to an empty string. This method can be overridden by derived classes. The implementation must not call the parent class' implementation. The default implementation returns an empty list. """ return [] @doc.api("override") def zeekctl_config(self): """Returns a string containing Zeek script code that should be written to the dynamically generated Zeek script named "zeekctl-config.zeek". This provides a way for plugins to easily add Zeek script code that depends on zeekctl settings. This method can be overridden by derived classes. The default implementation does nothing. """ return def broctl_config(self): """Deprecated legacy name for `zeekctl_config`.""" return @doc.api("override") def init(self): """Called once just before ZeekControl starts executing any commands. This method can do any initialization that the plugin may require. Note that when this method executes, ZeekControl guarantees that all internals are fully set up (e.g., user-defined options are available). This may not be the case when the class ``__init__`` method runs. Returns a boolean, indicating whether the plugin should be used. If it returns ``False``, the plugin will be removed and no other methods called. This method can be overridden by derived classes. The default implementation always returns True. """ return True @doc.api("override") def done(self): """Called once just before ZeekControl terminates. This method can do any cleanup the plugin may require. This method can be overridden by derived classes. The default implementation does nothing. """ return @doc.api("override") def hostStatusChanged(self, host, status): """Called when ZeekControl's ``cron`` command finds the availability of a cluster system to have changed. Initially, all systems are assumed to be up and running. Once ZeekControl notices that a system isn't responding (defined as not accepting SSH sessions), it calls this method, passing in a string with the name of the *host* and a boolean *status* set to False. Once the host becomes available again, the method will be called again for the same host with *status* now set to True. Note that ZeekControl's ``cron`` tracks a host's availability across execution, so if the next time it's run the host is still down, this method will not be called again. This method can be overridden by derived classes. The default implementation does nothing. """ return @doc.api("override") def zeekProcessDied(self, node): """Called when ZeekControl finds the Zeek process for Node_ *node* to have terminated unexpectedly. This method will be called just before ZeekControl prepares the node's "crash report" and before it cleans up the node's spool directory. This method can be overridden by derived classes. The default implementation does nothing. """ return def broProcessDied(self, node): """Deprecated legacy name for `zeekProcessDied`.""" # We keep this around as it's difficult to warn about its usage. return # Per-command help currently not supported by zeekctl. May add this later. # #@doc.api(override): #def help_custom(self, cmd): # """Called for getting the ``help`` text for a custom command defined # by Plugin.commands_. Returns a string with the text, or an empty # string if no help is available. # # This method can be overridden by derived classes. The default # implementation always returns an empty string. # """ # return "" @doc.api("override") def cmd_nodes_pre(self): """Called just before the ``nodes`` command is run. Returns a boolean indicating whether or not the command should run. This method can be overridden by derived classes. The default implementation does nothing. """ return True @doc.api("override") def cmd_nodes_post(self): """Called just after the ``nodes`` command has finished. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_config_pre(self): """Called just before the ``config`` command is run. Returns a boolean indicating whether or not the command should run. This method can be overridden by derived classes. The default implementation does nothing. """ return True @doc.api("override") def cmd_config_post(self): """Called just after the ``config`` command has finished. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_exec_pre(self, cmdline): """Called just before the ``exec`` command is run. *cmdline* is a string with the command line to execute. Returns a boolean indicating whether or not the ``exec`` command should run. This method can be overridden by derived classes. The default implementation does nothing. """ return True @doc.api("override") def cmd_exec_post(self, cmdline): """Called just after the ``exec`` command has finished. Arguments are as with the ``pre`` method. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_install_pre(self): """Called just before the ``install`` command is run. Returns a boolean indicating whether or not the command should run. This method can be overridden by derived classes. The default implementation does nothing. """ return True @doc.api("override") def cmd_install_post(self): """Called just after the ``install`` command has finished. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_cron_pre(self, arg, watch): """Called just before the ``cron`` command is run. *arg* is an empty string if the command is executed without arguments. Otherwise, it is one of the strings: ``enable``, ``disable``, ``?``. *watch* is a boolean indicating whether the ``cron`` command should restart abnormally terminated Zeek processes; it's only valid if *arg* is empty. Returns a boolean indicating whether or not the ``cron`` command should run. This method can be overridden by derived classes. The default implementation does nothing. """ return True @doc.api("override") def cmd_cron_post(self, arg, watch): """Called just after the ``cron`` command has finished. Arguments are as with the ``pre`` method. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_check_pre(self, nodes): """Called just before the ``check`` command is run. It receives the list of nodes, and returns the list of nodes that should proceed with the command. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_check_post(self, results): """Called just after the ``check`` command has finished. It receives the list of 2-tuples ``(node, bool)`` indicating the nodes the command was executed for, along with their success status. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_start_pre(self, nodes): """Called just before the ``start`` command is run. It receives the list of nodes, and returns the list of nodes that should proceed with the command. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_start_post(self, results): """Called just after the ``start`` command has finished. It receives the list of 2-tuples ``(node, bool)`` indicating the nodes the command was executed for, along with their success status. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_stop_pre(self, nodes): """Called just before the ``stop`` command is run. It receives the list of nodes, and returns the list of nodes that should proceed with the command. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_stop_post(self, results): """Called just after the ``stop`` command has finished. It receives the list of 2-tuples ``(node, bool)`` indicating the nodes the command was executed for, along with their success status. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_deploy_pre(self): """Called just before the ``deploy`` command is run. Returns a boolean indicating whether or not the command should run. This method can be overridden by derived classes. The default implementation does nothing. """ return True @doc.api("override") def cmd_deploy_post(self): """Called just after the ``deploy`` command has finished. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_status_pre(self, nodes): """Called just before the ``status`` command is run. It receives the list of nodes, and returns the list of nodes that should proceed with the command. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_status_post(self, nodes): """Called just after the ``status`` command has finished. Arguments are as with the ``pre`` method. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_update_pre(self, nodes): """Called just before the ``update`` command is run. It receives the list of nodes, and returns the list of nodes that should proceed with the command. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_update_post(self, results): """Called just after the ``update`` command has finished. It receives the list of 2-tuples ``(node, bool)`` indicating the nodes the command was executed for, along with their success status. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_custom(self, cmd, args, cmdout): """Called when a command defined by the ``commands`` method is executed. *cmd* is the command (without the plugin's prefix), and *args* is a single string with all arguments. It returns a CmdResult object containing the command results. If the arguments are actually node names, ``parseNodes`` can be used to get the `Node`_ objects. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_df_pre(self, nodes): """Called just before the ``df`` command is run. It receives the list of nodes, and returns the list of nodes that should proceed with the command. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_df_post(self, nodes): """Called just after the ``df`` command has finished. Arguments are as with the ``pre`` method. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_diag_pre(self, nodes): """Called just before the ``diag`` command is run. It receives the list of nodes, and returns the list of nodes that should proceed with the command. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_diag_post(self, nodes): """Called just after the ``diag`` command has finished. Arguments are as with the ``pre`` method. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_peerstatus_pre(self, nodes): """Called just before the ``peerstatus`` command is run. It receives the list of nodes, and returns the list of nodes that should proceed with the command. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_peerstatus_post(self, nodes): """Called just after the ``peerstatus`` command has finished. Arguments are as with the ``pre`` method. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_netstats_pre(self, nodes): """Called just before the ``netstats`` command is run. It receives the list of nodes, and returns the list of nodes that should proceed with the command. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_netstats_post(self, nodes): """Called just after the ``netstats`` command has finished. Arguments are as with the ``pre`` method. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_top_pre(self, nodes): """Called just before the ``top`` command is run. It receives the list of nodes, and returns the list of nodes that should proceed with the command. Note that when ``top`` is run interactively to auto-refresh continuously, this method will be called once before each update. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_top_post(self, nodes): """Called just after the ``top`` command has finished. Arguments are as with the ``pre`` method. Note that when ``top`` is run interactively to auto-refresh continuously, this method will be called once after each update. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_restart_pre(self, nodes, clean): """Called just before the ``restart`` command is run. It receives the list of nodes, and returns the list of nodes that should proceed with the command. *clean* is boolean indicating whether the ``--clean`` argument has been given. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_restart_post(self, nodes): """Called just after the ``restart`` command has finished. It receives a list of *nodes* indicating the nodes on which the command was executed. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_cleanup_pre(self, nodes, all): """Called just before the ``cleanup`` command is run. It receives the list of nodes, and returns the list of nodes that should proceed with the command. *all* is boolean indicating whether the ``--all`` argument has been given. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_cleanup_post(self, nodes, all): """Called just after the ``cleanup`` command has finished. Arguments are as with the ``pre`` method. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_capstats_pre(self, nodes, interval): """Called just before the ``capstats`` command is run. It receives the list of nodes, and returns the list of nodes that should proceed with the command. *interval* is an integer with the measurement interval in seconds. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_capstats_post(self, nodes, interval): """Called just after the ``capstats`` command has finished. Arguments are as with the ``pre`` method. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_scripts_pre(self, nodes, check): """Called just before the ``scripts`` command is run. It receives the list of nodes, and returns the list of nodes that should proceed with the command. *check* is boolean indicating whether the ``-c`` option was given. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_scripts_post(self, nodes, check): """Called just after the ``scripts`` command has finished. Arguments are as with the ``pre`` method. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_print_pre(self, nodes, id): """Called just before the ``print`` command is run. It receives the list of nodes, and returns the list of nodes that should proceed with the command. *id* is a string with the name of the ID to be printed. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_print_post(self, nodes, id): """Called just after the ``print`` command has finished. Arguments are as with the ``pre`` method. This method can be overridden by derived classes. The default implementation does nothing. """ pass @doc.api("override") def cmd_process_pre(self, trace, options, scripts): """Called just before the ``process`` command is run. It receives the *trace* to read from as a string, a list of additional Zeek *options*, and a list of additional Zeek *scripts*. Returns a boolean indicating whether or not the ``process`` command should run. This method can be overridden by derived classes. The default implementation does nothing. """ return True @doc.api("override") def cmd_process_post(self, trace, options, scripts, success): """Called just after the ``process`` command has finished. Arguments are as with the ``pre`` method, plus an additional boolean *success* indicating whether Zeek terminated normally. This method can be overridden by derived classes. The default implementation does nothing. """ pass # Internal methods. def _to_bool(self, val): if val.lower() in ("1", "true"): return True if val.lower() in ("0", "false"): return False raise ValueError("invalid boolean: '%s'" % val) def _registerOptions(self): type_converters = {"bool": self._to_bool, "int": int, "string": str} pytype = {"bool": bool, "int": int, "string": str} for (name, ty, default, descr) in self.options(): if not name: self.error("plugin %s option name must not be empty" % self.name()) continue if "." in name or " " in name: self.error('plugin %s option name "%s" must not contain dots or spaces' % (self.name(), name)) continue optname = "%s.%s" % (self.prefix(), name) if ty not in pytype: self.error('plugin option %s has invalid type "%s"' % (optname, ty)) continue if not isinstance(default, pytype[ty]): self.error("plugin option %s default value must be type %s" % (optname, ty)) continue val = config.Config.get_option(optname) if val is not None: # Convert option values to correct data type for options # specified in zeekctl.cfg try: newval = type_converters[ty](val) except ValueError: self.error('zeekctl option "%s" has invalid value "%s" for type %s' % (optname, val, ty)) continue config.Config.set_option(optname, newval) else: # Set default value for options not specified in zeekctl.cfg config.Config.init_option(optname, default)