androguard.core.analysis package

The analysis module implements an abstraction layer for androguard.core.bytecodes.dvm.DalvikVMFormat objects. The the help of the androguard.core.analysis.analysis.Analsyis object, you can bundle several DEX files together. This is not only useful for multidex files, but also for a single dex, as Analysis offers many features to investigate DEX files. One of these features is crossreferencing (XREF). It allows you to build a graph of the methods inside the DEX files. You can then create callgraphs or find methods which use a specific API method.

Submodules

androguard.core.analysis.analysis module

class androguard.core.analysis.analysis.Analysis(vm=None)

Bases: object

add(vm)

Add a DalvikVMFormat to this Analysis

Parameters:vmdvm.DalvikVMFormat to add to this Analysis
create_xref()

Create Class, Method, String and Field crossreferences for all classes in the Analysis.

If you are using multiple DEX files, this function must be called when all DEX files are added. If you call the function after every DEX file, the crossreferences might be wrong!

find_classes(name='.*', no_external=False)

Find classes by name, using regular expression This method will return all ClassAnalysis Object that match the name of the class.

Parameters:
  • name – regular expression for class name (default “.*”)
  • no_external – Remove external classes from the output (default False)
Return type:

generator of ClassAnalysis

find_fields(classname='.*', fieldname='.*', fieldtype='.*', accessflags='.*')

find fields by regex

Parameters:
  • classname – regular expression of the classname
  • fieldname – regular expression of the fieldname
  • fieldtype – regular expression of the fieldtype
  • accessflags – regular expression of the access flags
Return type:

generator of FieldClassAnalysis

find_methods(classname='.*', methodname='.*', descriptor='.*', accessflags='.*', no_external=False)

Find a method by name using regular expression. This method will return all MethodClassAnalysis objects, which match the classname, methodname, descriptor and accessflags of the method.

Parameters:
  • classname – regular expression for the classname
  • methodname – regular expression for the method name
  • descriptor – regular expression for the descriptor
  • accessflags – regular expression for the accessflags
  • no_external – Remove external method from the output (default False)
Return type:

generator of MethodClassAnalysis

find_strings(string='.*')

Find strings by regex

Parameters:string – regular expression for the string to search for
Return type:generator of StringAnalysis
get_call_graph(classname='.*', methodname='.*', descriptor='.*', accessflags='.*', no_isolated=False, entry_points=[])

Generate a directed graph based on the methods found by the filters applied. The filters are the same as in find_methods()

A networkx.DiGraph is returned, containing all edges only once! that means, if a method calls some method twice or more often, there will only be a single connection.

Parameters:
  • classname – regular expression of the classname (default: “.*”)
  • fieldname – regular expression of the fieldname (default: “.*”)
  • fieldtype – regular expression of the fieldtype (default: “.*”)
  • accessflags – regular expression of the access flags (default: “.*”)
  • no_isolated – remove isolated nodes from the graph, e.g. methods which do not call anything (default: False)
  • entry_points – A list of classes that are marked as entry point
Return type:

DiGraph

get_class_analysis(class_name)

Returns the ClassAnalysis object for a given classname.

Parameters:class_name – classname like ‘Ljava/lang/Object;’ (including L and ;)
Returns:ClassAnalysis
get_classes()

Returns a list of ClassAnalysis objects

Returns both internal and external classes (if any)

Return type:list of ClassAnalysis
get_external_classes()

Returns all external classes, that means all classes that are not defined in the given set of DalvikVMObjects.

Return type:generator of ClassAnalysis
get_field_analysis(field)

Get the FieldAnalysis for a given fieldname

Parameters:field – TODO
Returns:FieldClassAnalysis
get_fields()

Returns a list of FieldClassAnalysis objects

get_internal_classes()

Returns all external classes, that means all classes that are defined in the given set of DalvikVMFormat.

Return type:generator of ClassAnalysis
get_method(method)

Get the MethodAnalysis object for a given EncodedMethod. This Analysis object is used to enhance EncodedMethods.

Parameters:methodEncodedMethod to search for
Returns:MethodAnalysis object for the given method, or None if method was not found
get_method_analysis(method)

