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:
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. |
Value | Meaning |
---|---|
CanariMode.LocalDispatch |
Transform running in local production mode. |
CanariMode.RemotePlumeDispatch |
Transform is running in Plume production mode. |
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. |
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 isCanariMode.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 |