timecs 2.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.
Files changed (94) hide show
  1. app.py +3014 -0
  2. ast_scanner.py +36187 -0
  3. banner.py +146 -0
  4. ci_reporter.py +570 -0
  5. cli.py +2347 -0
  6. config_loader.py +307 -0
  7. cross_file_engine.py +1781 -0
  8. delivery_models.py +145 -0
  9. delivery_repository.py +78 -0
  10. diff_scan.py +127 -0
  11. durable_delivery_sink.py +103 -0
  12. event_bus.py +155 -0
  13. event_publisher.py +345 -0
  14. event_taxonomy.py +313 -0
  15. function_summarizer.py +354 -0
  16. html_auditor.py +274 -0
  17. iac_auditor.py +400 -0
  18. in_app_adapter.py +115 -0
  19. js_scanner.py +895 -0
  20. manifest_parser.py +960 -0
  21. master_rules_bank.py +389 -0
  22. notification_models.py +346 -0
  23. notification_policy.py +309 -0
  24. notification_repository.py +118 -0
  25. notification_routes.py +394 -0
  26. notification_service.py +199 -0
  27. osv_client.py +437 -0
  28. remediation/__init__.py +39 -0
  29. remediation/base.py +102 -0
  30. remediation/contracts.py +196 -0
  31. remediation/cwe1188_binding.py +78 -0
  32. remediation/cwe1336_jinja.py +91 -0
  33. remediation/cwe22_path_traversal.py +348 -0
  34. remediation/cwe295_ssl.py +87 -0
  35. remediation/cwe327_weak_hash.py +78 -0
  36. remediation/cwe377_tempfile.py +77 -0
  37. remediation/cwe489_debug.py +80 -0
  38. remediation/cwe502_yaml.py +89 -0
  39. remediation/cwe614_cookie.py +91 -0
  40. remediation/cwe78_cmdi.py +415 -0
  41. remediation/cwe798_credentials.py +153 -0
  42. remediation/cwe89_sqli.py +425 -0
  43. remediation/cwe916_password_hash.py +131 -0
  44. remediation/cwe95_eval.py +77 -0
  45. remediation/dispatcher.py +114 -0
  46. remediation/orchestrator.py +541 -0
  47. remediation/patch_engine.py +213 -0
  48. remediation/verification.py +253 -0
  49. rule_engine.py +1535 -0
  50. sarif_adapter.py +719 -0
  51. sarif_exporter.py +88 -0
  52. sca_reachability/__init__.py +28 -0
  53. sca_reachability/ast_analyzer.py +366 -0
  54. sca_reachability/call_graph.py +203 -0
  55. sca_reachability/contracts.py +365 -0
  56. sca_reachability/dist_import_map.py +46 -0
  57. sca_reachability/engine.py +603 -0
  58. sca_reachability/resolver.py +169 -0
  59. scanners/__init__.py +70 -0
  60. scanners/container_scanner.py +323 -0
  61. scanners/cve_index.py +521 -0
  62. scanners/iac_scanner.py +328 -0
  63. scanners/sbom.py +183 -0
  64. scanners/sca_scanner.py +667 -0
  65. scanners/secret_scanner.py +345 -0
  66. scanners/yaml_lite.py +217 -0
  67. secret_filters.py +435 -0
  68. secret_scanner.py +943 -0
  69. sqlite_delivery_repository.py +277 -0
  70. sqlite_notification_repository.py +441 -0
  71. ssrf_guard.py +276 -0
  72. staged_scanner.py +492 -0
  73. suppression_resolver.py +282 -0
  74. symbol_indexer.py +424 -0
  75. tcs/__init__.py +1 -0
  76. tcs/analysis/__init__.py +1 -0
  77. tcs/analysis/def_use.py +408 -0
  78. tcs/analysis/function_contracts.py +290 -0
  79. tcs/parallel_analyzer.py +276 -0
  80. tcs/parallel_scanner.py +630 -0
  81. tcs/treesitter_packer.py +1446 -0
  82. tcs_cli.py +2086 -0
  83. tcs_config.py +218 -0
  84. tcs_gui.py +2123 -0
  85. timecs-2.0.0.dist-info/METADATA +142 -0
  86. timecs-2.0.0.dist-info/RECORD +94 -0
  87. timecs-2.0.0.dist-info/WHEEL +5 -0
  88. timecs-2.0.0.dist-info/entry_points.txt +4 -0
  89. timecs-2.0.0.dist-info/licenses/LICENSE +201 -0
  90. timecs-2.0.0.dist-info/top_level.txt +49 -0
  91. version_matcher.py +934 -0
  92. webhook_adapter.py +495 -0
  93. webhook_client.py +483 -0
  94. webhook_formatters.py +245 -0
