sekka 0.2.1__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.
- sekka/__init__.py +50 -0
- sekka/cli.py +286 -0
- sekka/fastpath.py +108 -0
- sekka/pdata.py +141 -0
- sekka/pe.py +145 -0
- sekka/state.py +85 -0
- sekka/unwind.py +239 -0
- sekka-0.2.1.dist-info/METADATA +459 -0
- sekka-0.2.1.dist-info/RECORD +13 -0
- sekka-0.2.1.dist-info/WHEEL +5 -0
- sekka-0.2.1.dist-info/entry_points.txt +2 -0
- sekka-0.2.1.dist-info/licenses/LICENSE +201 -0
- sekka-0.2.1.dist-info/top_level.txt +1 -0
sekka/__init__.py
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
"""sekka - static analysis for x64 PE exception tables (.pdata).
|
|
2
|
+
|
|
3
|
+
Sekka reads the exception-handling metadata of x64 PE images:
|
|
4
|
+
|
|
5
|
+
* RUNTIME_FUNCTION enumeration and lookup (function ranges from .pdata),
|
|
6
|
+
* UNWIND_INFO parsing: flags, prolog size, unwind codes, the language
|
|
7
|
+
handler RVA, and chained info,
|
|
8
|
+
* multi-capture selection: when several snapshots of the same image are
|
|
9
|
+
available, estimate which one holds the target region in a readable
|
|
10
|
+
state before parsing.
|
|
11
|
+
|
|
12
|
+
The name comes from the Japanese word for a snow crystal.
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
__version__ = "0.2.1"
|
|
16
|
+
|
|
17
|
+
from .pe import ( # noqa: F401
|
|
18
|
+
EXCEPTION_DIRECTORY_INDEX,
|
|
19
|
+
MACHINE_AMD64,
|
|
20
|
+
MACHINE_ARM64,
|
|
21
|
+
MACHINE_I386,
|
|
22
|
+
Image,
|
|
23
|
+
PEError,
|
|
24
|
+
load,
|
|
25
|
+
)
|
|
26
|
+
from .pdata import ( # noqa: F401
|
|
27
|
+
RuntimeFunction,
|
|
28
|
+
load_entries,
|
|
29
|
+
lookup,
|
|
30
|
+
scan_candidates,
|
|
31
|
+
)
|
|
32
|
+
from .unwind import ( # noqa: F401
|
|
33
|
+
REG64,
|
|
34
|
+
UNW_FLAG_CHAININFO,
|
|
35
|
+
UNW_FLAG_EHANDLER,
|
|
36
|
+
UNW_FLAG_UHANDLER,
|
|
37
|
+
UnwindInfo,
|
|
38
|
+
parse,
|
|
39
|
+
resolve_chain,
|
|
40
|
+
)
|
|
41
|
+
from .state import classify, choose, shannon_entropy # noqa: F401
|
|
42
|
+
|
|
43
|
+
__all__ = [
|
|
44
|
+
"Image", "PEError", "load",
|
|
45
|
+
"RuntimeFunction", "load_entries", "lookup", "scan_candidates",
|
|
46
|
+
"UnwindInfo", "parse", "resolve_chain",
|
|
47
|
+
"UNW_FLAG_EHANDLER", "UNW_FLAG_UHANDLER", "UNW_FLAG_CHAININFO",
|
|
48
|
+
"classify", "choose", "shannon_entropy",
|
|
49
|
+
"__version__",
|
|
50
|
+
]
|
sekka/cli.py
ADDED
|
@@ -0,0 +1,286 @@
|
|
|
1
|
+
"""sekka command line interface."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import argparse
|
|
6
|
+
import json
|
|
7
|
+
import os
|
|
8
|
+
import sys
|
|
9
|
+
|
|
10
|
+
from . import __version__
|
|
11
|
+
from . import pe, pdata
|
|
12
|
+
from . import unwind as unwind_mod
|
|
13
|
+
from .state import choose as choose_state
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def _load_image(path):
|
|
17
|
+
with open(path, "rb") as fh:
|
|
18
|
+
raw = fh.read()
|
|
19
|
+
return pe.load(raw, name=os.path.basename(path))
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def _parse_int(text):
|
|
23
|
+
return int(text, 0)
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def _flag_names(info):
|
|
27
|
+
return "|".join(info.flag_names()) or "none"
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def _entry_dict(image, entry, with_unwind=True):
|
|
31
|
+
result = {
|
|
32
|
+
"image": image.name,
|
|
33
|
+
"function": entry.to_dict(),
|
|
34
|
+
"function_va": {
|
|
35
|
+
"begin": image.va(entry.begin),
|
|
36
|
+
"end": image.va(entry.end),
|
|
37
|
+
"unwind": image.va(entry.unwind),
|
|
38
|
+
},
|
|
39
|
+
}
|
|
40
|
+
if with_unwind:
|
|
41
|
+
try:
|
|
42
|
+
info = unwind_mod.parse(image, entry.unwind)
|
|
43
|
+
except pe.PEError as exc:
|
|
44
|
+
result["unwind"] = {"error": str(exc)}
|
|
45
|
+
else:
|
|
46
|
+
result["unwind"] = info.to_dict()
|
|
47
|
+
if info.chained is not None:
|
|
48
|
+
chain = []
|
|
49
|
+
try:
|
|
50
|
+
for sub in unwind_mod.resolve_chain(image, info.chained.unwind):
|
|
51
|
+
chain.append(sub.to_dict())
|
|
52
|
+
except pe.PEError:
|
|
53
|
+
pass
|
|
54
|
+
result["chain"] = chain
|
|
55
|
+
return result
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def _print_entry(image, entry, note=None):
|
|
59
|
+
print("image: %s" % image.name)
|
|
60
|
+
if note:
|
|
61
|
+
print("note: %s" % note)
|
|
62
|
+
print("function: begin rva 0x%X (VA 0x%X) end rva 0x%X (VA 0x%X)" % (
|
|
63
|
+
entry.begin, image.va(entry.begin), entry.end, image.va(entry.end)))
|
|
64
|
+
print("unwind: rva 0x%X (VA 0x%X)" % (entry.unwind, image.va(entry.unwind)))
|
|
65
|
+
try:
|
|
66
|
+
info = unwind_mod.parse(image, entry.unwind)
|
|
67
|
+
except pe.PEError as exc:
|
|
68
|
+
print("unwind info: parse failed: %s" % exc)
|
|
69
|
+
return
|
|
70
|
+
print("unwind info: version %d flags %s prolog 0x%X codes %d" % (
|
|
71
|
+
info.version, _flag_names(info), info.size_of_prolog, info.count_of_codes))
|
|
72
|
+
if info.frame_register:
|
|
73
|
+
reg = unwind_mod.REG64[info.frame_register] if info.frame_register < 16 else "?"
|
|
74
|
+
print("frame register: %s (offset %d)" % (reg, info.frame_offset))
|
|
75
|
+
for code in info.codes:
|
|
76
|
+
print(" [%d] %s" % (code.slot, code.text))
|
|
77
|
+
if info.handler_rva is not None:
|
|
78
|
+
print("language handler: rva 0x%X (VA 0x%X)" % (
|
|
79
|
+
info.handler_rva, image.va(info.handler_rva)))
|
|
80
|
+
if info.chained is not None:
|
|
81
|
+
print("chained entry: begin 0x%X end 0x%X unwind 0x%X" % (
|
|
82
|
+
info.chained.begin, info.chained.end, info.chained.unwind))
|
|
83
|
+
try:
|
|
84
|
+
sub = unwind_mod.parse(image, info.chained.unwind)
|
|
85
|
+
if sub.handler_rva is not None:
|
|
86
|
+
print("chained handler: rva 0x%X (VA 0x%X)" % (
|
|
87
|
+
sub.handler_rva, image.va(sub.handler_rva)))
|
|
88
|
+
except pe.PEError as exc:
|
|
89
|
+
print("chained unwind info: parse failed: %s" % exc)
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def _warn_machine(image):
|
|
93
|
+
if image.machine != pe.MACHINE_AMD64:
|
|
94
|
+
sys.stderr.write("warning: %s: machine is %s; "
|
|
95
|
+
"x64 unwind parsing may not apply\n"
|
|
96
|
+
% (image.name, image.machine_name()))
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
def cmd_lookup(args):
|
|
100
|
+
images = [_load_image(p) for p in args.image]
|
|
101
|
+
for image in images:
|
|
102
|
+
_warn_machine(image)
|
|
103
|
+
ordered = images
|
|
104
|
+
if len(images) > 1:
|
|
105
|
+
# Same-basename captures from different directories would silently
|
|
106
|
+
# clobber each other in the mapping; disambiguate with a "#N" suffix.
|
|
107
|
+
mapping = {}
|
|
108
|
+
for image in images:
|
|
109
|
+
name = image.name
|
|
110
|
+
n = 2
|
|
111
|
+
while name in mapping:
|
|
112
|
+
name = "%s #%d" % (image.name, n)
|
|
113
|
+
n += 1
|
|
114
|
+
if name != image.name:
|
|
115
|
+
image.name = name
|
|
116
|
+
mapping[name] = image
|
|
117
|
+
rows = choose_state(mapping, args.rva)
|
|
118
|
+
print("captures at rva 0x%X (plain-like first):" % args.rva)
|
|
119
|
+
for row in rows:
|
|
120
|
+
print(" %-24s entropy=%s zero=%s %s" % (
|
|
121
|
+
row["name"],
|
|
122
|
+
"%.3f" % row["entropy"] if row["entropy"] is not None else "-",
|
|
123
|
+
"%.4f" % row["zero_ratio"] if row["zero_ratio"] is not None else "-",
|
|
124
|
+
row["verdict"]))
|
|
125
|
+
ordered = [mapping[row["name"]] for row in rows
|
|
126
|
+
if row["name"] in mapping]
|
|
127
|
+
found = []
|
|
128
|
+
for image in ordered:
|
|
129
|
+
entry = pdata.lookup(image, args.rva)
|
|
130
|
+
if entry is not None:
|
|
131
|
+
found.append((image, entry, None))
|
|
132
|
+
break
|
|
133
|
+
if args.scan:
|
|
134
|
+
candidates = pdata.scan_candidates(image, args.rva)
|
|
135
|
+
if candidates:
|
|
136
|
+
for off, candidate in candidates:
|
|
137
|
+
found.append((image, candidate,
|
|
138
|
+
"scan candidate at file offset 0x%X" % off))
|
|
139
|
+
break
|
|
140
|
+
if args.json:
|
|
141
|
+
rows = []
|
|
142
|
+
for image, entry, note in found:
|
|
143
|
+
row = _entry_dict(image, entry)
|
|
144
|
+
if note:
|
|
145
|
+
row["note"] = note
|
|
146
|
+
rows.append(row)
|
|
147
|
+
print(json.dumps(rows, indent=2))
|
|
148
|
+
else:
|
|
149
|
+
for image, entry, note in found:
|
|
150
|
+
print()
|
|
151
|
+
_print_entry(image, entry, note=note)
|
|
152
|
+
if not found:
|
|
153
|
+
sys.stderr.write("no RUNTIME_FUNCTION covers rva 0x%X\n" % args.rva)
|
|
154
|
+
return 2
|
|
155
|
+
return 0
|
|
156
|
+
|
|
157
|
+
|
|
158
|
+
def cmd_table(args):
|
|
159
|
+
image = _load_image(args.image)
|
|
160
|
+
_warn_machine(image)
|
|
161
|
+
entries = pdata.load_entries(image)
|
|
162
|
+
rows = []
|
|
163
|
+
for entry in entries:
|
|
164
|
+
if args.start is not None and entry.end <= args.start:
|
|
165
|
+
continue
|
|
166
|
+
if args.end is not None and entry.begin >= args.end:
|
|
167
|
+
continue
|
|
168
|
+
rows.append({
|
|
169
|
+
"begin_rva": entry.begin, "end_rva": entry.end,
|
|
170
|
+
"unwind_rva": entry.unwind, "begin_va": image.va(entry.begin),
|
|
171
|
+
"end_va": image.va(entry.end),
|
|
172
|
+
})
|
|
173
|
+
if args.json:
|
|
174
|
+
print(json.dumps(rows, indent=2))
|
|
175
|
+
return 0
|
|
176
|
+
if not rows:
|
|
177
|
+
print("no RUNTIME_FUNCTION entries")
|
|
178
|
+
return 0
|
|
179
|
+
for row in rows[:args.limit]:
|
|
180
|
+
print("0x%06X-0x%06X (VA 0x%X-0x%X) unwind 0x%X" % (
|
|
181
|
+
row["begin_rva"], row["end_rva"], row["begin_va"], row["end_va"],
|
|
182
|
+
row["unwind_rva"]))
|
|
183
|
+
if len(rows) > args.limit:
|
|
184
|
+
print("... %d more (use --limit)" % (len(rows) - args.limit))
|
|
185
|
+
print("total: %d entries" % len(rows))
|
|
186
|
+
return 0
|
|
187
|
+
|
|
188
|
+
|
|
189
|
+
def cmd_handlers(args):
|
|
190
|
+
image = _load_image(args.image)
|
|
191
|
+
_warn_machine(image)
|
|
192
|
+
rows = []
|
|
193
|
+
for entry in pdata.load_entries(image):
|
|
194
|
+
try:
|
|
195
|
+
info = unwind_mod.parse(image, entry.unwind)
|
|
196
|
+
except pe.PEError:
|
|
197
|
+
continue
|
|
198
|
+
if info.handler_rva is not None:
|
|
199
|
+
rows.append({
|
|
200
|
+
"begin_rva": entry.begin, "end_rva": entry.end,
|
|
201
|
+
"handler_rva": info.handler_rva,
|
|
202
|
+
"handler_va": image.va(info.handler_rva),
|
|
203
|
+
"flags": info.flag_names(),
|
|
204
|
+
})
|
|
205
|
+
if args.json:
|
|
206
|
+
print(json.dumps(rows, indent=2))
|
|
207
|
+
return 0
|
|
208
|
+
for row in rows:
|
|
209
|
+
print("function 0x%06X-0x%06X handler rva 0x%06X (VA 0x%X) [%s]" % (
|
|
210
|
+
row["begin_rva"], row["end_rva"], row["handler_rva"],
|
|
211
|
+
row["handler_va"], ",".join(row["flags"])))
|
|
212
|
+
print("total: %d entries with a language handler" % len(rows))
|
|
213
|
+
return 0
|
|
214
|
+
|
|
215
|
+
|
|
216
|
+
def cmd_validate(args):
|
|
217
|
+
image = _load_image(args.image)
|
|
218
|
+
entry = pdata.lookup(image, args.rva)
|
|
219
|
+
if entry is None:
|
|
220
|
+
print("FAIL: no RUNTIME_FUNCTION covers rva 0x%X" % args.rva)
|
|
221
|
+
return 1
|
|
222
|
+
try:
|
|
223
|
+
info = unwind_mod.parse(image, entry.unwind)
|
|
224
|
+
except pe.PEError as exc:
|
|
225
|
+
print("FAIL: unwind parse error: %s" % exc)
|
|
226
|
+
return 1
|
|
227
|
+
if info.handler_rva == args.handler:
|
|
228
|
+
print("PASS: function 0x%X-0x%X handler rva 0x%X (VA 0x%X)" % (
|
|
229
|
+
entry.begin, entry.end, info.handler_rva, image.va(info.handler_rva)))
|
|
230
|
+
return 0
|
|
231
|
+
print("FAIL: expected handler 0x%X, found 0x%X" % (
|
|
232
|
+
args.handler, info.handler_rva if info.handler_rva is not None else 0))
|
|
233
|
+
return 1
|
|
234
|
+
|
|
235
|
+
|
|
236
|
+
def build_parser():
|
|
237
|
+
parser = argparse.ArgumentParser(
|
|
238
|
+
prog="sekka",
|
|
239
|
+
description="Static analysis for x64 PE exception tables (.pdata)")
|
|
240
|
+
parser.add_argument("--version", action="version",
|
|
241
|
+
version="%(prog)s " + __version__)
|
|
242
|
+
sub = parser.add_subparsers(dest="command")
|
|
243
|
+
|
|
244
|
+
p = sub.add_parser("lookup", help="find the RUNTIME_FUNCTION covering an RVA")
|
|
245
|
+
p.add_argument("image", nargs="+", help="image or capture file(s)")
|
|
246
|
+
p.add_argument("--rva", required=True, type=_parse_int,
|
|
247
|
+
help="target RVA (hex with 0x prefix)")
|
|
248
|
+
p.add_argument("--scan", action="store_true",
|
|
249
|
+
help="fall back to a brute-force scan when the table misses")
|
|
250
|
+
p.add_argument("--json", action="store_true", help="JSON output")
|
|
251
|
+
p.set_defaults(func=cmd_lookup)
|
|
252
|
+
|
|
253
|
+
p = sub.add_parser("table", help="list RUNTIME_FUNCTION entries")
|
|
254
|
+
p.add_argument("image", help="image or capture file")
|
|
255
|
+
p.add_argument("--start", type=_parse_int, default=None)
|
|
256
|
+
p.add_argument("--end", type=_parse_int, default=None)
|
|
257
|
+
p.add_argument("--limit", type=int, default=50)
|
|
258
|
+
p.add_argument("--json", action="store_true", help="JSON output")
|
|
259
|
+
p.set_defaults(func=cmd_table)
|
|
260
|
+
|
|
261
|
+
p = sub.add_parser("handlers", help="list entries with a language handler")
|
|
262
|
+
p.add_argument("image", help="image or capture file")
|
|
263
|
+
p.add_argument("--json", action="store_true", help="JSON output")
|
|
264
|
+
p.set_defaults(func=cmd_handlers)
|
|
265
|
+
|
|
266
|
+
p = sub.add_parser(
|
|
267
|
+
"validate", help="assert that an RVA resolves to an expected handler")
|
|
268
|
+
p.add_argument("image", help="image or capture file")
|
|
269
|
+
p.add_argument("--rva", required=True, type=_parse_int)
|
|
270
|
+
p.add_argument("--handler", required=True, type=_parse_int)
|
|
271
|
+
p.set_defaults(func=cmd_validate)
|
|
272
|
+
|
|
273
|
+
return parser
|
|
274
|
+
|
|
275
|
+
|
|
276
|
+
def main(argv=None):
|
|
277
|
+
parser = build_parser()
|
|
278
|
+
args = parser.parse_args(argv)
|
|
279
|
+
if not getattr(args, "command", None):
|
|
280
|
+
parser.print_help()
|
|
281
|
+
return 0
|
|
282
|
+
return args.func(args)
|
|
283
|
+
|
|
284
|
+
|
|
285
|
+
if __name__ == "__main__":
|
|
286
|
+
sys.exit(main())
|
sekka/fastpath.py
ADDED
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
"""NumPy-vectorized hot paths (optional dependency).
|
|
2
|
+
|
|
3
|
+
The core always runs on the standard library alone. When NumPy is
|
|
4
|
+
installed, hot paths switch automatically to vectorized implementations
|
|
5
|
+
(see :data:`HAVE_NUMPY`). Equivalence between the two implementations is
|
|
6
|
+
guarded by the test suite; on NumPy-less environments those tests skip
|
|
7
|
+
and the core runs the pure implementations.
|
|
8
|
+
|
|
9
|
+
What gets vectorized:
|
|
10
|
+
|
|
11
|
+
- shannon_entropy / zero_ratio:
|
|
12
|
+
the byte histogram is built with one ``bincount`` call and the zero
|
|
13
|
+
ratio with one equality mask (the per-byte Python loop disappears).
|
|
14
|
+
- RUNTIME_FUNCTION extraction (pdata.load_entries):
|
|
15
|
+
the whole directory is read once and viewed as a ``(N, 3)`` ``<u4``
|
|
16
|
+
matrix; invalid entries (begin == 0, end <= begin, unwind == 0) are
|
|
17
|
+
removed with a single boolean mask.
|
|
18
|
+
- scan_candidates pre-filter (pdata.scan_candidates):
|
|
19
|
+
the capture is viewed as a ``<u4`` array and every 4-aligned offset is
|
|
20
|
+
tested at once with masks (covers target, plausible size, non-null
|
|
21
|
+
unwind).
|
|
22
|
+
|
|
23
|
+
What stays pure (sequential by nature, or already cheap):
|
|
24
|
+
|
|
25
|
+
- UNWIND_CODE decoding (a slot-walking state machine),
|
|
26
|
+
- the binary search in lookup (already O(log n)),
|
|
27
|
+
- per-candidate UNWIND_INFO validation (bounded by the candidate count).
|
|
28
|
+
"""
|
|
29
|
+
from __future__ import annotations
|
|
30
|
+
|
|
31
|
+
try:
|
|
32
|
+
import numpy as _np
|
|
33
|
+
HAVE_NUMPY = True
|
|
34
|
+
except ImportError: # pragma: no cover - environment dependent
|
|
35
|
+
_np = None
|
|
36
|
+
HAVE_NUMPY = False
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def _require_numpy():
|
|
40
|
+
if _np is None:
|
|
41
|
+
raise RuntimeError("sekka.fastpath requires numpy (not installed)")
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def shannon_entropy(data):
|
|
45
|
+
"""Vectorized :func:`sekka.state.shannon_entropy`."""
|
|
46
|
+
_require_numpy()
|
|
47
|
+
arr = _np.frombuffer(data, dtype=_np.uint8)
|
|
48
|
+
n = int(arr.size)
|
|
49
|
+
if n == 0:
|
|
50
|
+
return 0.0
|
|
51
|
+
counts = _np.bincount(arr, minlength=256).astype(_np.float64)
|
|
52
|
+
p = counts / n
|
|
53
|
+
nz = p > 0
|
|
54
|
+
return float(-(p[nz] * _np.log2(p[nz])).sum())
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
def zero_ratio(data):
|
|
58
|
+
"""Vectorized :func:`sekka.state.zero_ratio`."""
|
|
59
|
+
_require_numpy()
|
|
60
|
+
arr = _np.frombuffer(data, dtype=_np.uint8)
|
|
61
|
+
if arr.size == 0:
|
|
62
|
+
return 1.0
|
|
63
|
+
return float(int((arr == 0).sum())) / float(int(arr.size))
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def load_entries(image, rva, size):
|
|
67
|
+
"""Extract RUNTIME_FUNCTION triples from ``[rva, rva + size)``.
|
|
68
|
+
|
|
69
|
+
Returns ``(begins, ends, unwinds)`` lists, or ``None`` when the
|
|
70
|
+
directory is not fully readable; the caller then falls back to the
|
|
71
|
+
pure loop, which can consume a truncated directory entry by entry.
|
|
72
|
+
"""
|
|
73
|
+
_require_numpy()
|
|
74
|
+
usable = (size // 12) * 12
|
|
75
|
+
if usable <= 0:
|
|
76
|
+
return [], [], []
|
|
77
|
+
chunk = image.read(rva, usable)
|
|
78
|
+
if chunk is None:
|
|
79
|
+
return None
|
|
80
|
+
view = _np.frombuffer(chunk, dtype="<u4").reshape(-1, 3)
|
|
81
|
+
begin = view[:, 0]
|
|
82
|
+
end = view[:, 1]
|
|
83
|
+
unwind = view[:, 2]
|
|
84
|
+
mask = (begin != 0) & (end > begin) & (unwind != 0)
|
|
85
|
+
rows = view[mask]
|
|
86
|
+
return rows[:, 0].tolist(), rows[:, 1].tolist(), rows[:, 2].tolist()
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def scan_triples(data, rva, max_size):
|
|
90
|
+
"""4-aligned offsets whose (begin, end, unwind) triple covers *rva*.
|
|
91
|
+
|
|
92
|
+
Vectorized mask pre-filter of :func:`sekka.pdata.scan_candidates`;
|
|
93
|
+
the caller validates each offset (UNWIND_INFO parse) afterwards.
|
|
94
|
+
"""
|
|
95
|
+
_require_numpy()
|
|
96
|
+
usable = len(data) - (len(data) % 4)
|
|
97
|
+
if usable < 12:
|
|
98
|
+
return []
|
|
99
|
+
v = _np.frombuffer(data[:usable], dtype="<u4")
|
|
100
|
+
n = int(v.size)
|
|
101
|
+
if n < 3:
|
|
102
|
+
return []
|
|
103
|
+
begin = v[: n - 2]
|
|
104
|
+
end = v[1: n - 1]
|
|
105
|
+
unwind = v[2:]
|
|
106
|
+
mask = ((begin != 0) & (begin <= rva) & (end > rva)
|
|
107
|
+
& ((end - begin) <= max_size) & (unwind != 0))
|
|
108
|
+
return (_np.flatnonzero(mask) * 4).tolist()
|
sekka/pdata.py
ADDED
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
"""RUNTIME_FUNCTION enumeration and lookup over the x64 exception table.
|
|
2
|
+
|
|
3
|
+
Each .pdata entry is a 12-byte RUNTIME_FUNCTION triple::
|
|
4
|
+
|
|
5
|
+
struct RUNTIME_FUNCTION {
|
|
6
|
+
ULONG BeginAddress; // inclusive
|
|
7
|
+
ULONG EndAddress; // exclusive
|
|
8
|
+
ULONG UnwindDataAddress;
|
|
9
|
+
};
|
|
10
|
+
|
|
11
|
+
Entries are sorted by BeginAddress, and functions do not overlap. When the
|
|
12
|
+
exception data directory is absent or empty, a section literally named
|
|
13
|
+
``.pdata`` is used as a fallback. :func:`scan_candidates` provides a
|
|
14
|
+
brute-force fallback for captures whose directory is unreadable.
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
from __future__ import annotations
|
|
18
|
+
|
|
19
|
+
import struct
|
|
20
|
+
|
|
21
|
+
from . import fastpath
|
|
22
|
+
from .pe import PEError
|
|
23
|
+
|
|
24
|
+
ENTRY_SIZE = 12
|
|
25
|
+
|
|
26
|
+
MAX_PLAUSIBLE_FUNCTION = 0x1000000 # 16 MB: beyond this a "function" is junk
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
class RuntimeFunction(object):
|
|
30
|
+
__slots__ = ("begin", "end", "unwind")
|
|
31
|
+
|
|
32
|
+
def __init__(self, begin, end, unwind):
|
|
33
|
+
self.begin = begin
|
|
34
|
+
self.end = end
|
|
35
|
+
self.unwind = unwind
|
|
36
|
+
|
|
37
|
+
def covers(self, rva):
|
|
38
|
+
return self.begin <= rva < self.end
|
|
39
|
+
|
|
40
|
+
def __repr__(self):
|
|
41
|
+
return "RuntimeFunction(begin=0x%x, end=0x%x, unwind=0x%x)" % (
|
|
42
|
+
self.begin, self.end, self.unwind)
|
|
43
|
+
|
|
44
|
+
def to_dict(self):
|
|
45
|
+
return {"begin_rva": self.begin, "end_rva": self.end, "unwind_rva": self.unwind}
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def load_entries(image):
|
|
49
|
+
"""Enumerate all RUNTIME_FUNCTION entries present in *image*."""
|
|
50
|
+
rva, size = image.exception_dir()
|
|
51
|
+
if not rva or not size:
|
|
52
|
+
for section in image.sections:
|
|
53
|
+
if section.name == ".pdata":
|
|
54
|
+
rva, size = section.vaddr, section.vsize
|
|
55
|
+
break
|
|
56
|
+
if not rva or not size:
|
|
57
|
+
return []
|
|
58
|
+
if fastpath.HAVE_NUMPY:
|
|
59
|
+
triples = fastpath.load_entries(image, rva, size)
|
|
60
|
+
if triples is not None:
|
|
61
|
+
begins, ends, unwinds = triples
|
|
62
|
+
return [RuntimeFunction(b, e, u)
|
|
63
|
+
for b, e, u in zip(begins, ends, unwinds)]
|
|
64
|
+
entries = []
|
|
65
|
+
for off in range(0, size - ENTRY_SIZE + 1, ENTRY_SIZE):
|
|
66
|
+
chunk = image.read(rva + off, ENTRY_SIZE)
|
|
67
|
+
if chunk is None:
|
|
68
|
+
break
|
|
69
|
+
begin, end, unwind = struct.unpack("<III", chunk)
|
|
70
|
+
if begin == 0 or end <= begin or unwind == 0:
|
|
71
|
+
continue
|
|
72
|
+
entries.append(RuntimeFunction(begin, end, unwind))
|
|
73
|
+
return entries
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def lookup(image, rva):
|
|
77
|
+
"""Return the RUNTIME_FUNCTION covering *rva*, or None."""
|
|
78
|
+
entries = load_entries(image)
|
|
79
|
+
lo, hi = 0, len(entries)
|
|
80
|
+
while lo < hi:
|
|
81
|
+
mid = (lo + hi) // 2
|
|
82
|
+
if entries[mid].begin <= rva:
|
|
83
|
+
lo = mid + 1
|
|
84
|
+
else:
|
|
85
|
+
hi = mid
|
|
86
|
+
if lo > 0 and entries[lo - 1].covers(rva):
|
|
87
|
+
return entries[lo - 1]
|
|
88
|
+
# Tolerate unsorted tables with a linear pass.
|
|
89
|
+
for entry in entries:
|
|
90
|
+
if entry.covers(rva):
|
|
91
|
+
return entry
|
|
92
|
+
return None
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def scan_candidates(image, rva, limit=16):
|
|
96
|
+
"""Brute-force scan for plausible RUNTIME_FUNCTION entries covering *rva*.
|
|
97
|
+
|
|
98
|
+
Used when the exception directory is missing or unreadable (for example
|
|
99
|
+
when the directory itself was not readable at capture time). Walks the
|
|
100
|
+
whole image looking for 12-byte triples that cover the target and whose
|
|
101
|
+
UnwindData resolves to a parseable UNWIND_INFO. Returns a list of
|
|
102
|
+
``(offset, RuntimeFunction)`` pairs.
|
|
103
|
+
|
|
104
|
+
With NumPy installed the offset pre-filter runs as one vectorized mask
|
|
105
|
+
(:func:`sekka.fastpath.scan_triples`); per-candidate UNWIND_INFO
|
|
106
|
+
validation stays pure either way.
|
|
107
|
+
"""
|
|
108
|
+
from .unwind import parse as parse_unwind # local import: avoids a cycle
|
|
109
|
+
|
|
110
|
+
data = image.data
|
|
111
|
+
results = []
|
|
112
|
+
if fastpath.HAVE_NUMPY:
|
|
113
|
+
for off in fastpath.scan_triples(data, rva, MAX_PLAUSIBLE_FUNCTION):
|
|
114
|
+
begin, end, unwind = struct.unpack_from("<III", data, off)
|
|
115
|
+
if unwind == 0 or image.rva_to_off(unwind) is None:
|
|
116
|
+
continue
|
|
117
|
+
try:
|
|
118
|
+
parse_unwind(image, unwind)
|
|
119
|
+
except PEError:
|
|
120
|
+
continue
|
|
121
|
+
results.append((off, RuntimeFunction(begin, end, unwind)))
|
|
122
|
+
if len(results) >= limit:
|
|
123
|
+
break
|
|
124
|
+
return results
|
|
125
|
+
n = len(data)
|
|
126
|
+
for off in range(0, n - ENTRY_SIZE, 4):
|
|
127
|
+
begin, end, unwind = struct.unpack_from("<III", data, off)
|
|
128
|
+
if begin == 0 or not (begin <= rva < end):
|
|
129
|
+
continue
|
|
130
|
+
if end - begin > MAX_PLAUSIBLE_FUNCTION:
|
|
131
|
+
continue
|
|
132
|
+
if unwind == 0 or image.rva_to_off(unwind) is None:
|
|
133
|
+
continue
|
|
134
|
+
try:
|
|
135
|
+
parse_unwind(image, unwind)
|
|
136
|
+
except PEError:
|
|
137
|
+
continue
|
|
138
|
+
results.append((off, RuntimeFunction(begin, end, unwind)))
|
|
139
|
+
if len(results) >= limit:
|
|
140
|
+
break
|
|
141
|
+
return results
|