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.

Instance = None
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")
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.

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

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