Returns the crossreferencing object for a given Method.

Beware: the similar named function get_method() will return a MethodAnalysis object, while this function returns a MethodClassAnalysis object!

This Method will only work after a run of create_xref()

Parameters:methodEncodedMethod
Returns:MethodClassAnalysis for the given method or None, if method was not found
get_method_analysis_by_name(class_name, method_name, method_descriptor)

Returns the crossreferencing object for a given method.

This function is similar to get_method_analysis(), with the difference that you can look up the Method by name

Parameters:
  • class_name – name of the class, for example ‘Ljava/lang/Object;’
  • method_name – name of the method, for example ‘onCreate’
  • method_descriptor – method descriptor, for example ‘(I I)V’
Returns:

MethodClassAnalysis

get_method_by_name(class_name, method_name, method_descriptor)

Search for a EncodedMethod in all classes in this analysis

Parameters:
  • class_name – name of the class, for example ‘Ljava/lang/Object;’
  • method_name – name of the method, for example ‘onCreate’
  • method_descriptor – descriptor, for example ‘(I I Ljava/lang/String)V
Returns:

EncodedMethod or None if method was not found

get_methods()

Returns a list of MethodClassAnalysis objects

get_strings()

Returns a list of StringAnalysis objects

Return type:list of StringAnalysis
get_strings_analysis()

Returns a dictionary of strings and their corresponding StringAnalysis

Returns:a dictionary
is_class_present(class_name)

Checks if a given class name is part of this Analysis.

Parameters:class_name – classname like ‘Ljava/lang/Object;’ (including L and ;)
Returns:True if class was found, False otherwise
class androguard.core.analysis.analysis.BasicBlocks(_vm)

Bases: object

This class represents all basic blocks of a method

get()
Return type:return each basic block (DVMBasicBlock object)
get_basic_block(idx)
get_basic_block_pos(idx)
gets()
Return type:a list of basic blocks (DVMBasicBlock objects)
pop(idx)
push(bb)
class androguard.core.analysis.analysis.ClassAnalysis(classobj)

Bases: object

AddFXrefRead(method, classobj, field)

Add a Field Read to this class

Parameters:
  • method
  • classobj
  • field
Returns:

AddFXrefWrite(method, classobj, field)

Add a Field Write to this class

Parameters:
  • method
  • classobj
  • field
Returns:

AddMXrefFrom(method1, classobj, method2, offset)
AddMXrefTo(method1, classobj, method2, offset)
AddXrefFrom(ref_kind, classobj, methodobj, offset)

Creates a crossreference from this class. XrefFrom means, that the current class is called by another class.

Parameters:
  • ref_kind
  • classobjClassAnalysis object to link
  • methodobj
  • offset – Offset in the methods bytecode, where the call happens
Returns:

AddXrefTo(ref_kind, classobj, methodobj, offset)

Creates a crossreference to another class. XrefTo means, that the current class calls another class. The current class should also be contained in the another class’ XrefFrom list.

Parameters:
  • ref_kind
  • classobjClassAnalysis object to link
  • methodobj
  • offset – Offset in the Methods Bytecode, where the call happens
Returns:

get_fake_method(name, descriptor)

Search for the given method name and descriptor and return a fake (ExternalMethod) if required.

Parameters:
  • name – name of the method
  • descriptor – descriptor of the method, for example ‘(I I I)V’
Returns:

ExternalMethod

get_field_analysis(field)
get_fields()

Return all FieldClassAnalysis objects of this class

get_method_analysis(method)

Return the MethodClassAnalysis object for a given EncodedMethod

Parameters:methodEncodedMethod
Returns:MethodClassAnalysis
get_methods()

Return all MethodClassAnalysis objects of this class

get_nb_methods()

Get the number of methods in this class

get_vm_class()
get_xref_from()
get_xref_to()
is_android_api()

Tries to guess if the current class is an Android API class.

This might be not very precise unless an apilist is given, with classes that are in fact known APIs. Such a list might be generated by using the android.jar files.

Returns:boolean
is_external()

Tests wheather this class is an external class

