mirage.core package¶

Submodules¶

mirage.core.app module¶

class mirage.core.app.App(quiet=False, homeDir='/home/user/.mirage', tempDir='/tmp/mirage')¶

Bases: mirage.core.interpreter.Interpreter

This class defines the main Application. It inherits from core.interpreter.Interpreter, allowing to use Mirage as a command line interpreter.

exception IncorrectParameter¶: Bases: mirage.core.app.App.SetParameterException

Instance = None¶

exception MultipleModulesLoaded¶: Bases: mirage.core.app.App.SetParameterException

exception NoModuleLoaded¶: Bases: mirage.core.app.App.SetParameterException

exception SetParameterException¶: Bases: Exception

args()¶: This method is an alias for showargs.

clear()¶: This method allows to clear the screen.

create_module()¶: This method allows to interact with the user in order to easily generate an user module.

create_scenario()¶: This method allows to interact with the user in order to easily generate an user scenario.

exit()¶: This method allows to exit the framework.

info()¶: This method displays informations about the loaded module, such as the name, technology used, etc.

list(pattern='')¶

This method allows to list the different modules available in the framework. A string pattern can be provided as a filter.

Parameters: pattern (str) – Filter

load(moduleName: !method:_autocompleteModules)¶

This method allows to load a module according to its name. It allows to load a sequence of modules by using the pipe (|) symbol.

Parameters: moduleName (str) – name of the module (or sequence of modules) to load
Example

>>> app.load('ble_info')
>>> app.load('ble_connect|ble_discover')

loop()¶: This method allows to run the main interpreter loop.

restart(task)¶

This method allows to restart a specific background task according to its name.

Parameters: task (str) – Task name to restart

run()¶: This method runs the loaded module with the input parameters provided.

set(name: !method:_autocompleteParameters, value)¶

This method allows to provide a value for a specific input parameter of the loaded module.

Parameters

name (str) – parameter’s name
value (str) – value of parameter

Example

>>> app.set("INTERFACE","hci0")
>>> app.set("ble_connect1.INTERFACE", "hci0")

shortcuts(pattern='')¶

This method allows to list the different shortcuts available in the framework. A string pattern can be provided as a filter.

Parameters: pattern (str) – Filter

showargs()¶: This method displays a chart describing the available input parameters for the loaded module.

start(task)¶

This method allows to start a specific background task according to its name.

Parameters: task (str) – Task to start

stop(task)¶

This method allows to stop a specific background task according to its name.

Parameters: task (str) – Task to stop

tasks(pattern='')¶

This method allows to display the existing background tasks. A string pattern can be provided as a filter.

Parameters: pattern (str) – Filter

mirage.core.argParser module¶

class mirage.core.argParser.ArgParser(appInstance=None)¶

Bases: object

This class allows to easily parse parameters from command line.

create_module()¶: This method checks if the create_module parameter has been provided by the user on the command line. It will call the method create_module of the main application instance (core.app.App).

create_scenario()¶: This method checks if the create_scenario parameter has been provided by the user on the command line. It will call the method create_scenario of the main application instance (core.app.App).

debug()¶: This method checks if the debug parameter has been provided by the user on the command line. It will modify the attribute debugMode stored in the provided instance of core.app.App.

launcher()¶

This method checks if a Mirage module to run has been provided by the user on the command line. It will load and run the corresponding module with the parameters provided by the user.

Example

./mirage.py moduleName PARAMETER1=value1 PARAMETER2=value2 PARAMETER3=value3

list()¶: This method checks if the list parameter has been provided by the user on the command line. It will call the method list of the main application instance (core.app.App).

quiet()¶: This method checks if the quiet parameter has been provided by the user on the command line. It will modify the attribute quiet stored in the provided instance of core.app.App.

run()¶: This method checks if Mirage has been launched with some parameters. - If no Mirage module has been provided by the user on the command line, it will launch the main application loop (method loop of core.app.App) - If a Mirage module has been provided by the user, it calls the method launcher of core.argParser.ArgParser.

verbosity()¶: This method checks if the verbosity parameter has been provided by the user on the command line. It will modify the variable VERBOSITY_LEVEL stored in libs.io.

mirage.core.config module¶

class mirage.core.config.Config(filename)¶

Bases: object

This class is used to parse and generate a configuration file in “.cfg” format.

dataExists(moduleName, arg)¶

This method checks if a value has been provided in the configuration file for the argument arg of the module named according to moduleName.

Parameters

moduleName (str) – name of the module
arg (str) – name of the argument

Returns

boolean indicating if a value has been provided

Return type

bool

generateDatas()¶: This method parses the configuration file and store the corresponding arguments in the attribute datas.

generateShortcuts()¶: This method parses the configuration file and store the corresponding arguments in the attribute datas.

getData(moduleName, arg)¶

This method returns the value provided in the configuration file for the argument arg of the module named according to moduleName.

Parameters

moduleName (str) – name of the module
arg (str) – name of the argument

