scientific-method-engine 2.2.0__tar.gz → 2.3.0__tar.gz

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.
Files changed (61) hide show
  1. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/PKG-INFO +1 -1
  2. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/pyproject.toml +1 -1
  3. scientific_method_engine-2.3.0/src/scientific_method_engine/x86/argument_frames.py +210 -0
  4. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/x86/machine.py +27 -13
  5. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/x86/reports.py +6 -11
  6. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/x86/trace.py +5 -3
  7. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/tests/test_pe.py +10 -0
  8. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/tests/test_x86.py +186 -0
  9. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/.gitignore +0 -0
  10. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/LICENSE +0 -0
  11. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/README.md +0 -0
  12. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/__init__.py +0 -0
  13. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/__main__.py +0 -0
  14. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/cli.py +0 -0
  15. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  16. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  17. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  18. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  19. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  20. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  21. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  22. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  23. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  24. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  25. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  26. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  27. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  28. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  29. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  30. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  31. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  32. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  33. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  34. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  35. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  36. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  37. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  38. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  39. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  40. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  41. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  42. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  43. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  44. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  45. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  46. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
  47. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
  48. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/x86/image.py +0 -0
  49. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
  50. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  51. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
  52. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/x86/pe.py +0 -0
  53. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  54. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/src/scientific_method_engine/x86/values.py +0 -0
  55. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/tests/oracle.py +0 -0
  56. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/tests/test_dispatch.py +0 -0
  57. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/tests/test_effect_order.py +0 -0
  58. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/tests/test_memory_scopes.py +0 -0
  59. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/tests/test_nested_frame_request.py +0 -0
  60. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/tests/test_oracle.py +0 -0
  61. {scientific_method_engine-2.2.0 → scientific_method_engine-2.3.0}/tests/test_table_continuations.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: scientific-method-engine
3
- Version: 2.2.0
3
+ Version: 2.3.0
4
4
  Summary: Bounded instruction-derived x86 evidence reports for segmented MZ/FBOV and PE32/i386 code.
5
5
  Project-URL: Source, https://github.com/kibertoad/refurbished-dinosaurs-toolkit/tree/main/packages/scientific-method-engine
6
6
  Author: kibertoad
@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
5
5
  [project]
6
6
  name = "scientific-method-engine"
7
7
  # The release workflow writes the published version from the package's release tag.
8
- version = "2.2.0"
8
+ version = "2.3.0"
9
9
  description = "Bounded instruction-derived x86 evidence reports for segmented MZ/FBOV and PE32/i386 code."
10
10
  readme = "README.md"
11
11
  requires-python = ">=3.12"