Returns:True if the Class is external, False otherwise
class androguard.core.analysis.analysis.DVMBasicBlock(start, vm, method, context)

Bases: object

A simple basic block of a dalvik method

add_note(note)
clear_notes()
get_end()
get_exception_analysis()
get_instructions()

Get all instructions from a basic block.

Return type:Return all instructions in the current basic block
get_last()
get_last_length()
get_method()
get_name()
get_nb_instructions()
get_next()

Get next basic blocks

Return type:a list of the next basic blocks
get_notes()
get_prev()

Get previous basic blocks

Return type:a list of the previous basic blocks
get_special_ins(idx)

Return the associated instruction to a specific instruction (for example a packed/sparse switch)

Parameters:idx – the index of the instruction
Return type:None or an Instruction
get_start()
push(i)
set_childs(values)
set_exception_analysis(exception_analysis)
set_fathers(f)
set_notes(value)
show()
class androguard.core.analysis.analysis.ExceptionAnalysis(exception, bb)

Bases: object

get()
show_buff()
class androguard.core.analysis.analysis.Exceptions(_vm)

Bases: object

add(exceptions, basic_blocks)
get()
get_exception(addr_start, addr_end)
gets()
class androguard.core.analysis.analysis.ExternalClass(name)

Bases: object

GetMethod(name, descriptor)
get_method(name, descriptor)

Get the method by name and descriptor, or create a new one if the requested method does not exists.

Parameters:
  • name – method name
  • descriptor – method descriptor, for example ‘(I)V’
Returns:

ExternalMethod

get_methods()

Return the stored methods for this external class :return:

get_name()

Returns the name of the ExternalClass object

class androguard.core.analysis.analysis.ExternalMethod(class_name, name, descriptor)

Bases: object

get_access_flags_string()
get_class_name()
get_descriptor()
get_name()
class androguard.core.analysis.analysis.FieldClassAnalysis(field)

Bases: object

AddXrefRead(classobj, methodobj)
AddXrefWrite(classobj, methodobj)
get_field()
get_xref_read()
get_xref_write()
class androguard.core.analysis.analysis.MethodAnalysis(vm, method)

Bases: object

get_basic_blocks()
Return type:a BasicBlocks object
get_length()
Return type:an integer which is the length of the code
get_method()
get_vm()
show()

Prints the content of this method to stdout.

This will print the method signature and the decompiled code.

class androguard.core.analysis.analysis.MethodClassAnalysis(method)

Bases: object

AddXrefFrom(classobj, methodobj, offset)

Add a crossrefernece from another method (this method is called by another method)

Parameters:
AddXrefTo(classobj, methodobj, offset)

Add a crossreference to another method (this method calls another method)

Parameters:
get_method()

Return the EncodedMethod object that relates to this object :return: dvm.EncodedMethod

get_xref_from()

Returns a list of three tuples cotaining the class, method and offset of the call, from where this object was called.

The list of tuples has the form: (ClassAnalysis, EncodedMethod or ExternalMethod, int)

get_xref_to()

Returns a list of three tuples cotaining the class, method and offset of the call, which are called by this method.

The list of tuples has the form: (ClassAnalysis, EncodedMethod or ExternalMethod, int)

is_android_api()

Returns True if the method seems to be an Android API method.

This method might be not very precise unless an list of known API methods is given.

Returns:boolean
is_external()

Return True if the underlying methd is external

Return type:boolean
class androguard.core.analysis.analysis.StringAnalysis(value)

Bases: object

AddXrefFrom(classobj, methodobj)
get_orig_value()
get_value()
get_xref_from()
set_value(value)
androguard.core.analysis.analysis.is_ascii_obfuscation(vm)

Tests if any class inside a DalvikVMObject uses ASCII Obfuscation (e.g. UTF-8 Chars in Classnames)

Parameters:vmDalvikVMObject
Returns:True if ascii obfuscation otherwise False

androguard.core.analysis.auto module

class androguard.core.analysis.auto.AndroAuto(settings)

Bases: object

The main class which analyse automatically android apps by calling methods from a specific object :param settings: the settings of the analysis :type settings: dict

dump()

Dump the analysis

dump_file(filename)

Dump the analysis in a filename

