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.
- app.py +3014 -0
- ast_scanner.py +36187 -0
- banner.py +146 -0
- ci_reporter.py +570 -0
- cli.py +2347 -0
- config_loader.py +307 -0
- cross_file_engine.py +1781 -0
- delivery_models.py +145 -0
- delivery_repository.py +78 -0
- diff_scan.py +127 -0
- durable_delivery_sink.py +103 -0
- event_bus.py +155 -0
- event_publisher.py +345 -0
- event_taxonomy.py +313 -0
- function_summarizer.py +354 -0
- html_auditor.py +274 -0
- iac_auditor.py +400 -0
- in_app_adapter.py +115 -0
- js_scanner.py +895 -0
- manifest_parser.py +960 -0
- master_rules_bank.py +389 -0
- notification_models.py +346 -0
- notification_policy.py +309 -0
- notification_repository.py +118 -0
- notification_routes.py +394 -0
- notification_service.py +199 -0
- osv_client.py +437 -0
- remediation/__init__.py +39 -0
- remediation/base.py +102 -0
- remediation/contracts.py +196 -0
- remediation/cwe1188_binding.py +78 -0
- remediation/cwe1336_jinja.py +91 -0
- remediation/cwe22_path_traversal.py +348 -0
- remediation/cwe295_ssl.py +87 -0
- remediation/cwe327_weak_hash.py +78 -0
- remediation/cwe377_tempfile.py +77 -0
- remediation/cwe489_debug.py +80 -0
- remediation/cwe502_yaml.py +89 -0
- remediation/cwe614_cookie.py +91 -0
- remediation/cwe78_cmdi.py +415 -0
- remediation/cwe798_credentials.py +153 -0
- remediation/cwe89_sqli.py +425 -0
- remediation/cwe916_password_hash.py +131 -0
- remediation/cwe95_eval.py +77 -0
- remediation/dispatcher.py +114 -0
- remediation/orchestrator.py +541 -0
- remediation/patch_engine.py +213 -0
- remediation/verification.py +253 -0
- rule_engine.py +1535 -0
- sarif_adapter.py +719 -0
- sarif_exporter.py +88 -0
- sca_reachability/__init__.py +28 -0
- sca_reachability/ast_analyzer.py +366 -0
- sca_reachability/call_graph.py +203 -0
- sca_reachability/contracts.py +365 -0
- sca_reachability/dist_import_map.py +46 -0
- sca_reachability/engine.py +603 -0
- sca_reachability/resolver.py +169 -0
- scanners/__init__.py +70 -0
- scanners/container_scanner.py +323 -0
- scanners/cve_index.py +521 -0
- scanners/iac_scanner.py +328 -0
- scanners/sbom.py +183 -0
- scanners/sca_scanner.py +667 -0
- scanners/secret_scanner.py +345 -0
- scanners/yaml_lite.py +217 -0
- secret_filters.py +435 -0
- secret_scanner.py +943 -0
- sqlite_delivery_repository.py +277 -0
- sqlite_notification_repository.py +441 -0
- ssrf_guard.py +276 -0
- staged_scanner.py +492 -0
- suppression_resolver.py +282 -0
- symbol_indexer.py +424 -0
- tcs/__init__.py +1 -0
- tcs/analysis/__init__.py +1 -0
- tcs/analysis/def_use.py +408 -0
- tcs/analysis/function_contracts.py +290 -0
- tcs/parallel_analyzer.py +276 -0
- tcs/parallel_scanner.py +630 -0
- tcs/treesitter_packer.py +1446 -0
- tcs_cli.py +2086 -0
- tcs_config.py +218 -0
- tcs_gui.py +2123 -0
- timecs-2.0.0.dist-info/METADATA +142 -0
- timecs-2.0.0.dist-info/RECORD +94 -0
- timecs-2.0.0.dist-info/WHEEL +5 -0
- timecs-2.0.0.dist-info/entry_points.txt +4 -0
- timecs-2.0.0.dist-info/licenses/LICENSE +201 -0
- timecs-2.0.0.dist-info/top_level.txt +49 -0
- version_matcher.py +934 -0
- webhook_adapter.py +495 -0
- webhook_client.py +483 -0
- webhook_formatters.py +245 -0
tcs/analysis/def_use.py
ADDED
|
@@ -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
|