ELEGANT is a tool to effectively locate fragmentation-induced compatibility issues. A self-implementation of FicFinder.
- Intro
- ELEGANT and ele-cli
- Build (for command line users)
- Build (for IntelliJ IDEA users)
- Tutorials - ele-cli
- Tutorials - ELEGANT
- License
By default, we refer ELEGANT as a library, but we also provide a command line tool for convenience, i.e. ele-cli. Both released as an uber-jar.
$ git clone https://github.com/Leetsong/ELEGANT.gitELEGANT is released by default as a uber-jar, because we modified codes of soot-infoflow-android.
$ mvn packageYou will find the uber-jar ELEGANT.jar and ele-cli.jar respectively in the elegant/target folder and ele-cli/target folder. If you insist use ELEGANT not
by an uber-jar, the jar file prefixed with original- is it (the dependencies, either modified or not,
are installed ahead of time to the m2 directory, you can find them in it).
If you just want to compile and get the built package, then you are done can skip step3.
But once you want to run it, you must enter into step3.
Move the jar file to any place that you like, and enter that folder, then enter the following commands to download ELEGANT-dbs, the databases (or datasets, resources) ELEGANT and ele-cli needs.
$ git clone https://github.com/Leetsong/ELEGANT-dbs.git dbs
$ cd dbs && rm -rf .git && cd ..Then you can use it.
$ git clone https://github.com/Leetsong/ELEGANT.gitMove to ELEGANT/ele-cli folder, download ELEGANT-dbs.
$ git clone https://github.com/Leetsong/ELEGANT-dbs.git dbs
$ cd dbs && rm -rf .git && cd ..Open IntelliJ IDEA, and click Import Project and choose the downloaded ELEGANT folder.
Choose import project from external model and choose Maven, click Next until it's done.
Go to File-Project Structure....
- In the Project tab, set Project SDK and Project language level both to Java 1.8.
- In the Modules tab, click ele-cli and mark
resfolder as Resources.
The entry is simonlee.elegantcli.CLI. If you want to run it, remember to go to the corresponding Run/Debug Configurations, and set Working directory to ELEGANT/ele-cli.
For easily use, we provide a tool ele-cli that you can use from your command line. And ele-cli is a best practice of using ELEGANT. To use ele-cli,
usage: java -jar ele-cli.jar [option ...] <apk>
option:
-d3,--d3-algo <value> algorithms used in 3rd party library
detection, <value> is one of: d3.none,
d3.whitelist, d3.libscout.
-h,--help show help
-m,--models <file> custom api context models, in json format
-o,--output <file> redirect technique report output to <file>
-p,--platforms <direcotry> android platforms
-V,--verbose print verbose information
-v,--version show versionAs shown above,
-d3or--d3-algodesignate the third party library detection algorithms.d3.whitelistas default,d3.noneandd3.libscoutare alternatives.-mor--modelsdesignate the models json file you want to use. Themodel.jsonprovide inresdirectory is the default one.-oor--outputdesignate the output file that the technique report will redirect to.stdoutby default.-por--platformsdesignate the android platforms directory.$ANDROID_HOME/platformsby default.-Vor—verbosedesignate whether output the call chain details.falseby default.
ELEGANT is a library, on top of Soot [3], writing in Java. Having downloaded ELEGANT.jar according to download, there are 3 steps left to use ELEGANT.
The first thing you do is to create an ELEGANT instance using the builder ELEGANT.Builder,
String apkPath = "some_directory/test.apk";
String modelsPath = "some_directory/test.models.json";
String platformsPath = "your_android_home/platforms";
String d3Algo = "d3.whitelist";
ELEGANT.Builder builder = new ELEGANT.Builder();
ELEGANT elegant = builder
.withApkPath(apkPath)
.withModelsPath(modelsPath)
.withPlatformsPath(platformsPath)
.withD3Algo(d3Algo)
.build();As shown above, the ELEGANT.Builder will guide you to construct a legal ELEGANT instance. If any REQUIRED field are missed, ELEGANT.Builder willfail. All fields are,
withApkPathREQUIREDwithModelsPathREQUIRED you can usemodels.jsonprovided by ele-cli, see details in section ele-cliwithPlatformsPathREQUIREDwithD3AlgoOPTIONAL alternatives ared3.whitelist,d3.noneandd3.libscout.
The second step is to write a issue handle to receive the issues emitted by ELEGANT, and watch it.
Any issue handle you want to use must inherit from PubSub.Handle. ELEGANT, by far, reports 2 types of Issue, i.e. PIssue and RIssue, you receive them using your issue handle one by one and take care of them.
public abstract class IssueHandle implements PubSub.Handle {
@Override
public void handle(PubSub.Message message) {
if (!(message instanceof Issue)) {
return ;
} else if (message instanceof PIssue){
System.out.println("PIssue: " + message.toString());
} else if (message instanceof RIssue){
System.out.println("RIssue: " + message.toString());
}
}
}Then you should tell ELEGANT that you want to watch issues by your issue handle.
elegant.watchIssues(new IssueHandle());The last step is to report them. The report codes should inhabit in your issue handle, but the recommended way is to write your own reporter to take care of them separately and use your issue handle as a proxy from ELEGANT to your own reporter.
MIT License.
