apkdiff-core 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
apkdiff_core/diff.py ADDED
@@ -0,0 +1,311 @@
1
+ """Compare two APK analyses and classify every change.
2
+
3
+ dex.py and apk.py understand one APK; this module understands the difference
4
+ between two APKs.
5
+
6
+ Four change states:
7
+ added present only in the new APK
8
+ deleted present only in the old APK
9
+ modified present in both with different content
10
+ renamed a deleted and an added entry with identical content
11
+ (only with --detect-renames)
12
+
13
+ Classes compare by semantic fingerprint (see dex.py); resources compare by
14
+ SHA-256 content hash.
15
+
16
+ The summary (APK delta, class/resource counts, ...) is consumed by reporters.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ from dataclasses import dataclass, field
22
+
23
+ from .apk import ApkAnalysis, ApkClass, ApkEntry
24
+
25
+ ADDED = "added"
26
+ DELETED = "deleted"
27
+ MODIFIED = "modified"
28
+ RENAMED = "renamed"
29
+ UNCHANGED = "unchanged"
30
+
31
+ STATUS_LABEL = {
32
+ ADDED: "新增",
33
+ DELETED: "删除",
34
+ MODIFIED: "修改",
35
+ RENAMED: "重命名",
36
+ UNCHANGED: "未变",
37
+ }
38
+
39
+
40
+ @dataclass
41
+ class Change:
42
+ key: str
43
+ kind: str # "class" | "resource"
44
+ status: str
45
+ old_size: int # uncompressed bytes
46
+ new_size: int
47
+ old_compressed: int
48
+ new_compressed: int
49
+ old_hash: str = ""
50
+ new_hash: str = ""
51
+ detail: dict = field(default_factory=dict)
52
+
53
+ @property
54
+ def delta(self) -> int:
55
+ return self.new_size - self.old_size
56
+
57
+ @property
58
+ def compressed_delta(self) -> int:
59
+ return self.new_compressed - self.old_compressed
60
+
61
+ def size_for(self, metric: str) -> int:
62
+ return self.compressed_delta if metric == "compressed" else self.delta
63
+
64
+ def old_for(self, metric: str) -> int:
65
+ return self.old_compressed if metric == "compressed" else self.old_size
66
+
67
+ def new_for(self, metric: str) -> int:
68
+ return self.new_compressed if metric == "compressed" else self.new_size
69
+
70
+ def as_dict(self) -> dict:
71
+ return {
72
+ "key": self.key,
73
+ "kind": self.kind,
74
+ "status": self.status,
75
+ "status_label": STATUS_LABEL.get(self.status, self.status),
76
+ "old_size": self.old_size,
77
+ "new_size": self.new_size,
78
+ "delta": self.delta,
79
+ "old_compressed": self.old_compressed,
80
+ "new_compressed": self.new_compressed,
81
+ "compressed_delta": self.compressed_delta,
82
+ "old_hash": self.old_hash,
83
+ "new_hash": self.new_hash,
84
+ "detail": self.detail,
85
+ }
86
+
87
+
88
+ @dataclass
89
+ class DiffResult:
90
+ old: ApkAnalysis
91
+ new: ApkAnalysis
92
+ classes: list[Change] = field(default_factory=list)
93
+ resources: list[Change] = field(default_factory=list)
94
+ summary: dict = field(default_factory=dict)
95
+
96
+ @property
97
+ def changes(self) -> list[Change]:
98
+ return self.classes + self.resources
99
+
100
+
101
+ def _class_changes(old: ApkAnalysis, new: ApkAnalysis) -> list[Change]:
102
+ out: list[Change] = []
103
+ all_keys = sorted(set(old.classes) | set(new.classes))
104
+ for key in all_keys:
105
+ o: ApkClass | None = old.classes.get(key)
106
+ n: ApkClass | None = new.classes.get(key)
107
+ if o is None and n is not None:
108
+ out.append(Change(
109
+ key=key, kind="class", status=ADDED,
110
+ old_size=0, new_size=n.size, old_compressed=0,
111
+ new_compressed=n.compressed_size, new_hash=n.content_hash,
112
+ detail={
113
+ "raw_name": n.raw_name, "dex": n.dex,
114
+ "methods": n.methods, "fields": n.fields,
115
+ "breakdown": n.breakdown.as_dict(),
116
+ "partial": n.partial, "warning": n.warning,
117
+ },
118
+ ))
119
+ elif o is not None and n is None:
120
+ out.append(Change(
121
+ key=key, kind="class", status=DELETED,
122
+ old_size=o.size, new_size=0, old_compressed=o.compressed_size,
123
+ new_compressed=0, old_hash=o.content_hash,
124
+ detail={
125
+ "raw_name": o.raw_name, "dex": o.dex,
126
+ "methods": o.methods, "fields": o.fields,
127
+ "breakdown": o.breakdown.as_dict(),
128
+ "partial": o.partial, "warning": o.warning,
129
+ },
130
+ ))
131
+ else:
132
+ assert o is not None and n is not None
133
+ if o.content_hash == n.content_hash:
134
+ # Present in both. Compare semantic fingerprints, not byte counts:
135
+ # an identical fingerprint means the source did not change, even if index
136
+ # pool reshuffling shifted attributed bytes slightly.
137
+ # Without this, adding one unrelated class would mark almost every class
138
+ # as modified and drown the report.
139
+ continue
140
+ old_breakdown = o.breakdown.as_dict()
141
+ new_breakdown = n.breakdown.as_dict()
142
+ breakdown_delta = {
143
+ k: new_breakdown[k] - old_breakdown[k] for k in old_breakdown
144
+ }
145
+ out.append(Change(
146
+ key=key, kind="class", status=MODIFIED,
147
+ old_size=o.size, new_size=n.size,
148
+ old_compressed=o.compressed_size, new_compressed=n.compressed_size,
149
+ old_hash=o.content_hash, new_hash=n.content_hash,
150
+ detail={
151
+ "raw_name": n.raw_name,
152
+ "dex": f"{o.dex} -> {n.dex}" if o.dex != n.dex else n.dex,
153
+ "methods_before": o.methods, "methods_after": n.methods,
154
+ "fields_before": o.fields, "fields_after": n.fields,
155
+ "breakdown_delta": breakdown_delta,
156
+ "partial": o.partial or n.partial,
157
+ "warning": " | ".join(filter(None, [o.warning, n.warning])),
158
+ },
159
+ ))
160
+ return out
161
+
162
+
163
+ def _entry_change(
164
+ key: str,
165
+ o: ApkEntry | None,
166
+ n: ApkEntry | None,
167
+ status: str,
168
+ renamed_from: str = "",
169
+ ) -> Change:
170
+ detail: dict = {"category": n.category if n is not None else o.category}
171
+ if o is not None and n is not None:
172
+ detail["crc_before"] = f"{o.crc:08x}"
173
+ detail["crc_after"] = f"{n.crc:08x}"
174
+ detail["hash_before"] = o.sha256[:16]
175
+ detail["hash_after"] = n.sha256[:16]
176
+ detail["compression_before"] = (
177
+ round((1 - o.compress_size / o.file_size) * 100, 1) if o.file_size else 0
178
+ )
179
+ detail["compression_after"] = (
180
+ round((1 - n.compress_size / n.file_size) * 100, 1) if n.file_size else 0
181
+ )
182
+ if renamed_from:
183
+ detail["renamed_from"] = renamed_from
184
+ return Change(
185
+ key=key,
186
+ kind="resource",
187
+ status=status,
188
+ old_size=o.file_size if o else 0,
189
+ new_size=n.file_size if n else 0,
190
+ old_compressed=o.compress_size if o else 0,
191
+ new_compressed=n.compress_size if n else 0,
192
+ old_hash=o.sha256 if o else "",
193
+ new_hash=n.sha256 if n else "",
194
+ detail=detail,
195
+ )
196
+
197
+
198
+ def _included_entries(apk: ApkAnalysis, include_meta: bool) -> dict[str, ApkEntry]:
199
+ """Resource entries participating in the comparison (META-INF is opt-in)."""
200
+ return {
201
+ name: entry
202
+ for name, entry in apk.resource_entries.items()
203
+ if include_meta or entry.category != "meta"
204
+ }
205
+
206
+
207
+ def _resource_changes(
208
+ old_entries: dict[str, ApkEntry],
209
+ new_entries: dict[str, ApkEntry],
210
+ detect_renames: bool,
211
+ ) -> list[Change]:
212
+ added = sorted(set(new_entries) - set(old_entries))
213
+ deleted = sorted(set(old_entries) - set(new_entries))
214
+
215
+ changes: list[Change] = []
216
+ paired_old: set[str] = set()
217
+ paired_new: set[str] = set()
218
+
219
+ if detect_renames:
220
+ # Find renamed files: a deleted old entry and an added new entry with
221
+ # identical content hashes are likely the same file under a new name
222
+ # (for example a drawable renamed).
223
+ # Group deleted files by hash, then match each added file's hash.
224
+ by_hash: dict[str, list[str]] = {}
225
+ for name in deleted:
226
+ h = old_entries[name].sha256
227
+ if h:
228
+ by_hash.setdefault(h, []).append(name)
229
+ for name in added:
230
+ h = new_entries[name].sha256
231
+ candidates = by_hash.get(h, []) if h else []
232
+ if not candidates:
233
+ continue
234
+ old_name = candidates.pop(0)
235
+ if not candidates:
236
+ del by_hash[h]
237
+ paired_old.add(old_name)
238
+ paired_new.add(name)
239
+ changes.append(_entry_change(name, old_entries[old_name], new_entries[name],
240
+ RENAMED, renamed_from=old_name))
241
+
242
+ for name in sorted(set(new_entries)):
243
+ if name in old_entries:
244
+ o, n = old_entries[name], new_entries[name]
245
+ if o.sha256 != n.sha256 or o.file_size != n.file_size:
246
+ changes.append(_entry_change(name, o, n, MODIFIED))
247
+ elif name not in paired_new:
248
+ changes.append(_entry_change(name, None, new_entries[name], ADDED))
249
+
250
+ for name in deleted:
251
+ if name not in paired_old:
252
+ changes.append(_entry_change(name, old_entries[name], None, DELETED))
253
+
254
+ return changes
255
+
256
+
257
+ def diff_apks(
258
+ old: ApkAnalysis,
259
+ new: ApkAnalysis,
260
+ include_meta: bool = False,
261
+ detect_renames: bool = False,
262
+ ) -> DiffResult:
263
+ old_entries = _included_entries(old, include_meta)
264
+ new_entries = _included_entries(new, include_meta)
265
+ classes = _class_changes(old, new)
266
+ resources = _resource_changes(old_entries, new_entries, detect_renames)
267
+
268
+ def counts(items: list[Change], status: str) -> int:
269
+ return sum(1 for c in items if c.status == status)
270
+
271
+ old_class_bytes = old.total_class_bytes
272
+ new_class_bytes = new.total_class_bytes
273
+ old_class_compressed = old.total_class_compressed_bytes
274
+ new_class_compressed = new.total_class_compressed_bytes
275
+ old_resource_bytes = sum(e.file_size for e in old_entries.values())
276
+ new_resource_bytes = sum(e.file_size for e in new_entries.values())
277
+ old_resource_compressed = sum(e.compress_size for e in old_entries.values())
278
+ new_resource_compressed = sum(e.compress_size for e in new_entries.values())
279
+
280
+ summary = {
281
+ "old_apk_size": old.file_size,
282
+ "new_apk_size": new.file_size,
283
+ "apk_size_delta": new.file_size - old.file_size,
284
+ "old_class_bytes": old_class_bytes,
285
+ "new_class_bytes": new_class_bytes,
286
+ "class_bytes_delta": new_class_bytes - old_class_bytes,
287
+ "old_class_compressed": old_class_compressed,
288
+ "new_class_compressed": new_class_compressed,
289
+ "class_compressed_delta": new_class_compressed - old_class_compressed,
290
+ "old_resource_bytes": old_resource_bytes,
291
+ "new_resource_bytes": new_resource_bytes,
292
+ "old_resource_compressed": old_resource_compressed,
293
+ "new_resource_compressed": new_resource_compressed,
294
+ "class_count_old": len(old.classes),
295
+ "class_count_new": len(new.classes),
296
+ "class_added": counts(classes, ADDED),
297
+ "class_deleted": counts(classes, DELETED),
298
+ "class_modified": counts(classes, MODIFIED),
299
+ "resource_added": counts(resources, ADDED),
300
+ "resource_deleted": counts(resources, DELETED),
301
+ "resource_modified": counts(resources, MODIFIED),
302
+ "resource_renamed": counts(resources, RENAMED),
303
+ "dex_unattributed_old": old.unattributed_dex_bytes,
304
+ "dex_unattributed_new": new.unattributed_dex_bytes,
305
+ }
306
+ summary["resource_bytes_delta"] = new_resource_bytes - old_resource_bytes
307
+ summary["resource_compressed_delta"] = (
308
+ new_resource_compressed - old_resource_compressed
309
+ )
310
+
311
+ return DiffResult(old=old, new=new, classes=classes, resources=resources, summary=summary)
@@ -0,0 +1,84 @@
1
+ """Read ProGuard/R8 mapping.txt and restore obfuscated class names.
2
+
3
+ Release code is usually obfuscated: com.shop.ui.MainActivity becomes a.b.
4
+ mapping.txt records "a.b came from com.shop.ui.MainActivity".
5
+
6
+ Reports should show readable business names, so names are translated through
7
+ this table.
8
+
9
+ Only **class-level** mappings are parsed. Method/field mappings exist in the
10
+ file but are not displayed by reports.
11
+
12
+ A missing mapping file is fine: names from the dex are shown unchanged.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ import re
18
+ from dataclasses import dataclass, field
19
+
20
+ from .dex import descriptor_to_class_name
21
+
22
+ _CLASS_RE = re.compile(r"^\s*(\S+)\s+->\s+(\S+):\s*$")
23
+
24
+
25
+ @dataclass
26
+ class Mapping:
27
+ path: str
28
+ # obfuscated dotted name -> original dotted name
29
+ class_names: dict[str, str] = field(default_factory=dict)
30
+ warnings: list[str] = field(default_factory=list)
31
+
32
+ def original_name(self, obfuscated: str) -> str:
33
+ """Resolve a dotted obfuscated class name, longest-prefix safe.
34
+
35
+ Falls back to the input when no mapping exists.
36
+ """
37
+ name = obfuscated.strip()
38
+ if name in self.class_names:
39
+ return self.class_names[name]
40
+ # Some R8 versions emit array-ish or generic suffixes; strip them.
41
+ for suffix in ("[]", "..."):
42
+ while name.endswith(suffix):
43
+ name = name[: -len(suffix)]
44
+ return self.class_names.get(name, obfuscated)
45
+
46
+ def deobfuscate_descriptor(self, descriptor: str) -> str:
47
+ """'La/b/c;' -> original fully-qualified class name."""
48
+ obfuscated = descriptor_to_class_name(descriptor)
49
+ return self.original_name(obfuscated)
50
+
51
+ @classmethod
52
+ def parse(cls, path: str) -> "Mapping":
53
+ mapping = cls(path=path)
54
+ try:
55
+ with open(path, "r", encoding="utf-8", errors="replace") as fh:
56
+ lines = fh.readlines()
57
+ except OSError as exc:
58
+ mapping.warnings.append(f"cannot read mapping file: {exc}")
59
+ return mapping
60
+
61
+ for lineno, line in enumerate(lines, 1):
62
+ # mapping.txt contains comments, method mappings and field mappings.
63
+ # Only class mappings are recognized:
64
+ # com.shop.ui.MainActivity -> a.b:
65
+ # Other lines (comments or non "original -> obfuscated:" forms) are skipped.
66
+ match = _CLASS_RE.match(line)
67
+ if not match:
68
+ continue
69
+ original, obfuscated = match.group(1), match.group(2)
70
+ if original.startswith("#") or obfuscated.startswith("#"):
71
+ continue
72
+ if obfuscated in mapping.class_names and mapping.class_names[obfuscated] != original:
73
+ mapping.warnings.append(
74
+ f"line {lineno}: duplicate obfuscated name {obfuscated!r}"
75
+ )
76
+ mapping.class_names[obfuscated] = original
77
+ return mapping
78
+
79
+
80
+ def load_mapping(path: str | None) -> Mapping:
81
+ """Load a mapping file, returning an empty Mapping when path is None."""
82
+ if not path:
83
+ return Mapping(path="")
84
+ return Mapping.parse(path)