0
# Androguard
1

2
A comprehensive Python toolkit for Android application reverse engineering and security analysis. Androguard provides extensive capabilities for processing and analyzing various Android file formats including DEX/ODEX bytecode, APK packages, Android binary XML files, and Android resources.
3

4
## Package Information
5

6
- **Package Name**: androguard
7
- **Language**: Python
8
- **Installation**: `pip install androguard`
9
- **Python Requirements**: Python >= 3.9
10
- **License**: Apache License 2.0
11

12
## Core Imports
13

14
```python
15
import androguard
16
```
17

18
Common for APK analysis:
19

20
```python
21
from androguard.core.apk import APK
22
from androguard.core.dex import DEX
23
from androguard.core.axml import AXMLPrinter, ARSCParser
24
```
25

26
For analysis and decompilation:
27

28
```python
29
from androguard.core.analysis.analysis import Analysis
30
from androguard.decompiler.dad.decompile import DvClass, DvMethod
31
```
32

33
Session-based analysis:
34

35
```python
36
from androguard.session import Session
37
from androguard.misc import AnalyzeAPK, AnalyzeDex
38
```
39

40
## Basic Usage
41

42
```python
43
from androguard.core.apk import APK
44
from androguard.misc import AnalyzeAPK
45

46
# Basic APK analysis
47
apk_path = "path/to/app.apk"
48
apk = APK(apk_path)
49

50
# Get basic APK information
51
print(f"Package name: {apk.get_package()}")
52
print(f"App name: {apk.get_app_name()}")
53
print(f"Version: {apk.get_androidversion_name()}")
54
print(f"Permissions: {apk.get_permissions()}")
55

56
# Complete analysis with DEX and decompilation
57
a, d, dx = AnalyzeAPK(apk_path)
58

59
# Access classes and methods
60
for cls in dx.get_classes():
61
    print(f"Class: {cls.name}")
62
    for method in cls.get_methods():
63
        print(f"  Method: {method.name}")
64

65
# Decompile a specific method
66
for cls in d:
67
    for method in cls.get_methods():
68
        if method.get_name() == "onCreate":
69
            print(method.get_source())
70
```
71

72
## Architecture
73

74
Androguard follows a layered architecture enabling comprehensive Android reverse engineering:
75

76
- **Core Parsers**: APK, DEX, AXML, and ARSC parsers handle Android file format processing
77
- **Analysis Layer**: Static analysis engine providing control flow, call graphs, and method analysis
78
- **Decompiler**: DAD (Dex to Android Decompiler) converts bytecode to readable Java-like source
79
- **Session Management**: Persistent sessions for complex analysis workflows
80
- **CLI Tools**: Command-line utilities for quick analysis tasks
81
- **Dynamic Analysis**: Integration with Frida for runtime analysis and modification
82

83
This modular design enables both simple one-off analysis tasks and complex automated security research workflows.
84

85
## Capabilities
86

87
### APK Processing
88

89
Complete Android Package (APK) file analysis including manifest parsing, resource extraction, signature verification, permission analysis, and file structure inspection.
90

91
```python { .api }
92
class APK:
93
    def __init__(self, filename: str, raw: bool = False, skip_analysis: bool = False, testzip: bool = False): ...
94
    def get_package(self) -> str: ...
95
    def get_app_name(self, locale=None) -> str: ...
96
    def get_androidversion_name(self) -> str: ...
97
    def get_permissions(self) -> list[str]: ...
98
    def get_activities(self) -> list[str]: ...
99
    def get_services(self) -> list[str]: ...
100
    def get_receivers(self) -> list[str]: ...
101
    def is_signed(self) -> bool: ...
102
```
103

104
[APK Processing](./apk-processing.md)
105

106
### DEX Analysis
107

108
Dalvik Executable (DEX) file parsing and bytecode analysis providing access to classes, methods, instructions, and control flow structures.
109

110
```python { .api }
111
class DEX:
112
    def get_classes_names(self) -> list[str]: ...
113
    def get_class(self, name: str): ...
114
    def get_methods(self) -> list: ...
115
    def get_fields(self) -> list: ...
116
```
117

118
[DEX Analysis](./dex-analysis.md)
119

120
### Android XML Processing
121

122
Binary Android XML (AXML) and Android Resource (ARSC) file processing for accessing application resources, layouts, and configuration data.
123

124
```python { .api }
125
class AXMLPrinter:
126
    def __init__(self, raw_buff: bytes): ...
127
    def get_xml(self, pretty: bool = True) -> bytes: ...
128
    def is_valid(self) -> bool: ...
129

130
class ARSCParser:
131
    def __init__(self, raw_buff: bytes): ...
132
    def get_packages_names(self) -> list[str]: ...
133
    def get_string_resources(self, package_name: str, locale: str = '\x00\x00') -> bytes: ...
134
```
135

