Skip to content

About

A library to facilitate the static analysis of Android apps

Resources

Contributing

Stars

13 stars

Watchers

2 watching

Forks

Latest commit

 

History

174 Commits

Folders and files

Repository files navigation

AndroSpecter logo

AndroSpecter

Android static analysis as a Java library, command-line tool, or desktop application.

AndroSpecter wraps Soot and FlowDroid to help you build call graphs, inspect classes and invocations, run source-to-sink taint analyses, and compose instrumentation. Use it as a Java library, where your application controls execution, cancellation, logging, and output, or as a standalone command-line tool for common analysis and export tasks. The optional Electron desktop application provides a local workspace for APK overview, code inspection, and interactive call-graph exploration.

Getting started · Wiki · Runnable examples · Command-line tool · Desktop application · Contributing

What you can do

Task Main APIs Guide
Open an APK analysis and manage its lifetime AndroidAnalysis, AnalysisContext Analysis sessions
Read manifest metadata without an SDK or Soot session ApkInfo APK metadata
Query callers, reachability, shortest call paths, and filtered subgraphs after analysis closes CallGraphSnapshot Graphs and inspection
Save, reload, visualize, and compare graphs GraphJson, GraphDot, GraphHtml, GraphDifference Graph export and comparison
Visit only the classes, methods, statements, or invocations you need Inspection, LibraryFilter Graphs and inspection
Obtain structured findings with sources, sinks, paths, and status SourceSinkConfiguration, TaintAnalysisResult Taint analysis
Apply scoped logging probes and ordered transformations Logger, TransformationPipeline Instrumentation
Choose deadlines and logging behavior in the calling application CancellationSource, Deadline, SLF4J Execution and logging

Requirements and installation

Component Version used by this checkout
Java 17 or later
AndroSpecter 2.0.0
Soot 4.7.1
FlowDroid 2.15.1

You need Maven to build the library and an Android SDK platforms directory containing platform JARs for Soot/FlowDroid analyses. Reading APK metadata and querying saved graph snapshots require no SDK. A connected Android device is not needed.

Version 2.0.0 is available from Maven Central. Add the dependency below to use the published library. To build or develop this checkout locally:

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

Check java -version and mvn -version if Maven uses a different JDK from your shell. In your application's pom.xml, add:

<dependency>
    <groupId>com.jordansamhi</groupId>
    <artifactId>androspecter</artifactId>
    <version>2.0.0</version>
</dependency>

The library supplies the SLF4J API, without a logging provider or global logging configuration. If your application has no provider yet, it can select one:

<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-simple</artifactId>
    <version>2.0.17</version>
    <scope>runtime</scope>
</dependency>

Use one compatible SLF4J 2.x provider. See Getting started for a complete Maven setup and the distinction between local and published versions.

Desktop application

AndroSpecter Desktop is an optional Electron application for macOS, Windows, and Linux. It opens in its own native window and runs locally, without a web server, browser tab, account, or APK upload.

  • Open an APK and read its manifest, permissions, and components.
  • Search application classes and methods, then build a scoped call graph.
  • Navigate callers and callees, inspect call sites, and find shortest call paths.
  • Open saved graph JSON without an SDK; export JSON, DOT, interactive HTML, or a run record containing configuration and APK identity.
  • Configure Java, SDK location, heap, and a hard time limit; cancel a running JVM.

To launch from source, install Node.js 22.12 or later, then run:

mvn -B -f cli/pom.xml package
cd desktop
npm ci
npm start

Source launches need Java 17 or later. Packaged desktop builds include their own Java runtime. Code inspection and APK graph construction require an Android SDK platforms directory; the app checks common SDK locations and offers a native folder picker. See the desktop guide for native packaging, testing, and the scope of this first GUI. The library has no Electron dependency.

Standalone command-line tool

Build the library, then the executable CLI (Java 17 or later):

mvn -B install
mvn -B -f cli/pom.xml package
java -jar cli/target/androspecter-cli.jar --help

From the repository, bin/androspecter launches that same JAR. These commands read metadata, build a graph, and turn the saved graph into an interactive offline page:

bin/androspecter metadata --apk app.apk --format text
bin/androspecter graph --apk app.apk --platforms /path/to/sdk/platforms \
  --package com.example.app --format json -o callgraph.json
bin/androspecter graph --input-json callgraph.json --format html -o callgraph.html

Open callgraph.html directly in a browser to search methods, follow callers and callees, inspect call sites, and pan or zoom. No server or network connection is needed. The viewer shows a bounded neighborhood and reports omitted items; the file retains the entire exported graph. --package selects an induced subgraph, so calls crossing that scope are omitted. Remove it to export the full graph.

The CLI also supports DOT export, class-only inspection, offline reachability and shortest-path queries, and taint analysis. JSON results go to standard output by default; logs go to standard error. Existing files require --overwrite. See the CLI guide for all commands, exit codes, filtering, and timeouts.

The executable JAR contains its dependencies and logging provider. The library artifacts remain available independently with their existing logging contract.

Your first library analysis

This complete class opens an APK, builds its Android entry points and CHA call graph, then queries the detached graph after the analysis has closed:

import com.jordansamhi.androspecter.analysis.AndroidAnalysis;
import com.jordansamhi.androspecter.graph.CallGraphSnapshot;
import java.nio.file.Path;

