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
@@ -0,0 +1,408 @@
1
+ """
2
+ Deterministic Intra-Procedural Def-Use Tracker (Zero-FP Guarantee)
3
+
4
+ Pure AST-based alias tracking within a single FunctionDef scope.
5
+ Tracks variable assignments, propagates taint through alias chains,
6
+ and applies kill-gen semantics for safe reassignments.
7
+
8
+ NO HEURISTICS / NO AI / NO LLM — deterministic AST analysis only.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import ast
14
+ from dataclasses import dataclass, field
15
+ from typing import Optional, Dict, Set, Tuple, List
16
+
17
+
18
+ # Known sanitizers that break taint propagation
19
+ # CRITICAL: str/bytes/repr/ascii are NOT sanitizers — they don't neutralize
20
+ # shell metacharacters, SQL quotes, or path traversal dots.
21
+ KNOWN_SANITIZERS: Set[str] = {
22
+ "int", "float", "bool", # Strict type conversions (reject non-numeric → exception)
23
+ "shlex.quote", # Shell argument quoting
24
+ "html.escape", # HTML entity encoding
25
+ "urllib.parse.quote", # URL percent-encoding
26
+ "os.path.abspath", # Path normalization (removes ..)
27
+ "os.path.realpath", # Symlink-resolving path normalization
28
+ "pathlib.Path.resolve", # Modern pathlib path resolution
29
+ }
30
+
31
+
32
+ @dataclass(frozen=True)
33
+ class AliasInfo:
34
+ """Represents a tracked alias relationship."""
35
+ target: str
36
+ source: str
37
+ lineno: int
38
+ is_tainted: bool = False
39
+ sanitizer_applied: Optional[str] = None
40
+
41
+
42
+ @dataclass
43
+ class LocalDefUseTracker:
44
+ """
45
+ Deterministic intra-procedural def-use tracker for a single function scope.
46
+
47
+ Tracks:
48
+ - Direct aliases: b = a
49
+ - Multi-hop aliases: c = b where b = a
50
+ - Kill-gen: b = "constant" kills previous taint
51
+ - Sanitizer boundaries: b = int(a) breaks taint chain
52
+ """
53
+
54
+ # Maps variable name -> current alias info
55
+ alias_map: Dict[str, AliasInfo] = field(default_factory=dict)
56
+
57
+ # Set of variables known to be tainted at entry (function parameters or sources)
58
+ tainted_vars: Set[str] = field(default_factory=set)
59
+
60
+ # Track which variables have been killed (reassigned to safe literals)
61
+ killed_vars: Set[str] = field(default_factory=set)
62
+
63
+ # Function name for scoping
64
+ function_name: Optional[str] = None
65
+
66
+ def reset(self) -> None:
67
+ """Reset all tracking state."""
68
+ self.alias_map.clear()
69
+ self.tainted_vars.clear()
70
+ self.killed_vars.clear()
71
+ self.function_name = None
72
+
73
+ def analyze_function(self, func_node: ast.FunctionDef, file_path: str = "<unknown>") -> None:
74
+ """
75
+ Analyze a single FunctionDef node and build the alias map.
76
+
77
+ This walks the function body in order, tracking:
78
+ - Parameter bindings (initial potential taint sources)
79
+ - Assignments (alias creation)
80
+ - AnnAssign (annotated assignments)
81
+ - AugAssign (augmented assignments like +=)
82
+ """
83
+ self.reset()
84
+ self.function_name = func_node.name
85
+
86
+ # Mark function parameters as potential taint sources
87
+ for arg in func_node.args.args:
88
+ if arg.arg != "self": # Skip 'self' parameter
89
+ self.tainted_vars.add(arg.arg)
90
+
91
+ # Walk function body and track assignments
92
+ for stmt in func_node.body:
93
+ self._process_statement(stmt)
94
+
95
+ def _process_statement(self, stmt: ast.AST) -> None:
96
+ """Process a single statement for def-use tracking."""
97
+ if isinstance(stmt, ast.Assign):
98
+ self._process_assignment(stmt)
99
+ elif isinstance(stmt, ast.AnnAssign):
100
+ self._process_annotated_assignment(stmt)
101
+ elif isinstance(stmt, ast.AugAssign):
102
+ self._process_augmented_assignment(stmt)
103
+ elif isinstance(stmt, (ast.For, ast.While)):
104
+ # Process loop bodies (conservative: assume all paths execute)
105
+ for sub_stmt in stmt.body:
106
+ self._process_statement(sub_stmt)
107
+ elif isinstance(stmt, ast.If):
108
+ # Process both branches conservatively
109
+ for sub_stmt in stmt.body:
110
+ self._process_statement(sub_stmt)
111
+ for sub_stmt in stmt.orelse:
112
+ self._process_statement(sub_stmt)
113
+ elif isinstance(stmt, ast.Try):
114
+ # Process try/except/finally blocks
115
+ for sub_stmt in stmt.body:
116
+ self._process_statement(sub_stmt)
117
+ for handler in stmt.handlers:
118
+ for sub_stmt in handler.body:
119
+ self._process_statement(sub_stmt)
120
+ for sub_stmt in stmt.finalbody:
121
+ self._process_statement(sub_stmt)
122
+
123
+ def _process_assignment(self, node: ast.Assign) -> None:
124
+ """Process an assignment statement (a = b)."""
125
+ # Handle tuple unpacking: a, b = c, d
126
+ if isinstance(node.targets[0], ast.Tuple):
127
+ if isinstance(node.value, ast.Tuple):
128
+ targets = node.targets[0].elts
129
+ values = node.value.elts
130
+ if len(targets) == len(values):
131
+ for target, value in zip(targets, values):
132
+ if isinstance(target, ast.Name):
133
+ self._track_variable(target.id, value, node.lineno)
134
+ return
135
+
136
+ # Simple assignment: a = b
137
+ if isinstance(node.targets[0], ast.Name):
138
+ target_name = node.targets[0].id
139
+ self._track_variable(target_name, node.value, node.lineno)
140
+
141
+ def _process_annotated_assignment(self, node: ast.AnnAssign) -> None:
142
+ """Process an annotated assignment (a: str = b)."""
143
+ if node.target and isinstance(node.target, ast.Name) and node.value:
144
+ self._track_variable(node.target.id, node.value, node.lineno)
145
+
146
+ def _process_augmented_assignment(self, node: ast.AugAssign) -> None:
147
+ """Process an augmented assignment (a += b).
148
+
149
+ Augmented assignments are treated as redefinitions that may preserve
150
+ taint from the left-hand side.
151
+ """
152
+ if isinstance(node.target, ast.Name):
153
+ target_name = node.target.id
154
+ # If target was tainted, it remains tainted after augmentation
155
+ # The right-hand side value is also considered
156
+ if target_name in self.tainted_vars and target_name not in self.killed_vars:
157
+ # Taint preserved through augmentation
158
+ pass
159
+ else:
160
+ # Check if RHS is tainted
161
+ rhs_is_tainted = self._is_node_tainted(node.value)
162
+ if rhs_is_tainted:
163
+ self.tainted_vars.add(target_name)
164
+ self.killed_vars.discard(target_name)
165
+
166
+ def _track_variable(self, target_name: str, value_node: ast.AST, lineno: int) -> None:
167
+ """
168
+ Track a variable assignment and determine if it carries taint.
169
+
170
+ Implements kill-gen semantics:
171
+ - If assigned to a constant/safe literal → KILL taint
172
+ - If assigned to a tainted variable → PROPAGATE taint
173
+ - If assigned through a sanitizer → BREAK taint chain
174
+ """
175
+ # Check if this is a safe literal (kill taint)
176
+ if self._is_safe_literal(value_node):
177
+ self.killed_vars.add(target_name)
178
+ self.tainted_vars.discard(target_name)
179
+ self.alias_map[target_name] = AliasInfo(
180
+ target=target_name,
181
+ source="<literal>",
182
+ lineno=lineno,
183
+ is_tainted=False
184
+ )
185
+ return
186
+
187
+ # Check if this is a sanitizer application (break taint chain)
188
+ sanitizer_name = self._extract_sanitizer_name(value_node)
189
+ if sanitizer_name:
190
+ self.killed_vars.add(target_name)
191
+ self.tainted_vars.discard(target_name)
192
+ self.alias_map[target_name] = AliasInfo(
193
+ target=target_name,
194
+ source=self._get_source_name(value_node),
195
+ lineno=lineno,
196
+ is_tainted=False,
197
+ sanitizer_applied=sanitizer_name
198
+ )
199
+ return
200
+
201
+ # Check if this is an alias to another variable
202
+ if isinstance(value_node, ast.Name):
203
+ source_name = value_node.id
204
+ source_is_tainted = source_name in self.tainted_vars and source_name not in self.killed_vars
205
+
206
+ if source_is_tainted:
207
+ # Propagate taint through alias
208
+ self.tainted_vars.add(target_name)
209
+ self.killed_vars.discard(target_name)
210
+ else:
211
+ # Source is not tainted, so target is clean
212
+ self.tainted_vars.discard(target_name)
213
+ self.killed_vars.add(target_name)
214
+
215
+ self.alias_map[target_name] = AliasInfo(
216
+ target=target_name,
217
+ source=source_name,
218
+ lineno=lineno,
219
+ is_tainted=source_is_tainted
220
+ )
221
+ return
222
+
223
+ # Check if the expression contains tainted variables
224
+ expr_is_tainted = self._is_node_tainted(value_node)
225
+ if expr_is_tainted:
226
+ self.tainted_vars.add(target_name)
227
+ self.killed_vars.discard(target_name)
228
+ else:
229
+ self.tainted_vars.discard(target_name)
230
+ self.killed_vars.add(target_name)
231
+
232
+ self.alias_map[target_name] = AliasInfo(
233
+ target=target_name,
234
+ source=ast.unparse(value_node) if hasattr(ast, 'unparse') else "<complex_expr>",
235
+ lineno=lineno,
236
+ is_tainted=expr_is_tainted
237
+ )
238
+
239
+ def _is_safe_literal(self, node: ast.AST) -> bool:
240
+ """Check if a node is a safe literal (constant string, number, etc.)."""
241
+ if isinstance(node, ast.Constant):
242
+ return True
243
+ if hasattr(ast, 'Num') and isinstance(node, ast.Num):
244
+ return True
245
+ if hasattr(ast, 'Str') and isinstance(node, ast.Str):
246
+ return True
247
+ if isinstance(node, ast.List) or isinstance(node, ast.Dict):
248
+ # Empty collections are safe
249
+ if isinstance(node, ast.List) and len(node.elts) == 0:
250
+ return True
251
+ if isinstance(node, ast.Dict) and len(node.keys) == 0:
252
+ return True
253
+ return False
254
+
255
+ def _extract_sanitizer_name(self, node: ast.AST) -> Optional[str]:
256
+ """Extract sanitizer name if the node is a known sanitizer call."""
257
+ if not isinstance(node, ast.Call):
258
+ return None
259
+
260
+ func_name = self._get_call_func_name(node)
261
+ if func_name in KNOWN_SANITIZERS:
262
+ return func_name
263
+
264
+ return None
265
+
266
+ def _get_call_func_name(self, node: ast.Call) -> Optional[str]:
267
+ """Extract the dotted name of a function call."""
268
+ if isinstance(node.func, ast.Name):
269
+ return node.func.id
270
+ if isinstance(node.func, ast.Attribute):
271
+ parts = []
272
+ current = node.func
273
+ while isinstance(current, ast.Attribute):
274
+ parts.append(current.attr)
275
+ current = current.value
276
+ if isinstance(current, ast.Name):
277
+ parts.append(current.id)
278
+ return ".".join(reversed(parts))
279
+ return None
280
+
281
+ def _get_source_name(self, node: ast.AST) -> str:
282
+ """Get the source variable name from a node."""
283
+ if isinstance(node, ast.Call):
284
+ if node.args:
285
+ first_arg = node.args[0]
286
+ if isinstance(first_arg, ast.Name):
287
+ return first_arg.id
288
+ return "<unknown>"
289
+
290
+ def _is_node_tainted(self, node: ast.AST) -> bool:
291
+ """
292
+ Recursively check if an AST node contains tainted variables.
293
+
294
+ This handles:
295
+ - Direct variable references
296
+ - Binary operations (e.g., string concatenation)
297
+ - F-strings (JoinedStr) with tainted expressions
298
+ - Function calls with tainted arguments
299
+ - Attribute access on tainted objects
300
+ - Subscript access on tainted containers
301
+ """
302
+ if isinstance(node, ast.Name):
303
+ return node.id in self.tainted_vars and node.id not in self.killed_vars
304
+
305
+ if isinstance(node, ast.BinOp):
306
+ # Check both sides of binary operation
307
+ return self._is_node_tainted(node.left) or self._is_node_tainted(node.right)
308
+
309
+ if isinstance(node, ast.JoinedStr):
310
+ # f-string: check all FormattedValue nodes inside
311
+ for val in node.values:
312
+ if isinstance(val, ast.FormattedValue):
313
+ if self._is_node_tainted(val.value):
314
+ return True
315
+ elif self._is_node_tainted(val):
316
+ return True
317
+ return False
318
+
319
+ if isinstance(node, ast.Call):
320
+ # Check if the function being called is tainted (method on tainted object)
321
+ if self._is_node_tainted(node.func):
322
+ return True
323
+ # Check if any argument is tainted
324
+ for arg in node.args:
325
+ if self._is_node_tainted(arg):
326
+ return True
327
+ for kw in node.keywords:
328
+ if self._is_node_tainted(kw.value):
329
+ return True
330
+ return False
331
+
332
+ if isinstance(node, ast.Attribute):
333
+ # Attribute access: check the value (object being accessed)
334
+ return self._is_node_tainted(node.value)
335
+
336
+ if isinstance(node, ast.Subscript):
337
+ # Subscript: check the value and slice
338
+ return self._is_node_tainted(node.value) or self._is_node_tainted(node.slice)
339
+
340
+ if isinstance(node, ast.FormattedValue):
341
+ # Individual expression inside f-string
342
+ return self._is_node_tainted(node.value)
343
+
344
+ return False
345
+
346
+ def is_variable_tainted(self, var_name: str) -> bool:
347
+ """Check if a variable is currently tainted."""
348
+ return var_name in self.tainted_vars and var_name not in self.killed_vars
349
+
350
+ def get_alias_chain(self, var_name: str) -> List[str]:
351
+ """
352
+ Get the full alias chain for a variable.
353
+
354
+ Returns list of variable names in the alias chain, from target back to source.
355
+ """
356
+ chain = []
357
+ current = var_name
358
+ visited = set()
359
+
360
+ while current in self.alias_map and current not in visited:
361
+ visited.add(current)
362
+ alias_info = self.alias_map[current]
363
+ chain.append(current)
364
+ if alias_info.source and alias_info.source not in ("<literal>", "<unknown>", "<complex_expr>"):
365
+ current = alias_info.source
366
+ else:
367
+ break
368
+
369
+ return chain
370
+
371
+ def get_tainted_aliases(self) -> Dict[str, AliasInfo]:
372
+ """Get all variables that are currently tainted with their alias info."""
373
+ return {
374
+ var: info
375
+ for var, info in self.alias_map.items()
376
+ if info.is_tainted and var not in self.killed_vars
377
+ }
378
+
379
+ def trace_taint_path(self, sink_var: str) -> Optional[List[Tuple[str, int]]]:
380
+ """
381
+ Trace the taint propagation path from source to a sink variable.
382
+
383
+ Returns list of (variable_name, lineno) tuples showing the taint flow,
384
+ or None if the variable is not tainted.
385
+ """
386
+ if not self.is_variable_tainted(sink_var):
387
+ return None
388
+
389
+ path = []
390
+ current = sink_var
391
+ visited = set()
392
+
393
+ while current in self.alias_map and current not in visited:
394
+ visited.add(current)
395
+ alias_info = self.alias_map[current]
396
+ path.append((current, alias_info.lineno))
397
+
398
+ if alias_info.source and alias_info.source not in ("<literal>", "<unknown>", "<complex_expr>"):
399
+ current = alias_info.source
400
+ else:
401
+ break
402
+
403
+ # Add initial tainted source if it's a parameter
404
+ if current in self.tainted_vars and current not in self.alias_map:
405
+ path.append((current, 0)) # lineno 0 indicates function parameter
406
+
407
+ path.reverse()
408
+ return path if path else None
@@ -0,0 +1,290 @@
1
+ """
2
+ Deterministic Function Contract Extractor (Zero-FP Guarantee)
3
+
4
+ Bottom-up analysis that identifies wrapper functions where a parameter
5
+ flows deterministically into a known security sink.
6
+
7
+ NO HEURISTICS / NO AI / NO LLM — pure deterministic AST analysis only.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import ast
13
+ from dataclasses import dataclass, field
14
+ from typing import Optional, Dict, List, Set, Tuple
15
+
16
+ # Known dangerous sinks mapped to their CWE IDs
17
+ KNOWN_SINKS: Dict[str, str] = {
18
+ # SQL Injection
19
+ "execute": "CWE-89",
20
+ "cursor.execute": "CWE-89",
21
+ "conn.execute": "CWE-89",
22
+ "db.execute": "CWE-89",
23
+
24
+ # Command Injection
25
+ "subprocess.run": "CWE-78",
26
+ "subprocess.call": "CWE-78",
27
+ "subprocess.Popen": "CWE-78",
28
+ "os.system": "CWE-78",
29
+ "os.popen": "CWE-78",
30
+ "os.execvp": "CWE-78",
31
+ "os.execl": "CWE-78",
32
+
33
+ # Path Traversal
34
+ "open": "CWE-22",
35
+ "os.open": "CWE-22",
36
+ "pathlib.Path.open": "CWE-22",
37
+
38
+ # Code Injection
39
+ "eval": "CWE-95",
40
+ "exec": "CWE-95",
41
+ "compile": "CWE-95",
42
+
43
+ # Deserialization
44
+ "pickle.loads": "CWE-502",
45
+ "yaml.load": "CWE-502",
46
+ "marshal.loads": "CWE-502",
47
+
48
+ # SSRF
49
+ "requests.get": "CWE-918",
50
+ "requests.post": "CWE-918",
51
+ "urllib.request.urlopen": "CWE-918",
52
+
53
+ # XSS
54
+ "flask.render_template_string": "CWE-79",
55
+ "jinja2.Template.render": "CWE-79",
56
+ }
57
+
58
+ # Known sanitizers that break taint propagation
59
+ CONTRACT_SANITIZERS: Set[str] = {
60
+ "int", "float", "bool", # Strict type conversions
61
+ "shlex.quote", # Shell argument quoting
62
+ "html.escape", # HTML entity encoding
63
+ "urllib.parse.quote", # URL percent-encoding
64
+ "os.path.abspath", # Path normalization
65
+ "os.path.realpath", # Symlink-resolving path normalization
66
+ "pathlib.Path.resolve", # Modern pathlib resolution
67
+ }
68
+
69
+
70
+ @dataclass(frozen=True)
71
+ class FunctionSinkContract:
72
+ """
73
+ Represents a verified contract where a function parameter flows
74
+ deterministically into a known security sink.
75
+
76
+ Example:
77
+ def run_cmd(c): # func_name="run_cmd"
78
+ subprocess.run(c) # sink_arg_index=0, cwe_id="CWE-78", target_sink="subprocess.run"
79
+
80
+ SAFETY GUARANTEE:
81
+ - Only registered if path from parameter to sink has NO sanitizers
82
+ - Only registered if no constant overrides kill the taint
83
+ - 100% deterministic within the function body
84
+ """
85
+ func_name: str
86
+ sink_arg_index: int # Which parameter of the wrapper function
87
+ cwe_id: str # The CWE classification
88
+ target_sink: str # The underlying dangerous sink
89
+ func_lineno: int # Line number of the function definition
90
+ sink_lineno: int # Line number of the sink call
91
+
92
+
93
+ class FunctionContractExtractor:
94
+ """
95
+ Deterministic bottom-up function contract extractor.
96
+
97
+ Analyzes each FunctionDef in a module and identifies wrappers where
98
+ a parameter flows directly into a known security sink without sanitization.
99
+ """
100
+
101
+ def __init__(self):
102
+ self.contracts: Dict[str, FunctionSinkContract] = {}
103
+
104
+ def extract_from_module(self, tree: ast.AST, file_path: str = "<unknown>") -> Dict[str, FunctionSinkContract]:
105
+ """
106
+ Extract all function contracts from an AST module.
107
+
108
+ Returns dict mapping function name to FunctionSinkContract.
109
+ Perf: one pass collects functions and calls; a module with zero calls
110
+ into known sinks is rejected before any per-function analysis runs.
111
+ """
112
+ self.contracts.clear()
113
+
114
+ # Perf: collect functions and sink candidate calls in one pass
115
+ func_nodes: List[ast.AST] = []
116
+ sink_shortnames = {name.split(".")[-1] for name in KNOWN_SINKS}
117
+ has_known_sink_call = False
118
+ for node in ast.walk(tree):
119
+ if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
120
+ func_nodes.append(node)
121
+ elif isinstance(node, ast.Call):
122
+ call_name = self._get_call_name(node)
123
+ if call_name and (
124
+ call_name in KNOWN_SINKS
125
+ or call_name.split(".")[-1] in sink_shortnames
126
+ ):
127
+ has_known_sink_call = True
128
+
129
+ if not has_known_sink_call:
130
+ return self.contracts
131
+
132
+ for func_node in func_nodes:
133
+ contract = self._analyze_function(func_node, file_path)
134
+ if contract:
135
+ # Only register if not already present (first one wins for safety)
136
+ if contract.func_name not in self.contracts:
137
+ self.contracts[contract.func_name] = contract
138
+
139
+ return self.contracts
140
+
141
+ def _analyze_function(
142
+ self, func_node: ast.FunctionDef, file_path: str
143
+ ) -> Optional[FunctionSinkContract]:
144
+ """
145
+ Analyze a single function for parameter-to-sink flows.
146
+
147
+ Returns FunctionSinkContract if a deterministic flow is found, None otherwise.
148
+ """
149
+ param_names = [arg.arg for arg in func_node.args.args]
150
+
151
+ # Skip functions with no parameters
152
+ if not param_names:
153
+ return None
154
+
155
+ # Walk function body looking for sink calls
156
+ for stmt in ast.walk(func_node):
157
+ if not isinstance(stmt, ast.Call):
158
+ continue
159
+
160
+ # Check if this call is a known sink
161
+ sink_name = self._get_call_name(stmt)
162
+ if not sink_name:
163
+ continue
164
+
165
+ cwe_id = KNOWN_SINKS.get(sink_name)
166
+ if not cwe_id:
167
+ continue
168
+
169
+ # Check each argument of the sink call
170
+ for arg_idx, arg_node in enumerate(stmt.args):
171
+ # Check if this argument is a direct reference to a parameter
172
+ if isinstance(arg_node, ast.Name) and arg_node.id in param_names:
173
+ param_idx = param_names.index(arg_node.id)
174
+
175
+ # Verify the flow is clean (no sanitizers, no overrides)
176
+ if self._verify_clean_flow(func_node, arg_node.id, stmt.lineno):
177
+ return FunctionSinkContract(
178
+ func_name=func_node.name,
179
+ sink_arg_index=param_idx,
180
+ cwe_id=cwe_id,
181
+ target_sink=sink_name,
182
+ func_lineno=func_node.lineno,
183
+ sink_lineno=stmt.lineno
184
+ )
185
+
186
+ # Also check keyword arguments
187
+ for kw in stmt.keywords:
188
+ if isinstance(kw.value, ast.Name) and kw.value.id in param_names:
189
+ param_idx = param_names.index(kw.value.id)
190
+
191
+ if self._verify_clean_flow(func_node, kw.value.id, stmt.lineno):
192
+ return FunctionSinkContract(
193
+ func_name=func_node.name,
194
+ sink_arg_index=param_idx,
195
+ cwe_id=cwe_id,
196
+ target_sink=sink_name,
197
+ func_lineno=func_node.lineno,
198
+ sink_lineno=stmt.lineno
199
+ )
200
+
201
+ return None
202
+
203
+ def _get_call_name(self, call_node: ast.Call) -> Optional[str]:
204
+ """Extract dotted name from a call node."""
205
+ if isinstance(call_node.func, ast.Name):
206
+ return call_node.func.id
207
+ if isinstance(call_node.func, ast.Attribute):
208
+ parts = []
209
+ current = call_node.func
210
+ while isinstance(current, ast.Attribute):
211
+ parts.append(current.attr)
212
+ current = current.value
213
+ if isinstance(current, ast.Name):
214
+ parts.append(current.id)
215
+ return ".".join(reversed(parts))
216
+ return None
217
+
218
+ def _verify_clean_flow(
219
+ self, func_node: ast.FunctionDef, param_name: str, sink_lineno: int
220
+ ) -> bool:
221
+ """
222
+ Verify that the flow from parameter to sink is clean.
223
+
224
+ Returns True ONLY if:
225
+ - No sanitizers are applied to the parameter before the sink
226
+ - No constant reassignments kill the taint
227
+ - NO conditional guards (if statements) exist before the sink
228
+ - The parameter is used directly without intervening logic
229
+
230
+ This is the CRITICAL SAFETY FILTER for zero false positives.
231
+ Perf: single traversal — guard, sanitizer, and kill checks in one pass.
232
+ """
233
+ for stmt in ast.walk(func_node):
234
+ if not hasattr(stmt, 'lineno'):
235
+ continue
236
+ if stmt.lineno >= sink_lineno:
237
+ continue
238
+
239
+ # If there's ANY if statement before the sink, don't create contract
240
+ # This prevents contracts on guarded wrappers like SSRF validators
241
+ if isinstance(stmt, ast.If):
242
+ return False
243
+
244
+ # Check for assignments to the parameter
245
+ if isinstance(stmt, ast.Assign):
246
+ for target in stmt.targets:
247
+ if isinstance(target, ast.Name) and target.id == param_name:
248
+ # Check if it's reassigned to a safe constant (kill-gen)
249
+ if self._is_safe_literal(stmt.value):
250
+ return False
251
+
252
+ # Check if it's passed through a sanitizer
253
+ if isinstance(stmt.value, ast.Call):
254
+ func_name = self._get_call_name(stmt.value)
255
+ if func_name in CONTRACT_SANITIZERS:
256
+ return False
257
+
258
+ # Check for annotated assignments
259
+ if isinstance(stmt, ast.AnnAssign) and stmt.target:
260
+ if isinstance(stmt.target, ast.Name) and stmt.target.id == param_name:
261
+ if stmt.value:
262
+ if self._is_safe_literal(stmt.value):
263
+ return False
264
+ if isinstance(stmt.value, ast.Call):
265
+ func_name = self._get_call_name(stmt.value)
266
+ if func_name in CONTRACT_SANITIZERS:
267
+ return False
268
+
269
+ return True
270
+
271
+ def _is_safe_literal(self, node: ast.AST) -> bool:
272
+ """Check if a node is a safe literal constant."""
273
+ if isinstance(node, ast.Constant):
274
+ return True
275
+ if hasattr(ast, 'Num') and isinstance(node, ast.Num):
276
+ return True
277
+ if hasattr(ast, 'Str') and isinstance(node, ast.Str):
278
+ return True
279
+ return False
280
+
281
+ def get_contract_for_call(self, call_node: ast.Call) -> Optional[FunctionSinkContract]:
282
+ """
283
+ Look up a contract for a given call node.
284
+
285
+ Returns the contract if the call matches a registered wrapper function.
286
+ """
287
+ func_name = self._get_call_name(call_node)
288
+ if func_name:
289
+ return self.contracts.get(func_name)
290
+ return None