Returns

value of the parameter

Return type

str

getShortcuts()¶

This method returns the shortcuts loaded from the configuration file.

Returns: dictionary listing the existing shortcuts
Return type: dict

mirage.core.interpreter module¶

class mirage.core.interpreter.Interpreter(prompt='\x1b[36m ~~> \x1b[39m', autocompletion=True, suggestion=True)¶

Bases: object

If a class inherits of this class, it becomes a tiny command interpreter. Every method listed in availableCommands becomes a command of the interpreter, and can receive arguments. If a command is not found, the fail() method is raised. The interaction loop is contained in the loop() method.

Every method listed in availableCommands becomes a command usable in the interpreter. If the method has parameters, the following rules are applied :

if a parameter has no default value, the parameter is mandatory in the interpreter

if a parameter has a default value, the parameter is optional (if it is not provided, the default value is used)

Every parameter can be automatically autocompleted if the autocompletion mode is enabled. Indeed, you can specify how to autocomplete this parameter by indicating a way to get a list of possible values using annotations :

You can provide a list :
def my_cmd(self,my_parameter:["value1","value2"]="value1"):
        pass
You can provide a string indicating a method using the syntax !method:<methodName> :
def _autocompleteMyCmd(self):
        return ["value"+str(i) for i in range(10)]

def my_cmd(self,my_parameter:"!method:_autocompleteMyCmd"="value1"):
        pass
You can also provide a string indicating a function using the syntax !function:<functionName> :
def my_cmd(self,my_parameter:"!function:_autocompleteMyCmd"="value1"):
        pass
You can provide a string indicating an attribute using the syntax !attribute:<attributeName> :
def my_cmd(self,my_parameter:"!attribute:_myAutocompleteAttribute"="value1"):
        pass
You can provide a string indicating a variable using the syntax !variable:<variableName> :
def my_cmd(self,my_parameter:"!variable:myVariable"="value1"):
        pass
You can provide a string indicating a file path using the syntax !path :
def my_cmd(self,my_parameter:"!path"="/home/user/test.gatt"):
        pass
Any other string will be interpreted as a single completion value :
def my_cmd(self,my_parameter:"value1"="value1"):
        pass

If the suggestion mode is enabled, the name of the parameters are displayed when the user types a known command. The mandatory parameters are displayed as <parameter> and the optional parameters are displayed as [parameter]

evaluateCommand(command)¶

This method allows to evaluate a specific command provided by the user in the interpreter. It uses introspection in order to find a corresponding method in the current class.

Parameters: command (list of str) – command provided by the user

evaluateScript(script)¶

This method allows to evaluate a specific list of commands (script) provided by the user in the interpreter. It splits the string provided by the user using the delimiter ; and calls the method evaluateCommand on each command found.

Parameters: script (str) – script provided by the user

exit()¶: This method exits the interpreter’s main loop. It is a command available in the interpreter by default.

fail()¶: This method is called if a command typed by the user is not found in the availableCommand attribute.

loop()¶: This method is the main interaction loop of the interpreter.

mirage.core.loader module¶

class mirage.core.loader.Loader¶

Bases: object

This class permits to dynamically load the modules.

getModulesNames()¶

This method returns a list of existing modules’ names.

Returns: list of modules’ name
Return type: list of str

list(pattern='')¶

Display the list of module, filtered by the string provided as pattern.

Parameters: pattern (str) – filter

load(moduleName)¶

This method returns an instance of a specific module according to the name provided as parameter.

Parameters: moduleName (str) – name of a module
Returns: an instance of the module
Return type: core.module.Module

mirage.core.module module¶

class mirage.core.module.Module¶

Bases: object

This class defines the standard behaviour of a Mirage Module. Every module must inherit of this class.

execute()¶: This method allows launch a module execution by calling the methods prerun, run and postrun.

info()¶: This method is an helper allowing to generate a dictionary including some useful informations about the module. It is mainly used by the list command of the main application.

init()¶

This method is an initialization method, called at the end of the constructor’s execution.

It must be overloaded in order to define the parameters of module, especially :

type : it defines the type of the module (e.g. “sniffing”, “mitm” …)
technology : it defines the type of technology used by the module (e.g. “ble”, “wifi”, …)
description : a short string indicating the role of the module
args : a dictionary of string describing the input parameters and their potential default values
dependencies : an array of string indicating the dependencies of the module
dynamicArgs : a boolean indicating if the user can provide input parameters not defined in the args dictionary

key(*args, **kwargs)¶

loadScenario()¶: Helper allowing to check if a scenario has been provided and run the scenario if needed. It initializes the keyboard related signals and instantiates the selected scenario.

nok()¶

This method is an helper to format the output of the module if its execution was not successful. It calls the out method.

Returns: dictionary composed of the success boolean (key “success”) and an empty dictionary.
Return type: dict

ok(output={})¶

This method is an helper to format the output of the module if its execution was successful. It calls the out method.

