canari.mode - Canari Execution Modes

New in version 3.0.


Canari now supports the concept of execution modes. Execution modes allow transform developers to detect what context a transform is operating in (i.e. local or remote, production or debug, etc.) and alter the behaviour of their transforms accordingly. Execution modes also globally enable or disable high-risk functionality or modules that you would normally allow in local transform mode. Here’s an example of how a transform can check if it’s running as a local or transform:

from canari.maltego.entities import Phrase,WebSite
from canari.mode import is_local_exec_mode

class MyTransform(Transform):
    input_type = WebSite

    def do_transform(self, request, response, config):
        website = request.entity
        if is_local_exec_mode():
            # TODO: do something locally
            pass
        else:
            # TODO: do something remotely
            pass
        return response

You can also determine which transform runner is invoking the transform or whether it is operating in debug versus production mode, like so:

# ...
def do_transform(self, request, response, config):
    if is_local_debug_exec_mode():
        debug("We're running in debug mode.")

Canari modes can also be checked in the global scope to prevent a transform, entity, sensitive function or variable from being exposed or defined when operating in a particular mode:

if is_local_exec_mode():
    @RequireSuperUser
    class MyTransform(Transform):
        # Does risky stuff in local mode
        pass
else:
    class MyTransform(Transform):
        # Does safer stuff in remote mode
        pass

Canari currently supports the following execution modes:

Primitive Modes
Value Meaning
CanariMode.Local Transform is running locally.
CanariMode.Remote Transform is running remotely.
CanariMode.Debug Transform is running in debugging mode.
CanariMode.Dispatch Transform is running in production mode.
CanariMode.Plume Transform is running in Plume container.
CanariMode.Shell Transform is running from canari shell.
Production Modes
Value Meaning
CanariMode.LocalDispatch Transform running in local production mode.
CanariMode.RemotePlumeDispatch Transform is running in Plume production mode.
Debugging Modes
Value Meaning
CanariMode.LocalDebug Transform running local debugging mode.
CanariMode.RemotePlumeDebug Transform is running in Plume in debugging mode.
CanariMode.LocalShellDebug Transform is running running from canari shell.
Unknown Modes
Value Meaning
CanariMode.Unknown Canari hasn’t been initialized and is operating in an unknown mode.
CanariMode.RemoteUnknown Canari hasn’t been initialized but is operating in remote mode.
CanariMode.LocalUnknown Canari hasn’t been initialized but is operating in local mode.

The 5 transform runners that come out of the box with Canari operate in the following modes, by default:

Runner Mode
dispatcher CanariMode.LocalDispatch
canari run-transform CanariMode.LocalDispatch
canari debug-transform CanariMode.LocalDebug
canari shell CanariMode.LocalShellDebug
plume CanariMode.RemotePlumeDispatch

Non-primitive operating modes are or’d bitmasks of the primitive operating modes. For example, CanariMode.LocalDebug is equivalent to CanariMode.Local | CanariMode.Debug. This makes it possible to perform a broad (i.e. is_local_exec_mode()) or narrow (i.e. is_local_debug_exec_mode()) check on an operating mode. For example:

>>> from canari.mode import *
>>> old_mode = set_canari_mode(CanariMode.LocalDebug)
>>> is_local_exec_mode()
True
>>> is_debug_exec_mode()
True
>>> is_local_debug_exec_mode()
True

The canari.mode module provides the following functions:

canari.mode.set_canari_mode(mode)
Parameters:mode (CanariMode) – the desired operating mode.
Returns:the old operating mode.

Sets the Canari operating mode and returns the old one. The old operating mode can be ignored if you never wish to restore the original operating mode.

canari.mode.get_canari_mode()
Returns:current Canari operating mode.

Gets the current Canari operating mode. If a prior call to canari_set_mode() has not been made, the default operating mode is CanariMode.Unknown.

canari.mode.get_canari_mode_str()
Returns:current Canari operating mode as a user-friendly string.

Gets the current Canari operating mode as a user-friendly string which can be displayed in logs or debugging information. For example:

>>> print get_canari_mode_str()
Local (runner=shell, debug=True)

As demonstrated earlier, canari.mode provides convenience functions that can be used to query the current operating mode. These functions return either True or False depending on whether the operating mode being queried has the appropriate operating mode bits set:

Function Returns True For Operating Modes
is_local_exec_mode() CanariMode.Local*
is_debug_exec_mode() CanariMode.*Debug*
is_dispatch_exec_mode() CanariMode.*Dispatch*
is_remote_exec_mode() CanariMode.Remote*
is_plume_exec_mode() CanariMode.*Plume*
is_shell_exec_mode() CanariMode.*Shell*
is_unknown_exec_mode() CanariMode.*Unknown*
is_local_debug_exec_mode() CanariMode.Local*Debug*
is_local_dispatch_exec_mode() CanariMode.Local*Dispatch*
is_local_unknown_exec_mode() CanariMode.LocalUnknown
is_remote_plume_debug_exec_mode() CanariMode.RemotePlumeDebug
is_remote_plume_dispatch_exec_mode() CanariMode.RemotePlumeDispatch
is_remote_unknown_exec_mode() CanariMode.RemoteUnknown
is_local_shell_debug_exec_mode() CanariMode.LocalShellDebug