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 2.0.0.

Install 2.0.0 locally

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

Version 2.0.0 is prepared for release, but publication has not completed. Until it is available from Maven Central, install this checkout in the same local Maven repository used by your consumer. The historical 1.1.8 artifact does not contain these session APIs; changing the dependency version alone is not enough before 2.0.0 is published.

Use the command-line tool

After installing the library, build the separate CLI from the repository root:

mvn -B -f cli/pom.xml package
bin/androspecter --help
bin/androspecter metadata --apk /absolute/path/to/app.apk

The executable artifact is cli/target/androspecter-cli.jar; it can also be run with java -Xmx4g -jar cli/target/androspecter-cli.jar --help. See the command-line guide for inspection, graph JSON/DOT/HTML export, offline queries, taint definitions, output protection, and exit codes.

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>2.0.0</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.

The root library JAR has no main entry point. These Java examples run through an explicit classpath. For java -jar, use the separately built CLI artifact.

API reference

From the library repository:

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

Open target/site/apidocs/index.html. This includes public APIs and protected subclass extension points. Both require Javadoc; see the contribution guidelines.

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

Maintainers: the release guide covers Central Publisher Portal credentials, signing, and local packaging checks. Once those prerequisites are in place, mvn clean deploy -P release uploads, validates, and automatically publishes 2.0.0, waiting for the published state (autoPublish=true, waitUntil=published). This is a publication command, not a local installation step.