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 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