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: vm – dvm.DalvikVMFormat
to add to this Analysis
-
create_ipython_exports
()¶ Warning
this feature is experimental and is currently not enabled by default! Use with caution!
Creates attributes for all classes, methods and fields on the Analysis object itself. This makes it easier to work with Analysis module in an iPython shell.
Classes can be search by typing
dx.CLASS_<tab>
, as each class is added via this attribute name. Each class will have all methods attached to it viadx.CLASS_Foobar.METHOD_<tab>
. Fields have a similar syntax:dx.CLASS_Foobar.FIELD_<tab>
.As Strings can contain nearly anything, use
find_strings()
instead.- Each CLASS_ item will return a
ClassAnalysis
- Each METHOD_ item will return a
MethodClassAnalysis
- Each FIELD_ item will return a
FieldClassAnalysis
- Each CLASS_ item will return a
-
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
objectsReturns 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 givenEncodedMethod
. This Analysis object is used to enhance EncodedMethods.Parameters: method – EncodedMethod
to search forReturns: 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 aMethodAnalysis
object, while this function returns aMethodClassAnalysis
object!This Method will only work after a run of
create_xref()
Parameters: method – EncodedMethod
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 nameParameters: - 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:
-
get_method_by_name
(class_name, method_name, method_descriptor)¶ Search for a
EncodedMethod
in all classes in this analysisParameters: - 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
objectsReturn 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 –
- classobj –
ClassAnalysis
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 –
- classobj –
ClassAnalysis
object to link - methodobj –
- offset – Offset in the Methods Bytecode, where the call happens
Returns:
-
extends
¶ Return the parent class
For external classes, this is not sure, thus we return always Object (which is the parent of all classes)
Returns: a string of the parent class name
-
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:
-
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: method – EncodedMethod
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
()¶
-
implements
¶ Get a list of interfaces which are implemented by this class
Returns: a list of Interface names
-
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
-
name
¶ Return the class name
Returns:
-
-
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)¶ Deprecated since version 3.1.0: Use
get_method()
instead.
-
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:
-
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
()¶
-
name
¶
-
-
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: - classobj –
ClassAnalysis
- methodobj –
EncodedMethod
- offset – integer where in the method the call happens
- classobj –
-
AddXrefTo
(classobj, methodobj, offset)¶ Add a crossreference to another method (this method calls another method)
Parameters: - classobj –
ClassAnalysis
- methodobj –
EncodedMethod
- offset – integer where in the method the call happens
- classobj –
-
access
¶ Returns the access flags to the method as a string
-
descriptor
¶ Returns the type descriptor for this method
-
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
orExternalMethod
, 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
orExternalMethod
, 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
-
name
¶ Returns the name of this method
-
-
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: vm – DalvikVMObject 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
Automatic analysis requires two objects to be created:
- a Logger, found at key log in the settings
- an Analysis runner, found at key my in the settings
Both are passed to
AndroAuto
via a dictionary. The setting dict understands the following keys:- my: The Analysis runner (required)
- log: The Logger
- max_fetcher: Maximum number of concurrent threads
DefaultAndroLog
can be used as a baseclass for the Logger, whileDefaultAndroAnalysis
can be used a baseclass for the Analysis. There is alsoDirectoryAndroAnalysis
which implements a fetcher which recursively reads a directory for files and can be used a baseclass as well.example:
from androguard.core.analysis import auto class AndroTest(auto.DirectoryAndroAnalysis): # This is the Test Runner def analysis_app(self, log, apkobj, dexobj, analysisobj): # Just print all objects to stdout print(log.id_file, log.filename, apkobj, dexobj, analysisobj) settings = { # The directory `some/directory` should contain some APK files "my": AndroTest('some/directory'), # Use the default Logger "log": auto.DefaultAndroLog, # Use maximum of 2 threads "max_fetcher": 2, } aa = auto.AndroAuto(settings) aa.go()
Parameters: settings (dict) – the settings of the analysis -
dump
()¶ Dump the analysis
Calls dump() on the Analysis object
-
dump_file
(filename)¶ Dump the analysis into a file
Calls dump_file(filename) on the Analysis object
-
go
()¶ Launch the analysis.
this will start a total of max_fetcher threads.
-
class
androguard.core.analysis.auto.
DefaultAndroAnalysis
¶ Bases:
object
This class can be used as a template in order to analyse apps
The order of methods called in this class is the following:
fetcher()
is called to get filesfilter_file()
is called to get the filetypecreate_apk()
orcreate_axml()
orcreate_arsc()
andcreate_dex()
orcreate_dey()
depending on the filetypeanalysis_apk()
oranalysis_axml()
oranalysis_arsc()
andanalysis_dex()
oranalysis_dey()
depending on the filetypecreate_adex()
if at least one dex was foundanalysis_app()
with all the gathered objects so farfinish()
is called in any case after the analysis
crash()
can be called during analysis if any Exception happens.-
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 (androguard.core.analysis.analysis.Analysis) – a
Analysis
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 (androguard.core.bytecodes.apk.APK) – a
APK
object
Returns: True if a DEX file should be analyzed as well
Return type: bool
-
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 (androguard.core.bytecodes.apk.APK) – a
APK
object - dexobj (androguard.core.bytecodes.dvm.DalvikVMFormat) – a
DalvikVMFormat
object - adexobj (androguard.core.analysis.analysis.Analysis) – a
Analysis
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 (androguard.core.bytecodes.axml.ARSCParser) – a
ARSCParser
object
Returns: True if the analysis should continue afterwards
Return type: bool
-
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 (androguard.core.bytecodes.axml.AXMLPrinter) – a
AXMLPrinter
object
Returns: True if the analysis should continue afterwards
Return type: bool
-
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 (androguard.core.bytecodes.dvm.DalvikVMFormat) – a
DalvikVMFormat
object
Returns: True if the analysis should continue with an analysis.Analysis
Return type: bool
-
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 (androguard.core.bytecodes.dvm.DalvikOdexVMFormat) – a
DalvikOdexVMFormat
object
Returns: True if the analysis should continue with an analysis.Analysis
Return type: bool
-
crash
(log, why)¶ This method is called if a crash happens
Parameters: - log – an object which corresponds to an unique app
- why – the exception
-
create_adex
(log, dexobj)¶ This method is called in order to create an Analysis object
Parameters: - log – an object which corresponds to a unique app
- dexobj (androguard.core.bytecodes.dvm.DalvikVMFormat) – 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
ARSCParser
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
AXMLPrinter
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)
must return False if the queue is filled, thus all files are read.
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 (bytes) – the raw file as bytes
Return type: a tuple 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 an unique app
-
class
androguard.core.analysis.auto.
DefaultAndroLog
(id_file, filename)¶ Bases:
object
A base class for the Androguard Auto Logger.
The Logger contains two attributes of the analyzed File:
filename
andid_file
, which is the Adler32 Checksum of the file.The Logger can be extended to contain more attributes.
-
class
androguard.core.analysis.auto.
DirectoryAndroAnalysis
(directory)¶ Bases:
androguard.core.analysis.auto.DefaultAndroAnalysis
A simple class example to analyse a whole directory with many APKs in it
-
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)
must return False if the queue is filled, thus all files are read.
Parameters: q – the Queue to put new app
-