@@ -0,0 +1,210 @@
1
+ """Per-call maps from the stack slots a caller wrote to the widths its callee consumed.
2
+
3
+ Each traced call on a path gets one frame. Its slots are the caller-side writes that last covered
4
+ each argument byte when the call ran; its reads are the callee's own BP- or SP-relative argument
5
+ reads. A grouping comes only from a read: adjacent pushes, a relocated segment word or a cleanup
6
+ amount never join or split slots. Whatever a read did not settle on the path stays open.
7
+ """
8
+ from capstone.x86 import X86_OP_IMM, X86_OP_REG
9
+
10
+ from .machine import may_alias, written_domain
11
+
12
+ # The argument bytes one frame maps; a wider frame is mapped up to here and stays open.
13
+ WINDOW_BYTES = 256
14
+
15
+
16
+ def stack_cleanup(ins):
17
+ """The bytes an immediate ADD SP/ESP releases, or None for any other instruction or a negative immediate."""
18
+ if (ins is None or ins.mnemonic != "add" or len(ins.operands) != 2 or ins.operands[0].type != X86_OP_REG
19
+ or ins.reg_name(ins.operands[0].reg) not in ("sp", "esp") or ins.operands[1].type != X86_OP_IMM):
20
+ return None
21
+ bits = 8 * ins.operands[0].size
22
+ amount = ins.operands[1].imm & ((1 << bits) - 1)
23
+ return amount if 0 < amount < 1 << (bits - 1) else None
24
+
25
+
26
+ def _covered(event, segment, base, start, width, modulus):
27
+ """The frame offsets below `width` that a write event stored, counted from stack byte `start`."""
28
+ interval = event.get("interval")
29
+ if event["kind"] != "write" or not interval or interval["segment"] != segment or interval["base"] != base:
30
+ return []
31
+ # Symbolic stack keys wrap at the address size; linear keys do not.
32
+ offsets = ((at - start) % modulus if modulus else at - start for at in range(interval["start"], interval["end"]))
33
+ return [at for at in offsets if 0 <= at < width]
34
+
35
+
36
+ def _writers(events, before, segment, base, start, width, modulus, image):
37
+ """The last write before index `before` that covered each frame byte, and why each byte without one has none.
38
+
39
+ A modeled call drops every byte outside its `preservesMemory` scopes. Scopes name linear bytes,
40
+ so they keep only frame bytes of a linear stack; the search goes on past the call for those.
41
+ A write through another segment or base drops every frame byte it may alias, by the same rule
42
+ the machine applies when it stores.
43
+ """
44
+ writers, invalidated = {}, {}
45
+ for j in range(before - 1, -1, -1):
46
+ event = events[j]
47
+ interval = event.get("interval")
48
+ if (event["kind"] == "write" and event.get("uncertainAliasesInvalidated") and interval
49
+ and (interval["segment"], interval["base"]) != (segment, base)):
50
+ written = written_domain(interval["segment"], interval["base"], interval["start"],
51
+ interval["end"] - interval["start"], image.bits, image.flat)
52
+ for at in range(width):
53
+ key = (segment, base, (start + at) % modulus if modulus else start + at)
54
+ if at not in writers and at not in invalidated and may_alias(key, written, image.bits, image.flat):
55
+ invalidated[at] = f"memory possibly overwritten through another address by the write at {event['site']}"
56
+ if event["kind"] == "call-return" and event.get("unknownMemoryEffects"):
57
+ kept = set()
58
+ if segment == ("linear",):
59
+ kept = {at for scope in event.get("preservedMemoryScopes") or ()
60
+ for at in range(scope["linearStart"], scope["linearEnd"])}
61
+ for at in range(width):
62
+ if at not in writers and at not in invalidated and start + at not in kept:
63
+ invalidated[at] = "memory invalidated by the modeled call at " + str(event["callSite"])
64
+ for at in _covered(event, segment, base, start, width, modulus):
65
+ if at not in invalidated:
66
+ writers.setdefault(at, event)
67
+ if len(writers) + len(invalidated) == width:
68
+ break
69
+ return writers, {at: invalidated.get(at, "no write on this path") for at in range(width) if at not in writers}
70
+
71
+
72
+ def _frame(image, events, index):
73
+ call = events[index]
74
+ depth = call["depth"]
75
+ pushes = [e for e in events[index + 1:index + 3] if e["kind"] == "write" and e.get("role") == "push" and e["site"] == call["site"]]
76
+ end = next((j for j in range(index + 1, len(events))
77
+ if events[j]["kind"] == "call-return" and events[j].get("callSite") == call["site"] and events[j]["depth"] == depth), None)
78
+ inside = events[index + 1:end if end is not None else len(events)]
79
+ open_reasons = []
80
+ if not pushes:
81
+ return None
82
+ # The return-address push comes last and sits at the callee's entry SP; the frame's return bytes lie above it.
83
+ entry = pushes[-1]["interval"]
84
+ segment, base = entry["segment"], entry["base"]
85
+ modulus = None if segment == ("linear",) else 1 << image.bits
86
+ start = entry["start"] + call["returnFrameBytes"]
87
+ if modulus:
88
+ start %= modulus
89
+ reads = [e for e in inside if e["kind"] == "read" and e.get("argument") and e["depth"] == depth + 1]
90
+ returned = next((e for e in inside if e["kind"] == "return" and e["depth"] == depth + 1 and e.get("callSite") == call["site"]), None)
91
+ callee_cleanup = returned["cleanupBytes"] if returned else None
92
+ caller_cleanup = None
93
+ if end is not None:
94
+ following = image.decode(call["site"] + image.decode(call["site"]).size)
95
+ caller_cleanup = stack_cleanup(following)
96
+ else:
97
+ open_reasons.append("the callee did not return on this path")
98
+ consumed_end = max((r["argument"]["offsetFromEntrySP"] - r["argument"]["returnFrameBytes"] + r["argument"]["width"] for r in reads), default=0)
99
+ width = max(consumed_end, callee_cleanup or 0, caller_cleanup or 0)
100
+ if not callee_cleanup and caller_cleanup is None:
101
+ open_reasons.append("no cleanup amount bounds the frame; slots above the highest read are not mapped")
102
+ if width > WINDOW_BYTES:
103
+ open_reasons.append(f"the frame is wider than the {WINDOW_BYTES}-byte window")
104
+ width = WINDOW_BYTES
105
+
106
+ # Slots: runs of argument bytes that one write event last covered.
107
+ slots, by_byte = [], {}
108
+ writers, reasons = _writers(events, index, segment, base, start, width, modulus, image)
109
+ for at in range(width):
110
+ writer = writers.get(at)
111
+ key = writer["order"] if writer else reasons[at]
112
+ if slots and slots[-1]["_key"] == key and slots[-1]["offset"] + slots[-1]["width"] == at:
113
+ slots[-1]["width"] += 1
114
+ else:
115
+ slot = {"_key": key, "offset": at, "width": 1}
116
+ if writer:
117
+ byte_offset = start + at - writer["interval"]["start"]
118
+ slot.update(writerSite=writer["site"], writerOrder=writer["order"], writerDepth=writer["depth"],
119
+ writerRole=writer.get("role"), writerWidth=writer["width"],
120
+ writerByteOffset=byte_offset % modulus if modulus else byte_offset, writerValue=writer["value"])
121
+ else:
122
+ slot.update(writerSite=None, reason=reasons[at])
123
+ slots.append(slot)
124
+ by_byte[at] = slots[-1]
125
+ for slot in slots:
126
+ slot.update(consumedBy=[], derivedReads=[])
127
+
128
+ # The first callee store to each frame byte: a later read of that byte sees the callee's bytes.
129
+ first_store = {}
130
+ for e in inside:
131
+ for at in _covered(e, segment, base, start, width, modulus):
132
+ first_store.setdefault(at, e["order"])
133
+ groupings = []
134
+ for read in reads:
135
+ offset = read["argument"]["offsetFromEntrySP"] - read["argument"]["returnFrameBytes"]
136
+ span = range(offset, min(offset + read["argument"]["width"], width))
137
+ covered = []
138
+ for at in span:
139
+ slot = by_byte[at]
140
+ if not covered or covered[-1] is not slot:
141
+ covered.append(slot)
142
+ if read["order"] not in slot["consumedBy"]:
143
+ slot["consumedBy"].append(read["order"])
144
+ # A read byte with no known caller writer, one the callee stored to first, or one whose producers
145
+ # lack the slot's writer saw something other than the caller's bytes. The store check catches an
146
+ # overwrite derived from the argument itself, which keeps the writer among its producers.
147
+ stale = [i for i, at in enumerate(span) if by_byte[at]["writerSite"] is None or first_store.get(at, read["order"]) < read["order"]
148
+ or by_byte[at]["writerSite"] not in read["byteProducers"][i]["producers"]]
149
+ partial = [s["offset"] for s in covered if s["offset"] < offset or s["offset"] + s["width"] > offset + read["argument"]["width"]]
150
+ groupings.append({"readSite": read["site"], "readOrder": read["order"], "offset": offset, "width": read["argument"]["width"],
151
+ "grouping": read["argument"]["grouping"], "slotOffsets": [s["offset"] for s in covered],
152
+ "partialSlots": partial, "bytesNotFromSlotWriter": stale})
153
+ if stale:
154
+ open_reasons.append(f"bytes {stale} of the read at {read['site']} do not come from the slot's writer")
155
+ if partial:
156
+ open_reasons.append(f"the read at {read['site']} covers part of the slots at {partial}")
157
+
158
+ # Reads deeper in the callee whose bytes were produced by a slot's writer: forwarded or derived copies.
159
+ for event in inside:
160
+ if event["kind"] != "read" or not event.get("argument") or event["depth"] <= depth + 1:
161
+ continue
162
+ for slot in slots:
163
+ if slot["writerSite"] is None:
164
+ continue
165
+ hits = [i for i, b in enumerate(event["byteProducers"]) if slot["writerSite"] in b["producers"]]
166
+ if hits:
167
+ slot["derivedReads"].append({"readSite": event["site"], "readOrder": event["order"], "entry": event["entry"],
168
+ "depth": event["depth"], "width": event["argument"]["width"],
169
+ "offsetFromEntrySP": event["argument"]["offsetFromEntrySP"], "bytes": hits})
170
+
171
+ intervals = sorted({(g["offset"], g["width"]) for g in groupings})
172
+ competing = [[list(a), list(b)] for i, a in enumerate(intervals) for b in intervals[i + 1:] if a[0] < b[0] + b[1] and b[0] < a[0] + a[1]]
173
+ if competing:
174
+ open_reasons.append("reads of different widths overlap")
175
+ for slot in slots:
176
+ if slot["writerSite"] is not None and not slot["consumedBy"]:
177
+ open_reasons.append(f"the slot at {slot['offset']} was not read by the callee on this path")
178
+ del slot["_key"]
179
+ return {"callSite": call["site"], "callOrder": call["order"], "target": call["target"], "depth": depth,
180
+ "returnFrameBytes": call["returnFrameBytes"], "calleeReturned": end is not None,
181
+ "calleeCleanupBytes": callee_cleanup, "callerCleanupBytes": caller_cleanup, "mappedBytes": width,
182
+ "slots": slots, "groupings": groupings, "competingWidths": competing,
183
+ "settledOnThisPath": not open_reasons, "openReasons": open_reasons}
184
+
185
+
186
+ def argument_frames(report, image):
187
+ """Add `argumentFrames` to each path and `argumentFrameSites` to the report.
188
+
189
+ A path gets one map per traced call, from caller-written slots to callee reads. A site's
190
+ groupings agree only when every path that traced a call there settled on the same read widths
191
+ and groupings.
192
+ """
193
+ sites = {}
194
+ for path_index, path in enumerate(report["paths"]):
195
+ events = path["events"]
196
+ frames = [_frame(image, events, i) for i, e in enumerate(events) if e["kind"] == "call" and "returnFrameBytes" in e]
197
+ path["argumentFrames"] = [f for f in frames if f is not None]
198
+ for frame in path["argumentFrames"]:
199
+ sites.setdefault(frame["callSite"], []).append((path_index, frame))
200
+ report["argumentFrameSites"] = []
201
+ for site, rows in sorted(sites.items()):
202
+ # A set holds each read's grouping too: a far-pointer load and a plain dword over the same bytes disagree.
203
+ widths = sorted({tuple(sorted({(g["offset"], g["width"], g["grouping"]) for g in f["groupings"]})) for _, f in rows})
204
+ report["argumentFrameSites"].append({
205
+ "callSite": site, "paths": sorted({i for i, _ in rows}), "frames": len(rows),
206
+ "unsettledPaths": sorted({i for i, f in rows if not f["settledOnThisPath"]}),
207
+ "readWidthSets": [[{"offset": o, "width": w, "grouping": k} for o, w, k in group] for group in widths],
208
+ "agreed": len(widths) == 1 and all(f["settledOnThisPath"] for _, f in rows),
209
+ "interpretation": "read widths per traced path; paths that never reached this call are not represented"})
210
+ return report
@@ -224,23 +224,12 @@ class State:
224
224
  write = Value(write.bits, write.term, sources(write, site=self.at))