Parameters: output (dict of str) – dictionary of strings indicating the output parameters.
Returns: dictionary composed of the success boolean (key “success”) and the output dictionary.
Return type: dict

out(success, output={})¶

This method is an helper to format the output of the module as needed by the framework.

Parameters

success (bool) – boolean indicating if the module failed or succeeded.
output (dict of str) – dictionary of strings indicating the output parameters.

Returns

dictionary composed of the success boolean (key “success”) and the output dictionary.

Return type

dict

postrun()¶: This method is called after the run method, and can be overloaded to clean up some components after the module execution.

prerun()¶: This method is called before the run method, and can be overloaded to initialize some components before the module execution.

run()¶: This method implements the behaviour of the module. It must be overloaded by every module in order to define the module execution.

watchKeyboard()¶: This method allows to register a callback called if a key is pressed (if a scenario is provided). It allows to provide a simple user interaction in scenarios.

class mirage.core.module.WirelessModule¶

Bases: mirage.core.module.Module

This class inherits from core.module.Module. It adds some methods in order to facilitate the selection of the right couple of Emitters / Receivers according to the technology attribute.

Emitters = {}¶

EmittersClass = {}¶

Receivers = {}¶

ReceiversClass = {}¶

getEmitter(interface='')¶

Helper allowing to easily get a specific Emitter instance according to the technology attribute.

Parameters: interface (str) – string indicating the interface to use
Returns: Emitter instance
Return type: core.wireless.Emitter

getReceiver(interface='')¶

Helper allowing to easily get a specific Receiver instance according to the technology attribute.

Parameters: interface (str) – string indicating the interface to use
Returns: Receiver instance
Return type: core.wireless.Receiver

classmethod registerEmitter(technology, emitter=None)¶

This class method allows to link a given Emitter and a specific technology.

Parameters

technology (str) – string indicating a technology (e.g. “ble”, “wifi”, …)
emitter (core.wireless.Emitter) – Emitter

classmethod registerReceiver(technology, receiver=None)¶

This class method allows to link a given Receiver and a specific technology.

Parameters

technology (str) – string indicating a technology (e.g. “ble”, “wifi”, …)
receiver (core.wireless.Receiver) – Receiver

mirage.core.scenario module¶

class mirage.core.scenario.Scenario(name='', module=None)¶

Bases: object

This class defines a scenario. A Scenario is a Mirage entity allowing to customize the behaviour of a module without modifying its code, and can be compared to a list of callbacks called when a specific event (or signal) happens.

receiveSignal(signal, *args, **kwargs)¶: This method is called when a signal is received, and calls the corresponding method in the scenario if it exists.

mirage.core.scenario.scenarioSignal(argument)¶

Decorator allowing to link a module’s method to a specific signal.

Parameters: argument (str) – signal name

mirage.core.task module¶

class mirage.core.task.Task(function, name, args=[], kwargs={})¶

Bases: multiprocessing.context.Process

This class defines a background Task, it inherits from multiprocessing.Process. It provides an user friendly API to easily run a given function in background.

run()¶: This method runs the specified function in background.

Note

The standard output is automatically redirected in a temporary file, named <taskName>-<taskPID>.out

start()¶: This method allows to start the current task.

stop()¶: This method allows to stop the current task.

toList()¶

This method returns a list representing the current task. It is composed of :

the task’s PID

the task’s name

the task’s state

the associated output file

Returns: list representing the current task
Return type: list of str

mirage.core.taskManager module¶

class mirage.core.taskManager.TaskManager¶

Bases: object

This class is a manager allowing to easily manipulate background tasks (using multiprocessing). It is instantiated by the main application instance (core.app.App).

addTask(function, name='', args=[], kwargs={})¶

This method allows to create a new background task. It instantiates a core.task.Task and adds it to the task dictionary tasks. If a task already exists using the specified name, it will be suffixed by a number.

Parameters

function (function) – function to launch in background
name (str) – name of the task
args (list) – array of unnamed arguments
kwargs (dict) – dictionary of named arguments

Returns

real name of the instantiated task (it may be suffixed)

Return type

str

getTaskPID(name)¶

This method returns a task’s PID according to its name.

Parameters: name (str) – name of the task
Returns: task’s PID
Return type: int

getTaskState(name)¶

This method returns a task’s state according to its name.

Parameters: name (str) – name of the task
Returns: task’s state
Return type: str

getTasksList(pattern='')¶

This method returns the list of the existing tasks, filtered by a specified pattern.

Parameters: pattern (str) – Filter
Returns: list of existing tasks
Return type: list

restartTask(name)¶

This method restarts an existing task according to its (real) name.

Parameters: name (str) – name of the task to restart

startTask(name)¶

This method starts an existing task according to its (real) name.

Parameters: name (str) – name of the task to start

stopAllTasks()¶: This method stop all running tasks.

stopTask(name)¶

This method stops an existing task according to its (real) name.

Parameters: name (str) – name of the task to stop