The Starter-Toolbox is a simple starter framework for creating an analysis toolbox using Atlas.
1) Install Atlas. See http://www.ensoftcorp.com/atlas.
The Starter-Toolbox has a dependency on the Toolbox-Commons library. It can be installed by following instructions at https://ensoftcorp.github.io/toolbox-commons/install.
The Starter-Toolbox also has a dependency on the org.apache.commons.codec library. Install the Apache commons library as a plugin from the http://www.eclipse.org/orbit/ repos by navigating to Help->Install New Software... and entering "http://download.eclipse.org/tools/orbit/downloads/drops/R20140525021250/repository/" in the Work with: field. Expand the All Orbit Bundles category and select Apache Commons Codec (version 1.4.0) and then press Next and Finish. You will need to restart Eclipse.
Note: If your toolbox project has other dependencies you may need to install additional plugins at this time.
git clone https://github.com/EnSoftCorp/Starter-Toolbox.git
- Import the
toolbox.analysisandtoolbox.shellprojects into your Eclipse workspace.
To use the analysis toolbox interactively make sure you have both the toolbox.analysis and toolbox.shell projects imported into the Eclipse workspace. Then navigate to Window->Show View->Other->Atlas->Atlas Shell. Select the toolbox.shell project from the shells list and press OK.
From the Atlas Shell you can run any program analyzers in the toolbox.analysis project. To automatically import packages or classes on the Shell edit the shellInit.scala file.
To open an interactive Smart View right click on the toolbox.shell project and navigate to Atlas->Open Atlas Smart View. Drag the Smart View window to your preferred location in the Eclipse IDE. In the Smart View window click on the down arrow and navigate to Script and then select the Smart View you'd like to display.
The toolbox.analysis project is also an Eclipse plugin that can be installed and run in a headless mode. To install the Eclipse plugin from the workspace right click on the project and navigate to Export->Plug-in Development->Deployable plug-ins and fragments. Select Next and make sure only the toolbox.analysis project is selected. Then select the Install into host. radio and click Finish. You will need to restart Eclipse.
To run the analysis toolbox project in a headless mode invoke Eclipse from the command line with arguments similar to the following:
./eclipse -application toolbox.analysis.Headless
-nosplash
-consoleLog
-data <workspace path>/headless-workspace/
-import <project path>/{MyProject}
-output <output path>/output.xml
-remove-imported-projects-after-analysis
-vmargs -Dsdtcore.headless=true
| Argument | Explanation |
|---|---|
| -application toolbox.analysis.Headless | The identifier of the Eclipse application to run. This specifies the headless toolbox entry point. |
| -nosplash | Disables the Eclipse splash screen |
| -consoleLog | Redirects any log output sent to Java's System.out (typically back to the command shell if any) |
| -data <workspace path> | Set the Eclipse workspace to use |
| -vmargs -Dsdtcore.headless=true | Sets a VM argument to run the Scala plugin in a headless mode. Without this argument the toolbox will crash. |
For additional Eclipse runtime arguments see help.eclipse.org.
| Argument | Explanation |
|---|---|
| -import <project path>/{MyProject or MyApp.apk} | Imports a Eclipse project or Android binary into the workspace |
| -sdk-bundle-path <Android SDK Bundle> | Manually specify the Android SDK Bundle path, if not specified the toolbox will search Eclipse preferences for this information. |
| -output <output file path> | Sets the output file path |
| -close-imported-projects-after-analysis | Closes the imported project after the analysis is complete |
| -remove-imported-projects-after-analysis | Closes and removes the imported project after the analysis is complete |
To add a program analyzer extend com.ensoftcorp.open.toolbox.commons.analysis.Analyzer and implement the evaluateEnvelope method. Alternatively create your own Java classes for analysis and invoke them directly from the Headless entry point or on the Atlas Shell.
To add a custom Atlas Smart View implement the AtlasSmartViewScript interface and enable the Class in the selectionScripts.atlas file. The custom Smart View can be accessed by right clicking on the toolbox.shell project, and selecting Atlas->Open Atlas Smart View. Drag the Smart View window to your preferred location in the Eclipse IDE. In the Smart View window click on the down arrow and navigate to Script and then select the Smart View you'd like to display.
An example custom Smart View can be seen in toolbox.shell.smartviews.SuperTypeHierarchy.
QueryAddons is a collection of Scala methods that are dynamically added to the Q query object. By adding methods here you can add custom query chaining methods.
Some examples are present in toolbox.shell.addons.QueryAddons.scala.
Depending on your analysis needs, other specialized toolboxes exist that may satisfy or quick start your analysis task. Some toolboxes compatible with this starter toolbox are listed below.
- Android Essentials Toolbox - Utilities for analyzing Android permissions and the Android Manifest
- AuditMon - Utilities for recording analyst code audits