Build instructions and running instructions to come.
- This repo pulled from git
- A version of JDK 8 somewhere in your path. This project has been built and run using Java 8. It will likely build and run for newer versions of Java, but it has not been tested as such. Note: If Java 8 is not in the path, this should still build fine as the build process uses Gradle 7 and is configured to automatically download the required Java version if not present. However, it may be easier to install the appropriate JDK manually.
-
Make sure your system matches the requirements above.
-
Run one of the following commands from inside the pulled git repo.
# Linux/OSX (pulls and runs the approiate version of gradle before building) ./gradlew build # Windows (pulls and runs the approiate version of gradle before building) ./gradlew.bat build # Gradle 7.3.3 on path (uses gradle that has been manually installed) gradle build
-
The above commands produce two jars in the
build/libsfolder:ACMiner.jarandACMiner-All.jar. Both will run ACMiner. However,ACMiner-All.jarcompiles together all dependencies into a single runnable jar that should run on any system with Java 8 installed whileACMiner.jarmust be run frombuild/libson the same system. The latter includes no dependencies and relies on the dependencies maven pulls while building.
From the jar help message we can see that ACMiner requires the user to provide several input files in order to run. Note work here is whatever working directory you specify to the jar.
work/acminer/excluded_elements_db.txt,
work/acminer/context_queries_descriptor_db.xml,
work/acminer/control_predicate_filter_db.xml,
work/system_img.zip,
work/android_info.xml
A example of each required input file is provided in the samples folder except for system_img.zip. All these example files have been fine-tuned for AOSP 10.0.0 and can used to run ACMiner on AOSP 10 and below. Minor modifications to these files may be required for OEM versions of Android and newer versions of Android.
Excluded classes and methods are defined in the file work/acminer/excluded_elements_db.txt and are the primary way to reduce call graph bloat. Excluding a method or class means that the method or all the methods in a class will not be considered in the analysis of ACMiner and will appear as end points in the call graph generated by Soot.
The easiest way to provide this file is to copy the example file in samples/acminer/excluded_elements_db.txt and modify it as needed. To modify the text file, first note that each line begins with either a +/-, where + adds elements to the exclude list and - remove them from the list. The basic entries in the exclude list text file are as follows.
# Excludes all classes and methods in the package java. and all packages below it
+ ClassPath [all] java.*
# Excludes the methods in the class android.util.Log
+ ClassPath [all] android.util.Log
# Excludes the all methods in the class java.lang.Throwable and all methods in any class
# that extends java.lang.Throwable. This effectively removes exceptions from the analysis.
+ SuperClass [all] java.lang.Throwable
# Excludes all methods in the class java.lang.Object and methods in any class that extends
# it but only if the method is overriding a method of the java.lang.Object class. This
# would eliminate methods list equals, hashCode, and toString.
+ SuperClass java.lang.Object
# Excludes all the methods defined in the java.util.Map and implemented in the various
# child classes
+ Interface java.util.Map
# Excludes a single method by method signature
+ MethodSignature <com.android.server.wm.WindowStateAnimator: void dump(java.io.PrintWriter,java.lang.String,boolean)>To know what to add to the exclude list, run the jar with the gradle acminerDebugLite or the gradle acminerDebug options described below. Then run the scripts/getcgexpeps.sh file passing it the cg_method that was output by the above ACMiner command and the lower file size bound in MB. This script will identify all files in a directory that are larger than the defined lower bound in MB which generally indicates some kind of call graph bloat. See the script help message for specifics on how to pass in these arguments.
The cg_method directory will be under the debug directory of the working directory of ACMiner and contains the call graph of each entry point method as a graphml file. As a rule of thumb, a call graph of an entry point should not be more than 8-10 MB maximum for some outliers, but on average should be around 5 MB or less. As such, the default value of 10 MB for the lower file size bound in MB generally works, but you may need to adjust it to a lower value as you try and eliminate call graph bloat.
Once you have identified entry points potentially containing call graph bloat, note the name and containing class of the entry point and locate the file by the same name in the cg_method_limit directory of the debug directory (i.e., the directory of call graphs for each entry point limited to a deapth of 5 by default). Open this file in a renderer of graphml files like yed to visualize the call graph. Attempt to locate the cause or causes of call graph bloat in the call graph. If it cannot be found, you may need to re-run the gradle acminerDebugLite or the gradle acminerDebug commands with a larger depth for CGMethodLimit:5. You may also with to try opening the graph files in the cg_method directory. However, the larger the graphml file is the less likely yed is to be able to render it given resource constraints. You may also try locating the files for the entry point in the other output directories of debug and looking at their data.
Note when excluding methods in the call graph, ensure the methods do not contain control predicates and that the methods are not context queries. If the methods are context queries and you need to add them to the exclude list, make sure the excluded context queries are also described in the context queries descriptor file (see below). If the method you want to exclude contains control predicates but is not a context query this may not be the right method to add to the exclude list. Refer to the paper for the differences between context queries and control predicates so that you may identify them properly.
Context queries or known authorization check methods are defined in a sudo-regex manner in the file work\acminer\context_queries_descriptor_db.xml. The easiest way to provide this file is to copy the example file in samples\acminer\context_queries_descriptor_db.xml and modify it as needed.
There are two ways of running ACMiner: from gradle and directly from the jar.
ACMiner can be run from Gradle using one of the following commands below. In the commands below, replace gradle with ./graldew or ./gradle.bat as needed. For specifics on what the commands below do run gralde tasks and look under Run Tasks for descriptions. For more information, see the jar help message.
# Performs a complete run of ACMiner with default options. Use this if you want to perform
# a normal run of ACMiner.
gradle acminer
# Runs the ACMinerDebug phase of the ACMiner phase group with options set to produce the
# most useful information ACMiner can output to aid the user in eliminating entry
# point call graph bloat.
gradle acminerDebugLite
# Runs the ACMinerDebug phase of the ACMiner phase group with all options enabled. This
# will cause ACMiner to output all the information it can in regards to eliminating entry
# point call graph bloat.
gradle acminerDebug
# Enables all debugging options for all phases of ACMiner in addition to running the
# ACMinerDebug phase of the ACMiner phase group with all options enabled. This produces
# an extreme amount of output and should only be used when there is an actual error in
# the ACMiner tool itself and not just an issue with call graph bloat.
gradle acminerDebugAll
# Output the help message
gradle helpDiagThe options for the above tasks may be customized by giving the jar arguments through gradle using the following example format --args='-i \"path/to/working dir\"', where everything inside the '' of --args= would be formatted exactly as if it was passed directly to the jar.
Additionally, you may also customize the jvm arguments using the following example format -Djvmargs='-Xms32g -Xmx32g'. Note setting the jvm arguments overrides the default jvm arguments, which are '-Xms8g -Xmx(max_free_memory - 2)g', and is not recommended.
Simply use the command java -Xms8g -Xmx32g -jar ACMiner-All.jar and adjust the -Xmx value to be the max your system can support. Equlivant jar commands for the gradle commands above are as follows.
# Same as gradle acminer
java -Xms8g -Xmx32g -jar ACMiner-All.jar --ACMiner
# Same as gradle acminerDebugLite
java -Xms8g -Xmx32g -jar ACMiner-All.jar -p ACMiner ACMinerDebug enable:true,Paths:true,CGMethod:true,CGMethodLimit:5
# gradle acminerDebug
java -Xms8g -Xmx32g -jar ACMiner-All.jar --ACMinerDebugWithAllOption
# gradle acminerDebugAll
java -Xms8g -Xmx32g -jar ACMiner-All.jar --ACMinerAllDebugOptions
# Same as gradle helpDiag
java -Xms8g -Xmx32g -jar ACMiner-All.jar -hSee the jar help message for more information and other possible arguments.
This is the same message you will get if you run gradle helpDiag or java -jar ACMiner-All.jar -h.
Usage: [-h|--help] [-i <dir>] [-p <phase_group> <phase_1>
<phase_opt_1>:<value_1>,<phase_opt_2>:<value_2>,...,<phase_opt_n>:<val
ue_n> <phase_2> <phase_opt>:<value> ... <phase_n> <phase_opt>:<value>]
[--<quick_option>]
Examples: [java -jar ACMiner-All.jar -h], [java -jar ACMiner-All.jar --ACMiner],
[java -jar ACMiner-All.jar -p ACMiner ACMinerDebug
enable:true,Paths:true,CGMethod:true,CGMethodLimit:5], [java -jar
ACMiner-All.jar --ACMinerDebugWithAllOption]
Options:
-h|--help - Display this help message.
-i <dir> - The path to the working directory. This directory
should contain the input files for whatever phases are
enabled and the files should be in the appropriate
directories. See the descriptions of the phases below
for specific file locations relative to this supplied
working directory.This directory will also be used to
write output files as indicated in the phase
descriptions below.
-p <pg> <p> <po>:<v> - Set the phase options for the phase groups that will
run. The format of this is follows after the indicator
-p. 1) The <phase_group> (<pg>) specifies the phase
group of the phases and phase options. Phases may be
used by multiple phase groups with different options in
the same run. 2) The <phase> (<p>) indicates the phase
that the options are for. A phase identifier is always
followed by 3) a list of comma separated <phase_option>
(<po>) and <value> (<v>) pairs for the proceeding phase
identifier. Each phase option and value pair is
separated by a colon. There can be as many phase option
and value pairs in the comma separated list as needed
so long as they are for the proceeding phase
identifier. The comma separated list of phase options
and value pairs should contain no spaces unless it is
in the value field. Spaces in the value field must be
quoted. Multiple phase and phase option list pairs may
be provided so long as they are for the proceeding
phase group. For a description of the phase groups,
their phases, and their phase options see below.
--<quick_option> - A means of quickly specifying commonly used phase
options for a specific phase group. A quick option id
always begins with the phase group it is associated
with followed by a unique identifier that describes its
purpose. Every phase group has at least one quick
option (i.e. the default) that is equal to the name of
the phase group. This default is a quick way of
specifying that a complete run of the all phases in the
phase group should be performed sans any debugging
phases or debugging phase options.
Note: Enabling a phase in a phase group will automatically enable all other
phases in that group that the phase depends on. There is no need for
the user to individually enable each phase that needs to run. Simply
enabling the last phase a user wishes to run will enable all other
required phases. The phases in each phase group listed below are
listed according to hierarchy (i.e. run order from first to last) and
also indicate the phase or phases they immediately depend on. For
example, enabling the ACMiner phase of the ACMiner phase group will
enable all other phases listed above it sans any debugging phases.
Note: The input files listed at the beginning of each phase group are the
minimum files a user must provide to be able to perform a full run of
the phase group. A full run is defined here as the the phases enabled
by the default quick option of a phase group (i.e. --ACMiner for the
phase group ACMiner).
+++++++++++++++++++++++++++++++++[Phase Groups]+++++++++++++++++++++++++++++++++
==================================[ACMiner]===================================
Description - The authorization check miner phase group. Use this phase
group if a run of ACMiner is desired.
Input Files - work\acminer\excluded_elements_db.txt,
work\acminer\context_queries_descriptor_db.xml,
work\acminer\control_predicate_filter_db.xml,
work\system_img.zip, work\android_info.xml
Quick Options:
--ACMiner - Runs ACMiner with default options for
all required phases. = (-p ACMiner
ACMiner enable:true)
--ACMinerPreCallGraph - Runs the phases of ACMiner that do not
require a Call Graph to be generated. =
(-p ACMiner ExcludedElements
enable:true)
--ACMinerDefUseGraphDump - Enables the phases that dump the
def-use graph both before and after the
ControlPredicateFilter phase. Note that
if this option is used alone, the
ControlPredicateFilter phase will be
the last of the normal ACMiner phases
to be run. = (-p ACMiner
DefUseGraphDumpBeforeFilter enable:true
DefUseGraphDumpAfterFilter enable:true)
--ACMinerDebugWithAllOption - Enables all options on the ACMinerDebug
phase. If a option requires a value its
default value is used. Note that if
this option is used alone, the
CallGraph phase will be the last of the
normal ACMiner phases to be run. = (-p
ACMiner ACMinerDebug
enable:true,All:true)
--ACMinerAllDebugOptions - Runs ACMiner with all debugging options
or phases enabled. The output from
using this option is extremely verbose
(large amount of data written to disk)
and may result in extreme slow downs. =
(-p ACMiner DefUseGraphDumpBeforeFilter
enable:true DefUseGraphDumpAfterFilter
enable:true ACMinerDebug
enable:true,All:true
ControlPredicateMarker EnableDebug:true
ControlPredicateFilter EnableDebug:true
ACMiner EnableDebug:true)
--ACMinerVariedAnalysis - Enables the VariedAnalysis phase. See
phase description. = (-p ACMiner
VariedAnalysis enable:true)
--ACMinerVariedCallGraphAnalysis - Enables the VariedCallGraphAnalysis
phase. See phase description. = (-p
ACMiner VariedCallGraphAnalysis
enable:true)
Phases:
--------------------------------------------------------------------------
[JimpleJar] - From the files of a system image, this phase identifies the
java class of the Android system, converts the classes to the Soot's
intermediate representation Jimple, and creates a Jimple JAR to house the
converted class files. This Jimple JAR contains all the classes analyzed
in later analysis phases.
Input Files - work\system_img.zip, work\android_info.xml
Output Files - work\sje\system_jimple.jar
Additional Paths - work\sje\system_archives.zip,
work\sje\system_jimple_framework_only.jar,
work\sje\system_jimple_class_conflicts.zip,
work\sje\work, work\system_class.jar,
work\system_img.zip, work\android_info.xml,
work\sje\system_class.jar,
work\sje\framework_pkgs.txt
Phase Options:
enable - Specifies if the phase 'JimpleJar' is enabled. Thus
the phase may run if a run is required as determined
by the input and output files for the phase. - (Type
= Boolean, Default = false)
force-run - If the phase 'JimpleJar' is enabled setting this
option forces the phase to run even if the phase
output files exist and no changes are detected in
the required phase input files. - (Type = Boolean,
Default = false)
--------------------------------------------------------------------------
[EntryPoints] - Identifies all methods called in the onTransact method of
Binder Stub classes that are defined in the child classes of the Binder
Stub classes. These methods are considered RPC Entry Points into the
Android System and associated with the transaction ID used to call them in
the onTransact method.
Dependency Phases - JimpleJar
Input Files - work\sje\system_jimple.jar
Output Files - work\acminer\entry_points_db.xml
Phase Options:
enable - Specifies if the phase 'EntryPoints' is enabled.
Thus the phase may run if a run is required as
determined by the input and output files for the
phase. - (Type = Boolean, Default = false)
force-run - If the phase 'EntryPoints' is enabled setting this
option forces the phase to run even if the phase
output files exist and no changes are detected in
the required phase input files. - (Type = Boolean,
Default = false)
--------------------------------------------------------------------------
[BinderGroups] - Uses the data generated during the EntryPoints phase to
identify the IInterface and Proxy classes and methods associated the Stub
and RPC Entry Points. This gives a more complete overview of the
mechanisms that may be used to call an RPC Entry Point.
Dependency Phases - EntryPoints
Input Files - work\sje\system_jimple.jar,
work\acminer\entry_points_db.xml
Output Files - work\acminer\binder_groups_db.xml
Phase Options:
enable - Specifies if the phase 'BinderGroups' is enabled.
Thus the phase may run if a run is required as
determined by the input and output files for the
phase. - (Type = Boolean, Default = false)
force-run - If the phase 'BinderGroups' is enabled setting this
option forces the phase to run even if the phase
output files exist and no changes are detected in
the required phase input files. - (Type = Boolean,
Default = false)
--------------------------------------------------------------------------
[BinderServices] - Identifies the Binder services registered with the
Service Manager for a specific build of Android. Only those services
registered with the Service Manager can have RPC Entry Points callable
through binder.
Dependency Phases - BinderGroups
Input Files - work\sje\system_jimple.jar,
work\acminer\entry_points_db.xml,
work\acminer\binder_groups_db.xml
Output Files - work\acminer\binder_services_db.xml
Phase Options:
enable - Specifies if the phase 'BinderServices' is enabled.
Thus the phase may run if a run is required as
determined by the input and output files for the
phase. - (Type = Boolean, Default = false)
force-run - If the phase 'BinderServices' is enabled setting
this option forces the phase to run even if the
phase output files exist and no changes are detected
in the required phase input files. - (Type =
Boolean, Default = false)
--------------------------------------------------------------------------
[VariedAnalysis] - Houses optional analysis components that do not require
the call graph being generated. This phase will not be run unless one of
its options is enabled.
Dependency Phases - JimpleJar
Input Files - work\sje\system_jimple.jar
Phase Options:
enable - Specifies if the phase 'VariedAnalysis' is enabled.
Thus the phase may run if a run is required as
determined by the input and output files for the
phase. - (Type = Boolean, Default = false)
force-run - If the phase 'VariedAnalysis' is enabled setting
this option forces the phase to run even if the
phase output files exist and no changes are detected
in the required phase input files. - (Type =
Boolean, Default = false)
DumpNative - Dumps all the native methods to a file. - (Type =
Boolean, Default = false)
--------------------------------------------------------------------------
[ExcludedElements] - Generates a list of the excluded methods for this
build of Android to be used when construction the Call Graph. This is
based on the classes and methods defined in the exclude list text file.
Dependency Phases - BinderServices
Input Files - work\sje\system_jimple.jar,
work\acminer\entry_points_db.xml,
work\acminer\binder_groups_db.xml,
work\acminer\binder_services_db.xml,
work\acminer\excluded_elements_db.txt
Output Files - work\acminer\excluded_elements_db.xml
Phase Options:
enable - Specifies if the phase 'ExcludedElements' is
enabled. Thus the phase may run if a run is required
as determined by the input and output files for the
phase. - (Type = Boolean, Default = false)
force-run - If the phase 'ExcludedElements' is enabled setting
this option forces the phase to run even if the
phase output files exist and no changes are detected
in the required phase input files. - (Type =
Boolean, Default = false)
--------------------------------------------------------------------------
[CallGraph] - Uses CHA to construct a Call Graph for all RPC Entry Points.
Dependency Phases - ExcludedElements
Input Files - work\sje\system_jimple.jar,
work\acminer\entry_points_db.xml,
work\acminer\binder_groups_db.xml,
work\acminer\binder_services_db.xml,
work\acminer\excluded_elements_db.txt,
work\acminer\excluded_elements_db.xml
Phase Options:
enable - Specifies if the phase 'CallGraph' is enabled. Thus
the phase may run if a run is required as determined
by the input and output files for the phase. - (Type
= Boolean, Default = false)
force-run - If the phase 'CallGraph' is enabled setting this
option forces the phase to run even if the phase
output files exist and no changes are detected in
the required phase input files. - (Type = Boolean,
Default = false)
--------------------------------------------------------------------------
[VariedCallGraphAnalysis] - Houses optional analysis components that
require the call graph to be generated. This phase will not be run unless
on of its options is enabled.
Dependency Phases - CallGraph
Input Files - work\sje\system_jimple.jar,
work\acminer\entry_points_db.xml,
work\acminer\binder_groups_db.xml,
work\acminer\binder_services_db.xml,
work\acminer\excluded_elements_db.txt,
work\acminer\excluded_elements_db.xml
Phase Options:
enable - Specifies if the phase 'VariedCallGraphAnalysis' is
enabled. Thus the phase may run if a run is required
as determined by the input and output files for the
phase. - (Type = Boolean, Default = false)
force-run - If the phase 'VariedCallGraphAnalysis' is enabled
setting this option forces the phase to run even if
the phase output files exist and no changes are
detected in the required phase input files. - (Type
= Boolean, Default = false)
ReachingGraphs - Read in the given file containing method sinks and
output reaching graphs for all entry points that
call these methods. The graphs contain only paths to
these sinks and are in the .tgf format. - (Type =
Path, Default = work\acminer\sinks.txt)
DumpNative - Dumps the native methods reachable from the entry
points to files. - (Type = Boolean, Default = false)
--------------------------------------------------------------------------
[AccessControlMarker] - Identifies known access control methods based on
the context queries descriptor file.
Dependency Phases - CallGraph
Input Files - work\sje\system_jimple.jar,
work\acminer\entry_points_db.xml,
work\acminer\binder_groups_db.xml,
work\acminer\binder_services_db.xml,
work\acminer\excluded_elements_db.txt,
work\acminer\excluded_elements_db.xml,
work\acminer\context_queries_descriptor_db.xml
Output Files - work\acminer\context_queries_db.xml,
work\acminer\throw_security_exceptions_db.xml,
work\acminer\entry_point_edges_db.xml
Phase Options:
enable - Specifies if the phase 'AccessControlMarker' is
enabled. Thus the phase may run if a run is required
as determined by the input and output files for the
phase. - (Type = Boolean, Default = false)
force-run - If the phase 'AccessControlMarker' is enabled
setting this option forces the phase to run even if
the phase output files exist and no changes are
detected in the required phase input files. - (Type
= Boolean, Default = false)
--------------------------------------------------------------------------
[ControlPredicateMarker] - Identifies control predicates based on the
marked context queries and placement of security exceptions.
Dependency Phases - AccessControlMarker
Input Files - work\sje\system_jimple.jar,
work\acminer\entry_points_db.xml,
work\acminer\binder_groups_db.xml,
work\acminer\binder_services_db.xml,
work\acminer\excluded_elements_db.txt,
work\acminer\excluded_elements_db.xml,
work\acminer\context_queries_descriptor_db.xml,
work\acminer\context_queries_db.xml,
work\acminer\throw_security_exceptions_db.xml,
work\acminer\entry_point_edges_db.xml
Output Files - work\acminer\control_predicates_db.xml
Phase Options:
enable - Specifies if the phase 'ControlPredicateMarker' is
enabled. Thus the phase may run if a run is required
as determined by the input and output files for the
phase. - (Type = Boolean, Default = false)
force-run - If the phase 'ControlPredicateMarker' is enabled
setting this option forces the phase to run even if
the phase output files exist and no changes are
detected in the required phase input files. - (Type
= Boolean, Default = false)
EnableDebug - Enables the dumping of debugging information for the
phase ControlPredicateMarker to log files. - (Type =
Boolean, Default = false)
DebugToConsole - If debugging information is enabled for the phase
ControlPredicateMarker this option causes the
information to be output to the terminal as well as
files. - (Type = Boolean, Default = false)
--------------------------------------------------------------------------
[DefUseGraph] - Generates a def-use graph of values used in the context
queries and currently marked control predicates.
Dependency Phases - ControlPredicateMarker
Input Files - work\sje\system_jimple.jar,
work\acminer\entry_points_db.xml,
work\acminer\binder_groups_db.xml,
work\acminer\binder_services_db.xml,
work\acminer\excluded_elements_db.txt,
work\acminer\excluded_elements_db.xml,
work\acminer\context_queries_descriptor_db.xml,
work\acminer\context_queries_db.xml,
work\acminer\throw_security_exceptions_db.xml,
work\acminer\entry_point_edges_db.xml,
work\acminer\control_predicates_db.xml
Output Files - work\acminer\defusegraph\_def_use_graph_db.xml
Phase Options:
enable - Specifies if the phase 'DefUseGraph' is enabled.
Thus the phase may run if a run is required as
determined by the input and output files for the
phase. - (Type = Boolean, Default = false)
force-run - If the phase 'DefUseGraph' is enabled setting this
option forces the phase to run even if the phase
output files exist and no changes are detected in
the required phase input files. - (Type = Boolean,
Default = false)
--------------------------------------------------------------------------
[DefUseGraphDumpBeforeFilter] - Dumps the def-use graph in a more readable
format before filtering out any control predicates. This phase will not be
run unless enabled.
Dependency Phases - DefUseGraph
Input Files - work\sje\system_jimple.jar,
work\acminer\entry_points_db.xml,
work\acminer\binder_groups_db.xml,
work\acminer\binder_services_db.xml,
work\acminer\excluded_elements_db.txt,
work\acminer\excluded_elements_db.xml,
work\acminer\context_queries_descriptor_db.xml,
work\acminer\context_queries_db.xml,
work\acminer\throw_security_exceptions_db.xml,
work\acminer\entry_point_edges_db.xml,
work\acminer\control_predicates_db.xml,
work\acminer\defusegraph\_def_use_graph_db.xml
Output Files - work\debug\2022-08-04_11-51-45\defusegraph_before_fi
lter\_file_hash_list_db.xml
Phase Options:
enable - Specifies if the phase 'DefUseGraphDumpBeforeFilter'
is enabled. Thus the phase may run if a run is
required as determined by the input and output files
for the phase. - (Type = Boolean, Default = false)
force-run - If the phase 'DefUseGraphDumpBeforeFilter' is
enabled setting this option forces the phase to run
even if the phase output files exist and no changes
are detected in the required phase input files. -
(Type = Boolean, Default = false)
--------------------------------------------------------------------------
[ControlPredicateFilter] - Filters out control predicates based on the
data in the def-use graph and the definitions in the control predicate
filter file.
Dependency Phases - DefUseGraph
Input Files - work\sje\system_jimple.jar,
work\acminer\entry_points_db.xml,
work\acminer\binder_groups_db.xml,
work\acminer\binder_services_db.xml,
work\acminer\excluded_elements_db.txt,
work\acminer\excluded_elements_db.xml,
work\acminer\context_queries_descriptor_db.xml,
work\acminer\context_queries_db.xml,
work\acminer\throw_security_exceptions_db.xml,
work\acminer\entry_point_edges_db.xml,
work\acminer\control_predicates_db.xml,
work\acminer\defusegraph\_def_use_graph_db.xml,
work\acminer\control_predicate_filter_db.xml
Output Files - work\acminer\control_predicates_filtered_db.xml
Additional Paths - work\acminer\control_predicates_db.xml
Phase Options:
enable - Specifies if the phase 'ControlPredicateFilter' is
enabled. Thus the phase may run if a run is required
as determined by the input and output files for the
phase. - (Type = Boolean, Default = false)
force-run - If the phase 'ControlPredicateFilter' is enabled
setting this option forces the phase to run even if
the phase output files exist and no changes are
detected in the required phase input files. - (Type
= Boolean, Default = false)
EnableDebug - Enables the dumping of debugging information for the
phase ControlPredicateFilter to log files. - (Type =
Boolean, Default = false)
DebugToConsole - If debugging information is enabled for the phase
ControlPredicateFilter this option causes the
information to be output to the terminal as well as
files. - (Type = Boolean, Default = false)
--------------------------------------------------------------------------
[DefUseGraphDumpAfterFilter] - Dumps the def-use graph in a more readable
format after filtering out control predicates. This phase will not be run
unless enabled.
Dependency Phases - ControlPredicateFilter
Input Files - work\sje\system_jimple.jar,
work\acminer\entry_points_db.xml,
work\acminer\binder_groups_db.xml,
work\acminer\binder_services_db.xml,
work\acminer\excluded_elements_db.txt,
work\acminer\excluded_elements_db.xml,
work\acminer\context_queries_descriptor_db.xml,
work\acminer\context_queries_db.xml,
work\acminer\throw_security_exceptions_db.xml,
work\acminer\entry_point_edges_db.xml,
work\acminer\control_predicates_db.xml,
work\acminer\defusegraph\_def_use_graph_db.xml,
work\acminer\control_predicate_filter_db.xml,
work\acminer\control_predicates_filtered_db.xml
Output Files - work\debug\2022-08-04_11-51-45\defusegraph_after_fil
ter\_file_hash_list_db.xml
Phase Options:
enable - Specifies if the phase 'DefUseGraphDumpAfterFilter'
is enabled. Thus the phase may run if a run is
required as determined by the input and output files
for the phase. - (Type = Boolean, Default = false)
force-run - If the phase 'DefUseGraphDumpAfterFilter' is enabled
setting this option forces the phase to run even if
the phase output files exist and no changes are
detected in the required phase input files. - (Type
= Boolean, Default = false)
--------------------------------------------------------------------------
[DefUseGraphMod] - Regenerates the def-use graph with the reduced list of
control predicates and additional information for authorization check
mining.
Dependency Phases - ControlPredicateFilter
Input Files - work\sje\system_jimple.jar,
work\acminer\entry_points_db.xml,
work\acminer\binder_groups_db.xml,
work\acminer\binder_services_db.xml,
work\acminer\excluded_elements_db.txt,
work\acminer\excluded_elements_db.xml,
work\acminer\context_queries_descriptor_db.xml,
work\acminer\context_queries_db.xml,
work\acminer\throw_security_exceptions_db.xml,
work\acminer\entry_point_edges_db.xml,
work\acminer\control_predicates_db.xml,
work\acminer\defusegraph\_def_use_graph_db.xml,
work\acminer\control_predicate_filter_db.xml,
work\acminer\control_predicates_filtered_db.xml
Output Files - work\acminer\defusegraphmod\_def_use_graph_db.xml
Phase Options:
enable - Specifies if the phase 'DefUseGraphMod' is enabled.
Thus the phase may run if a run is required as
determined by the input and output files for the
phase. - (Type = Boolean, Default = false)
force-run - If the phase 'DefUseGraphMod' is enabled setting
this option forces the phase to run even if the
phase output files exist and no changes are detected
in the required phase input files. - (Type =
Boolean, Default = false)
--------------------------------------------------------------------------
[ACMinerDebug] - Dumps an extensive amount of debugging information about
the state of the analysis. Use this phase to fine-tune files such as the
exclude list, context query definitions, and control predicate filter.
This phase will not be run unless one of its options is enabled.
Dependency Phases - CallGraph
Input Files - work\sje\system_jimple.jar,
work\acminer\entry_points_db.xml,
work\acminer\binder_groups_db.xml,
work\acminer\binder_services_db.xml,
work\acminer\excluded_elements_db.txt,
work\acminer\excluded_elements_db.xml
Phase Options:
enable - Specifies if the phase 'ACMinerDebug' is enabled.
Thus the phase may run if a run is required as
determined by the input and output files for the
phase. - (Type = Boolean, Default = false)
force-run - If the phase 'ACMinerDebug' is enabled setting this
option forces the phase to run even if the phase
output files exist and no changes are detected in
the required phase input files. - (Type = Boolean,
Default = false)
CFG - Dumps a control flow graph for any method that
contains authorization checks in graphml format. -
(Type = Boolean, Default = false)
CGMethod - Dumps the full method call graph for all entry
points in graphml format. - (Type = Boolean, Default
= false)
CGMethodLimit - Dumps the method call graph for all entry points in
graphml format where the depth of the call graph is
restricted to the maximum depth provided (default
5). - (Type = Int, Default = 5)
CGClass - Dumps a call graph in graphml format of all entry
points where the nodes have been simplified to the
classes of the methods in the call graph and the
edges represent calls to methods in a class. - (Type
= Boolean, Default = false)
CGClassLimit - Dumps a call graph in graphml format of all entry
points where the nodes have been simplified to the
classes of the methods in the call graph and the
edges represent calls to methods in a class but the
depth of the call graph is restricted to the maximum
depth provided (default 5). - (Type = Int, Default =
5)
CGThrowSE - Dumps a full method call graph for each entry point,
highlighting the methods containing authorization
checks and their types in graphml format. - (Type =
Boolean, Default = false)
CQSubGraph - Dumps a full method call graph for each context
query method in graphml format. - (Type = Boolean,
Default = false)
CGSubGraphData - Dumps to XML file all the methods reachable from
each entry point and all methods reachable from
those methods. This is basically a collapsed
representation for the entry points call graph if
traversed using BFS where each method is visited
only the first time it is encountered. A number of
simple text representations of the collapsed call
graph are also output. - (Type = Boolean, Default =
false)
CommonSubgraphs - For each group of entry points provided as input,
dumps the entry points in the group which contain
one or more equal subgraphs in their call graph,
collapsed representations of the subgraphs using
generated BFS, and a graphml representation of each
common subgraph. If no input file is provided it
looks for an input file at commongroups.txt in the
acminer directory. If no input file is found then
this is not run. - (Type = Path, Default =
work\acminer\commongroups.txt)
SubgraphCount - For each group of entry points provided as input,
outputs a call graph for all entry points in the
group where common sub graphs are highlighted by
there root method and the number of common methods
contained within the sub graph. If no input file is
provided it looks for an input file at
subgraphgroups.txt in the acminer directory. If no
input file is found then this is not run. - (Type =
Path, Default = work\acminer\subgraphgroups.txt)
Paths - For each entry point, generate a list of possible
paths in the call graph from the entry point to all
end points (i.e. methods with no outgoing edges in
the call graph). The paths generated represent only
the first path encountered to a end point and do not
include all paths in the call graph. - (Type =
Boolean, Default = false)
PathsToMethods - For each entry point, generates a call graph in
graphml format containing all paths to the given
methods. If no input file is provided it looks for
an input file at pathstomethods.txt in the acminer
directory. If no input file is found then this is
not run. - (Type = Path, Default =
work\acminer\pathstomethods.txt)
CGInac - Dumps a text file that highlights invoke statements
which could not be resolved a single method in the
call graph. - (Type = Boolean, Default = false)
DataDumps - Dumps to text files statics and text representations
of various data bases created in previous phases. -
(Type = Boolean, Default = false)
All - Enables all the above options using the default
value for those that require input. If you wish to
override the default value for a specific option the
it needs to be listed separately like normal. -
(Type = Boolean, Default = false)
--------------------------------------------------------------------------
[ACMiner] - Using the def-use graph, marked context queries, and marked
control predicates, this phase mines the authorization checks in the
Android system. Any values identified as used within a authorization check
by the def-use graph are also extracted.
Dependency Phases - DefUseGraphMod
Input Files - work\sje\system_jimple.jar,
work\acminer\entry_points_db.xml,
work\acminer\binder_groups_db.xml,
work\acminer\binder_services_db.xml,
work\acminer\excluded_elements_db.txt,
work\acminer\excluded_elements_db.xml,
work\acminer\context_queries_descriptor_db.xml,
work\acminer\context_queries_db.xml,
work\acminer\throw_security_exceptions_db.xml,
work\acminer\entry_point_edges_db.xml,
work\acminer\control_predicates_db.xml,
work\acminer\defusegraph\_def_use_graph_db.xml,
work\acminer\control_predicate_filter_db.xml,
work\acminer\control_predicates_filtered_db.xml,
work\acminer\defusegraphmod\_def_use_graph_db.xml
Output Files - work\acminer\acminer\_acminer_db_.xml
Phase Options:
enable - Specifies if the phase 'ACMiner' is enabled. Thus
the phase may run if a run is required as determined
by the input and output files for the phase. - (Type
= Boolean, Default = false)
force-run - If the phase 'ACMiner' is enabled setting this
option forces the phase to run even if the phase
output files exist and no changes are detected in
the required phase input files. - (Type = Boolean,
Default = false)
EnableDebug - Enables the dumping of debugging information for the
phase ACMiner to log files. - (Type = Boolean,
Default = false)
DebugToConsole - If debugging information is enabled for the phase
ACMiner this option causes the information to be
output to the terminal as well as files. - (Type =
Boolean, Default = false)
OnlyStubs - Limits the ACMiner analysis to only those entry
points within the provided stub classes. If no input
file is provided it looks for an input file at
onlystubs.txt in the acminer directory. If no input
file is found then this option is ignored and all
entry points are analyzed. - (Type = Path, Default =
work\acminer\onlystubs.txt)
OnlyClasses - Limits the ACMiner analysis to only those entry
points within the provided classes. If no input file
is provided it looks for an input file at
onlyclasses.txt in the acminer directory. If no
input file is found then this option is ignored and
all entry points are analyzed. - (Type = Path,
Default = work\acminer\onlyclasses.txt)
--------------------------------------------------------------------------
==============================================================================
====================================[GJFR]====================================
Description - This is a placeholder phase group for code that has not been
transferred over to the phase group system. It currently
does nothing.
Phases:
--------------------------------------------------------------------------
[JimpleJar] - From the files of a system image, this phase identifies the
java class of the Android system, converts the classes to the Soot's
intermediate representation Jimple, and creates a Jimple JAR to house the
converted class files. This Jimple JAR contains all the classes analyzed
in later analysis phases.
Input Files - work\system_img.zip, work\android_info.xml
Output Files - work\sje\system_jimple.jar
Additional Paths - work\sje\system_archives.zip,
work\sje\system_jimple_framework_only.jar,
work\sje\system_jimple_class_conflicts.zip,
work\sje\work, work\system_class.jar,
work\system_img.zip, work\android_info.xml,
work\sje\system_class.jar,
work\sje\framework_pkgs.txt
Phase Options:
enable - Specifies if the phase 'JimpleJar' is enabled. Thus the
phase may run if a run is required as determined by the
input and output files for the phase. - (Type = Boolean,
Default = false)
force-run - If the phase 'JimpleJar' is enabled setting this option
forces the phase to run even if the phase output files
exist and no changes are detected in the required phase
input files. - (Type = Boolean, Default = false)
--------------------------------------------------------------------------
==============================================================================
====================================[SJE]=====================================
Description - The Soot Jimple Jar Extractor phase group. Allows for the
generation of the Jimple Jar without having to run the
ACMiner phase group.
Input Files - work\system_img.zip, work\android_info.xml
Quick Options:
--SJE - See the JimpleJar phase description. = (-p SJE JimpleJar
enable:true)
Phases:
--------------------------------------------------------------------------
[JimpleJar] - From the files of a system image, this phase identifies the
java class of the Android system, converts the classes to the Soot's
intermediate representation Jimple, and creates a Jimple JAR to house the
converted class files. This Jimple JAR contains all the classes analyzed
in later analysis phases.
Input Files - work\system_img.zip, work\android_info.xml
Output Files - work\sje\system_jimple.jar
Additional Paths - work\sje\system_archives.zip,
work\sje\system_jimple_framework_only.jar,
work\sje\system_jimple_class_conflicts.zip,
work\sje\work, work\system_class.jar,
work\system_img.zip, work\android_info.xml,
work\sje\system_class.jar,
work\sje\framework_pkgs.txt
Phase Options:
enable - Specifies if the phase 'JimpleJar' is enabled. Thus the
phase may run if a run is required as determined by the
input and output files for the phase. - (Type = Boolean,
Default = false)
force-run - If the phase 'JimpleJar' is enabled setting this option
forces the phase to run even if the phase output files
exist and no changes are detected in the required phase
input files. - (Type = Boolean, Default = false)
--------------------------------------------------------------------------
==============================================================================
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++