cross_file_engine.py ADDED
@@ -0,0 +1,1781 @@
1
+ """
2
+ TimeCodeSecurity - Phase 4: Inter-Procedural / Cross-File Taint Engine
3
+ Stitches global symbol index and function taint contracts to detect multi-file exploit paths.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ import ast
9
+ import io
10
+ import sys
11
+ import time
12
+ import tokenize
13
+ from dataclasses import dataclass, field
14
+ from pathlib import Path
15
+ from typing import Dict, List, NamedTuple, Optional, Set
16
+
17
+ from symbol_indexer import GlobalSymbolIndex
18
+ from function_summarizer import KNOWN_SANITIZERS, FunctionSummarizer, FunctionSummary, ParamSinkEdge
19
+
20
+
21
+ # Common web entrypoint sources
22
+ TAINT_SOURCE_PATTERNS = {
23
+ "request.GET", "request.POST", "request.data", "request.body",
24
+ "request.args", "request.form", "request.params", "request.headers",
25
+ "request.COOKIES", "request.query_params"
26
+ }
27
+
28
+
29
+ # Framework event-bus vocabulary: a producer never calls a handler directly, so the
30
+ # dispatch method has to be re-read as a call of the registered subscriber.
31
+ SIGNAL_FACTORY_METHODS = {"Signal"}
32
+ SIGNAL_SUBSCRIBE_DECORATORS = {"receiver"}
33
+ SIGNAL_EMISSION_METHODS = {"send", "send_robust"}
34
+ TASK_DECORATOR_NAMES = {"shared_task", "task"}
35
+ TASK_DISPATCH_METHODS = {"delay", "apply_async"}
36
+ _DISPATCH_ATTRS = SIGNAL_EMISSION_METHODS | TASK_DISPATCH_METHODS
37
+
38
+
39
+ _SCOPES = (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda, ast.ClassDef)
40
+ # Concrete node types the sanitizer scan's two loops can ever read: _sanitized_sites tests
41
+ # ast.Assign / ast.Call on the loop node, and _instance_bindings tests ast.Assign on it. AnnAssign
42
+ # and AugAssign are carried as well so a node can only ever be kept by mistake - the loops below
43
+ # keep their isinstance guards, so a kept-by-mistake node is re-tested and ignored. Dropping a
44
+ # node the other way would cost a suppression, which is how a false negative is born.
45
+ _GATE_SITE_NODES = frozenset({ast.Assign, ast.AnnAssign, ast.AugAssign, ast.Call})
46
+ _GATE_RECEIVER_NODES = frozenset({ast.Assign, ast.AnnAssign, ast.AugAssign})
47
+
48
+
49
+ def _ordered_nodes(root: ast.AST, skip_scopes: bool = False):
50
+ """Yield nodes in source (pre-order) sequence so assignment state is chronological.
51
+
52
+ With skip_scopes, nested function/class bodies are not descended into, keeping the
53
+ traversal to the root node's own lexical scope.
54
+ """
55
+ stack = [root]
56
+ while stack:
57
+ node = stack.pop()
58
+ yield node
59
+ if skip_scopes and node is not root and isinstance(node, _SCOPES):
60
+ continue
61
+ stack.extend(reversed(list(ast.iter_child_nodes(node))))
62
+
63
+
64
+ def _contracted_functions(tree: ast.AST):
65
+ """Yield (node, qualname) pairs using the same keys FunctionSummarizer indexes by."""
66
+ for stmt in tree.body:
67
+ if isinstance(stmt, (ast.FunctionDef, ast.AsyncFunctionDef)):
68
+ yield stmt, stmt.name
69
+ elif isinstance(stmt, ast.ClassDef):
70
+ for item in stmt.body:
71
+ if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
72
+ yield item, f"{stmt.name}.{item.name}"
73
+
74
+
75
+ def _function_defs(tree: ast.AST):
76
+ """Yield every FunctionDef/AsyncFunctionDef in a module by visiting statements only.
77
+
78
+ A def can only ever sit in statement position, so skipping `ast.expr` and `ast.pattern`
79
+ subtrees returns the same node set an isinstance filter over `ast.walk(tree)` produces,
80
+ without paying for the expression nodes that make up most of a module's tree. Nested
81
+ `match`/`try`/`with`/`if` bodies are still descended, and defs nested inside a def body
82
+ are included, exactly as `ast.walk` would find them.
83
+ """
84
+ stack = [tree]
85
+ while stack:
86
+ node = stack.pop()
87
+ for child in ast.iter_child_nodes(node):
88
+ if isinstance(child, (ast.expr, ast.pattern)):
89
+ continue
90
+ if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
91
+ yield child
92
+ stack.append(child)
93
+
94
+
95
+ def _has_assign_statement(root: ast.AST) -> bool:
96
+ """Is there any assignment-shaped statement anywhere below `root`?
97
+
98
+ `ast.Assign` only ever sits in statement position - a statement cannot hide inside an
99
+ `ast.expr` / `ast.pattern` subtree (a lambda body is an expression) - so pruning those, exactly
100
+ as _function_defs does, still answers yes for every body the full walk would have found an
101
+ Assign in. A body answering no therefore cannot fill `assigned`, so it cannot yield a site.
102
+ The test is deliberately assignment-shaped rather than Assign-only: an AnnAssign body costs
103
+ one extra full walk that then finds nothing, which is cheap, whereas a false "no" would delete
104
+ a suppression.
105
+ """
106
+ stack = [root]
107
+ while stack:
108
+ node = stack.pop()
109
+ for child in ast.iter_child_nodes(node):
110
+ if isinstance(child, (ast.expr, ast.pattern)):
111
+ continue
112
+ if type(child) in _GATE_RECEIVER_NODES:
113
+ return True
114
+ stack.append(child)
115
+ return False
116
+
117
+
118
+ def _record_productive(root: ast.AST):
119
+ """One pre-order walk of a body that records only the nodes the site loops can use.
120
+
121
+ Returns (own_scope_assigns, productive):
122
+ * `productive` is the same sequence _ordered_nodes(root) restricted to _GATE_SITE_NODES
123
+ would have yielded, so replaying over it keeps the two walks' node order untouched.
124
+ * `own_scope_assigns` carries the `depth == 0` entries, which is exactly what
125
+ _ordered_nodes(root, skip_scopes=True) yields for assignments: a nested scope node is
126
+ itself still own-scope, its children are not. `_sanitized_sites` needs the two separate
127
+ because the engine builds the receiver map for the WHOLE body first and hands that finished
128
+ map to every assignment it resolves; folding both loops into one chronological pass would
129
+ show an earlier line a smaller map, which is a behaviour change, not a speed-up.
130
+ """
131
+ own_scope_assigns: List[ast.AST] = []
132
+ productive: List[ast.AST] = []
133
+ stack: List[tuple[ast.AST, int]] = [(root, 0)]
134
+ while stack:
135
+ node, depth = stack.pop()
136
+ if depth == 0 and type(node) in _GATE_RECEIVER_NODES:
137
+ own_scope_assigns.append(node)
138
+ if type(node) in _GATE_SITE_NODES:
139
+ productive.append(node)
140
+ child_depth = depth + 1 if (node is not root and isinstance(node, _SCOPES)) else depth
141
+ stack.extend((child, child_depth)
142
+ for child in reversed(list(ast.iter_child_nodes(node))))
143
+ return own_scope_assigns, productive
144
+
145
+
146
+ def _dotted_prefix(expr: ast.expr) -> str:
147
+ """Dotted spelling of a Name/Attribute expression chain, '' when it is anything else."""
148
+ parts: List[str] = []
149
+ current: ast.expr = expr
150
+ while isinstance(current, ast.Attribute):
151
+ parts.append(current.attr)
152
+ current = current.value
153
+ if not isinstance(current, ast.Name):
154
+ return ""
155
+ parts.append(current.id)
156
+ return ".".join(reversed(parts))
157
+
158
+
159
+ def _name_uses(expr: ast.expr) -> Set[str]:
160
+ """Names an expression reads, excluding the callee identifiers of the calls inside it.
161
+
162
+ `int(record_id)` reads one value, `record_id`; without this the sanitizer's own name
163
+ would count as a second input and block an argument that is provably cleaned.
164
+ """
165
+ excluded = set()
166
+ for node in ast.walk(expr):
167
+ if isinstance(node, ast.Call) and isinstance(node.func, (ast.Name, ast.Attribute)):
168
+ excluded.update(id(child) for child in ast.walk(node.func))
169
+ return {
170
+ node.id
171
+ for node in ast.walk(expr)
172
+ if isinstance(node, ast.Name) and id(node) not in excluded
173
+ }
174
+
175
+
176
+ def _callee_tail(func: ast.AST) -> str:
177
+ """Trailing identifier of a callee expression, '' when it is not a Name/Attribute."""
178
+ if isinstance(func, ast.Name):
179
+ return func.id
180
+ if isinstance(func, ast.Attribute):
181
+ return func.attr
182
+ return ""
183
+
184
+
185
+ def _func_descriptor(func: ast.AST) -> Optional[str]:
186
+ """Source spelling of a callee (`cursor.execute`), None when unparse is unavailable/fails."""
187
+ if not hasattr(ast, "unparse"):
188
+ return None
189
+ try:
190
+ return ast.unparse(func)
191
+ except Exception:
192
+ return None
193
+
194
+
195
+ def _is_signal_factory(value: ast.AST) -> bool:
196
+ """True for `x = Signal()` / `x = django.dispatch.Signal()` (Django, Blinker)."""
197
+ if not isinstance(value, ast.Call):
198
+ return False
199
+ callee = value.func
200
+ if isinstance(callee, ast.Name):
201
+ return callee.id in SIGNAL_FACTORY_METHODS
202
+ return isinstance(callee, ast.Attribute) and callee.attr in SIGNAL_FACTORY_METHODS
203
+
204
+
205
+ def _decorator_label(decorator: ast.AST) -> Optional[str]:
206
+ """Trailing dotted component of a decorator, whether bare, dotted, or called."""
207
+ target = decorator.func if isinstance(decorator, ast.Call) else decorator
208
+ if isinstance(target, ast.Name):
209
+ return target.id
210
+ if isinstance(target, ast.Attribute):
211
+ return target.attr
212
+ return None
213
+
214
+
215
+ # ─── PEP 695 tolerance: 3.12 type-parameter syntax on a 3.11 ast ────────────────
216
+ # `ast.parse(..., feature_version=(3, 11))` cannot help here: feature_version can only *restrict*
217
+ # the grammar, never enable newer syntax, and on a 3.11 interpreter (3, 11) is already the default.
218
+ # So a file the default parse rejects gets one retry on a rewritten source that removes exactly the
219
+ # three PEP 695 constructs (`type X[T] =`, `def f[T](`, `class C[T](`/`:`) by overwriting those
220
+ # characters with spaces. Newlines are never touched, so every line number - and therefore every
221
+ # finding line - stays identical to the original file. The retry tree is used only when the rewritten
222
+ # source parses; otherwise the file is skipped exactly as it was before.
223
+ def _matching_bracket(tokens: List[tokenize.TokenInfo], open_index: int) -> Optional[int]:
224
+ depth = 0
225
+ for index in range(open_index, len(tokens)):
226
+ text = tokens[index].string
227
+ if text == "[":
228
+ depth += 1
229
+ elif text == "]":
230
+ depth -= 1
231
+ if depth == 0:
232
+ return index
233
+ return None
234
+
235
+
236
+ def _rewrite_pep695(source: str) -> Optional[str]:
237
+ """Blank PEP 695 type-parameter tokens, preserving every line and column offset."""
238
+ try:
239
+ tokens = [t for t in tokenize.generate_tokens(io.StringIO(source).readline)
240
+ if t.type not in (tokenize.NL, tokenize.COMMENT, tokenize.ENCODING)]
241
+ except (tokenize.TokenError, IndentationError, SyntaxError):
242
+ return None
243
+
244
+ starts = [0]
245
+ for line in source.splitlines(keepends=True):
246
+ starts.append(starts[-1] + len(line))
247
+
248
+ def offset(position) -> int:
249
+ row, col = position
250
+ return starts[row - 1] + col
251
+
252
+ words = ("def", "class", "type")
253
+ # (start, end, replacement): a `type` alias moves its name to the start of the span rather
254
+ # than blanking the `type ` prefix -- blanking would leave the name indented by five
255
+ # columns and the module-level statement would be an `unexpected indent`. Moving the name
256
+ # keeps the line's total width, so every token after the span keeps its column.
257
+ edits: List[tuple[int, int, str]] = []
258
+ total = len(tokens)
259
+ for index, token in enumerate(tokens):
260
+ if token.type != tokenize.NAME or token.string not in words:
261
+ continue
262
+ previous = tokens[index - 1] if index else None
263
+ at_statement_start = (
264
+ previous is None
265
+ or previous.type in (tokenize.NEWLINE, tokenize.INDENT, tokenize.DEDENT)
266
+ or previous.string == ";"
267
+ )
268
+ if token.string == "def" and previous is not None and previous.string == "async":
269
+ before_async = tokens[index - 2] if index >= 2 else None
270
+ at_statement_start = (
271
+ before_async is None
272
+ or before_async.type in (tokenize.NEWLINE, tokenize.INDENT, tokenize.DEDENT)
273
+ or before_async.string == ";"
274
+ )
275
+ if not at_statement_start or index + 2 >= total:
276
+ continue
277
+ name_token = tokens[index + 1]
278
+ if name_token.type != tokenize.NAME:
279
+ continue
280
+ marker = tokens[index + 2]
281
+ if marker.string == "[":
282
+ close = _matching_bracket(tokens, index + 2)
283
+ if close is None or close + 1 >= total:
284
+ continue
285
+ after = tokens[close + 1].string
286
+ if token.string == "type":
287
+ if after != "=":
288
+ continue
289
+ edits.append((offset(token.start), offset(name_token.end),
290
+ name_token.string))
291
+ edits.append((offset(marker.start), offset(tokens[close].end), ""))
292
+ elif token.string == "def":
293
+ if after != "(":
294
+ continue
295
+ edits.append((offset(marker.start), offset(tokens[close].end), ""))
296
+ else:
297
+ if after not in ("(", ":"):
298
+ continue
299
+ edits.append((offset(marker.start), offset(tokens[close].end), ""))
300
+ elif token.string == "type" and marker.string == "=":
301
+ edits.append((offset(token.start), offset(name_token.end), name_token.string))
302
+
303
+ if not edits:
304
+ return None
305
+ characters = list(source)
306
+ for start, end, text in edits:
307
+ position = start
308
+ for character in text:
309
+ while position < end and characters[position] in ("\n", "\r"):
310
+ position += 1
311
+ if position >= end:
312
+ break
313
+ characters[position] = character
314
+ position += 1
315
+ while position < end:
316
+ if characters[position] not in ("\n", "\r"):
317
+ characters[position] = " "
318
+ position += 1
319
+ return "".join(characters)
320
+
321
+
322
+ def _parse_source(path: str, source: str) -> Optional[ast.AST]:
323
+ """Parse `source`, retrying once on a PEP 695-rewritten spelling; None when both fail."""
324
+ try:
325
+ return ast.parse(source, filename=path)
326
+ except Exception:
327
+ pass
328
+ rewritten = _rewrite_pep695(source)
329
+ if rewritten is None:
330
+ return None
331
+ try:
332
+ return ast.parse(rewritten, filename=path)
333
+ except Exception:
334
+ return None
335
+
336
+
337
+ # ─── Compact symbol facts: the cross-file symbol table ─────────────────────────
338
+ # Nothing below retains an AST. The engine keeps, per module, only what the six cross-module
339
+ # passes ask of a tree: who a call names, how its receiver is spelled, which arguments are bare
340
+ # names (the only shape the parameter-forwarding lift can follow), the decorator shapes, the
341
+ # class bases, and the call spelling on the right-hand side of assignments (the only shape the
342
+ # sanitizer replay can start from). Source stays on disk; a module is re-parsed only when the
343
+ # caller analysis or the sanitizer audit actually has to run its AST.
344
+ _SITE_FUNC_OTHER = 0 # callee is neither a Name nor an Attribute
345
+ _SITE_FUNC_NAME = 1 # foo(...)
346
+ _SITE_FUNC_ATTR = 2 # <receiver>.foo(...)
347
+
348
+ _SITE_RECV_OTHER = 0 # receiver is neither a Name, a Name-call, nor an attribute chain
349
+ _SITE_RECV_NAME = 1 # receiver is a bare Name
350
+ _SITE_RECV_CTOR = 2 # receiver is ClassName(...) with a bare constructor
351
+ _SITE_RECV_ATTR = 3 # receiver is an attribute chain
352
+
353
+
354
+ class CallShape(NamedTuple):
355
+ """Everything about a call that resolution reads, minus its line number.
356
+
357
+ Shapes are pooled per run, so a repeated spelling (`self.db.execute(query)`) is one object
358
+ shared by every site that writes it.
359
+ """
360
+ fkind: int
361
+ fname: str
362
+ rkind: int
363
+ rname: str
364
+ rprefix: str
365
+ rprefix_bare: bool
366
+ argn: tuple # positional argument spellings: interned Name id or None
367
+ kwn: tuple # ((keyword, interned Name id or None), ...)
368
+
369
+
370
+ class DecoFacts(NamedTuple):
371
+ """One decorator: its label, whether it is a call, and the shape of its first argument."""
372
+ label: Optional[str]
373
+ is_call: bool
374
+ bare: Optional[str] # resolvable name for a non-call decorator, None otherwise
375
+ arg0kind: int # 0 = Name, 1 = Attribute, 2 = other or absent
376
+ arg0name: str
377
+ arg0prefix: str
378
+ arg0bare: bool
379
+
380
+
381
+ class WrapperShape(NamedTuple):
382
+ """The provable decorator shape `_wrapper_sanitized_slots` accepts, precomputed at harvest."""
383
+ ok: bool
384
+ wparams: tuple # wrapper positional parameter names
385
+ flen: int # forwarded argument count
386
+ fargs: tuple # per forwarded argument: (used names, is_call, callee tail)
387
+
388
+
389
+ class FuncFacts:
390
+ """Facts for one contracted function: its contract, calls, receivers and decorators."""
391
+ __slots__ = ("qual", "summary", "recv", "calls", "decos", "wrapper")
392
+
393
+ def __init__(self, qual, summary, recv, calls, decos, wrapper):
394
+ self.qual = qual
395
+ self.summary = summary
396
+ self.recv = recv
397
+ self.calls = calls
398
+ self.decos = decos
399
+ self.wrapper = wrapper
400
+
401
+
402
+ class ModuleFacts:
403
+ """The symbol-table row for one module; holds no AST and no source text."""
404
+ __slots__ = ("funcs", "bases", "signals", "sink_lines", "assign_callees")
405
+
406
+ def __init__(self, funcs, bases, signals, sink_lines, assign_callees):
407
+ self.funcs = funcs
408
+ self.bases = bases
409
+ self.signals = signals
410
+ self.sink_lines = sink_lines
411
+ self.assign_callees = assign_callees
412
+
413
+
414
+ def _call_shape(call: ast.Call, pool: Dict[CallShape, CallShape]) -> CallShape:
415
+ func = call.func
416
+ if isinstance(func, ast.Name):
417
+ fkind, fname = _SITE_FUNC_NAME, func.id
418
+ rkind, rname, rprefix, rprefix_bare = _SITE_RECV_OTHER, "", "", False
419
+ elif isinstance(func, ast.Attribute):
420
+ fkind, fname = _SITE_FUNC_ATTR, func.attr
421
+ value = func.value
422
+ if isinstance(value, ast.Name):
423
+ rkind, rname, rprefix, rprefix_bare = _SITE_RECV_NAME, value.id, "", False
424
+ elif isinstance(value, ast.Call) and isinstance(value.func, ast.Name):
425
+ rkind, rname, rprefix, rprefix_bare = _SITE_RECV_CTOR, value.func.id, "", False
426
+ elif isinstance(value, ast.Attribute):
427
+ rkind = _SITE_RECV_ATTR
428
+ rname = value.attr
429
+ rprefix = _dotted_prefix(value.value)
430
+ rprefix_bare = isinstance(value.value, ast.Name)
431
+ else:
432
+ rkind, rname, rprefix, rprefix_bare = _SITE_RECV_OTHER, "", "", False
433
+ else:
434
+ fkind, fname = _SITE_FUNC_OTHER, ""
435
+ rkind, rname, rprefix, rprefix_bare = _SITE_RECV_OTHER, "", "", False
436
+
437
+ shape = CallShape(
438
+ fkind, sys.intern(fname), rkind, sys.intern(rname), sys.intern(rprefix),
439
+ rprefix_bare,
440
+ tuple(sys.intern(a.id) if isinstance(a, ast.Name) else None for a in call.args),
441
+ tuple((sys.intern(k.arg), sys.intern(k.value.id)
442
+ if isinstance(k.value, ast.Name) else None)
443
+ for k in call.keywords if k.arg),
444
+ )
445
+ pooled = pool.get(shape)
446
+ if pooled is None:
447
+ pool[shape] = shape
448
+ return shape
449
+ return pooled
450
+
451
+
452
+ def _deco_facts(decorator: ast.AST) -> DecoFacts:
453
+ is_call = isinstance(decorator, ast.Call)
454
+ label = _decorator_label(decorator)
455
+ bare = label if not is_call else None
456
+ kind, name, prefix, bare_inner = 2, "", "", False
457
+ if is_call and decorator.args:
458
+ argument = decorator.args[0]
459
+ if isinstance(argument, ast.Name):
460
+ kind, name = 0, argument.id
461
+ elif isinstance(argument, ast.Attribute):
462
+ kind, name = 1, argument.attr
463
+ prefix = _dotted_prefix(argument.value)
464
+ bare_inner = isinstance(argument.value, ast.Name)
465
+ return DecoFacts(label, is_call, bare, kind, sys.intern(name), sys.intern(prefix), bare_inner)
466
+
467
+
468
+ def _wrapper_shape(node: ast.FunctionDef | ast.AsyncFunctionDef) -> Optional[WrapperShape]:
469
+ """Precompute the decorator-wrapper result `_wrapper_sanitized_slots` used to walk for."""
470
+ wrapper = None
471
+ for stmt in node.body:
472
+ if isinstance(stmt, (ast.FunctionDef, ast.AsyncFunctionDef)):
473
+ wrapper = stmt
474
+ break
475
+ if wrapper is None:
476
+ return None
477
+ if wrapper.args.vararg or wrapper.args.kwarg or wrapper.args.kwonlyargs:
478
+ return WrapperShape(False, (), 0, ())
479
+ wrapper_params = tuple(sys.intern(a.arg) for a in wrapper.args.args)
480
+ wrapped_names = {a.arg for a in node.args.args}
481
+ forwarded = None
482
+ for inner in ast.walk(wrapper):
483
+ if (isinstance(inner, ast.Call) and isinstance(inner.func, ast.Name)
484
+ and inner.func.id in wrapped_names):
485
+ forwarded = inner
486
+ break
487
+ if forwarded is None or forwarded.keywords:
488
+ return WrapperShape(False, (), 0, ())
489
+ fargs = tuple(
490
+ (tuple(sorted(sys.intern(name) for name in _name_uses(argument))),
491
+ isinstance(argument, ast.Call),
492
+ sys.intern(_callee_tail(argument.func)) if isinstance(argument, ast.Call) else "")
493
+ for argument in forwarded.args
494
+ )
495
+ return WrapperShape(True, wrapper_params, len(forwarded.args), fargs)
496
+
497
+
498
+ def _harvest_module(mod_name: str, tree: ast.AST,
499
+ summaries: List[FunctionSummary],
500
+ pool: Dict[CallShape, CallShape]) -> ModuleFacts:
501
+ """One walk of a freshly parsed module -> its symbol-table row; the tree is dropped after."""
502
+ by_qual = {summary.qualname: summary for summary in summaries}
503
+ sink_lines = {edge.lineno for summary in summaries for edge in summary.param_sinks}
504
+
505
+ funcs: Dict[str, FuncFacts] = {}
506
+ for node, qual in _contracted_functions(tree):
507
+ summary = by_qual.get(qual)
508
+ if summary is None:
509
+ continue
510
+ calls = [
511
+ (getattr(call, "lineno", 0), _call_shape(call, pool))
512
+ for call in ast.walk(node) if isinstance(call, ast.Call)
513
+ ]
514
+ recv = []
515
+ for inner in _ordered_nodes(node, skip_scopes=True):
516
+ if (isinstance(inner, ast.Assign) and isinstance(inner.value, ast.Call)
517
+ and isinstance(inner.value.func, ast.Name)):
518
+ targets = tuple(sys.intern(t.id) for t in inner.targets
519
+ if isinstance(t, ast.Name))
520
+ if targets:
521
+ recv.append((targets, sys.intern(inner.value.func.id)))
522
+ funcs[qual] = FuncFacts(
523
+ qual, summary, tuple(recv), tuple(calls),
524
+ tuple(_deco_facts(d) for d in node.decorator_list),
525
+ _wrapper_shape(node),
526
+ )
527
+
528
+ bases: Dict[str, tuple] = {}
529
+ signals: List[str] = []
530
+ assign_callees: Set[str] = set()
531
+ sink_desc: Dict[int, list] = {}
532
+ for inner in ast.walk(tree):
533
+ if isinstance(inner, ast.Assign) and isinstance(inner.value, ast.Call):
534
+ tail = _callee_tail(inner.value.func)
535
+ if tail:
536
+ assign_callees.add(tail)
537
+ if isinstance(inner, ast.Call):
538
+ lineno = getattr(inner, "lineno", 0)
539
+ if lineno in sink_lines:
540
+ descriptor = _func_descriptor(inner.func)
541
+ if descriptor is not None:
542
+ entry = sink_desc.get(lineno)
543
+ if entry is None:
544
+ sink_desc[lineno] = [descriptor, {}]
545
+ else:
546
+ tail = _callee_tail(inner.func)
547
+ if tail and tail not in entry[1]:
548
+ entry[1][tail] = descriptor
549
+ for stmt in tree.body:
550
+ if isinstance(stmt, ast.ClassDef):
551
+ named = []
552
+ for base in stmt.bases:
553
+ if isinstance(base, ast.Name):
554
+ named.append((True, sys.intern(base.id)))
555
+ elif isinstance(base, ast.Attribute):
556
+ named.append((True, sys.intern(base.attr)))
557
+ else:
558
+ named.append((False, ""))
559
+ bases[stmt.name] = tuple(named)
560
+ elif isinstance(stmt, ast.Assign) and _is_signal_factory(stmt.value):
561
+ for target in stmt.targets:
562
+ if isinstance(target, ast.Name):
563
+ signals.append(target.id)
564
+
565
+ return ModuleFacts(
566
+ funcs,
567
+ bases,
568
+ tuple(signals),
569
+ {lineno: (entry[0], dict(entry[1])) for lineno, entry in sink_desc.items()},
570
+ frozenset(assign_callees),
571
+ )
572
+
573
+
574
+ @dataclass(slots=True)
575
+ class TraceHop:
576
+ """One labelled node in an exploit path: role is SOURCE, ROUTE or SINK."""
577
+ role: str
578
+ file_path: str
579
+ lineno: int
580
+ label: str
581
+
582
+
583
+ @dataclass(slots=True)
584
+ class CrossFileFinding:
585
+ cwe: str
586
+ caller_file: str
587
+ caller_lineno: int
588
+ caller_func: str
589
+ callee_file: str
590
+ callee_func: str
591
+ callee_sink_name: str
592
+ callee_sink_lineno: int
593
+ tainted_param: str
594
+ flow_trace: List[TraceHop] = field(default_factory=list)
595
+
596
+
597
+ class CrossFileTaintEngine:
598
+ """Pass 2: Traces data flow across modules using precomputed contracts.
599
+
600
+ The engine no longer keeps the parsed trees: `GlobalSymbolIndex` is built in streaming mode
601
+ (each module is indexed, summarised and harvested, then its tree is released), and every
602
+ cross-module decision runs on the compact `ModuleFacts` table. Only two phases re-read source:
603
+ the caller analysis, for the small set of modules whose facts show a call into a sink-bearing
604
+ contract, and the sanitizer audit, for the modules whose assignments can reach a sanitizer.
605
+ """
606
+
607
+ def __init__(self, root_dir: str | Path,
608
+ reuse_trees: Optional[dict] = None):
609
+ self.root_dir = Path(root_dir).resolve()
610
+ # Scanner-parsed (source, tree) snapshots keyed by resolved absolute path string;
611
+ # the indexer re-verifies each against disk before reuse (see GlobalSymbolIndex.build).
612
+ self.reuse_trees = reuse_trees
613
+ self.indexer = GlobalSymbolIndex(self.root_dir)
614
+ self.summarizer: Optional[FunctionSummarizer] = None
615
+ self.contracts: dict[tuple[str, str], FunctionSummary] = {}
616
+ # Per-module compact symbol table: signatures, call sites, receivers, decorators, bases.
617
+ self.module_facts: dict[str, ModuleFacts] = {}
618
+ self.findings: list[CrossFileFinding] = []
619
+ # ParamSinkEdge carries no file field, so transitively lifted edges record the
620
+ # module that actually owns the sink here: (mod, qualname, param_idx, sink, lineno) -> path.
621
+ self.sink_origins: dict[tuple[str, str, int, str, int], str] = {}
622
+ # Forwarding call sites between the caller and the ultimate sink, outermost first:
623
+ # (mod, qualname, param_idx, sink, lineno) -> [(file, lineno, callee label), ...].
624
+ self.sink_route: dict[tuple[str, str, int, str, int], List[tuple[str, int, str]]] = {}
625
+ # Cached per-callee decorator analysis: (mod, qualname) -> sanitised parameter indices.
626
+ self._decorator_slots: dict[tuple[str, str], Set[int]] = {}
627
+ # Event-bus catalog: (defining module, symbol) pairs for signals, their subscribers,
628
+ # and Celery-style task functions reachable only through a dispatch method.
629
+ self.signal_definitions: Set[tuple[str, str]] = set()
630
+ self.signal_subscribers: dict[tuple[str, str], List[tuple[str, str]]] = {}
631
+ self.task_definitions: Set[tuple[str, str]] = set()
632
+ # Observational only (Phase-1 instrumentation): rounds actually executed by the
633
+ # fixed-point loop below; never read by a decision.
634
+ self._propagation_rounds = 0
635
+ # Raw file path spelling -> owning module (None when the file is outside the indexed
636
+ # tree). `file_to_module` is filled by indexer.build() and never mutated again, so one
637
+ # path string always answers the same module; `Path.resolve()` is an OS call that would
638
+ # otherwise repeat per call site. Negative hits are cached for the same reason.
639
+ self._path_to_module_memo: dict[str, Optional[str]] = {}
640
+ # Call-shape pool: identical call spellings share one CallShape object.
641
+ self._shape_pool: Dict[CallShape, CallShape] = {}
642
+ # Observational counters for the PROFILE line.
643
+ self._summary_seconds = 0.0
644
+ self._caller_modules = 0
645
+ self._sanitizer_modules = 0
646
+ self._sanitizer_sites_cache: Optional[frozenset] = None
647
+ self._sanitizer_tails: Optional[frozenset] = None
648
+ self._sanitizer_aliases: dict[str, frozenset] = {}
649
+
650
+ def run(self) -> list[CrossFileFinding]:
651
+ # Phase-1 instrumentation: disjoint stage clocks over the existing sequence.
652
+ # Nothing here changes an algorithm, an iteration order, or a finding.
653
+ _t0 = time.perf_counter()
654
+ # 1. Build Index & Contracts. The indexer streams: it registers every module first (so
655
+ # symbol resolution already sees the whole project), then parses one file at a time,
656
+ # hands the tree to the callback below, and releases it before reading the next.
657
+ self.summarizer = FunctionSummarizer(self.indexer)
658
+ self.indexer.build(reuse_trees=self.reuse_trees, on_indexed=self._on_module_indexed)
659
+ self.contracts = self.summarizer.summaries
660
+ _t1 = time.perf_counter()
661
+ self._propagate_transitive_sink_contracts()
662
+ _t2 = time.perf_counter()
663
+ self._build_event_catalog()
664
+ _t3 = time.perf_counter()
665
+
666
+ # 2. Analyze Callers. Only modules whose facts contain a call into a sink-bearing
667
+ # contract (or a dispatch into a sink-bearing handler) can emit a finding, so only they
668
+ # are re-read and run through the unchanged AST analysis.
669
+ for mod_name, facts in self.module_facts.items():
670
+ if not self._module_emits(mod_name, facts):
671
+ continue
672
+ mod_idx = self.indexer.modules.get(mod_name)
673
+ if mod_idx is None:
674
+ continue
675
+ tree = self._tree_for(mod_name)
676
+ if tree is None:
677
+ continue
678
+ self._analyze_module_calls(mod_name, mod_idx.file_path, tree)
679
+ self._caller_modules += 1
680
+ del tree
681
+ _t4 = time.perf_counter()
682
+
683
+ from symbol_indexer import resolver_stats_line
684
+ print(f"TimeCodeSecurity [PROFILE] CrossEngine: IndexBuild={_t1 - _t0:.2f}s "
685
+ f"Summaries={self._summary_seconds:.2f}s Propagate={_t2 - _t1:.2f}s "
686
+ f"(rounds={self._propagation_rounds}) EventCatalog={_t3 - _t2:.2f}s "
687
+ f"CallerAnalysis={_t4 - _t3:.2f}s (modules={self._caller_modules}) "
688
+ f"TOTAL={_t4 - _t0:.2f}s "
689
+ f"modules={len(self.indexer.modules)} contracts={len(self.contracts)} "
690
+ f"facts={len(self.module_facts)} findings={len(self.findings)} "
691
+ f"| {resolver_stats_line()}",
692
+ file=sys.stderr)
693
+ return self.findings
694
+
695
+ def _on_module_indexed(self, mod_name: str, file_path: Path, tree: ast.AST) -> None:
696
+ """Streaming hook: summarise one module, harvest its facts, and let the tree go."""
697
+ started = time.perf_counter()
698
+ summaries = self.summarizer.summarize_module(mod_name, file_path, tree)
699
+ self._summary_seconds += time.perf_counter() - started
700
+ self.module_facts[mod_name] = _harvest_module(
701
+ mod_name, tree, summaries, self._shape_pool)
702
+
703
+ def _tree_for(self, mod_name: str) -> Optional[ast.AST]:
704
+ """Re-read one module's tree on demand; the scanner's snapshot is reused when it matches."""
705
+ path = self.indexer.module_to_file.get(mod_name)
706
+ if path is None:
707
+ return None
708
+ path_str = str(path)
709
+ try:
710
+ source = Path(path_str).read_text(encoding="utf-8", errors="replace")
711
+ except Exception:
712
+ return None
713
+ cached = self.reuse_trees.get(path_str) if self.reuse_trees else None
714
+ if cached is not None and cached[1] is not None and cached[0] == source:
715
+ return cached[1]
716
+ return _parse_source(path_str, source)
717
+
718
+ # ─── Framework event bus: Django signals and Celery tasks ───
719
+ def _build_event_catalog(self) -> None:
720
+ """Index signal objects, their @receiver handlers, and @shared_task / @app.task workers.
721
+
722
+ A producer never names these functions, it only calls `.send(...)` or `.delay(...)` on a
723
+ handle, so without this catalog the call graph has no edge into the handler and the sinks
724
+ behind it stay invisible across modules.
725
+ """
726
+ for mod_name, facts in self.module_facts.items():
727
+ for name in facts.signals:
728
+ self.signal_definitions.add((mod_name, name))
729
+ for qual, func in facts.funcs.items():
730
+ for decorator in func.decos:
731
+ if decorator.label is None:
732
+ continue
733
+ if (decorator.label in SIGNAL_SUBSCRIBE_DECORATORS
734
+ and decorator.is_call and decorator.arg0kind != 2):
735
+ signal_ref = self._resolve_reference_fact(
736
+ mod_name, decorator.arg0kind, decorator.arg0name,
737
+ decorator.arg0prefix, decorator.arg0bare)
738
+ if signal_ref is not None:
739
+ self.signal_definitions.add(signal_ref)
740
+ self.signal_subscribers.setdefault(signal_ref, []).append(
741
+ (mod_name, qual))
742
+ elif decorator.label in TASK_DECORATOR_NAMES:
743
+ self.task_definitions.add((mod_name, qual))
744
+
745
+ def _resolve_name_reference(self, mod_name: str, name: str) -> tuple[str, str]:
746
+ """(defining module, symbol) a bare reference spelling points at."""
747
+ mod_idx = self.indexer.modules.get(mod_name)
748
+ binding = mod_idx.imports.get(name) if mod_idx else None
749
+ if binding is not None:
750
+ target_mod = self.indexer._match_registered_module(binding.source_module)
751
+ if target_mod:
752
+ return (target_mod, binding.imported_name or name)
753
+ return (mod_name, name)
754
+
755
+ def _resolve_attr_reference(self, base: str, attr: str) -> tuple[str, str]:
756
+ """(defining module, symbol) a dotted reference spelling points at."""
757
+ return (self.indexer._match_registered_module(base) or base, attr)
758
+
759
+ def _resolve_reference_fact(
760
+ self,
761
+ mod_name: str,
762
+ kind: int,
763
+ name: str,
764
+ prefix: str,
765
+ prefix_bare: bool,
766
+ ) -> Optional[tuple[str, str]]:
767
+ """Fact spelling of `_resolve_reference` for a name/attribute expression."""
768
+ if kind == 0:
769
+ return self._resolve_name_reference(mod_name, name)
770
+ if kind == 1:
771
+ if prefix_bare and prefix in ("self", "cls"):
772
+ return None
773
+ if not prefix:
774
+ return None
775
+ return self._resolve_attr_reference(prefix, name)
776
+ return None
777
+
778
+ def _resolve_reference(self, mod_name: str, expr: ast.AST) -> Optional[tuple[str, str]]:
779
+ """(defining module, symbol) a receiver or decorator argument points at."""
780
+ if isinstance(expr, ast.Name):
781
+ return self._resolve_name_reference(mod_name, expr.id)
782
+ if isinstance(expr, ast.Attribute):
783
+ if isinstance(expr.value, ast.Name) and expr.value.id in ("self", "cls"):
784
+ return None
785
+ base = _dotted_prefix(expr.value)
786
+ if not base:
787
+ return None
788
+ return self._resolve_attr_reference(base, expr.attr)
789
+ return None
790
+
791
+ def _resolve_event_emission(
792
+ self,
793
+ caller_mod: str,
794
+ call: ast.Call,
795
+ ) -> List[tuple[str, FunctionSummary, ast.Call]]:
796
+ """Callee contracts hidden behind `signal.send(...)`, `signal.send_robust(...)` and
797
+ `task.delay(...)` / `task.apply_async(...)`, resolved through the event catalog.
798
+
799
+ Each entry also carries the call view to bind the contract against, because Celery's
800
+ `apply_async` hands the payload over in `args=` / `kwargs=` envelopes instead of in
801
+ its own signature.
802
+ """
803
+ if not isinstance(call.func, ast.Attribute):
804
+ return []
805
+ attr = call.func.attr
806
+ if attr in SIGNAL_EMISSION_METHODS:
807
+ ref = self._resolve_reference(caller_mod, call.func.value)
808
+ targets = self.signal_subscribers.get(ref, []) if ref else []
809
+ elif attr in TASK_DISPATCH_METHODS:
810
+ ref = self._resolve_reference(caller_mod, call.func.value)
811
+ targets = [ref] if ref and ref in self.task_definitions else []
812
+ else:
813
+ return []
814
+ dispatch_call = self._dispatch_call(attr, call)
815
+ resolved = []
816
+ for target in targets:
817
+ summary = self.contracts.get(target)
818
+ if summary is not None:
819
+ resolved.append((target[0], summary, dispatch_call))
820
+ return resolved
821
+
822
+ @staticmethod
823
+ def _dispatch_call(attr: str, call: ast.Call) -> ast.Call:
824
+ """Flatten `task.apply_async(args=[...], kwargs={...})` into the call it dispatches."""
825
+ if attr != "apply_async":
826
+ return call
827
+ args: List[ast.expr] = []
828
+ keywords: List[ast.keyword] = []
829
+ for kw in call.keywords:
830
+ if kw.arg == "args" and isinstance(kw.value, (ast.List, ast.Tuple)):
831
+ args.extend(kw.value.elts)
832
+ elif kw.arg == "kwargs" and isinstance(kw.value, ast.Dict):
833
+ for key, value in zip(kw.value.keys, kw.value.values):
834
+ if isinstance(key, ast.Constant) and isinstance(key.value, str):
835
+ keywords.append(ast.keyword(arg=key.value, value=value))
836
+ if not args and not keywords:
837
+ return call
838
+ dispatch = ast.Call(func=call.func, args=args, keywords=keywords)
839
+ for field_name in ("lineno", "end_lineno", "col_offset", "end_col_offset"):
840
+ setattr(dispatch, field_name, getattr(call, field_name, None))
841
+ return dispatch
842
+
843
+ def _propagate_transitive_sink_contracts(self) -> None:
844
+ """Fixed-point lift of callee sink contracts into pass-through callers.
845
+
846
+ A function that forwards one of its own parameters straight into a callee argument
847
+ inherits that callee's sink obligations, so a 3-layer chain (controller -> service
848
+ -> repo) becomes visible from the outermost call site. Only direct parameter
849
+ forwarding propagates, which keeps the lift alias-free and terminating.
850
+ """
851
+ while True:
852
+ self._propagation_rounds += 1
853
+ changed = False
854
+ for mod_name, facts in self.module_facts.items():
855
+ for qual, func in facts.funcs.items():
856
+ summary = func.summary
857
+ if not summary.params:
858
+ continue
859
+ if self._lift_callee_sinks(mod_name, summary, func):
860
+ changed = True
861
+ if not changed:
862
+ return
863
+
864
+ def _lift_callee_sinks(
865
+ self,
866
+ caller_mod: str,
867
+ summary: FunctionSummary,
868
+ func: FuncFacts,
869
+ ) -> bool:
870
+ param_index = {name: idx for idx, name in enumerate(summary.params)}
871
+ known = {
872
+ (edge.param_idx, edge.sink_cwe, edge.sink_name, edge.lineno)
873
+ for edge in summary.param_sinks
874
+ }
875
+ added = False
876
+ receivers = self._fact_receivers(caller_mod, summary.qualname, func)
877
+
878
+ for call_lineno, call in func.calls:
879
+ resolved = self._resolve_site_contract(caller_mod, call, receivers)
880
+ if resolved is None:
881
+ continue
882
+ callee_mod, callee_summary = resolved
883
+ if not callee_summary.param_sinks:
884
+ continue
885
+ # A slot the callee's decorator sanitises carries no sink obligation, so it must
886
+ # not lift either; otherwise the same leak would reappear one layer further out.
887
+ neutralized = self._decorator_sanitized_params(callee_mod, callee_summary)
888
+
889
+ for arg_idx, arg_name in sorted(
890
+ self._bind_site_args(
891
+ call,
892
+ callee_summary.params,
893
+ self._receiver_offset_site(caller_mod, call, callee_summary, receivers),
894
+ ).items()
895
+ ):
896
+ if arg_idx in neutralized:
897
+ continue
898
+ # Only a bare name forwards a parameter; the AST walk this replaces tested
899
+ # isinstance(arg, ast.Name) for exactly the same reason.
900
+ if arg_name is None:
901
+ continue
902
+ caller_param_idx = param_index.get(arg_name)
903
+ if caller_param_idx is None:
904
+ continue
905
+
906
+ for edge in callee_summary.param_sinks:
907
+ if edge.param_idx != arg_idx:
908
+ continue
909
+ key = (caller_param_idx, edge.sink_cwe, edge.sink_name, edge.lineno)
910
+ if key in known:
911
+ continue
912
+ known.add(key)
913
+ summary.param_sinks.append(ParamSinkEdge(
914
+ param_idx=caller_param_idx,
915
+ param_name=summary.params[caller_param_idx],
916
+ sink_cwe=edge.sink_cwe,
917
+ sink_name=edge.sink_name,
918
+ lineno=edge.lineno,
919
+ ))
920
+ origin_key = (callee_mod, callee_summary.qualname,
921
+ edge.param_idx, edge.sink_name, edge.lineno)
922
+ lifted_key = (caller_mod, summary.qualname, caller_param_idx,
923
+ edge.sink_name, edge.lineno)
924
+ self.sink_origins[lifted_key] = self.sink_origins.get(
925
+ origin_key, callee_summary.file_path
926
+ )
927
+ self.sink_route[lifted_key] = [
928
+ (summary.file_path, call_lineno,
929
+ f"{caller_mod}.{summary.qualname}")
930
+ ] + self.sink_route.get(origin_key, [])
931
+ added = True
932
+
933
+ return added
934
+
935
+ def _fact_receivers(
936
+ self,
937
+ caller_mod: str,
938
+ caller_func: str,
939
+ func: FuncFacts,
940
+ ) -> Dict[str, tuple[str, str]]:
941
+ """`_instance_bindings` over harvested facts: own-scope `var = ClassName(...)` bindings."""
942
+ bindings: Dict[str, tuple[str, str]] = {}
943
+ if "." in caller_func:
944
+ owning_class = (caller_func.split(".", 1)[0], caller_mod)
945
+ bindings["self"] = owning_class
946
+ bindings["cls"] = owning_class
947
+ for targets, ctor in func.recv:
948
+ class_ref = self._class_of_name(ctor, caller_mod)
949
+ if class_ref is None:
950
+ continue
951
+ for target in targets:
952
+ bindings[target] = class_ref
953
+ return bindings
954
+
955
+ def _resolve_site_contract(
956
+ self,
957
+ caller_mod: str,
958
+ site: CallShape,
959
+ receivers: Optional[Dict[str, tuple[str, str]]] = None,
960
+ ) -> Optional[tuple[str, FunctionSummary]]:
961
+ """Fact spelling of `_resolve_call_contract` for one harvested call site."""
962
+ if site.fkind == _SITE_FUNC_NAME:
963
+ call_name = site.fname
964
+ elif site.fkind == _SITE_FUNC_ATTR:
965
+ resolved_method = self._resolve_site_method(site, caller_mod, receivers)
966
+ if resolved_method is not None:
967
+ return resolved_method
968
+ resolved_module = self._resolve_site_module_attribute(site, caller_mod)
969
+ if resolved_module is not None:
970
+ return resolved_module
971
+ call_name = site.fname
972
+ else:
973
+ return None
974
+
975
+ symbol_def = self.indexer.resolve_symbol(caller_mod, call_name)
976
+ if not symbol_def:
977
+ return None
978
+
979
+ callee_mod = self._resolve_file_module(symbol_def.file_path)
980
+ if not callee_mod:
981
+ return None
982
+
983
+ summary = self.contracts.get((callee_mod, symbol_def.name))
984
+ if summary is None:
985
+ return None
986
+ return callee_mod, summary
987
+
988
+ def _resolve_site_method(
989
+ self,
990
+ site: CallShape,
991
+ caller_mod: str,
992
+ receivers: Optional[Dict[str, tuple[str, str]]],
993
+ ) -> Optional[tuple[str, FunctionSummary]]:
994
+ class_ref: Optional[tuple[str, str]] = None
995
+ if site.rkind == _SITE_RECV_NAME:
996
+ class_ref = ((receivers or {}).get(site.rname)
997
+ or self._class_of_name(site.rname, caller_mod))
998
+ elif site.rkind == _SITE_RECV_CTOR:
999
+ class_ref = self._class_of_name(site.rname, caller_mod)
1000
+ if class_ref is None:
1001
+ return None
1002
+ return self._resolve_inherited_method(class_ref, site.fname)
1003
+
1004
+ def _resolve_site_module_attribute(
1005
+ self,
1006
+ site: CallShape,
1007
+ caller_mod: str,
1008
+ ) -> Optional[tuple[str, FunctionSummary]]:
1009
+ if site.rkind != _SITE_RECV_NAME:
1010
+ return None
1011
+ target_mod = self._imported_module_of(site.rname, caller_mod)
1012
+ if target_mod is None:
1013
+ return None
1014
+ summary = self.contracts.get((target_mod, site.fname))
1015
+ return None if summary is None else (target_mod, summary)
1016
+
1017
+ def _bind_site_args(
1018
+ self,
1019
+ site: CallShape,
1020
+ param_names: List[str],
1021
+ arg_offset: int = 0,
1022
+ ) -> Dict[int, Optional[str]]:
1023
+ """`_bind_call_args` over facts: parameter index -> bare argument name (None otherwise)."""
1024
+ bound: Dict[int, Optional[str]] = {}
1025
+ for idx, name in enumerate(site.argn):
1026
+ param_idx = idx - arg_offset
1027
+ if 0 <= param_idx < len(param_names):
1028
+ bound[param_idx] = name
1029
+ param_to_idx = {name: idx for idx, name in enumerate(param_names)}
1030
+ for keyword, name in site.kwn:
1031
+ if keyword in param_to_idx:
1032
+ bound[param_to_idx[keyword]] = name
1033
+ else:
1034
+ slot = self._kwarg_slot_index(param_names, keyword)
1035
+ if slot is not None:
1036
+ bound[slot] = name
1037
+ return bound
1038
+
1039
+ def _receiver_offset_site(
1040
+ self,
1041
+ caller_mod: str,
1042
+ site: CallShape,
1043
+ summary: FunctionSummary,
1044
+ receivers: Optional[Dict[str, tuple[str, str]]] = None,
1045
+ ) -> int:
1046
+ """`_receiver_offset` over facts: 1 for an unbound `Class.method(receiver, ...)` call."""
1047
+ if not summary.takes_receiver or site.fkind != _SITE_FUNC_ATTR:
1048
+ return 0
1049
+ if site.rkind != _SITE_RECV_NAME:
1050
+ return 0
1051
+ if receivers and site.rname in receivers:
1052
+ return 0
1053
+ class_ref = self._class_of_name(site.rname, caller_mod)
1054
+ if class_ref is None:
1055
+ return 0
1056
+ resolved = self._resolve_inherited_method(class_ref, site.fname)
1057
+ return 1 if resolved is not None and resolved[1] is summary else 0
1058
+
1059
+ def _module_emits(self, mod_name: str, facts: ModuleFacts) -> bool:
1060
+ """Could any call in this module reach a sink-bearing contract?
1061
+
1062
+ Deliberately an over-approximation: every shape that can emit a finding resolves to a
1063
+ contract with a `param_sinks` edge, so answering no here proves the AST analysis has
1064
+ nothing to add. Answering yes only costs one re-parse.
1065
+ """
1066
+ for qual, func in facts.funcs.items():
1067
+ receivers = self._fact_receivers(mod_name, qual, func)
1068
+ for _lineno, site in func.calls:
1069
+ resolved = self._resolve_site_contract(mod_name, site, receivers)
1070
+ if resolved is not None and resolved[1].param_sinks:
1071
+ return True
1072
+ if site.fkind != _SITE_FUNC_ATTR or site.fname not in _DISPATCH_ATTRS:
1073
+ continue
1074
+ ref = self._resolve_reference_fact(
1075
+ mod_name, site.rkind, site.rname, site.rprefix, site.rprefix_bare)
1076
+ if ref is None:
1077
+ continue
1078
+ if site.fname in SIGNAL_EMISSION_METHODS:
1079
+ targets = self.signal_subscribers.get(ref, ())
1080
+ else:
1081
+ targets = (ref,) if ref in self.task_definitions else ()
1082
+ for target in targets:
1083
+ summary = self.contracts.get(target)
1084
+ if summary is not None and summary.param_sinks:
1085
+ return True
1086
+ return False
1087
+
1088
+ def sanitized_sink_locations(self) -> Set[tuple[str, int]]:
1089
+ """Call sites whose locally-assigned arguments were all neutralized by a
1090
+ cross-file sanitizer contract.
1091
+
1092
+ Single-file scanners cannot see the callee contract, so they report these sites
1093
+ as injectable. The returned keys are (resolved file path, call lineno).
1094
+ """
1095
+ _t_s0 = time.perf_counter()
1096
+ try:
1097
+ if self._sanitizer_sites_cache is not None:
1098
+ return set(self._sanitizer_sites_cache)
1099
+ suppressed: Set[tuple[str, int]] = set()
1100
+ if not any(summary.is_sanitizer for summary in self.contracts.values()):
1101
+ print(f"TimeCodeSecurity [PROFILE] CrossSanitizers: scan={time.perf_counter() - _t_s0:.2f}s "
1102
+ f"(no sanitizer contracts; 0 trees walked) sites=0", file=sys.stderr)
1103
+ return suppressed
1104
+
1105
+ # A site needs an assignment whose right-hand side resolves to a sanitizer, so a
1106
+ # module whose assignment spellings share no name with any sanitizer contract
1107
+ # cannot contribute one. The spelling test is a superset of every resolution path
1108
+ # (direct name, import alias, module attribute, method tail), which is what keeps
1109
+ # this selection from ever skipping a module that could suppress a finding.
1110
+ selected = [
1111
+ mod_name for mod_name, facts in self.module_facts.items()
1112
+ if facts.assign_callees and self._may_hold_sanitizer_site(mod_name, facts)
1113
+ ]
1114
+ for mod_name in selected:
1115
+ mod_idx = self.indexer.modules.get(mod_name)
1116
+ if mod_idx is None:
1117
+ continue
1118
+ tree = self._tree_for(mod_name)
1119
+ if tree is None:
1120
+ continue
1121
+ file_key = str(Path(mod_idx.file_path).resolve())
1122
+ qualnames = {id(node): name for node, name in _contracted_functions(tree)}
1123
+ for node in _function_defs(tree):
1124
+ suppressed.update(
1125
+ self._sanitized_sites(
1126
+ mod_name, file_key, node, qualnames.get(id(node), node.name)
1127
+ )
1128
+ )
1129
+ self._sanitizer_modules += 1
1130
+ del tree
1131
+ self._sanitizer_sites_cache = frozenset(suppressed)
1132
+ print(f"TimeCodeSecurity [PROFILE] CrossSanitizers: "
1133
+ f"scan={time.perf_counter() - _t_s0:.2f}s "
1134
+ f"(trees_walked={self._sanitizer_modules}/{len(self.indexer.modules)}) "
1135
+ f"sites={len(suppressed)}", file=sys.stderr)
1136
+ return suppressed
1137
+ finally:
1138
+ # This pass is the last consumer of the path memo: run() returns before the caller
1139
+ # (cli.py) asks for sanitizer sites, so the cache is released here instead of at the
1140
+ # end of run() - releasing it earlier would make this phase re-issue every OS path
1141
+ # lookup it has just been handed the answer to.
1142
+ self._path_to_module_memo.clear()
1143
+
1144
+ def _sanitizer_tail_set(self) -> frozenset:
1145
+ if self._sanitizer_tails is None:
1146
+ self._sanitizer_tails = frozenset(
1147
+ qual.rsplit(".", 1)[-1]
1148
+ for (_mod, qual), summary in self.contracts.items()
1149
+ if summary.is_sanitizer
1150
+ )
1151
+ return self._sanitizer_tails
1152
+
1153
+ def _module_sanitizer_aliases(self, mod_name: str) -> frozenset:
1154
+ cached = self._sanitizer_aliases.get(mod_name)
1155
+ if cached is not None:
1156
+ return cached
1157
+ found = set()
1158
+ mod_idx = self.indexer.modules.get(mod_name)
1159
+ if mod_idx is not None:
1160
+ for local_name, binding in mod_idx.imports.items():
1161
+ target_mod = self.indexer._match_registered_module(binding.source_module)
1162
+ if not target_mod:
1163
+ continue
1164
+ imported = binding.imported_name or local_name
1165
+ summary = self.contracts.get((target_mod, imported))
1166
+ if summary is not None and summary.is_sanitizer:
1167
+ found.add(local_name)
1168
+ result = frozenset(found)
1169
+ self._sanitizer_aliases[mod_name] = result
1170
+ return result
1171
+
1172
+ def _may_hold_sanitizer_site(self, mod_name: str, facts: ModuleFacts) -> bool:
1173
+ spellings = self._sanitizer_tail_set() | self._module_sanitizer_aliases(mod_name)
1174
+ return bool(facts.assign_callees & spellings)
1175
+
1176
+ def _sanitized_sites(
1177
+ self,
1178
+ mod_name: str,
1179
+ file_key: str,
1180
+ func_node: ast.AST,
1181
+ caller_func: str,
1182
+ ) -> Set[tuple[str, int]]:
1183
+ sites: Set[tuple[str, int]] = set()
1184
+ if not _has_assign_statement(func_node):
1185
+ # `assigned` is only ever filled by an ast.Assign below, and a site needs a non-empty
1186
+ # `relevant` drawn from it, so a body without one has nothing to contribute. The
1187
+ # receiver map is skipped with it: the Assign branch is its only reader here.
1188
+ return sites
1189
+ assigned: Set[str] = set()
1190
+ sanitized: Set[str] = set()
1191
+ # One walk of the body for both loops instead of the two the same nodes used to pay.
1192
+ own_assigns, productive = _record_productive(func_node)
1193
+ receivers = self._instance_bindings(mod_name, caller_func, func_node, own_assigns=own_assigns)
1194
+
1195
+ for node in productive:
1196
+ if isinstance(node, ast.Assign):
1197
+ summary = self._resolve_call_summary(mod_name, node.value, receivers)
1198
+ neutralized = bool(summary and summary.is_sanitizer)
1199
+ for target in node.targets:
1200
+ if isinstance(target, ast.Name):
1201
+ assigned.add(target.id)
1202
+ if neutralized:
1203
+ sanitized.add(target.id)
1204
+ else:
1205
+ sanitized.discard(target.id)
1206
+
1207
+ elif isinstance(node, ast.Call):
1208
+ relevant = {
1209
+ n.id
1210
+ for n in ast.walk(node)
1211
+ if isinstance(n, ast.Name) and isinstance(n.ctx, ast.Load) and n.id in assigned
1212
+ }
1213
+ if relevant and relevant <= sanitized:
1214
+ sites.add((file_key, node.lineno))
1215
+
1216
+ return sites
1217
+
1218
+ def _analyze_module_calls(self, mod_name: str, file_path: Path, tree: ast.AST) -> None:
1219
+ for stmt in tree.body:
1220
+ if isinstance(stmt, (ast.FunctionDef, ast.AsyncFunctionDef)):
1221
+ self._analyze_function_body(mod_name, str(file_path), stmt.name, stmt)
1222
+ elif isinstance(stmt, ast.ClassDef):
1223
+ for item in stmt.body:
1224
+ if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
1225
+ self._analyze_function_body(mod_name, str(file_path), f"{stmt.name}.{item.name}", item)
1226
+
1227
+ def _analyze_function_body(
1228
+ self,
1229
+ caller_mod: str,
1230
+ caller_file: str,
1231
+ caller_func_name: str,
1232
+ func_node: ast.FunctionDef | ast.AsyncFunctionDef,
1233
+ ) -> None:
1234
+ # Step A: Identify tainted variables inside caller function
1235
+ tainted_vars: set[str] = set()
1236
+
1237
+ # Check function parameters (e.g. 'request')
1238
+ for arg in func_node.args.args:
1239
+ if arg.arg in ("request", "req"):
1240
+ tainted_vars.add(arg.arg)
1241
+
1242
+ receivers = self._instance_bindings(caller_mod, caller_func_name, func_node)
1243
+ for stmt in func_node.body:
1244
+ if isinstance(stmt, ast.Assign):
1245
+ rhs_repr = ast.unparse(stmt.value) if hasattr(ast, "unparse") else ""
1246
+ is_source = any(src in rhs_repr for src in TAINT_SOURCE_PATTERNS)
1247
+
1248
+ # Contract-aware propagation: a resolved callee summary is authoritative
1249
+ # for whether its return value carries the taint of an argument.
1250
+ summary = self._resolve_call_summary(caller_mod, stmt.value, receivers)
1251
+ if summary is not None:
1252
+ if summary.is_sanitizer:
1253
+ is_derived = False
1254
+ else:
1255
+ is_derived = self._returns_tainted_arg(
1256
+ stmt.value, summary.params, summary.tainted_returns, tainted_vars,
1257
+ self._receiver_offset(caller_mod, stmt.value, summary, receivers),
1258
+ )
1259
+ else:
1260
+ is_derived = any(t_var in rhs_repr for t_var in tainted_vars)
1261
+
1262
+ if is_source or is_derived:
1263
+ for target in stmt.targets:
1264
+ if isinstance(target, ast.Name):
1265
+ tainted_vars.add(target.id)
1266
+
1267
+ # Step B: Check external calls in this statement
1268
+ for call_node in [n for n in ast.walk(stmt) if isinstance(n, ast.Call)]:
1269
+ self._check_call_against_contracts(
1270
+ caller_mod,
1271
+ caller_file,
1272
+ caller_func_name,
1273
+ call_node,
1274
+ tainted_vars,
1275
+ receivers,
1276
+ )
1277
+ for callee_mod, summary, dispatch_call in self._resolve_event_emission(
1278
+ caller_mod, call_node
1279
+ ):
1280
+ self._emit_contract_findings(
1281
+ caller_mod,
1282
+ caller_file,
1283
+ caller_func_name,
1284
+ dispatch_call,
1285
+ callee_mod,
1286
+ summary,
1287
+ tainted_vars,
1288
+ receivers,
1289
+ )
1290
+
1291
+ def _bind_call_args(
1292
+ self,
1293
+ call: ast.Call,
1294
+ param_names: List[str],
1295
+ arg_offset: int = 0,
1296
+ ) -> Dict[int, ast.AST]:
1297
+ """Maps parameter index -> argument AST expression for both args and kwargs.
1298
+
1299
+ ``param_names`` comes from FunctionSummary.params, which drops the implicit
1300
+ ``self``/``cls`` receiver, so binding a normal method call needs no offset.
1301
+ ``arg_offset`` skips the leading positional argument of an unbound call; binding
1302
+ against SymbolDefinition.params (which keeps ``self``) would shift every
1303
+ parameter position by one instead.
1304
+ """
1305
+ bound: Dict[int, ast.AST] = {}
1306
+ # Positional
1307
+ for idx, arg in enumerate(call.args):
1308
+ param_idx = idx - arg_offset
1309
+ if 0 <= param_idx < len(param_names):
1310
+ bound[param_idx] = arg
1311
+ # Keywords
1312
+ param_to_idx = {name: idx for idx, name in enumerate(param_names)}
1313
+ for kw in call.keywords:
1314
+ if kw.arg and kw.arg in param_to_idx:
1315
+ bound[param_to_idx[kw.arg]] = kw.value
1316
+ elif kw.arg:
1317
+ slot = self._kwarg_slot_index(param_names, kw.arg)
1318
+ if slot is not None:
1319
+ bound[slot] = kw.value
1320
+ return bound
1321
+
1322
+ @staticmethod
1323
+ def _kwarg_slot_index(param_names: List[str], keyword: str) -> Optional[int]:
1324
+ """Contract slot for an incoming keyword that only a `**kwargs` parameter can receive.
1325
+
1326
+ The summariser names those slots `<container>[<key>]`, so a signal payload keyword
1327
+ `payload=` binds onto `kwargs[payload]` and nothing else.
1328
+ """
1329
+ suffix = f"[{keyword}]"
1330
+ for idx, name in enumerate(param_names):
1331
+ if name.endswith(suffix):
1332
+ return idx
1333
+ return None
1334
+
1335
+ def _receiver_offset(
1336
+ self,
1337
+ caller_mod: str,
1338
+ call: ast.Call,
1339
+ summary: FunctionSummary,
1340
+ receivers: Optional[Dict[str, tuple[str, str]]] = None,
1341
+ ) -> int:
1342
+ """1 when the callee is a method invoked unbound as `Class.method(receiver, ...)`.
1343
+
1344
+ Contract parameter indices exclude the bound receiver, so the leading positional
1345
+ argument of an unbound call is the instance and must be skipped.
1346
+ """
1347
+ if not summary.takes_receiver or not isinstance(call.func, ast.Attribute):
1348
+ return 0
1349
+ receiver = call.func.value
1350
+ if not isinstance(receiver, ast.Name):
1351
+ return 0
1352
+ # A name already bound to an instance marks a bound call site; only a spelling that
1353
+ # resolves to a class symbol can hand the receiver over as an explicit first argument.
1354
+ if receivers and receiver.id in receivers:
1355
+ return 0
1356
+ class_ref = self._class_of_name(receiver.id, caller_mod)
1357
+ if class_ref is None:
1358
+ return 0
1359
+ # The contract may be declared on a base class, so comparing the receiver spelling with
1360
+ # the declaring class name loses every inherited unbound call. Re-resolving the
1361
+ # attribute on the receiver class and requiring the very same contract object proves
1362
+ # the call goes through that class, whether the method is owned or inherited.
1363
+ resolved = self._resolve_inherited_method(class_ref, call.func.attr)
1364
+ return 1 if resolved is not None and resolved[1] is summary else 0
1365
+
1366
+ def _resolve_file_module(self, file_path) -> Optional[str]:
1367
+ """Owning module for a file path spelling, resolving the OS path at most once each.
1368
+
1369
+ `file_to_module` is keyed by Path objects and is written only by indexer.build(), so
1370
+ the answer for a given spelling never changes during a run. The key is normalised with
1371
+ str() because callers hold either a str or a Path for the same file; misses (None) are
1372
+ cached too, since unindexed third-party paths are the common case.
1373
+ """
1374
+ key = str(file_path)
1375
+ memo = self._path_to_module_memo
1376
+ if key in memo:
1377
+ return memo[key]
1378
+ mod_name = self.indexer.file_to_module.get(Path(key).resolve())
1379
+ memo[key] = mod_name
1380
+ return mod_name
1381
+
1382
+ def _resolve_call_contract(
1383
+ self,
1384
+ caller_mod: str,
1385
+ value: ast.expr,
1386
+ receivers: Optional[Dict[str, tuple[str, str]]] = None,
1387
+ ) -> Optional[tuple[str, FunctionSummary]]:
1388
+ """Return (callee module, contract) for a direct call expression, or None."""
1389
+ if not isinstance(value, ast.Call):
1390
+ return None
1391
+
1392
+ if isinstance(value.func, ast.Name):
1393
+ call_name = value.func.id
1394
+ elif isinstance(value.func, ast.Attribute):
1395
+ resolved_method = self._resolve_method_contract(value.func, caller_mod, receivers)
1396
+ if resolved_method is not None:
1397
+ return resolved_method
1398
+ resolved_module = self._resolve_module_attribute_contract(value.func, caller_mod)
1399
+ if resolved_module is not None:
1400
+ return resolved_module
1401
+ call_name = value.func.attr
1402
+ else:
1403
+ return None
1404
+
1405
+ symbol_def = self.indexer.resolve_symbol(caller_mod, call_name)
1406
+ if not symbol_def:
1407
+ return None
1408
+
1409
+ callee_mod = self._resolve_file_module(symbol_def.file_path)
1410
+ if not callee_mod:
1411
+ return None
1412
+
1413
+ summary = self.contracts.get((callee_mod, symbol_def.name))
1414
+ if summary is None:
1415
+ return None
1416
+ return callee_mod, summary
1417
+
1418
+ def _resolve_method_contract(
1419
+ self,
1420
+ func: ast.Attribute,
1421
+ caller_mod: str,
1422
+ receivers: Optional[Dict[str, tuple[str, str]]],
1423
+ ) -> Optional[tuple[str, FunctionSummary]]:
1424
+ """Resolve `receiver.method(...)` against the owning class's contract.
1425
+
1426
+ FunctionSummarizer indexes methods under the qualified name 'Class.method', which a
1427
+ call site never spells out, so the receiver's class must be recovered from the local
1428
+ bindings, an inline construction, or the named class itself (unbound call). Returns
1429
+ None when the receiver type is unknown, letting the caller fall back to bare names.
1430
+ """
1431
+ class_ref: Optional[tuple[str, str]] = None
1432
+ if isinstance(func.value, ast.Name):
1433
+ class_ref = (receivers or {}).get(func.value.id) or self._class_of_name(func.value.id, caller_mod)
1434
+ elif isinstance(func.value, ast.Call):
1435
+ class_ref = self._instantiated_class(func.value, caller_mod)
1436
+ if class_ref is None:
1437
+ return None
1438
+
1439
+ class_name, class_mod = class_ref
1440
+ return self._resolve_inherited_method((class_name, class_mod), func.attr)
1441
+
1442
+ def _resolve_inherited_method(
1443
+ self,
1444
+ class_ref: tuple[str, str],
1445
+ attr: str,
1446
+ ) -> Optional[tuple[str, FunctionSummary]]:
1447
+ """Find `attr`'s contract on the class or, failing that, on its base classes.
1448
+
1449
+ Contracts are keyed by the declaring class, so a call through a subclass instance
1450
+ never spells out the qualified name the base was indexed under. The search is
1451
+ breadth-first from the concrete class, which makes an override on the subclass win
1452
+ over an unsafe inherited fallback, and a visited set bounds the walk on cyclic or
1453
+ repeated inheritance.
1454
+ """
1455
+ pending = [class_ref]
1456
+ seen: Set[tuple[str, str]] = set()
1457
+ while pending:
1458
+ name, mod = pending.pop(0)
1459
+ if (name, mod) in seen:
1460
+ continue
1461
+ seen.add((name, mod))
1462
+
1463
+ summary = self.contracts.get((mod, f"{name}.{attr}"))
1464
+ if summary is not None:
1465
+ return mod, summary
1466
+
1467
+ for parent in self._base_classes(name, mod):
1468
+ if parent not in seen:
1469
+ pending.append(parent)
1470
+ return None
1471
+
1472
+ def _base_classes(self, class_name: str, class_mod: str) -> List[tuple[str, str]]:
1473
+ """Resolve the base classes of `class_name` to (class, module) pairs, in source order."""
1474
+ facts = self.module_facts.get(class_mod)
1475
+ if facts is None:
1476
+ return []
1477
+ bases = facts.bases.get(class_name)
1478
+ if bases is None:
1479
+ return []
1480
+
1481
+ parents: List[tuple[str, str]] = []
1482
+ for named, spelling in bases:
1483
+ # Only a bare or dotted name identifies an inheritable class; call and subscript
1484
+ # bases (Generic[T], metaclass kwargs) carry no statically named class.
1485
+ parent = self._class_of_name(spelling, class_mod) if named else None
1486
+ if parent is not None:
1487
+ parents.append(parent)
1488
+ return parents
1489
+
1490
+ def _resolve_module_attribute_contract(
1491
+ self,
1492
+ func: ast.Attribute,
1493
+ caller_mod: str,
1494
+ ) -> Optional[tuple[str, FunctionSummary]]:
1495
+ """Resolve `alias.func(...)` where the alias names an imported module.
1496
+
1497
+ `import service as db_svc` binds a namespace rather than a symbol, so the function
1498
+ behind `db_svc.execute_query` is invisible to symbol resolution, which only knows
1499
+ explicitly imported names. Recovering the module from the import table and looking the
1500
+ attribute up in its contracts keeps the aliased call as precise as the direct one.
1501
+ """
1502
+ if not isinstance(func.value, ast.Name):
1503
+ return None
1504
+ target_mod = self._imported_module_of(func.value.id, caller_mod)
1505
+ if target_mod is None:
1506
+ return None
1507
+ summary = self.contracts.get((target_mod, func.attr))
1508
+ return None if summary is None else (target_mod, summary)
1509
+
1510
+ def _imported_module_of(self, name: str, caller_mod: str) -> Optional[str]:
1511
+ """Module a bare Name refers to when it was bound by `import x[.y] [as name]`."""
1512
+ mod_idx = self.indexer.modules.get(caller_mod)
1513
+ if mod_idx is None:
1514
+ return None
1515
+ binding = mod_idx.imports.get(name)
1516
+ if binding is None or binding.imported_name:
1517
+ return None
1518
+ return self.indexer._match_registered_module(binding.source_module)
1519
+
1520
+ def _decorator_sanitized_params(self, callee_mod: str, summary: FunctionSummary) -> Set[int]:
1521
+ """Parameter indices that a validating decorator neutralises before the body runs.
1522
+
1523
+ ``@validated def view(record_id)`` whose wrapper calls ``func(int(record_id))`` can
1524
+ never observe a raw value in that slot, so a tainted argument there is not injectable
1525
+ and the call site must not be reported. Only one shape is trusted, because it is the
1526
+ only one that is provable: the decorator declares a nested wrapper, that wrapper takes
1527
+ the decorated function's parameters positionally without ``*args``/``**kwargs``, and
1528
+ its call to the wrapped function passes, per position, either the parameter untouched
1529
+ or a known sanitizer applied to exactly that parameter. A passthrough decorator
1530
+ therefore stays transparent, which is what keeps a timed or logged sink reportable.
1531
+ """
1532
+ key = (callee_mod, summary.qualname)
1533
+ cached = self._decorator_slots.get(key)
1534
+ if cached is not None:
1535
+ return cached
1536
+
1537
+ sanitized: Set[int] = set()
1538
+ facts = self.module_facts.get(callee_mod)
1539
+ func = facts.funcs.get(summary.qualname) if facts is not None else None
1540
+ if func is not None and summary.params:
1541
+ for decorator in func.decos:
1542
+ if decorator.bare is None:
1543
+ continue
1544
+ symbol_def = self.indexer.resolve_symbol(callee_mod, decorator.bare)
1545
+ if symbol_def is None or symbol_def.kind not in ("function", "async_function"):
1546
+ continue
1547
+ decorator_mod = self._resolve_file_module(symbol_def.file_path)
1548
+ if decorator_mod is None:
1549
+ continue
1550
+ definition_facts = self.module_facts.get(decorator_mod)
1551
+ definition = (definition_facts.funcs.get(symbol_def.name)
1552
+ if definition_facts is not None else None)
1553
+ if definition is None or definition.wrapper is None:
1554
+ continue
1555
+ sanitized |= self._wrapper_slots(definition.wrapper, summary.params)
1556
+ self._decorator_slots[key] = sanitized
1557
+ return sanitized
1558
+
1559
+ @staticmethod
1560
+ def _wrapper_slots(shape: WrapperShape, decorated_params: List[str]) -> Set[int]:
1561
+ """Slots the decorator's wrapper rebuilds through a sanitizer before calling through."""
1562
+ if not shape.ok:
1563
+ return set()
1564
+ if len(shape.wparams) != len(decorated_params):
1565
+ return set()
1566
+ if shape.flen != len(decorated_params):
1567
+ return set()
1568
+ slots: Set[int] = set()
1569
+ for index, (used, is_call, tail) in enumerate(shape.fargs):
1570
+ if set(used) - {shape.wparams[index]}:
1571
+ continue
1572
+ if is_call and tail in KNOWN_SANITIZERS:
1573
+ slots.add(index)
1574
+ return slots
1575
+
1576
+ def _class_of_name(self, name: str, caller_mod: str) -> Optional[tuple[str, str]]:
1577
+ """(class name, defining module) when `name` resolves to an indexed class."""
1578
+ symbol_def = self.indexer.resolve_symbol(caller_mod, name)
1579
+ if symbol_def is None or symbol_def.kind != "class":
1580
+ return None
1581
+ class_mod = self._resolve_file_module(symbol_def.file_path)
1582
+ if class_mod is None:
1583
+ return None
1584
+ return symbol_def.name, class_mod
1585
+
1586
+ def _instantiated_class(
1587
+ self,
1588
+ call: ast.Call,
1589
+ caller_mod: str,
1590
+ ) -> Optional[tuple[str, str]]:
1591
+ """Class of a freshly built object: `ClassName(...).method()`."""
1592
+ ctor = call.func
1593
+ if not isinstance(ctor, ast.Name):
1594
+ return None
1595
+ return self._class_of_name(ctor.id, caller_mod)
1596
+
1597
+ def _instance_bindings(
1598
+ self,
1599
+ caller_mod: str,
1600
+ caller_func: str,
1601
+ func_node: ast.AST,
1602
+ own_assigns: Optional[list] = None,
1603
+ ) -> Dict[str, tuple[str, str]]:
1604
+ """Map receiver identifiers to (class name, defining module) inside one function.
1605
+
1606
+ Collects `var = ClassName(...)` bindings in source order (a later rebinding wins) and,
1607
+ for methods, the implicit `self`/`cls` receiver derived from the qualified caller name.
1608
+ `own_assigns` is the already-recorded own-scope assignment list from _record_productive,
1609
+ which is the same sequence in the same order the walk below would have produced; passing
1610
+ it saves that walk. The map is still completed before the caller uses it, which is the
1611
+ whole reason the sanitizer scan records first and replays second.
1612
+ """
1613
+ bindings: Dict[str, tuple[str, str]] = {}
1614
+ if "." in caller_func:
1615
+ owning_class = (caller_func.split(".", 1)[0], caller_mod)
1616
+ bindings["self"] = owning_class
1617
+ bindings["cls"] = owning_class
1618
+
1619
+ nodes = own_assigns if own_assigns is not None else _ordered_nodes(
1620
+ func_node, skip_scopes=True)
1621
+ for node in nodes:
1622
+ if not isinstance(node, ast.Assign) or not isinstance(node.value, ast.Call):
1623
+ continue
1624
+ ctor = node.value.func
1625
+ if not isinstance(ctor, ast.Name):
1626
+ continue
1627
+ class_ref = self._class_of_name(ctor.id, caller_mod)
1628
+ if class_ref is None:
1629
+ continue
1630
+ for target in node.targets:
1631
+ if isinstance(target, ast.Name):
1632
+ bindings[target.id] = class_ref
1633
+
1634
+ return bindings
1635
+
1636
+ def _resolve_call_summary(
1637
+ self,
1638
+ caller_mod: str,
1639
+ value: ast.expr,
1640
+ receivers: Optional[Dict[str, tuple[str, str]]] = None,
1641
+ ) -> Optional[FunctionSummary]:
1642
+ """Return the contract for a direct call expression, or None if unresolved."""
1643
+ resolved = self._resolve_call_contract(caller_mod, value, receivers)
1644
+ return resolved[1] if resolved else None
1645
+
1646
+ def _returns_tainted_arg(
1647
+ self,
1648
+ value: ast.Call,
1649
+ param_names: List[str],
1650
+ tainted_returns: Set[int],
1651
+ tainted_vars: Set[str],
1652
+ arg_offset: int = 0,
1653
+ ) -> bool:
1654
+ """True when an argument in a taint-propagating parameter position is tainted."""
1655
+ bound = self._bind_call_args(value, param_names, arg_offset)
1656
+ for param_idx in sorted(tainted_returns):
1657
+ arg = bound.get(param_idx)
1658
+ if arg is None:
1659
+ continue
1660
+ arg_names = {n.id for n in ast.walk(arg) if isinstance(n, ast.Name)}
1661
+ if arg_names & tainted_vars:
1662
+ return True
1663
+ return False
1664
+
1665
+ def _check_call_against_contracts(
1666
+ self,
1667
+ caller_mod: str,
1668
+ caller_file: str,
1669
+ caller_func_name: str,
1670
+ call: ast.Call,
1671
+ tainted_vars: set[str],
1672
+ receivers: Dict[str, tuple[str, str]],
1673
+ ) -> None:
1674
+ # Resolve callee symbol and contract (module-level call or class instance method)
1675
+ resolved = self._resolve_call_contract(caller_mod, call, receivers)
1676
+ if not resolved:
1677
+ return
1678
+ callee_mod, summary = resolved
1679
+ self._emit_contract_findings(caller_mod, caller_file, caller_func_name, call,
1680
+ callee_mod, summary, tainted_vars, receivers)
1681
+
1682
+ def _emit_contract_findings(
1683
+ self,
1684
+ caller_mod: str,
1685
+ caller_file: str,
1686
+ caller_func_name: str,
1687
+ call: ast.Call,
1688
+ callee_mod: str,
1689
+ summary: FunctionSummary,
1690
+ tainted_vars: set[str],
1691
+ receivers: Dict[str, tuple[str, str]],
1692
+ ) -> None:
1693
+ """Report every sink the callee reaches from an argument the caller passed tainted.
1694
+
1695
+ Shared by direct calls and by event dispatch (`signal.send(...)` / `task.delay(...)`), so
1696
+ a handler reached through the bus gets the same binding rules and trace shape.
1697
+ """
1698
+ # Check if caller passed tainted arguments into callee's sink parameters
1699
+ neutralized = self._decorator_sanitized_params(callee_mod, summary)
1700
+ for arg_idx, arg in sorted(
1701
+ self._bind_call_args(call, summary.params, self._receiver_offset(caller_mod, call, summary, receivers)).items()
1702
+ ):
1703
+ if arg_idx in neutralized:
1704
+ continue
1705
+ arg_repr = ast.unparse(arg) if hasattr(ast, "unparse") else ""
1706
+ is_tainted_arg = any(t in arg_repr for t in tainted_vars) or any(src in arg_repr for src in TAINT_SOURCE_PATTERNS)
1707
+
1708
+ if is_tainted_arg:
1709
+ # Check target sinks
1710
+ for sink in summary.param_sinks:
1711
+ if sink.param_idx != arg_idx:
1712
+ continue
1713
+
1714
+ trace_key = (callee_mod, summary.qualname, sink.param_idx,
1715
+ sink.sink_name, sink.lineno)
1716
+ sink_file = self.sink_origins.get(trace_key, summary.file_path)
1717
+ call_line = getattr(call, "lineno", 0)
1718
+ flow_trace = [
1719
+ TraceHop("SOURCE", caller_file, call_line,
1720
+ f"{caller_mod}.{caller_func_name}")
1721
+ ]
1722
+ flow_trace.extend(
1723
+ TraceHop("ROUTE", route_file, route_line, route_func)
1724
+ for route_file, route_line, route_func
1725
+ in self.sink_route.get(trace_key, [])
1726
+ )
1727
+ flow_trace.append(
1728
+ TraceHop("SINK", sink_file, sink.lineno,
1729
+ self._sink_descriptor(sink_file, sink.lineno, sink.sink_name))
1730
+ )
1731
+
1732
+ self.findings.append(
1733
+ CrossFileFinding(
1734
+ cwe=sink.sink_cwe,
1735
+ caller_file=caller_file,
1736
+ caller_lineno=call_line,
1737
+ caller_func=f"{caller_mod}.{caller_func_name}",
1738
+ callee_file=sink_file,
1739
+ callee_func=f"{callee_mod}.{summary.qualname}",
1740
+ callee_sink_name=sink.sink_name,
1741
+ callee_sink_lineno=sink.lineno,
1742
+ tainted_param=sink.param_name,
1743
+ flow_trace=flow_trace,
1744
+ )
1745
+ )
1746
+
1747
+ def _sink_descriptor(self, file_path: str, lineno: int, fallback: str) -> str:
1748
+ """Recover how the sink was written (e.g. 'cursor.execute') from its source line."""
1749
+ mod_name = self._resolve_file_module(file_path)
1750
+ facts = self.module_facts.get(mod_name) if mod_name else None
1751
+ entry = facts.sink_lines.get(lineno) if facts is not None else None
1752
+ if entry is None:
1753
+ return fallback
1754
+ first, by_tail = entry
1755
+ return by_tail.get(fallback, first)
1756
+
1757
+
1758
+ if __name__ == "__main__":
1759
+ target_dir = sys.argv[1] if len(sys.argv) > 1 else "."
1760
+ print(f"[*] Starting TimeCodeSecurity Cross-File Taint Engine on: {target_dir}")
1761
+ t0 = time.perf_counter()
1762
+
1763
+ engine = CrossFileTaintEngine(target_dir)
1764
+ findings = engine.run()
1765
+ elapsed = (time.perf_counter() - t0) * 1000
1766
+
1767
+ print("\n=================================================================")
1768
+ print(" TIMECODESECURITY - CROSS-FILE ANALYSIS REPORT ")
1769
+ print("=================================================================")
1770
+ print(f"Execution Time: {elapsed:.2f} ms")
1771
+ print(f"Total Cross-File Exploits: {len(findings)}")
1772
+ print("-----------------------------------------------------------------")
1773
+
1774
+ if findings:
1775
+ for i, f in enumerate(findings, 1):
1776
+ print(f"\n[{i}] VULNERABILITY: {f.cwe}")
1777
+ print(f" Source Call-site: {f.caller_func} ({f.caller_file}:{f.caller_lineno})")
1778
+ print(f" Flows Into: {f.callee_func} (Param: '{f.tainted_param}')")
1779
+ print(f" Exploit Sink: {f.callee_sink_name} at {f.callee_file}:{f.callee_sink_lineno}")
1780
+ else:
1781
+ print("[+] No unhandled cross-file taint leaks detected.")