225
225
  self.memory_epoch += 1
226
226
 
227
- def domain(k):
228
- if k[0] == ("linear",):
229
- return k[2], k[2] + 1
230
- if k[0][0] == "constant":
231
- start = k[0][1] * (1 if self.flat else 16)
232
- return start, start + (1 << self.bits)
233
- return None
234
- # A concrete write covers every byte it stores, not only its first byte.
235
- written = (keys[0][2], keys[-1][2] + 1) if seg == ("linear",) else domain(keys[0])
227
+ written = written_domain(seg, base, delta, width, self.bits, self.flat)
236
228
  for group, members in list(self.memory_groups.items()):
237
229
  if group == (seg, base):
238
230
  continue
239
231
  for key in list(members):
240
- # Different symbolic segments/bases may alias. Concrete linear locations do not.
241
- a, b = domain(key), written
242
- disjoint = a is not None and b is not None and (a[1] <= b[0] or b[1] <= a[0])
243
- if not disjoint:
232
+ if may_alias(key, written, self.bits, self.flat):
244
233
  uncertain.append(key)
245
234
  self.memory.pop(key, None)
246
235
  self.unread_memory.pop(key, None)
@@ -362,6 +351,31 @@ def repeated(ins):
362
351
  return 0xF3 in ins.prefix or (0xF2 in ins.prefix and compare_string(ins))
