|
1 | | -# Frida Dynamic Analysis |
| 1 | +# Frida Analysis for capa |
| 2 | +This tool uses Frida to monitor Android applications and generates behavioral JSONL data that capa can analyze to identify program capabilities. |
2 | 3 |
|
3 | | -This guide shows how to generate Frida hooks and analyze Android app API calls with capa. |
| 4 | +Frida enables dynamic analysis by watching what API calls an Android app makes when it runs. This tool instruments Android apps with Frida, recording hooked API call information. The recorded data is formatted as JSONL for capa to analyze using its capability detection rules. |
4 | 5 |
|
5 | 6 | ## Prerequisites |
6 | 7 |
|
7 | | -### 1. Download Android Studio |
8 | | -Download from: https://developer.android.com/studio |
| 8 | +**Android Development Environment** |
9 | 9 |
|
10 | | -**Required SDK components for auto-emulator creation** |
11 | | -(install via Settings → Languages & Frameworks → Android SDK → SDK Tools): |
12 | | -- Android SDK Command-line Tools |
13 | | -- Android Emulator |
14 | | -- Android SDK Platform-Tools |
| 10 | +Download Android Studio from [Android Studio Website](https://developer.android.com/studio). |
15 | 11 |
|
16 | | -**Default SDK locations:** |
| 12 | +Install these SDK components in Android Studio → Settings → Languages & Frameworks → Android SDK → SDK Tools: |
| 13 | +`Android SDK Command-line Tools`, `Android Emulator`, `Android SDK Platform-Tools`, and `Android SDK Build-Tools`. |
| 14 | + |
| 15 | +Default SDK locations: |
17 | 16 | - macOS: `~/Library/Android/sdk` |
18 | 17 | - Linux: `~/Android/Sdk` |
19 | 18 | - Windows: `~\AppData\Local\Android\Sdk` |
20 | 19 |
|
21 | | -### 2. Install Dependencies |
22 | | -```bash |
23 | | -# jinja2 pydantic could be added to requirements.txt later |
24 | | - |
25 | | -# Python packages |
26 | | -pip install frida==17.2.15 frida-tools jinja2 pydantic |
27 | | -pip install capa[frida] |
28 | | - |
29 | | -# Node.js (for frida-compile) |
30 | | -brew install node # macOS |
31 | | -# sudo apt install nodejs npm # Linux |
32 | | -# Download from nodejs.org for Windows |
33 | | -``` |
| 20 | +**Analysis Tool** |
34 | 21 |
|
35 | | -### (Optional) Create emulator and start frida-server |
36 | | -We can auto-create an rooted emulator with frida-server for you. |
37 | | -But you can manully setup your own emualtor/device. |
38 | | -For more details, see our [manual setup guide](setup.md) and |
39 | | -[Frida Server + Rooted Emulator](https://docs.google.com/document/d/1WpPRcdtnPYdOn4n7Wl3aghbZUv2wmefiuaf2WDIR5Pw/edit?tab=t.0#heading=h.sqgvzr4xgg42) |
| 22 | +Download capa from [capa repo](https://github.com/mandiant/capa) to analyze the behavioral data output. |
40 | 23 |
|
41 | | -## Usage |
42 | | -### Automated Analysis (Recommended) |
| 24 | +**Dependencies** |
43 | 25 |
|
44 | 26 | ```bash |
45 | | -# Complete pipeline - creates emulator if needed |
46 | | -# To start the AVDs auto-created, open your Android Studio |
47 | | -# Tools → Device Manager → find 'frida-emulator' and start it" |
| 27 | +# Python dependencies needed |
| 28 | +pip install frida==17.2.15 frida-tools jinja2 |
48 | 29 |
|
49 | | -python main.py --package com.scottyab.rootbeer.sample |
50 | | - |
51 | | -# python apk_meta_extractor.py --package com.app --apk /path/to/app.apk --apis frida_apis.json --script frida_monitor.ts --output api_calls.jsonl |
52 | | -# Options: |
53 | | -# --package: Android package name (required) |
54 | | -# --apk: Local APK file path (optional, will use ADB to get from device if not provided) |
55 | | -# --apis: JSON filename containing APIs (default: frida_apis.json) |
56 | | -# --script: Output script filename (default: frida_monitor.ts) |
57 | | -# --output: JSONL output filename in emulator that you wanna create after monitoring (default: api_calls.jsonl) |
| 30 | +# Install Node.js npm for frida-compile |
| 31 | +# macOS: `brew install node` |
| 32 | +# Linux: `sudo apt install nodejs npm` |
| 33 | +# Windows: Download from [nodejs.org](https://nodejs.org) |
58 | 34 | ``` |
59 | 35 |
|
60 | | -### Manual Steps (if you want) |
61 | | - |
62 | | -### Step 0: Device Preparation |
63 | | -```bash |
64 | | -# Create output directory with full permissions |
65 | | -adb shell su -c "mkdir -p /data/local/tmp/frida_outputs" |
66 | | -adb shell su -c "chmod -R 777 /data/local/tmp/frida_outputs" |
| 36 | +## Quick start |
67 | 37 |
|
68 | | -# Disable SELinux enforcement (resets on reboot) |
69 | | -adb shell su -c "setenforce 0" |
| 38 | +The tool creates an Android emulator automatically if you don't have one connected. |
70 | 39 |
|
71 | | -# Start Frida server on device |
72 | | -adb shell su -c "/data/local/tmp/frida-server &" |
73 | | -``` |
| 40 | +```bash |
| 41 | +# Scenario 1: Analyze app already on device |
| 42 | +python main.py --package com.example.app |
74 | 43 |
|
75 | | -### Step 1: Generate Frida Monitoring Script |
| 44 | +# Scenario 2: Install APK and analyze |
| 45 | +python main.py --apk /path/to/app.apk |
76 | 46 |
|
77 | | -```bash |
78 | | -# Navigate to the frida dir |
79 | | -cd scripts/frida/ |
80 | | - |
81 | | -# Extract APK metadata and hashes from apk getting via adb in device |
82 | | -python apk_meta_extractor.py --package com.app |
83 | | -# Options: |
84 | | -# python apk_meta_extractor.py --package com.app --apk /path/to/app.apk |
85 | | -# --package: Android package name (required) |
86 | | -# --apk: Local APK file path (optional, will use ADB to get from device if not provided) |
87 | | - |
88 | | -# Generate monitoring script |
89 | | -python hook_builder.py |
90 | | -# Options: |
91 | | -# python hook_builder.py --apis frida_apis.json --script frida_monitor.ts --output api_calls.jsonl |
| 47 | +# Additional customized options: |
92 | 48 | # --apis: JSON filename containing APIs (default: frida_apis.json) |
93 | 49 | # --script: Output script filename (default: frida_monitor.ts) |
94 | | -# --output: JSONL output filename in emulator that you wanna create after monitoring (default: api_calls.jsonl) |
95 | | -``` |
96 | | -### Step 2(Optional): JavaScript bundle via frida-compile |
97 | | -The generated TypeScript script could be compiled with frida-compile: |
98 | | -automation part contain this, because Frida 17.x bridge... |
99 | | -```bash |
100 | | -mkdir -p agent |
101 | | -cd agent |
102 | | -frida-create -t agent |
103 | | -npm install |
104 | | -npm install frida-java-bridge |
105 | | -cd .. |
106 | | - |
107 | | -# Prepare script for compilation (for example Java bridge import), add this to script: |
108 | | -import Java from "frida-java-bridge"; |
109 | | - |
110 | | -# Compile TypeScript to JavaScript bundle |
111 | | -frida-compile path_to_your_script -o agent/compiled_bundle.js |
| 50 | +# --output: JSONL output filename on device (default: api_calls.jsonl) |
112 | 51 | ``` |
113 | 52 |
|
114 | | -### Step 3: Run Dynamic Analysis |
115 | | - |
116 | | -```bash |
117 | | -# Launch Rootbeer app with Frida monitoring |
118 | | -# With frida-compile step, use compiled bundle: |
119 | | -frida -U -f com.scottyab.rootbeer.sample -l agent/compiled_bundle.js |
120 | | - |
121 | | -# Otherwise, use: |
122 | | -frida -U -f com.scottyab.rootbeer.sample -l frida_scripts/frida_monitor.ts |
123 | | - |
124 | | -# For other apps, use their package name: |
125 | | -# frida -U -f com.example.app -l frida_scripts/frida_monitor.ts |
126 | | - |
127 | | -# Let the app run and perform the behaviors you want to analyze |
128 | | -# Type `exit` and Press `Ctrl+C` to stop monitoring |
129 | | -``` |
130 | | - |
131 | | -**Notes:** |
132 | | -- File Permission Conflicts |
133 | | -Root Cause: Android apps create files with their UID ownership. App A cannot overwrite files created by App B. |
134 | | -- Solution 1: Delete this file before next analysis |
135 | | -- Solution 2: Change to a new filename for {jsonl_filename} in frida_monitor.ts, you can directly use --output command line: |
136 | | -var filePath = "/data/local/tmp/frida_outputs/{{jsonl_filename}}"; |
137 | | - |
138 | | -### Step 4: Retrieve Analysis Data |
139 | | - |
140 | | -```bash |
141 | | -# (Check if file exits) |
142 | | -adb shell su -c "ls -la /data/local/tmp/frida_outputs/" |
143 | | - |
144 | | -adb root |
145 | | -# Using adb pull |
146 | | -adb pull /data/local/tmp/frida_outputs/api_calls.jsonl ./frida_outputs/api_calls.jsonl |
147 | | -``` |
148 | | - |
149 | | -## Analyze with capa |
150 | | -```bash |
151 | | -# Navigate back to capa root directory |
152 | | -cd ../../ |
153 | | - |
154 | | -# Activate your capa environment |
155 | | -source ~/capa-env/bin/activate |
156 | | - |
157 | | -# Using your custom Frida rules (for development/testing) |
158 | | -python capa/main.py -r scripts/frida/test_rules/ -d scripts/frida/frida_outputs/api_calls.jsonl |
159 | | - |
160 | | -# Using this after integrated |
161 | | -capa api_calls.jsonl |
162 | | -``` |
163 | | - |
164 | | -### Folder Components |
165 | | -- **main.py**: Complete automation pipeline |
166 | | - |
167 | | -**Directories:** |
168 | | -- **/frida_apis/*.json**: Contains API JSON files |
169 | | -- **/frida_templates/**: Jinja2 templates for script generation |
170 | | -- **/frida_scripts/*.ts**: Generated executable scripts (output) |
171 | | -- **/agent/**: frida-compile environment and compiled bundles |
172 | | -- **/frida_outputs/*.jsonl**: outputs that need capa to anlaysis |
173 | | - |
174 | | - |
175 | | -!!! |
176 | | -Put these here for now |
| 53 | +Press Ctrl+D to stop Frida monitoring, results are saved to `frida_outputs/` folder. Then you can run capa on the output files to analyze capabilities. |
177 | 54 |
|
178 | | -- **Rooted Android emulator with Frida server running** |
179 | | -[Frida Server + Rooted Emulator](https://docs.google.com/document/d/1WpPRcdtnPYdOn4n7Wl3aghbZUv2wmefiuaf2WDIR5Pw/edit?tab=t.0#heading=h.sqgvzr4xgg42) |
| 55 | +**What the automation does:** |
| 56 | +Creates an configed emulator |
| 57 | +Extracts APK metadata and hashes |
| 58 | +Generates monitoring script from API specifications |
| 59 | +Executes Frida analysis with compiled script |
| 60 | +Retrieves results for capa |
180 | 61 |
|
181 | | -- **Python virtual environment with capa installed** |
182 | | -[capa install page](https://github.com/mandiant/capa/blob/master/doc/installation.md) |
| 62 | +## Manual Workflow (if you want) |
183 | 63 |
|
184 | | -- **Target app installed on emulator** |
185 | | -Example: RootBeer sample app from Google Play Store, or build from [Rootbeer Github](https://github.com/scottyab/rootbeer?tab=readme-ov-file) (Rootbeer GitHub version is newer) |
| 64 | +For users who prefer step-by-step control, see [Manual Steps Guide](manual_steps.md). |
0 commit comments