go()

Launch the analysis

class androguard.core.analysis.auto.DefaultAndroAnalysis

Bases: object

This class can be used as a template in order to analyse apps

analysis_adex(log, adexobj)

This method is called in order to know if the analysis must continue

Parameters:
  • log – an object which corresponds to a unique app
  • adexobj – a VMAnalysis object
Return type:

a boolean

analysis_apk(log, apkobj)

This method is called in order to know if the analysis must continue

Parameters:
  • log – an object which corresponds to a unique app
  • apkobj – a APK object
Return type:

a boolean

analysis_app(log, apkobj, dexobj, adexobj)

This method is called if you wish to analyse the final app

Parameters:
  • log – an object which corresponds to a unique app
  • apkobj – a APK object
  • dexobj – a DalvikVMFormat object
  • adexobj – a VMAnalysis object
analysis_arsc(log, arscobj)

This method is called in order to know if the analysis must continue

Parameters:
  • log – an object which corresponds to a unique app
  • arscobj – a ARSCParser object
Return type:

a boolean

analysis_axml(log, axmlobj)

This method is called in order to know if the analysis must continue

Parameters:
  • log – an object which corresponds to a unique app
  • axmlobj – a AXMLPrinter object
Return type:

a boolean

analysis_dex(log, dexobj)

This method is called in order to know if the analysis must continue

Parameters:
  • log – an object which corresponds to a unique app
  • dexobj – a DalvikVMFormat object
Return type:

a boolean

analysis_dey(log, deyobj)

This method is called in order to know if the analysis must continue

Parameters:
  • log – an object which corresponds to a unique app
  • deyobj – a DalvikOdexVMFormat object
Return type:

a boolean

crash(log, why)

This method is called if a crash appends

Parameters:
  • log – an object which corresponds to a unique app
  • why – the string exception
create_adex(log, dexobj)

This method is called in order to create a VMAnalysis object

Parameters:
  • log – an object which corresponds to a unique app
  • dexobj – a DalvikVMFormat object
Rytpe:

a Analysis object

create_apk(log, fileraw)

This method is called in order to create a new APK object

Parameters:
  • log – an object which corresponds to a unique app
  • fileraw – the raw apk (a string)
Return type:

an APK object

create_arsc(log, fileraw)

This method is called in order to create a new ARSC object

Parameters:
  • log – an object which corresponds to a unique app
  • fileraw – the raw arsc (a string)
Return type:

an APK object

create_axml(log, fileraw)

This method is called in order to create a new AXML object

Parameters:
  • log – an object which corresponds to a unique app
  • fileraw – the raw axml (a string)
Return type:

an APK object

create_dex(log, dexraw)

This method is called in order to create a DalvikVMFormat object

Parameters:
  • log – an object which corresponds to a unique app
  • dexraw – the raw classes.dex (a string)
Return type:

a DalvikVMFormat object

create_dey(log, dexraw)

This method is called in order to create a DalvikOdexVMFormat object

Parameters:
  • log – an object which corresponds to a unique app
  • dexraw – the raw odex file (a string)
Return type:

a DalvikOdexVMFormat object

dump()

This method is called to dump the result

dump_file(filename)

This method is called to dump the result in a file

Parameters:filename – the filename to dump the result
fetcher(q)

This method is called to fetch a new app in order to analyse it. The queue must be fill with the following format: (filename, raw)

Parameters:q – the Queue to put new app
filter_file(log, fileraw)

This method is called in order to filer a specific app

Parameters:
  • log – an object which corresponds to a unique app
  • fileraw – the raw app (a string)
Return type:

a set with 2 elements, the return value (boolean) if it is necessary to continue the analysis and the file type

finish(log)

This method is called before the end of the analysis

Parameters:log – an object which corresponds to a unique app
class androguard.core.analysis.auto.DirectoryAndroAnalysis(directory)

Bases: androguard.core.analysis.auto.DefaultAndroAnalysis

A simple class example to analyse a directory

fetcher(q)

This method is called to fetch a new app in order to analyse it. The queue must be fill with the following format: (filename, raw)

Parameters:q – the Queue to put new app

Module contents