Skip to content

Writing a Module

Jump to bottom
Daniel Bradberry edited this page Oct 18, 2013 · 9 revisions

A drozer module is a small piece of Python code, that interacts with the running Android platform through the Agent.

Module Structure

A drozer module is a Python class, than inherits from drozer.modules.Module. They are stored within a module repository (<drozer python path>/drozer/modules by default).

Metadata

drozer expects an amount of metadata to be configured for each module. This helps the system to organise the modules, and generate consistent help and usage information.

A module must define:

  • name a headline name that describes the module’s purpose
  • description a longer description of what the module does
  • examples a few examples of common usage patterns
  • author the name of the module author, or an array of names
  • date the date on which the module was last updated
  • license the license under which this module is released
  • path an array that describes the namespace of the module

See the example module for how this metadata is provided.

Executor

A module must define a single method execute(), which is invoked by drozer when the module is run. This method should perform some action against the Android platform, and write its results to screen.

drozer modules are stateless: they are instantiated shortly before the execute() method is invoked, and disposed shortly thereafter.

Output Streams

A drozer module should never use the print keyword, provided by Python. This bypasses the post-processing performed on data being shown on screen, such as applying colours and saving output to file.

drozer modules should write all display data to either self.stdout or self.stderr, by invoking the write() method.

An Example Module

As an example, we declare a module ex.random.getinteger, which utilises a pseudo-random number generator on the Android device to generate random integers.

from drozer.modules import Module

class GetInteger(Module):

    name = ""
    description = ""
    examples = ""
    author = "Joe Bloggs (@jbloggs)"
    date = "2012-12-21"
    license = "BSD (3-clause)"
    path = ["ex", "random"]

    def execute(self, arguments):
        random = self.new("java.util.Random")
        integer = random.nextInt()

        self.stdout.write("int: %d\n" % integer)

Module Repositories

drozer loads modules from a series of repositories, by default <drozer python path>/drozer/modules.

It is recommended that you do not add modules to the default repository, unless you are staging it to make a pull request, because this makes it difficult to upgrade to a newer version of drozer.

You should, instead, create your own module repository for development and your own plugins. A module repository is a Python package (a folder containing an __init__.py file), in which you can use a structure of subpackages to organise your modules.

You may create your module repository anywhere on your system. Then enable the repository in drozer, by running `module repository enable /path/to/your/repository`. You may enable any number of module repositories.

Modules API

Clone this wiki locally