How noidsirius/soottutorial works
1. This repository is a tutorial-style Java project for static program analysis with Soot. The code is organized as a small “analysis toolchain” plus a set of sample programs/APKs that serve as inputs to those analyses.
2. The main executable entrypoint is src/main/java/dev/navids/soottutorial/Main.java. It acts as a dispatcher: the first CLI argument selects which tutorial/analysis to run, and optional extra arguments control variants such as drawing a graph or choosing an Android call-graph algorithm.
3. The core analysis code is split by topic:
- hellosoot/ for the simplest Soot/Jimple and control-flow-graph examples.
- basicapi/ for basic Soot APIs on plain Java classes.
- intraanalysis/ for intraprocedural analyses, including usagefinder/ and npanalysis/.
- android/ for Android-specific instrumentation, call graphs, and points-to analysis.
- visual/ for graph filtering and visualization support.
4. The simplest pipeline is in the HelloSoot chapter: a demo Java file under demo/HelloSoot/FizzBuzz.java is loaded, converted to Soot’s intermediate representation, and printed or visualized as a CFG. This chapter is about understanding Soot’s core IR and method-level control flow.
5. The BasicAPI chapter follows a similar pattern but targets demo/BasicAPI/Circle.java. It exercises Soot’s class/method inspection and call-graph-related APIs, showing how to traverse and summarize a Java program rather than just inspect one method.
6. The intraprocedural analysis subsystem works over small Java examples in demo/IntraAnalysis/. UsageFinder searches for uses of a particular method signature inside a program, while npanalysis/ contains a null-pointer analysis built around custom flow-set logic. These are classic “analyze one program, report facts” tools rather than transformers.
7. The Android subsystem is the most boundary-heavy part of the repo. It consumes either a third-party APK (demo/Android/calc.apk) or the bundled demo app (demo/Android/st_demo.apk) and then uses Soot/FlowDroid-based utilities to build call graphs, run points-to analysis, and instrument bytecode. The Android classes are split between analysis logic and instrumentation helpers (AndroidLogger, AndroidClassInjector, InstrumentUtil, AndroidUtil).
8. Android instrumentation outputs a modified APK rather than just textual results. The README shows that instrumented artifacts are written under demo/Android/Instrumented, then signed with the provided scripts before installation. That creates a clear data flow: APK in → Soot transforms/injects code → signed APK out → device/runtime logs back via adb logcat.
9. The repository also includes a separate Android sample application source tree at demo/Android/STDemoApp/. This app is not the analysis engine; it is the analyzed target used for the call-graph and points-to chapters. Its compiled artifact is demo/Android/st_demo.apk.
10. The visual/ package provides the graph-facing boundary between analysis results and human-readable output. It contains filters for generic and Android call graphs plus a Visualizer utility, which implies analysis results can be reduced before being rendered or displayed.
11. External dependencies are important to the architecture: the repo depends on Soot and several FlowDroid-related JARs under lib/. Android chapters also require the Android SDK, because some analyses operate on APKs and need Android platform classes during resolution and instrumentation.
12. Build and execution are Gradle-based at the root, with Gradle wrappers checked in for reproducibility. The README’s ./gradlew run --args="..." pattern indicates one binary/tooling entrypoint that branches into multiple analysis workflows.
13. The repo is structured as a teaching artifact as much as a codebase. The docs/ tree mirrors the tutorial chapters, while the demo/ tree holds the concrete input programs/APKs that each chapter consumes. That separation is a key architectural boundary: tutorial text in docs/, analysis code in src/main, and sample targets in demo/.
14. Tests under src/test/java/dev/navids/soottutorial/ exercise the main tutorial modules, including Android-specific cases. This suggests the analyses are intended to be runnable end-to-end in CI, not just as standalone demos.
15. In diagram terms, the main flow is: sample source/APK from demo/ → Soot/FlowDroid-based analysis code in src/main → textual reports, call graphs, or transformed APKs → optional visualization or device execution. The major architectural boundaries are plain Java analysis vs. Android analysis, and analysis-only outputs vs. transformed runtime artifacts.
Main entry points: Main.java Main · AndroidCallgraph.java Android CG · AndroidClassInjector.java Instrument · AndroidPointsToAnalysis.java Android PTA
Components 20
Analysis Engine
Main Soot-based tutorial analyses and helpers
- Main · CLI entrypoint that selects which tutorial analysis to run
src/main/java/dev/navids/soottutorial/Main.java - HelloSoot · Introductory Soot/Jimple and CFG demo
src/main/java/dev/navids/soottutorial/hellosoot/HelloSoot.java - BasicAPI · Class and method inspection plus call-graph-oriented API usage
src/main/java/dev/navids/soottutorial/basicapi/BasicAPI.java - UsageFinder · Finds uses of a target method signature in a program
src/main/java/dev/navids/soottutorial/intraanalysis/usagefinder/UsageFinder.java - Null Analysis · Custom intraprocedural null-pointer analysis
src/main/java/dev/navids/soottutorial/intraanalysis/npanalysis/NullPointerAnalysis.java - NPAMain · Entry driver for the null-pointer analysis chapter
src/main/java/dev/navids/soottutorial/intraanalysis/npanalysis/NPAMain.java - Android CG · Builds Android call graphs with Soot/FlowDroid support
src/main/java/dev/navids/soottutorial/android/AndroidCallgraph.java - Android PTA · Points-to analysis over Android apps
src/main/java/dev/navids/soottutorial/android/AndroidPointsToAnalysis.java - Instrument · APK instrumentation and class injection utilities
src/main/java/dev/navids/soottutorial/android/AndroidClassInjector.java - Android Utils · Shared Android helpers, logging, and instrumentation utilities
src/main/java/dev/navids/soottutorial/android/AndroidUtil.java - Visualizer · Reduces and renders analysis output such as call graphs
src/main/java/dev/navids/soottutorial/visual/Visualizer.java
Demo Inputs
Small Java programs and APKs analyzed by the tutorials
- FizzBuzz · HelloSoot demo program used as the simplest analysis input
demo/HelloSoot/FizzBuzz.java - Circle · BasicAPI demo class used for class and method traversal
demo/BasicAPI/Circle.java - Usage Example · Sample program for method-usage searching
demo/IntraAnalysis/UsageExample.java - Null Example · Sample program for null-pointer analysis
demo/IntraAnalysis/NullPointerExample.java - calc.apk · Third-party APK used as an Android analysis target
demo/Android/calc.apk - st_demo.apk · Bundled compiled Android target app
demo/Android/st_demo.apk
Android Sample App
Bundled target app used by Android analyses
- STDemoApp · Source tree for the bundled Android sample application
demo/Android/STDemoApp/app/src/main/java/dev/navids/multicomp1/MainActivity.java
Platform
Build and external analysis dependencies
- Soot Libs · Soot and FlowDroid-related libraries used by the analyses
lib/soot-infoflow-classes.jar - Gradle Build · Root Gradle-based build and execution entrypoint
build.gradle
Connections 26
- Main → HelloSoot: dispatches · CLI selects HelloSoot tutorial
- Main → BasicAPI: dispatches · CLI selects BasicAPI tutorial
- Main → UsageFinder: dispatches · CLI selects usage-finding analysis
- Main → NPAMain: dispatches · CLI selects null-pointer analysis run
- Main → Android CG: dispatches · CLI selects Android call-graph workflow
- Main → Android PTA: dispatches · CLI selects Android points-to workflow
- Main → Instrument: dispatches · CLI selects APK instrumentation workflow
- HelloSoot → FizzBuzz: analyzes · Loads the demo program and prints or visualizes its CFG
- BasicAPI → Circle: analyzes · Inspects the demo Java class
- UsageFinder → Usage Example: analyzes · Searches the sample program for target method uses
- Null Analysis → Null Example: analyzes · Runs intraprocedural null analysis on the sample program
- NPAMain → Null Analysis: uses · Driver wires up the flow analysis
- Android CG → calc.apk: analyzes · Builds a call graph over an APK input
- Android CG → st_demo.apk: analyzes · Builds a call graph over the bundled demo app artifact
- Android PTA → calc.apk: analyzes · Runs Android points-to analysis on APK input
- Android PTA → STDemoApp: analyzes · Uses the bundled app source/artifact as Android target
- Instrument → calc.apk: transforms · Injects code into an APK
- Instrument → st_demo.apk: transforms · Produces a modified runtime artifact from the demo app
- Instrument → Android Utils: uses · Shares logging and instrumentation helpers
- Android CG → Visualizer: feeds · Call graphs can be filtered and visualized
- BasicAPI → Visualizer: feeds · Program summaries can be rendered
- Android CG → Soot Libs: depends on · Uses Soot/FlowDroid libraries
- Android PTA → Soot Libs: depends on · Uses Soot/FlowDroid libraries
- Instrument → Soot Libs: depends on · Uses Soot and Android infoflow classes
- Gradle Build → Main: builds · Compiles and runs the main tutorial tool
- Gradle Build → STDemoApp: builds · Builds the bundled Android sample app