# TRACE

**Repository Path**: AvailabilityCode/trace

## Basic Information

- **Project Name**: TRACE
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-27
- **Last Updated**: 2026-03-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TRACE

This is the unified top-level guide for the TRACE project, covering both:

- Java static analysis (`JavaStaticAnalysis`)
- Native dynamic analysis (`NativeDynamicAnalysis`, based on Unidbg + Triton)

## 1) Prerequisites

### Java static analysis dependency

Download
[`android-all-15-robolectric-12650502.jar`](https://mvnrepository.com/artifact/org.robolectric/android-all/15-robolectric-12650502)
and place it in repository root `dependencies/`.

Configure repository root `.env` (see `.env.example`):

- `ROBOLECTRIC_JAR`
- `JAVA_STATIC_ANALYSIS_JAR`

Both can be relative to repository root and can be quoted.

After `mvn package`, the fat JAR is copied to:

- `dependencies/JavaStaticAnalysis.jar`

`android-all` resolution priority:

1. CLI arg `-aj`
2. env `ROBOLECTRIC_JAR`
3. `.env`
4. auto-discovery at `dependencies/android-all-15-robolectric-12650502.jar`

### Native dynamic analysis dependency

For Unidbg + Triton flow, prepare DLLs visible to Java process (`PATH` or equivalent):

- `triton.dll`
- `unidbg_triton.dll`

## 2) JavaStaticAnalysis Outputs

Project root is resolved by `TRACE_ROOT`, `-Dtrace.root`, or auto-detection (directory containing `JavaStaticAnalysis/pom.xml`).

- logs: `result/java/logs/<input-name>.log`
- artifacts: `result/java/<input-name>/`
  - `result_callRelation.json`
  - `result_protectedData_dataFlow.json`
  - `result_fullCallGraph.json`
  - `jimple/`
  - `result_ir_manifest.json`

Temporary JARs may be created under `tmp/` and are removed on normal exit.
If interrupted, clean manually at repository root:

```bash
python3 scripts/clean_tmp_jars.py
```

## 3) Build and Run JavaStaticAnalysis

Requires **JDK 17** and **Maven**.

### One-click scripts (repository root)

| Action | Linux / macOS | Windows |
|---|---|---|
| Build | `./build.sh` | `build.bat` |
| Analyze one APK | `./run-apk.sh <apk> [opts]` | `run-apk.bat <apk>` or `.\run-apk.ps1 -Target <apk> [-Aj ...]` |
| Analyze APK directory | `./run-apk.sh bench_apks` | `run-apk.bat bench_apks` or `.\run-apk.ps1 -Target bench_apks` |

Important: after Java code changes, rebuild (`build.bat` / `build.sh` / `mvn package`) before rerun; otherwise old `dependencies/JavaStaticAnalysis.jar` will still be used.

Manual build:

```text
cd JavaStaticAnalysis
mvn package
```

Manual run:

```text
java -jar dependencies/JavaStaticAnalysis.jar -apk <path\to\app.apk>
```

## 4) NativeDynamicAnalysis Architecture

Native pipeline:

```text
Unidbg emulation
  -> TritonHook syncs register/memory/instruction state
  -> Triton executes taint/symbolic semantics
  -> PropagationObserver records propagation events
  -> BoundaryObserver records JNI/libc boundary events
  -> EffectBasedJimpleGenerator reconstructs high-level effects and emits Jimple
```

Core code:

- `NativeDynamicAnalysis/unidbg/unidbg-android/src/main/java/com/github/unidbg/triton/TritonAnalysisFacade.java`
- `NativeDynamicAnalysis/unidbg/unidbg-android/src/main/java/com/github/unidbg/triton/TritonHook.java`
- `NativeDynamicAnalysis/unidbg/unidbg-android/src/main/java/com/github/unidbg/triton/boundary/BoundaryObserver.java`
- `NativeDynamicAnalysis/unidbg/unidbg-android/src/main/java/com/github/unidbg/triton/propagation/PropagationObserver.java`
- `NativeDynamicAnalysis/unidbg/unidbg-android/src/main/java/com/github/unidbg/triton/jimple/EffectBasedJimpleGenerator.java`

## 5) Build Native Bridge and Test

Build JNI bridge (Windows PowerShell):

```powershell
cd NativeDynamicAnalysis
./build_unidbg_triton.ps1 -BuildType Release -Triplet x64-windows
```

Default output:

```text
NativeDynamicAnalysis/bridge/unidbg-triton/build-x64-windows-Release/Release/unidbg_triton.dll
```

Build/test unidbg:

```powershell
cd NativeDynamicAnalysis/unidbg
./mvnw clean install -DskipTests
```

Test only `unidbg-android`:

```powershell
cd NativeDynamicAnalysis/unidbg
./mvnw -pl unidbg-android clean test
```

## 6) Key Directories

```text
TRACE/
├── Readme.md
├── README_cn.md
├── JavaStaticAnalysis/
├── NativeDynamicAnalysis/
├── scripts/
├── evaluation/
└── result/
```

## 7) References

- [Triton documentation](https://triton-library.github.io/)
- [Unidbg repository](https://github.com/zhkl0228/unidbg)
- [JNI specification](https://docs.oracle.com/javase/8/docs/technotes/guides/jni/)