Getting started

Getting started

Requirements

Use JDK 17 or later, Maven, and an Android SDK platforms directory containing android-<api>/android.jar installations. An APK is the analysis input. No connected device, Redis server, or AndroZoo account is required for the core workflows. Manifest-only reads through ApkInfo.read(apk) need no Android SDK or Soot session. Saved graphs can also be queried without an SDK; see APK metadata and Graph export and comparison.

Check that java -version and mvn -version select the intended JDK. This checkout pins Soot 4.7.1 and FlowDroid 2.15.1. Its own version is 1.2.0-SNAPSHOT.

Install this development version

git clone https://github.com/JordanSamhi/AndroSpecter.git
cd AndroSpecter
mvn clean install

The snapshot has not been published to Maven Central. Installing the checkout makes it available in your local Maven repository. A published 1.1.8 artifact does not contain these new session APIs; changing a version string without installing the development build is not enough.

Use it in your application

A minimal Java 17 Maven project can use this pom.xml:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>example</groupId>
    <artifactId>android-analysis</artifactId>
    <version>1.0-SNAPSHOT</version>
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>
    <dependencies>
        <dependency>
            <groupId>com.jordansamhi</groupId>
            <artifactId>androspecter</artifactId>
            <version>1.2.0-SNAPSHOT</version>
        </dependency>
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-simple</artifactId>
            <version>2.0.17</version>
            <scope>runtime</scope>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.7.0</version>
                <configuration><release>17</release></configuration>
            </plugin>
        </plugins>
    </build>
</project>

Add the complete QuickStart class from the repository README to src/main/java/QuickStart.java. From your application's directory:

mvn package dependency:copy-dependencies
java -Xmx4g -cp 'target/classes:target/dependency/*' QuickStart \
    /absolute/path/to/app.apk /absolute/path/to/android-sdk/platforms

Use the SDK platforms directory, not a build-tools directory or an APK file, as the second argument. The heap limit is a starting point; large apps and graph snapshots may require more memory. On Windows, separate classpath entries with ;.

The logging provider belongs to the application. If it already uses a compatible SLF4J 2.x provider, keep that provider instead of adding another one.

Run the repository examples

The examples project is a ready-to-build consumer. From the AndroSpecter repository root, after installation:

mvn -f examples/pom.xml package dependency:copy-dependencies

APK=/absolute/path/to/app.apk
PLATFORMS=/absolute/path/to/android-sdk/platforms
APP_PREFIX=com.example.app

java -Xmx4g -cp 'examples/target/classes:examples/target/dependency/*' \
    com.jordansamhi.androspecter.examples.InspectApk \
    "$APK" "$PLATFORMS" "$APP_PREFIX"

InspectApk scopes body inspection to application classes under the supplied package prefix. Its full call graph still includes framework and generated entry points. See the example README for taint, instrumentation, and cancellation commands. It also covers PrintApkInfo, class-only inspection with InspectClasses, and the ExportGraph/GraphQueries workflow.

AndroSpecter is a library, and its own JAR has no main entry point. These examples run through an explicit Java classpath; they do not claim that a thin Maven JAR can be launched with java -jar.

API reference

From the library repository:

mvn org.apache.maven.plugins:maven-javadoc-plugin:3.4.0:javadoc \
    -Dshow=public -Ddoclint=all -Dmaven.javadoc.failOnWarnings=true

Open target/site/apidocs/index.html. All new or changed public APIs require Javadoc; see the contribution guidelines.

Next: Analysis sessions, then Call graphs and inspection or Taint analysis.

Maintainers: the release guide uses the Central Publisher Portal and includes local release packaging checks.