363
352
 
364
353
 
354
+ def key_domain(key, bits, flat):
355
+ """The linear bytes a memory key may name: one byte, a whole constant segment, or None when unknown."""
356
+ if key[0] == ("linear",):
357
+ return key[2], key[2] + 1
358
+ if key[0][0] == "constant":
359
+ start = key[0][1] * (1 if flat else 16)
360
+ return start, start + (1 << bits)
361
+ return None
362
+
363
+
364
+ def written_domain(segment, base, start, width, bits, flat):
365
+ """The linear bytes a write of `width` bytes at a location may cover, or None when unknown."""
366
+ # A concrete write covers every byte it stores, not only its first byte.
367
+ return (start, start + width) if segment == ("linear",) else key_domain((segment, base, start), bits, flat)
368
+
369
+
370
+ def may_alias(key, written, bits, flat):
371
+ """Whether a write over the `written` domain may store to `key` of another segment/base group.
372
+
373
+ Different symbolic segments or bases may alias. Concrete linear locations do not.
374
+ """
375
+ a = key_domain(key, bits, flat)
376
+ return a is None or written is None or not (a[1] <= written[0] or written[1] <= a[0])
377
+
378
+
365
379
  def string_width(ins, flat):
366
380
  """The element width of a string form: a byte for even opcodes, else the operand size."""
367
381
  return 1 if ins.opcode[0] % 2 == 0 else (4 if (0x66 in ins.prefix) != flat else 2)
@@ -7,6 +7,7 @@ from capstone.x86 import X86_OP_IMM, X86_OP_MEM, X86_OP_REG
7
7
  from .machine import State, StopPath, REGISTERS, ALIASES, segment_register, string_instruction
8
8
  from .values import unknown
9
9
  from .effect_order import effect_ordering
10
+ from .argument_frames import argument_frames, stack_cleanup
10
11
  from .result_flow import return_flows
11
12
  from .image import Image, integer