136
[XML and Resources](./xml-resources.md)
137

138
### Static Analysis
139

140
Advanced static analysis capabilities including control flow analysis, call graph generation, method analysis, and cross-reference detection.
141

142
```python { .api }
143
class Analysis:
144
    def get_classes(self) -> list: ...
145
    def get_methods(self) -> list: ...
146
    def get_call_graph(self): ...
147
    def find_classes(self, class_name: str): ...
148
    def find_methods(self, class_name: str = ".*", method_name: str = ".*"): ...
149
```
150

151
[Static Analysis](./static-analysis.md)
152

153
### Decompilation
154

155
Java-like source code generation from Android bytecode using the DAD (Dex to Android Decompiler) engine.
156

157
```python { .api }
158
class DvClass:
159
    def get_source(self) -> str: ...
160
    def get_methods(self): ...
161

162
class DvMethod:
163
    def get_source(self) -> str: ...
164
    def get_name(self) -> str: ...
165
```
166

167
[Decompilation](./decompilation.md)
168

169
### Session Management
170

171
Persistent analysis sessions for complex workflows, enabling save/restore of analysis state and incremental processing.
172

173
```python { .api }
174
class Session:
175
    def __init__(self): ...
176
    def add(self, filename: str, raw_data: bytes = None): ...
177
    def save(self, filename: str): ...
178
    def load(self, filename: str): ...
179
```
180

181
[Session Management](./session-management.md)
182

183
### Command Line Tools
184

185
Pre-built command-line utilities for common analysis tasks including APK inspection, DEX analysis, signature verification, and more.
186

187
```python { .api }
188
def entry_point(): ...  # Main CLI entry point
189
```
190

191
[Command Line Tools](./cli-tools.md)
192

193
### Utility Functions
194

195
High-level utility functions for common analysis workflows, providing simplified interfaces for complex operations.
196

197
```python { .api }
198
def AnalyzeAPK(filename: str, session=None, raw: bool = False): ...
199
def AnalyzeDex(filename: str, session=None, raw: bool = False): ...
200
def get_certificate_name_string(name, short: bool = False) -> str: ...
201
```
202

203
[Utility Functions](./utility-functions.md)
204

205
### Dynamic Analysis
206

207
Runtime analysis and modification capabilities using Frida integration for dynamic analysis, tracing, and runtime manipulation of Android applications.
208

209
```python { .api }
210
class Pentest:
211
    def __init__(self): ...
212
    def connect_default_usb(self) -> bool: ...
213
    def attach_package(self, package_name: str, list_file_scripts: list, pid=None) -> bool: ...
214
    def start_trace(self, filename: str, session: Session, list_modules: list, list_packages: list = None) -> None: ...
215
    def dump(self, package_name: str) -> dict: ...
216
```
217

218
[Dynamic Analysis](./dynamic-analysis.md)
219

220
### Bytecode Utilities
221

222
Advanced bytecode analysis and formatting utilities including visualization, export capabilities, and statistical analysis of Android bytecode.
223

224
```python { .api }
225
def method2dot(mx: MethodAnalysis, colors: dict = None) -> str: ...
226
def method2png(filename: str, mx: MethodAnalysis, colors: dict = None) -> None: ...
227
def method2json(mx: MethodAnalysis, colors: dict = None) -> str: ...
228
def FormatClassToJava(class_name: str) -> str: ...
229
def get_package_class_name(class_name: str) -> tuple[str, str]: ...
230
def get_method_complexity(mx: MethodAnalysis) -> dict: ...
231
```
232

233
[Bytecode Utilities](./bytecode-utilities.md)
234

235
## Common Types
236

237
```python { .api }
238
# Analysis results tuple from AnalyzeAPK
239
AnalysisResult = tuple[APK, list[DEX], Analysis]
240

241
# Analysis results tuple from AnalyzeDex  
242
DexAnalysisResult = tuple[list[DEX], Analysis]
243

244
# Permission information
245
Permission = str
246

247
# Certificate information
248
Certificate = object
249

250
# Resource configuration
251
ResourceConfig = object
252

253
# Dynamic analysis types
254
MessageEvent = object
255
MessageSystem = object
256

257
# Advanced signature types
258
APKV2SignedData = object
259
APKV3SignedData = object
260
APKV2Signer = object
261
APKV3Signer = object
262

263
# Decompiler IR types
264
IRForm = object
265
Constant = object
266
Variable = object
267
BinaryOperation = object
268
AssignExpression = object
269
InvokeInstruction = object
270
FieldAccess = object
271

272
# Basic block types
273
BasicBlock = object
274
StatementBlock = object
275
ConditionalBlock = object
276
LoopBlock = object
277
TryBlock = object
278
ReturnBlock = object
279

280
# Method analysis type
281
MethodAnalysis = object
282
```