public final class QuickStart {
    /**
     * Builds and inspects an APK's call graph.
     * @param args APK path and Android SDK platforms directory
     * @throws IllegalArgumentException if two paths are not supplied
     */
    public static void main(String[] args) {
        if (args.length != 2) {
            throw new IllegalArgumentException("Usage: QuickStart <app.apk> <sdk/platforms>");
        }

        CallGraphSnapshot graph;
        try (AndroidAnalysis analysis = AndroidAnalysis.open(
                Path.of(args[0]), Path.of(args[1]))) {
            System.out.println("Package: " + analysis.packageName());
            graph = analysis.callGraph();
        }

        System.out.println("Call graph edges: " + graph.edges().size());
        graph.methods().stream().limit(5).forEach(method -> {
            System.out.println(method);
            System.out.println("  Callees: " + graph.calleesOf(method));
        });
    }
}

Use AndroidAnalysis.builder(apk, platforms) to select CHA, RTA, VTA, or SPARK, configure callbacks and path reconstruction, add classpath entries, set source/sink definitions, or configure cancellation and phase limits. Advanced FlowDroid configuration is available through configureFlowDroid(...) while the session retains ownership of its APK, platform selection, and Soot lifecycle. The session guide explains these choices and shows how to collect instance-owned metrics.

For class and method inspection, choose initializationMode(InitializationMode.CLASSES_ONLY) to defer callback discovery and graph construction. Calling callGraph() or analyzeTaint() later prepares the Android graph using the loaded scene. For manifest metadata alone, ApkInfo.read(apk) does not require an SDK and does not initialize Soot.

Run the included examples

After installing the library, build the independent example project from the repository root:

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"

Replace the paths and package prefix with your own. The prefix controls inspection scope; it is not proof that a class is first-party code. On Windows, use ; instead of : between classpath entries.

Example Demonstrates
InspectApk Invocation callbacks, per-analysis metrics, and indexed graph queries
PrintApkInfo Manifest components, permissions, and SDK/version attributes without Soot or an SDK
InspectClasses Class and invocation inspection without constructing a call graph
ExportGraph Versioned graph JSON written after the session closes
GraphQueries Offline reachability, shortest paths, and DOT export from saved JSON
AnalyzeTaint File-based source/sink definitions, completion status, and JSON export after close
InstrumentInMemory Scoped logging probes, transformation composition, and graph rebuilding
CancelAnalysis A caller-owned cancellation token and cooperative deadline

The example README contains every command and expected behavior. These programs are executable consumers of the library. For a ready-made command-line application, use the separate CLI distribution.

Lifecycle and result semantics

  • One managed session per JVM. Open, use, and close it on the same thread. Soot has global state; use separate processes for parallel analyses. External Soot users must coordinate access too.
  • Live objects have a lifetime. Callback arguments such as SootMethod and Unit must not be reused after close or G.reset(). Graph, taint, and metric snapshots contain detached data and survive those operations.
  • Graphs describe static possibilities. They include framework and generated entry points. Snapshot nodes are methods incident to an edge, not every method declared in the APK; manually constructed and filtered snapshots can also retain isolated nodes. Reachability and shortest paths describe graph structure, not proven feasible executions. Large indexed snapshots require additional memory.
  • Check taint status. SUCCESS, FAILED, TIMED_OUT, and CANCELLED distinguish completion from partial results. An empty finding list alone is not evidence that no flow exists. Source/sink settings are empty unless explicitly supplied.
  • Cancellation is cooperative. Deadlines request cancellation; they do not forcibly terminate Java code. Some backend phases may finish before noticing a request. Callback timeouts can leave a partial graph.
  • Instrumentation changes the in-memory model. APK export and signing are separate caller-controlled steps. Pipelines execute in order without rollback. The deprecated Logger.v().instrument() adapter also supports Soot's body-pack workers; public logger calls still belong on the creating thread. After a failed legacy pack run, reset and reinitialize Soot before reacquiring the logger.

See Migration and troubleshooting for legacy singleton APIs, changed timeout/CLI behavior, backend diagnostics, and common setup errors.

Bundled library list

src/main/resources/libraries.txt contains the 36,926 distinct entries from AndroLibZoo2026.lst in AndroLibZoo, refreshed on 2026-11-06. Whitespace is trimmed, blank lines removed, and duplicates collapsed; all distinct entries are retained. This is the list used by LibrariesManager and LibraryFilter.knownLibraries().

Classification matches package prefixes at dot boundaries and remains a heuristic. The 2026 list includes the broad prefix org, so the bundled classifier treats all org.* classes as libraries. Use LibraryFilter.packages(...) or LibraryFilter.from(...) when your analysis needs a different classification policy. This source update takes effect when rebuilding AndroSpecter; it does not change previously published Maven artifacts or packaged applications.

Build, test, and browse the API

mvn clean verify
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 for public APIs and protected extension points. Tests use synthetic Soot bodies, generated DEX files, and local fixtures; they do not require an Android SDK, Redis service, or AndroZoo key. Optional real-backend tests use the reproducible APK fixture:

mvn -Dtest=AndroidAnalysisApkTest,LoggerApkTest \
    -Dandrospecter.androidPlatforms=/absolute/path/to/android-sdk/platforms test

Analysis examples require an APK and Android platform JARs. PrintApkInfo needs only an APK; GraphQueries operates on exported JSON without an SDK or Soot session.

Every new or changed public API and protected extension point must have usage-oriented Javadoc. See CONTRIBUTING.md for the documentation requirements.

The release guide describes local packaging checks, signing, and the Central Publisher Portal setup. For a configured maintainer environment, mvn clean deploy -P release signs, uploads, and automatically publishes the release after Central validation, then waits for publication. Updating this checkout alone does not publish a Maven artifact.

License and contact

AndroSpecter is licensed under GNU LGPL 2.1. For questions or contributions, open a GitHub issue or contact Jordan Samhi.

About

A library to facilitate the static analysis of Android apps

Resources

Contributing

Stars

13 stars

Watchers

2 watching

Forks

Releases

Packages

Used by

Contributors

Languages