12
13
  from .trace import (trace, walk, call_target, unsupported_transfer, uncovered, base_mnemonic, OVERLAP_REASON, CONTESTED_REASON,
@@ -1156,16 +1157,6 @@ def _operand_view(ins, o):
1156
1157
  return {"kind": "unresolved"}
1157
1158
 
1158
1159
 
1159
- def _stack_cleanup(ins):
1160
- """The bytes an immediate ADD SP/ESP releases, or None for any other instruction or a negative immediate."""
1161
- if (ins is None or ins.mnemonic != "add" or len(ins.operands) != 2 or ins.operands[0].type != X86_OP_REG
1162
- or ins.reg_name(ins.operands[0].reg) not in ("sp", "esp") or ins.operands[1].type != X86_OP_IMM):
1163
- return None
1164
- bits = 8 * ins.operands[0].size
1165
- amount = ins.operands[1].imm & ((1 << bits) - 1)
1166
- return amount if 0 < amount < 1 << (bits - 1) else None
1167
-
1168
-
1169
1160
  def call_order(image, config):
1170
1161
  """Group the confirmed incoming calls of each containing entry by necessary guards and CFG order."""
1171
1162
  flat = incoming(image, config)
@@ -1264,7 +1255,7 @@ def call_order(image, config):
1264
1255
  rows = []
1265
1256
  for at in selected:
1266
1257
  following = at + instructions[at].size
1267
- amount = _stack_cleanup(instructions.get(following))
1258
+ amount = stack_cleanup(instructions.get(following))
1268
1259
  rows.append({"site": at, "necessaryGuards": necessary[at] if not capped else [],
1269
1260
  "cleanup": {"continuation": following, "site": following if amount is not None else None,
1270
1261
  "argumentBytes": amount, "status": "observed after assumed return" if amount is not None else "unread cleanup",
@@ -1520,6 +1511,8 @@ def _run_report(image, config, command):
1520
1511
  report = trace(image, config)
1521
1512
  if command in ("arguments", "effects"):
1522
1513
  report = near_pointer_provenance(report, config)
1514
+ if command == "arguments":
1515
+ report = argument_frames(report, image)
1523
1516
  if command == "allocation":
1524
1517
  return allocations(report, config)
1525
1518
  if command == "effects":
@@ -1535,6 +1528,8 @@ def _run_report(image, config, command):
1535
1528
  for path in report["paths"]:
1536
1529
  # Returns keep the transfers, conversions and reads that depend on a declared result.
1537
1530
  consumed = {c["order"] for f in path.get("returnFlows", {}).get("results", ()) for c in f["consumers"]}
1531
+ # Arguments keeps the writes its argument-frame slots cite as writers.
1532
+ consumed |= {s["writerOrder"] for f in path.get("argumentFrames", ()) for s in f["slots"] if s["writerSite"] is not None}
1538
1533
  path["events"] = [e for e in path["events"] if e["kind"] in kinds or e["order"] in consumed or
1539
1534
  (command == "effects" and e["kind"] == "read" and (e.get("nearPointerAccessCandidates") or e.get("nearPointerArgumentCandidates")))]
1540
1535
  return report
@@ -515,8 +515,8 @@ def trace(image, config, continue_declared_jumps=True):
515
515
  if g.get("right", {}).get("value") == 0:
516
516
  guard_checks.append({"site": g["site"], "predicate": g["predicate"], "taken": g["taken"],
517
517
  "sameTargetValue": g.get("left", {}).get("expression") == indirect_value.term})
518
- state.event("call", target=target, provenance=provenance, registers=snapshot(state),
519
- indirectValue=indirect_value.report() if indirect_value is not None else None, guards=guard_checks)
518
+ call_event = state.event("call", target=target, provenance=provenance, registers=snapshot(state),
519
+ indirectValue=indirect_value.report() if indirect_value is not None else None, guards=guard_checks)
520
520
  previous = image.decode(state.path[-2]) if len(state.path) > 1 else None
521
521
  # push cs + near call builds a far frame only in real mode; far transfers stop in the flat model.
522
522
  push_cs = (not image.flat and m == "call" and previous is not None and previous.mnemonic == "push"
@@ -588,7 +588,9 @@ def trace(image, config, continue_declared_jumps=True):
588
588
  flags_frame = (16, flags_word.term) in state.saved_flags
589
589
  except StopPath:
590
590
  flags_frame = False
591
- state.frames.append({"entry": target, "sp": state.reg(state.sp), "returnBytes": 4 if m == "lcall" or push_cs else image.bits // 8,
591
+ # A traced call records its return-frame width; argumentFrames maps the slots above it.
592
+ call_event["returnFrameBytes"] = 4 if m == "lcall" or push_cs else image.bits // 8
593
+ state.frames.append({"entry": target, "sp": state.reg(state.sp), "returnBytes": call_event["returnFrameBytes"],
592
594
  "frameSource": "push-CS/near-call; matching far return required" if push_cs else m,
593
595
  "continuation": following, "returnIP": return_ip, "callSite": at,
594
596
  "callerCS": state.reg("cs"), "localFlagsFrame": flags_frame})
@@ -193,6 +193,16 @@ class PEReporterTests(unittest.TestCase):
193
193
  self.assertEqual([(e['width'], e['value']['value']) for e in args], [(2, 7), (4, DATA_VA)])
194
194
  self.assertTrue(all(e['argument']['grouping'] == 'consumed width only' for e in args))
195
195
 
196
+ def test_argument_frame_maps_a_word_and_a_pointer_under_callee_cleanup(self):
197
+ # A dword push and a word push, read as a word and a dword, released by RET 6.
198
+ c = Code().emit('68 00 20 40 00 66 68 07 00').branch('e8', 'callee').emit('c3')
199
+ c.label('callee').emit('55 89 e5 66 8b 45 08 8b 55 0a c9 c2 06 00')
200
+ frame = report(c, 'arguments')['paths'][0]['argumentFrames'][0]
201
+ self.assertEqual((frame['returnFrameBytes'], frame['calleeCleanupBytes'], frame['mappedBytes']), (4, 6, 6))
202
+ self.assertEqual([(s['offset'], s['width'], s['writerWidth']) for s in frame['slots']], [(0, 2, 2), (2, 4, 4)])
203
+ self.assertEqual([(g['offset'], g['width']) for g in frame['groupings']], [(0, 2), (2, 4)])
204
+ self.assertTrue(frame['settledOnThisPath'], frame['openReasons'])
205
+
196
206
  def test_returns_preserve_low_byte_predicate_and_discarded_width(self):
197
207
  for value in ('01 00 ff ff', '00 01 00 00'):
198
208
  c = Code().branch('e8', 'callee').emit('84 c0').branch('74', 'zero').emit('c3')
@@ -384,6 +384,192 @@ def ghidra_export(data, functions, **extra):
384
384
  "functionLimit": 128, "missingEntries": [], "unreadFunctions": [], "functions": rows, **extra}
385
385
 
386
386
 
387
+ class ArgumentFrameTests(unittest.TestCase):
388
+ def frames(self, code, **extra):
389
+ r = report(code, "arguments", **extra)
390
+ return r, [f for path in r["paths"] for f in path["argumentFrames"]]
391
+
392
+ def test_read_widths_group_pushed_words_and_forwarding_reaches_a_setter(self):
393
+ # Caller pushes id, segment, offset and mask words. The callee reads the mask as a word and the far
394
+ # pointer with LES, and forwards the id word to a setter, which reads it as a word.
395
+ c = Code().emit("68 05 00 68 00 30 68 44 00 68 07 00").branch("e8", "callee").emit("83 c4 08 c3")
396
+ c.label("callee").emit("55 89 e5 8b 46 04 c4 5e 06 ff 76 0a").branch("e8", "setter").emit("83 c4 02 5d c3")
397
+ c.label("setter").emit("55 89 e5 8b 46 04 5d c3")
398
+ r, frames = self.frames(c)
399
+ self.assertTrue(r["completeWithinModel"], r)
400
+ outer = next(f for f in frames if f["depth"] == 0)
401
+ self.assertTrue(outer["settledOnThisPath"], outer["openReasons"])
402
+ self.assertEqual((outer["returnFrameBytes"], outer["callerCleanupBytes"], outer["mappedBytes"]), (2, 8, 8))
403
+ self.assertEqual([(s["offset"], s["width"], s["writerSite"]) for s in outer["slots"]], [(0, 2, 9), (2, 2, 6), (4, 2, 3), (6, 2, 0)])
404
+ self.assertEqual([(g["offset"], g["width"], g["grouping"], g["slotOffsets"]) for g in outer["groupings"]],
405
+ [(0, 2, "consumed width only", [0]), (2, 4, "far-pointer", [2, 4]), (6, 2, "consumed width only", [6])])
406
+ # The setter's read of the forwarded id is a derived read of the id slot, two frames down.
407
+ identifier = outer["slots"][3]
408
+ self.assertEqual([(d["entry"], d["depth"], d["width"]) for d in identifier["derivedReads"]], [(c.labels["setter"], 2, 2)])
409
+ self.assertEqual(outer["slots"][0]["derivedReads"], [])
410
+ inner = next(f for f in frames if f["depth"] == 1)
411
+ self.assertTrue(inner["settledOnThisPath"], inner["openReasons"])
412
+ self.assertEqual(r["argumentFrameSites"][0]["readWidthSets"], [[{"offset": 0, "width": 2, "grouping": "consumed width only"},
413
+ {"offset": 2, "width": 4, "grouping": "far-pointer"},
414
+ {"offset": 6, "width": 2, "grouping": "consumed width only"}]])
415
+ self.assertTrue(all(site["agreed"] for site in r["argumentFrameSites"]))
416
+
417
+ def test_the_report_keeps_the_writes_its_slots_cite(self):
418
+ c = Code().emit("6a 01 6a 02").branch("e8", "callee").emit("83 c4 04 c3").label("callee").emit("55 89 e5 8b 46 04 8b 46 06 5d c3")
419
+ r, frames = self.frames(c)
420
+ events = {e["order"]: e for e in r["paths"][0]["events"]}
421
+ cited = [s["writerOrder"] for s in frames[0]["slots"]]
422
+ self.assertEqual(len(cited), 2)
423
+ self.assertEqual([(events[o]["kind"], events[o]["site"]) for o in cited], [("write", 2), ("write", 0)])
424
+ # Writes no slot cites are still filtered out of the arguments report.
425
+ self.assertEqual(sum(e["kind"] == "write" for e in events.values()), 2)
426
+
427
+ def test_a_far_call_maps_slots_above_its_four_byte_frame(self):
428
+ data = bytes.fromhex("68 00 30 68 44 00 68 07 00 9a 12 00 00 00 83 c4 06 c3 55 89 e5 8b 46 06 c5 5e 08 c9 cb")
429
+ cfg = configuration(data, relocations=[{"site": 12, "segment": 0x1000, "evidence": "synthetic relocated call"}])
430
+ frame = run_report(data, cfg, "arguments")["paths"][0]["argumentFrames"][0]
431
+ self.assertEqual(frame["returnFrameBytes"], 4)
432
+ self.assertTrue(frame["settledOnThisPath"], frame["openReasons"])
433
+ self.assertEqual([(g["offset"], g["width"]) for g in frame["groupings"]], [(0, 2), (2, 4)])
434
+
435
+ def test_a_far_frame_starts_at_the_return_ip_across_the_address_wrap(self):
436
+ # Four pops leave three pushed words at offsets 2..7, so the far call pushes CS at offset 0 and
437
+ # the return IP at 0xFFFE. The frame starts above the return IP, not above the CS word.
438
+ data = bytes.fromhex("5a 5a 5a 5a 68 00 30 68 44 00 68 07 00 9a 1a 00 00 00 83 c4 06 52 52 52 52 c3"
439
+ "55 89 e5 8b 46 06 c5 5e 08 c9 cb")
440
+ cfg = configuration(data, relocations=[{"site": 16, "segment": 0x1000, "evidence": "synthetic relocated call"}])
441
+ frame = run_report(data, cfg, "arguments")["paths"][0]["argumentFrames"][0]
442
+ self.assertEqual(frame["returnFrameBytes"], 4)
443
+ self.assertEqual([(s["offset"], s["width"], s["writerSite"]) for s in frame["slots"]], [(0, 2, 10), (2, 2, 7), (4, 2, 4)])
444
+ self.assertTrue(frame["settledOnThisPath"], frame["openReasons"])
445
+
446
+ def test_overlapping_read_widths_compete_and_stay_open(self):
447
+ # The callee reads the first pushed word as a byte and as a word.
448
+ c = Code().emit("68 07 00").branch("e8", "callee").emit("83 c4 02 c3")
449
+ c.label("callee").emit("55 89 e5 8a 46 04 8b 46 04 5d c3")
450
+ _, frames = self.frames(c)
451
+ frame = frames[0]
452
+ self.assertEqual(frame["competingWidths"], [[[0, 1], [0, 2]]])
453
+ self.assertEqual(frame["groupings"][0]["partialSlots"], [0])
454
+ self.assertFalse(frame["settledOnThisPath"])
455
+ self.assertIn("reads of different widths overlap", frame["openReasons"])
456
+
457
+ def test_an_unread_slot_an_overwritten_slot_and_an_unbounded_frame_stay_open(self):
458
+ # Two words pushed and released, only the first read.
459
+ c = Code().emit("6a 01 6a 02").branch("e8", "callee").emit("83 c4 04 c3").label("callee").emit("55 89 e5 8b 46 04 5d c3")
460
+ frame = self.frames(c)[1][0]
461
+ self.assertEqual(frame["slots"][1]["consumedBy"], [])
462
+ self.assertIn("the slot at 2 was not read by the callee on this path", frame["openReasons"])
463
+ # The callee overwrites its argument before reading it.
464
+ c = Code().emit("6a 01").branch("e8", "callee").emit("83 c4 02 c3").label("callee").emit("55 89 e5 c7 46 04 09 00 8b 46 04 5d c3")
465
+ frame = self.frames(c)[1][0]
466
+ self.assertEqual(frame["groupings"][0]["bytesNotFromSlotWriter"], [0, 1])
467
+ self.assertFalse(frame["settledOnThisPath"])
468
+ # The callee doubles its argument in place, so the stored word still carries the push among its producers.
469
+ c = Code().emit("6a 01").branch("e8", "callee").emit("83 c4 02 c3").label("callee").emit("55 89 e5 d1 66 04 8b 46 04 5d c3")
470
+ frame = self.frames(c)[1][0]
471
+ self.assertEqual([g["bytesNotFromSlotWriter"] for g in frame["groupings"]], [[], [0, 1]])
472
+ self.assertFalse(frame["settledOnThisPath"])
473
+ # The caller rebalances with POP, so no cleanup amount bounds the frame.
474
+ c = Code().emit("6a 01 6a 02").branch("e8", "callee").emit("59 59 c3").label("callee").emit("55 89 e5 8b 46 04 5d c3")
475
+ frame = self.frames(c)[1][0]
476
+ self.assertEqual((frame["callerCleanupBytes"], frame["mappedBytes"]), (None, 2))
477
+ self.assertIn("no cleanup amount bounds the frame; slots above the highest read are not mapped", frame["openReasons"])
478
+
479
+ def test_slots_follow_the_stack_across_the_address_wrap(self):
480
+ # The root pops its return word, so the call's return frame sits at the top of the stack
481
+ # offset range and the pushed argument sits at offset 0.
482
+ c = Code().emit("5a 6a 07").branch("e8", "callee").emit("83 c4 02 52 c3").label("callee").emit("55 89 e5 8b 46 04 5d c3")
483
+ frame = self.frames(c)[1][0]
484
+ self.assertEqual([(s["offset"], s["width"], s["writerSite"]) for s in frame["slots"]], [(0, 2, 1)])
485
+ self.assertTrue(frame["settledOnThisPath"], frame["openReasons"])
486
+
487
+ def test_a_read_of_a_word_a_modeled_call_invalidated_stays_open(self):
488
+ c = Code().emit("6a 01").branch("e8", "service").branch("e8", "callee").emit("83 c4 02 c3")
489
+ c.label("service").emit("c3").label("callee").emit("55 89 e5 8b 46 04 5d c3")
490
+ r, frames = self.frames(c, callModels=[{"site": 2, "evidence": "synthetic service", "preserves": ["ss"], "cases": [{}]}])
491
+ frame = frames[0]
492
+ self.assertEqual((frame["slots"][0]["writerSite"], frame["slots"][0]["reason"]), (None, "memory invalidated by the modeled call at 2"))
493
+ self.assertEqual(frame["groupings"][0]["bytesNotFromSlotWriter"], [0, 1])
494
+ self.assertFalse(frame["settledOnThisPath"])
495
+ self.assertFalse(r["argumentFrameSites"][0]["agreed"])
496
+
497
+ def test_a_word_a_modeled_call_preserved_keeps_its_writer(self):
498
+ # The model keeps the pushed word on a concrete stack, so the callee reads the push.
499
+ c = Code().emit("6a 01").branch("e8", "service").branch("e8", "callee").emit("83 c4 02 c3")
500
+ c.label("service").emit("c3").label("callee").emit("55 89 e5 8b 46 04 5d c3")
501
+ scope = {"segment": "ss", "base": "sp", "displacement": 0, "bytes": 2, "evidence": "synthetic pushed word"}
502
+ model = {"site": 2, "evidence": "synthetic service", "preserves": ["ss", "esp"], "cases": [{}], "preservesMemory": [scope]}
503
+ r, frames = self.frames(c, registers={"ss": 0x2000, "sp": 0x100}, callModels=[model])
504
+ frame = frames[0]
505
+ self.assertEqual([(s["offset"], s["width"], s["writerSite"]) for s in frame["slots"]], [(0, 2, 0)])
506
+ self.assertTrue(frame["settledOnThisPath"], frame["openReasons"])
507
+ # A frame byte outside the scope still loses its writer.
508
+ scope["bytes"] = 1
509
+ frame = self.frames(c, registers={"ss": 0x2000, "sp": 0x100}, callModels=[model])[1][0]
510
+ self.assertEqual([(s["offset"], s["width"], s["writerSite"], s.get("reason")) for s in frame["slots"]],
511
+ [(0, 1, 0, None), (1, 1, None, "memory invalidated by the modeled call at 2")])
512
+ self.assertFalse(frame["settledOnThisPath"])
513
+
514
+ def test_a_callee_that_stops_leaves_its_frame_open(self):
515
+ c = Code().emit("6a 01").branch("e8", "callee").emit("83 c4 02 c3").label("callee").emit("55 89 e5 8b 46 04 ff d3")
516
+ r, frames = self.frames(c)
517
+ self.assertFalse(r["completeWithinModel"])
518
+ self.assertFalse(frames[0]["calleeReturned"])
519
+ self.assertIn("the callee did not return on this path", frames[0]["openReasons"])
520
+
521
+ def test_the_window_limit_is_reported(self):
522
+ # The caller releases 0x200 bytes; only the first 256 are mapped.
523
+ c = Code().emit("6a 01").branch("e8", "callee").emit("81 c4 00 02 c3").label("callee").emit("55 89 e5 8b 46 04 5d c3")
524
+ frame = self.frames(c)[1][0]
525
+ self.assertEqual((frame["callerCleanupBytes"], frame["mappedBytes"]), (0x200, 256))
526
+ self.assertIn("the frame is wider than the 256-byte window", frame["openReasons"])
527
+ self.assertEqual(frame["slots"][-1]["writerSite"], None)
528
+ self.assertEqual(frame["slots"][-1]["offset"] + frame["slots"][-1]["width"], 256)
529
+
530
+ def test_paths_that_read_different_widths_keep_the_site_open(self):
531
+ # One path reads a word, the other a far pointer, from the same two pushed words.
532
+ c = Code().emit("6a 01 6a 02").branch("e8", "callee").emit("83 c4 04 c3")
533
+ c.label("callee").emit("55 89 e5 85 f6").branch("74", "far").emit("8b 46 04").branch("eb", "done")
534
+ c.label("far").emit("c4 5e 04").label("done").emit("5d c3")
535
+ r, frames = self.frames(c)
536
+ self.assertEqual(len(frames), 2)
537
+ site = r["argumentFrameSites"][0]
538
+ self.assertEqual(site["readWidthSets"], [[{"offset": 0, "width": 2, "grouping": "consumed width only"}],
539
+ [{"offset": 0, "width": 4, "grouping": "far-pointer"}]])
540
+ self.assertFalse(site["agreed"])
541
+ self.assertEqual(len(site["unsettledPaths"]), 1)
542
+
543
+ def test_paths_that_group_the_same_bytes_differently_keep_the_site_open(self):
544
+ # Both paths read four bytes at offset 0: one as a far pointer with LES, one as a 32-bit dword.
545
+ c = Code().emit("6a 01 6a 02").branch("e8", "callee").emit("83 c4 04 c3")
546
+ c.label("callee").emit("55 89 e5 85 f6").branch("74", "far").emit("66 8b 46 04").branch("eb", "done")
547
+ c.label("far").emit("c4 5e 04").label("done").emit("5d c3")
548
+ r, frames = self.frames(c)
549
+ self.assertEqual(len(frames), 2)
550
+ self.assertTrue(all(f["settledOnThisPath"] for f in frames), [f["openReasons"] for f in frames])
551
+ site = r["argumentFrameSites"][0]
552
+ self.assertEqual(site["readWidthSets"], [[{"offset": 0, "width": 4, "grouping": "consumed width only"}],
553
+ [{"offset": 0, "width": 4, "grouping": "far-pointer"}]])
554
+ self.assertFalse(site["agreed"])
555
+
556
+ def test_a_write_through_another_address_drops_the_slot_writer(self):
557
+ # A DS write between the push and the call may alias the symbolic stack, so the pushed word
558
+ # has no known writer when the callee reads it.
559
+ c = Code().emit("6a 01 c7 06 00 01 05 00").branch("e8", "callee").emit("83 c4 02 c3")
560
+ c.label("callee").emit("55 89 e5 8b 46 04 5d c3")
561
+ r, frames = self.frames(c)
562
+ frame = frames[0]
563
+ self.assertEqual([(s["offset"], s["width"], s["writerSite"], s.get("reason")) for s in frame["slots"]],
564
+ [(0, 2, None, "memory possibly overwritten through another address by the write at 2")])
565
+ self.assertEqual(frame["groupings"][0]["bytesNotFromSlotWriter"], [0, 1])
566
+ self.assertFalse(frame["settledOnThisPath"])
567
+ # On a concrete stack the DS write lands elsewhere, so the push stays the slot's writer.
568
+ frame = self.frames(c, registers={"ss": 0x2000, "sp": 0x100, "ds": 0x3000})[1][0]
569
+ self.assertEqual([(s["offset"], s["width"], s["writerSite"]) for s in frame["slots"]], [(0, 2, 0)])
570
+ self.assertTrue(frame["settledOnThisPath"], frame["openReasons"])
571
+
572
+
387
573
  class GhidraCrossCheckTests(unittest.TestCase):
388
574
  # root: call a (site 0); call b (site 3); call bx (site 6); ret. a and b return.
389
575
  code = Code().label("root").branch("e8", "a").branch("e8", "b").emit("ff d3 c3").label("a").emit("c3").label("b").emit("c3")