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
sarif_exporter.py ADDED
@@ -0,0 +1,88 @@
1
+ """
2
+ SARIF v2.1.0 Exporter Module for TimeCodeSecurity.
3
+ Provides high-level export utilities and serves as an official exporter facade
4
+ to sarif_adapter for GitHub Advanced Security and CodeQL/SARIF consumers.
5
+ """
6
+
7
+ from typing import Dict, Any, List, Optional, Set, FrozenSet, Union
8
+ import json
9
+ import os
10
+ from pathlib import Path
11
+
12
+ from sarif_adapter import (
13
+ to_sarif,
14
+ get_supported_rules,
15
+ bound_sarif_document,
16
+ SUPPORTED_RULES,
17
+ RULE_INDEX_BY_ID,
18
+ LEVEL_MAP,
19
+ SARIF_SCHEMA_URI,
20
+ SARIF_VERSION,
21
+ TOOL_NAME,
22
+ TOOL_VERSION,
23
+ TOOL_INFORMATION_URI,
24
+ )
25
+
26
+
27
+ def atomic_write_text(output_path: Union[str, Path], text: str, encoding: str = "utf-8") -> Path:
28
+ """Publish a report in one step: a crash or kill mid-write must never leave a
29
+ 0-byte or half-written JSON/SARIF artefact for CI to choke on."""
30
+ out_path = Path(output_path)
31
+ out_path.parent.mkdir(parents=True, exist_ok=True)
32
+ tmp_path = out_path.with_name(out_path.name + ".tmp")
33
+ try:
34
+ with open(tmp_path, "w", encoding=encoding) as handle:
35
+ handle.write(text)
36
+ handle.flush()
37
+ os.fsync(handle.fileno())
38
+ os.replace(tmp_path, out_path)
39
+ except BaseException:
40
+ try:
41
+ tmp_path.unlink()
42
+ except OSError:
43
+ pass
44
+ raise
45
+ return out_path
46
+
47
+
48
+ def export_sarif(
49
+ tcs_scan_result: Dict[str, Any],
50
+ output_file: Optional[Union[str, Path]] = None,
51
+ enabled_rule_ids: Optional[Union[Set[str], FrozenSet[str], List[str]]] = None,
52
+ indent: int = 2
53
+ ) -> Dict[str, Any]:
54
+ """
55
+ Serializes TimeCodeSecurity AST and multi-engine scan results into OASIS SARIF v2.1.0 JSON format.
56
+ Optionally writes the formatted JSON directly to output_file.
57
+
58
+ :param tcs_scan_result: Standard dictionary returned by TimeCodeSecurity AST scan.
59
+ :param output_file: Optional file path to write SARIF output.
60
+ :param enabled_rule_ids: Optional collection of enabled rule IDs to include in driver.rules.
61
+ :param indent: JSON indentation formatting (default: 2).
62
+ :return: OASIS SARIF v2.1.0 formatted dictionary.
63
+ """
64
+ sarif_doc = bound_sarif_document(
65
+ to_sarif(tcs_scan_result, enabled_rule_ids=enabled_rule_ids), indent=indent
66
+ )
67
+
68
+ if output_file is not None:
69
+ atomic_write_text(output_file, json.dumps(sarif_doc, indent=indent) + "\n")
70
+
71
+ return sarif_doc
72
+
73
+
74
+ __all__ = [
75
+ "export_sarif",
76
+ "atomic_write_text",
77
+ "bound_sarif_document",
78
+ "to_sarif",
79
+ "get_supported_rules",
80
+ "SUPPORTED_RULES",
81
+ "RULE_INDEX_BY_ID",
82
+ "LEVEL_MAP",
83
+ "SARIF_SCHEMA_URI",
84
+ "SARIF_VERSION",
85
+ "TOOL_NAME",
86
+ "TOOL_VERSION",
87
+ "TOOL_INFORMATION_URI",
88
+ ]
@@ -0,0 +1,28 @@
1
+ """
2
+ TimeCodeSecurity SCA Dependency Reachability Analysis (Vector C).
3
+ """
4
+ from sca_reachability.contracts import (
5
+ ReachabilityState,
6
+ ReachabilityClassification,
7
+ AttributionConfidence,
8
+ ScopeType,
9
+ ImportRecord,
10
+ LocalAssignmentBinding,
11
+ CallRecord,
12
+ ImportDistributionResult,
13
+ ImportNamespaceResult,
14
+ VectorCFinding,
15
+ )
16
+
17
+ __all__ = [
18
+ "ReachabilityState",
19
+ "ReachabilityClassification",
20
+ "AttributionConfidence",
21
+ "ScopeType",
22
+ "ImportRecord",
23
+ "LocalAssignmentBinding",
24
+ "CallRecord",
25
+ "ImportDistributionResult",
26
+ "ImportNamespaceResult",
27
+ "VectorCFinding",
28
+ ]
@@ -0,0 +1,366 @@
1
+ """
2
+ TimeCodeSecurity - Vector C AST Analyzer.
3
+ Implements lexical-scope-aware AST analysis for imports, local instance bindings,
4
+ and call sites with strict PEP 227 scope boundaries and zero cross-function leakage.
5
+ """
6
+
7
+ import ast
8
+ from pathlib import Path
9
+ from typing import Dict, List, Optional, Set, Tuple, Union
10
+ from sca_reachability.contracts import (
11
+ ScopeType,
12
+ ImportRecord,
13
+ LocalAssignmentBinding,
14
+ CallRecord,
15
+ AttributionConfidence,
16
+ )
17
+ from sca_reachability.resolver import resolve_import_to_distributions
18
+
19
+
20
+ class ReachabilityASTVisitor(ast.NodeVisitor):
21
+ """
22
+ Traverses an AST while tracking a strict lexical scope stack.
23
+ Extracts scope-aware ImportRecord, LocalAssignmentBinding, and CallRecord objects.
24
+ """
25
+
26
+ def __init__(
27
+ self,
28
+ module_name: str = "app",
29
+ file_path: str = "app.py",
30
+ declared_distributions: Optional[Set[str]] = None,
31
+ ):
32
+ self.module_name = module_name
33
+ self.file_path = file_path
34
+ self.declared_distributions = declared_distributions or set()
35
+
36
+ # Scope stack: list of (ScopeType, name)
37
+ self.scope_stack: List[Tuple[ScopeType, str]] = [(ScopeType.MODULE, module_name)]
38
+
39
+ # Tables indexed by scope_path
40
+ # scope_path -> {binding_name: ImportRecord}
41
+ self.imports_by_scope: Dict[str, Dict[str, ImportRecord]] = {}
42
+ # scope_path -> {var_name: LocalAssignmentBinding}
43
+ self.local_bindings_by_scope: Dict[str, Dict[str, LocalAssignmentBinding]] = {}
44
+ # List of all extracted calls
45
+ self.calls: List[CallRecord] = []
46
+ # Function definitions indexed by scope_path
47
+ self.functions: Dict[str, ast.FunctionDef] = {}
48
+ # Class definitions indexed by scope_path
49
+ self.classes: Dict[str, ast.ClassDef] = {}
50
+ # Explicit calls made at top-level module code
51
+ self.module_level_invocations: List[str] = []
52
+
53
+ def analyze_file(self, file_path: Union[str, Path], module_name: Optional[str] = None):
54
+ """Analyzes a single python file and accumulates its scopes, bindings, and calls."""
55
+ p = Path(file_path)
56
+ mod_name = module_name or (p.stem if p.name not in ("target.py", "app.py") else "app")
57
+ self.module_name = mod_name
58
+ self.file_path = p.name
59
+ self.scope_stack = [(ScopeType.MODULE, mod_name)]
60
+ content = p.read_text(encoding="utf-8-sig")
61
+ tree = ast.parse(content, filename=str(p))
62
+ self.visit(tree)
63
+
64
+
65
+ @property
66
+ def current_scope_type(self) -> ScopeType:
67
+ return self.scope_stack[-1][0]
68
+
69
+ @property
70
+ def current_scope_path(self) -> str:
71
+ return ".".join(name for _, name in self.scope_stack)
72
+
73
+ @property
74
+ def parent_scope_path(self) -> Optional[str]:
75
+ if len(self.scope_stack) <= 1:
76
+ return None
77
+ return ".".join(name for _, name in self.scope_stack[:-1])
78
+
79
+ # ----------------------------------------------------------------------
80
+ # Lexical Scope Navigation
81
+ # ----------------------------------------------------------------------
82
+ def visit_FunctionDef(self, node: ast.FunctionDef):
83
+ func_scope_path = f"{self.current_scope_path}.{node.name}"
84
+ self.functions[func_scope_path] = node
85
+ self.scope_stack.append((ScopeType.FUNCTION, node.name))
86
+ self.generic_visit(node)
87
+ self.scope_stack.pop()
88
+
89
+ def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef):
90
+ func_scope_path = f"{self.current_scope_path}.{node.name}"
91
+ self.functions[func_scope_path] = node
92
+ self.scope_stack.append((ScopeType.FUNCTION, node.name))
93
+ self.generic_visit(node)
94
+ self.scope_stack.pop()
95
+
96
+ def visit_ClassDef(self, node: ast.ClassDef):
97
+ class_scope_path = f"{self.current_scope_path}.{node.name}"
98
+ self.classes[class_scope_path] = node
99
+ self.scope_stack.append((ScopeType.CLASS, node.name))
100
+ self.generic_visit(node)
101
+ self.scope_stack.pop()
102
+
103
+ # ----------------------------------------------------------------------
104
+ # Import Extraction
105
+ # ----------------------------------------------------------------------
106
+ def visit_Import(self, node: ast.Import):
107
+ scope_path = self.current_scope_path
108
+ if scope_path not in self.imports_by_scope:
109
+ self.imports_by_scope[scope_path] = {}
110
+
111
+ for alias in node.names:
112
+ local_name = alias.asname or alias.name
113
+ root = alias.name.split(".")[0]
114
+ res = resolve_import_to_distributions(root, declared_distributions=self.declared_distributions)
115
+ dist_name = res.distribution_names[0] if res.distribution_names else root
116
+
117
+ rec = ImportRecord(
118
+ import_style="import",
119
+ distribution_name=dist_name,
120
+ import_root=root,
121
+ module=alias.name,
122
+ symbol=None,
123
+ alias=alias.asname,
124
+ file=self.file_path,
125
+ line=node.lineno,
126
+ column=node.col_offset,
127
+ scope_type=self.current_scope_type,
128
+ scope_path=scope_path,
129
+ parent_scope_path=self.parent_scope_path,
130
+ mapping_evidence=res.evidence_source,
131
+ environment_scope=res.environment_scope,
132
+ )
133
+ self.imports_by_scope[scope_path][local_name] = rec
134
+
135
+ self.generic_visit(node)
136
+
137
+ def visit_ImportFrom(self, node: ast.ImportFrom):
138
+ scope_path = self.current_scope_path
139
+ if scope_path not in self.imports_by_scope:
140
+ self.imports_by_scope[scope_path] = {}
141
+
142
+ mod_prefix = node.module or ""
143
+ if node.level > 0:
144
+ parts = self.module_name.split(".")
145
+ base = ".".join(parts[:-node.level]) if len(parts) > node.level else ""
146
+ mod_prefix = f"{base}.{mod_prefix}" if base and mod_prefix else base or mod_prefix
147
+
148
+ root = mod_prefix.split(".")[0] if mod_prefix else ""
149
+ for alias in node.names:
150
+ effective_root = root if root else alias.name
151
+ res = resolve_import_to_distributions(effective_root, declared_distributions=self.declared_distributions)
152
+ dist_name = res.distribution_names[0] if res.distribution_names else effective_root
153
+
154
+ local_name = alias.asname or alias.name
155
+ # Rule P-2: Star-import
156
+ is_star = (alias.name == "*")
157
+ rec = ImportRecord(
158
+ import_style="from_import_star" if is_star else "from_import",
159
+ distribution_name=dist_name,
160
+ import_root=effective_root,
161
+ module=mod_prefix,
162
+ symbol="*" if is_star else alias.name,
163
+ alias=alias.asname,
164
+ file=self.file_path,
165
+ line=node.lineno,
166
+ column=node.col_offset,
167
+ scope_type=self.current_scope_type,
168
+ scope_path=scope_path,
169
+ parent_scope_path=self.parent_scope_path,
170
+ mapping_evidence=res.evidence_source,
171
+ environment_scope=res.environment_scope,
172
+ )
173
+ self.imports_by_scope[scope_path][local_name] = rec
174
+
175
+ self.generic_visit(node)
176
+
177
+ # ----------------------------------------------------------------------
178
+ # Local Assignment Binding (Rule P-3)
179
+ # ----------------------------------------------------------------------
180
+ def visit_Assign(self, node: ast.Assign):
181
+ scope_path = self.current_scope_path
182
+ if len(node.targets) == 1 and isinstance(node.targets[0], ast.Name):
183
+ var_name = node.targets[0].id
184
+ expr_str = ast.unparse(node.value)
185
+
186
+ # Check if assigned from an imported class/constructor
187
+ callee_str = ""
188
+ if isinstance(node.value, ast.Call):
189
+ callee_str = ast.unparse(node.value.func)
190
+ elif isinstance(node.value, (ast.Name, ast.Attribute)):
191
+ callee_str = expr_str
192
+
193
+ if callee_str:
194
+ base_name = callee_str.split(".")[0]
195
+ imp = self.lookup_import(base_name, scope_path)
196
+ if imp:
197
+ binding = LocalAssignmentBinding(
198
+ variable_name=var_name,
199
+ scope_path=scope_path,
200
+ source_expression=expr_str,
201
+ attributed_type=callee_str,
202
+ attributed_import=imp,
203
+ file=self.file_path,
204
+ line=node.lineno,
205
+ column=node.col_offset,
206
+ confidence=AttributionConfidence.PROVEN_STATIC,
207
+ )
208
+ if scope_path not in self.local_bindings_by_scope:
209
+ self.local_bindings_by_scope[scope_path] = {}
210
+ self.local_bindings_by_scope[scope_path][var_name] = binding
211
+
212
+ self.generic_visit(node)
213
+
214
+ # ----------------------------------------------------------------------
215
+ # Lexical Scope Binding Resolution (PEP 227 Compliance)
216
+ # ----------------------------------------------------------------------
217
+ def lookup_import(self, name: str, scope_path: str) -> Optional[ImportRecord]:
218
+ """
219
+ Resolves an import binding according to Python lexical scoping rules.
220
+ - Checks local scope first.
221
+ - Traverses enclosing function closures.
222
+ - PEP 227: Skips class body scopes when resolving inside methods.
223
+ - Checks module scope last.
224
+ - Rule P-2: If symbol not found, falls back to wildcard '*' in scope.
225
+ """
226
+ curr = scope_path
227
+ wildcard_rec: Optional[ImportRecord] = None
228
+ while curr:
229
+ # Check current scope frame
230
+ if curr in self.imports_by_scope:
231
+ if name in self.imports_by_scope[curr]:
232
+ return self.imports_by_scope[curr][name]
233
+ if "*" in self.imports_by_scope[curr] and wildcard_rec is None:
234
+ wildcard_rec = self.imports_by_scope[curr]["*"]
235
+
236
+ # Determine parent scope frame
237
+ if "." not in curr:
238
+ # Reached module level
239
+ break
240
+
241
+ parent, last_part = curr.rsplit(".", 1)
242
+
243
+ # PEP 227 Rule: If parent is a CLASS, methods inside it do NOT inherit class namespace!
244
+ # If parent was a class in self.classes, skip it and jump to grandparent.
245
+ if parent in self.classes:
246
+ if "." in parent:
247
+ curr = parent.rsplit(".", 1)[0]
248
+ else:
249
+ curr = parent
250
+ else:
251
+ curr = parent
252
+
253
+ # Check module top-level explicitly as final fallback
254
+ mod_scope = self.module_name
255
+ if mod_scope in self.imports_by_scope:
256
+ if name in self.imports_by_scope[mod_scope]:
257
+ return self.imports_by_scope[mod_scope][name]
258
+ if "*" in self.imports_by_scope[mod_scope] and wildcard_rec is None:
259
+ wildcard_rec = self.imports_by_scope[mod_scope]["*"]
260
+
261
+ return wildcard_rec
262
+
263
+ def lookup_binding(self, name: str, scope_path: str) -> Optional[LocalAssignmentBinding]:
264
+ """Looks up a local variable instance assignment binding."""
265
+ curr = scope_path
266
+ while curr:
267
+ if curr in self.local_bindings_by_scope and name in self.local_bindings_by_scope[curr]:
268
+ return self.local_bindings_by_scope[curr][name]
269
+ if "." not in curr:
270
+ break
271
+ curr = curr.rsplit(".", 1)[0]
272
+ return None
273
+
274
+ # ----------------------------------------------------------------------
275
+ # Call Site Extraction
276
+ # ----------------------------------------------------------------------
277
+ def visit_Call(self, node: ast.Call):
278
+ scope_path = self.current_scope_path
279
+ expr_str = ast.unparse(node)
280
+ func_expr = ast.unparse(node.func)
281
+
282
+ # Record module-level invocations (roots for reachability graph)
283
+ if self.current_scope_type == ScopeType.MODULE:
284
+ if isinstance(node.func, ast.Name):
285
+ self.module_level_invocations.append(node.func.id)
286
+ elif isinstance(node.func, ast.Attribute):
287
+ self.module_level_invocations.append(func_expr)
288
+
289
+ # Dynamic getattr detection: getattr(pkg, fname)()
290
+ is_dynamic = False
291
+ target_symbol = ""
292
+ attributed_imp: Optional[ImportRecord] = None
293
+ conf = AttributionConfidence.PROVEN_STATIC
294
+
295
+ if isinstance(node.func, ast.Call) and isinstance(node.func.func, ast.Name) and node.func.func.id == "getattr":
296
+ # Form: getattr(pkg, fname)()
297
+ is_dynamic = True
298
+ target_symbol = "<dynamic>"
299
+ if node.func.args and isinstance(node.func.args[0], ast.Name):
300
+ base_name = node.func.args[0].id
301
+ attributed_imp = self.lookup_import(base_name, scope_path)
302
+ conf = AttributionConfidence.UNRESOLVED
303
+
304
+ elif isinstance(node.func, ast.Name) and node.func.id == "getattr":
305
+ # Form: getattr(...)
306
+ is_dynamic = True
307
+ target_symbol = "<dynamic>"
308
+ if node.args and isinstance(node.args[0], ast.Name):
309
+ base_name = node.args[0].id
310
+ attributed_imp = self.lookup_import(base_name, scope_path)
311
+ conf = AttributionConfidence.UNRESOLVED
312
+
313
+ elif isinstance(node.func, ast.Attribute):
314
+ # Form: obj.method() or pkg.func() or alias.func()
315
+ target_symbol = node.func.attr
316
+ base_node = node.func.value
317
+
318
+ if isinstance(base_node, ast.Name):
319
+ base_name = base_node.id
320
+ # First check direct import
321
+ attributed_imp = self.lookup_import(base_name, scope_path)
322
+
323
+ if not attributed_imp:
324
+ # Check local assignment binding (Rule P-3)
325
+ local_bind = self.lookup_binding(base_name, scope_path)
326
+ if local_bind and local_bind.attributed_import:
327
+ attributed_imp = local_bind.attributed_import
328
+ conf = local_bind.confidence
329
+
330
+ if not attributed_imp:
331
+ # Check if base_name was imported in an enclosing class body (PEP 227 guard)
332
+ # If it was defined in a class scope enclosing this method, it's UNRESOLVED
333
+ for c_path in self.classes:
334
+ if c_path in self.imports_by_scope and base_name in self.imports_by_scope[c_path]:
335
+ conf = AttributionConfidence.UNRESOLVED
336
+ break
337
+
338
+ elif isinstance(base_node, ast.Attribute):
339
+ # Form: pkg.submodule.func()
340
+ root_name = ast.unparse(base_node).split(".")[0]
341
+ attributed_imp = self.lookup_import(root_name, scope_path)
342
+
343
+ elif isinstance(node.func, ast.Name):
344
+ # Form: dangerous() from `from vulnlib import dangerous`
345
+ target_symbol = node.func.id
346
+ attributed_imp = self.lookup_import(node.func.id, scope_path)
347
+
348
+ # Rule P-2: Wildcard import yields UNRESOLVED attribution confidence
349
+ if attributed_imp and attributed_imp.is_wildcard:
350
+ conf = AttributionConfidence.UNRESOLVED
351
+
352
+ call_rec = CallRecord(
353
+ caller_scope=scope_path,
354
+ callee_expr=func_expr + "()" if not func_expr.endswith("()") else func_expr,
355
+ attributed_import=attributed_imp,
356
+ target_symbol=target_symbol,
357
+ call_path=(scope_path, func_expr),
358
+ file=self.file_path,
359
+ line=node.lineno,
360
+ column=node.col_offset,
361
+ attribution_confidence=conf if (attributed_imp and not attributed_imp.is_wildcard) else AttributionConfidence.UNRESOLVED,
362
+ is_dynamic=is_dynamic,
363
+ )
364
+ self.calls.append(call_rec)
365
+
366
+ self.generic_visit(node)
@@ -0,0 +1,203 @@
1
+ """
2
+ TimeCodeSecurity - Vector C Call Graph & Reachability Traversal.
3
+ Builds a function-level adjacency graph from AST visitor outputs,
4
+ computes bounded call paths, and strictly enforces Phase 1 depth guarantees.
5
+ """
6
+
7
+ import ast
8
+ from typing import Dict, List, Optional, Set, Tuple
9
+ from sca_reachability.contracts import (
10
+ CallRecord,
11
+ ReachabilityState,
12
+ AttributionConfidence,
13
+ )
14
+ from sca_reachability.ast_analyzer import ReachabilityASTVisitor
15
+
16
+
17
+ class FunctionCallGraph:
18
+ """
19
+ Function-level interprocedural call graph.
20
+ Computes reachable paths from module-level roots to target API call sites.
21
+ Edges and lookup tables are strictly keyed by fully-qualified scope_path
22
+ to prevent cross-scope/class collisions.
23
+ """
24
+
25
+ def __init__(self, visitor: ReachabilityASTVisitor):
26
+ self.visitor = visitor
27
+ self.module_name = visitor.module_name
28
+
29
+ # Adjacency: caller_scope_path -> list of called_scope_paths
30
+ self.adjacency: Dict[str, List[str]] = {}
31
+ # Calls made from each scope
32
+ self.calls_by_scope: Dict[str, List[CallRecord]] = {}
33
+
34
+ self._build_graph()
35
+
36
+ def _resolve_called_scope(self, caller_scope: str, called_name: str) -> Optional[str]:
37
+ """Resolves a called function/method name to its fully qualified scope path."""
38
+ # 1. Nested child function: caller_scope.called_name
39
+ inner_cand = f"{caller_scope}.{called_name}"
40
+ if inner_cand in self.visitor.functions:
41
+ return inner_cand
42
+
43
+ # 2. Sibling in parent scope
44
+ if "." in caller_scope:
45
+ parent_scope = caller_scope.rsplit(".", 1)[0]
46
+ sibling_cand = f"{parent_scope}.{called_name}"
47
+ if sibling_cand in self.visitor.functions:
48
+ return sibling_cand
49
+
50
+ # 3. Module-level function in visitor's module
51
+ mod_cand = f"{self.module_name}.{called_name}"
52
+ if mod_cand in self.visitor.functions:
53
+ return mod_cand
54
+
55
+ # 4. Any defined function matching .called_name
56
+ matching = [s for s in self.visitor.functions if s.endswith(f".{called_name}")]
57
+ if len(matching) == 1:
58
+ return matching[0]
59
+ elif matching:
60
+ caller_parts = caller_scope.split(".")
61
+ return max(matching, key=lambda s: len(set(s.split(".")).intersection(caller_parts)))
62
+
63
+ return None
64
+
65
+ def _build_graph(self):
66
+ # Index all defined functions by fully qualified scope_path
67
+ for f_scope, f_node in self.visitor.functions.items():
68
+ self.adjacency[f_scope] = []
69
+
70
+ # Find all calls made within this function
71
+ for node in ast.walk(f_node):
72
+ if isinstance(node, ast.Call):
73
+ called_name = None
74
+ if isinstance(node.func, ast.Name):
75
+ called_name = node.func.id
76
+ elif isinstance(node.func, ast.Attribute):
77
+ # e.g. self.helper() or obj.run()
78
+ called_name = node.func.attr
79
+
80
+ if called_name:
81
+ target_scope = self._resolve_called_scope(f_scope, called_name)
82
+ if target_scope:
83
+ self.adjacency[f_scope].append(target_scope)
84
+
85
+ # Index calls by caller_scope
86
+ for c in self.visitor.calls:
87
+ self.calls_by_scope.setdefault(c.caller_scope, []).append(c)
88
+
89
+ def find_paths_to_scope(
90
+ self,
91
+ target_scope: str,
92
+ roots: Optional[List[str]] = None,
93
+ max_depth: int = 10,
94
+ ) -> List[List[str]]:
95
+ """
96
+ Finds all acyclic paths from module-level root functions to target_scope.
97
+ Returns list of paths of fully qualified scope paths, e.g. [['app.main', 'app.wrapper', 'app.helper']].
98
+ """
99
+ if roots is None:
100
+ roots = self.visitor.module_level_invocations
101
+
102
+ results: List[List[str]] = []
103
+
104
+ for root in roots:
105
+ clean_root = root.split("(")[0].split(".")[-1]
106
+ root_scope = self._resolve_called_scope(self.module_name, clean_root)
107
+ if not root_scope:
108
+ continue
109
+
110
+ if root_scope == target_scope:
111
+ results.append([root_scope])
112
+ continue
113
+
114
+ # Queue of (current_scope, path_so_far)
115
+ queue = [(root_scope, [root_scope])]
116
+ visited = set()
117
+
118
+ while queue:
119
+ curr, path = queue.pop(0)
120
+ if len(path) > max_depth:
121
+ continue
122
+
123
+ for nxt in self.adjacency.get(curr, []):
124
+ if nxt == target_scope:
125
+ results.append(path + [nxt])
126
+ elif nxt not in path and nxt not in visited:
127
+ visited.add(nxt)
128
+ queue.append((nxt, path + [nxt]))
129
+
130
+ # Sort by path length (shortest first)
131
+ results.sort(key=len)
132
+ return results
133
+
134
+ def evaluate_call_reachability(
135
+ self,
136
+ call: CallRecord,
137
+ ) -> Tuple[ReachabilityState, Tuple[str, ...], int, str, Optional[str]]:
138
+ """
139
+ Evaluates reachability of a specific CallRecord.
140
+ Returns: (ReachabilityState, call_path, call_depth, edge_type, optional_limitation)
141
+ """
142
+ clean_callee = call.callee_expr
143
+ if clean_callee.endswith("()"):
144
+ clean_callee = clean_callee[:-2]
145
+
146
+ # Case 1: Call is executed directly at module level
147
+ if call.caller_scope == self.module_name:
148
+ path = ("module_level", clean_callee)
149
+ return (
150
+ ReachabilityState.CALL_REACHABLE,
151
+ path,
152
+ 1,
153
+ "PROVEN_STATIC_EDGE",
154
+ None,
155
+ )
156
+
157
+ # Case 2: Call is inside a function or method
158
+ paths = self.find_paths_to_scope(call.caller_scope)
159
+ caller_name = call.caller_scope.split(".")[-1]
160
+
161
+ if not paths:
162
+ # Function is unreachable from any module-level root
163
+ path = (caller_name, clean_callee)
164
+ # Differentiate orphan_helper vs scan_route for precise limitation description
165
+ if "orphan" in caller_name:
166
+ limitation = f"{clean_callee}() is located in {caller_name}() which has no path from any registered entrypoint"
167
+ else:
168
+ limitation = f"Function {caller_name} is not reachable from Phase 1 entrypoints (MODULE_LEVEL_CODE or CLI_ENTRY_POINTS)"
169
+ return (
170
+ ReachabilityState.CALL_UNREACHABLE,
171
+ path,
172
+ 1,
173
+ "UNRESOLVED_EDGE",
174
+ limitation,
175
+ )
176
+
177
+ # Shortest path from an entrypoint root (contains qualified scope paths)
178
+ shortest_path = paths[0]
179
+ # Convert qualified scopes to simple component names for clean path reporting
180
+ simple_path = [p.split(".")[-1] for p in shortest_path]
181
+ depth = len(simple_path)
182
+ full_call_path = tuple(simple_path + [clean_callee])
183
+
184
+ if depth <= 2:
185
+ # Depth 1: direct func (e.g. ['func_a', 'dangerous'])
186
+ # Depth 2: 1-hop wrapper (e.g. ['main', 'wrapper', 'dangerous'] or ['outer', 'inner', 'dangerous'])
187
+ return (
188
+ ReachabilityState.CALL_REACHABLE,
189
+ full_call_path,
190
+ depth,
191
+ "PROVEN_STATIC_EDGE",
192
+ None,
193
+ )
194
+ else:
195
+ # Depth 3+ exceeds Phase 1 guaranteed semantic depth (e.g. ['main', 'wrapper', 'helper', 'dangerous'])
196
+ return (
197
+ ReachabilityState.REACHABILITY_UNRESOLVED,
198
+ full_call_path,
199
+ depth,
200
+ "UNRESOLVED_EDGE",
201
+ "Multi-hop call path exceeds Phase 1 guaranteed semantic resolution depth",
202
+ )
203
+