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
function_summarizer.py ADDED
@@ -0,0 +1,354 @@
1
+ """
2
+ TimeCodeSecurity - Phase 4: Function Summary Extractor
3
+ Extracts deterministic taint contracts (Param -> Return, Param -> Sink) per function.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ import ast
9
+ import sys
10
+ from dataclasses import dataclass, field
11
+ from pathlib import Path
12
+ from typing import Dict, List, Optional, Set, Tuple
13
+
14
+ from symbol_indexer import GlobalSymbolIndex, SymbolDefinition
15
+
16
+
17
+ KNOWN_SINKS = {
18
+ # CWE-89: SQL Injection
19
+ "execute": "CWE-89",
20
+ "executemany": "CWE-89",
21
+ "raw": "CWE-89",
22
+ # CWE-78: Command Injection
23
+ "system": "CWE-78",
24
+ "popen": "CWE-78",
25
+ "check_output": "CWE-78",
26
+ "call": "CWE-78",
27
+ "run": "CWE-78",
28
+ # CWE-95 / 94: Code Exec
29
+ "eval": "CWE-95",
30
+ "exec": "CWE-94",
31
+ # CWE-502: Deserialization
32
+ "loads": "CWE-502",
33
+ "load": "CWE-502",
34
+ # CWE-22: Path Traversal
35
+ "open": "CWE-22",
36
+ }
37
+
38
+ KNOWN_SANITIZERS = {
39
+ "int", "float", "bool", "len", "escape", "quote", "sha256", "md5"
40
+ }
41
+
42
+
43
+ def _has_static_decorator(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
44
+ """True for a @staticmethod, whose first parameter is a real argument, not a receiver."""
45
+ for decorator in node.decorator_list:
46
+ if isinstance(decorator, ast.Name) and decorator.id == "staticmethod":
47
+ return True
48
+ if isinstance(decorator, ast.Attribute) and decorator.attr == "staticmethod":
49
+ return True
50
+ return False
51
+
52
+
53
+ def _const_str(node: Optional[ast.AST]) -> Optional[str]:
54
+ """The literal string a key expression holds, or None when it is not one."""
55
+ if isinstance(node, ast.Index): # Python < 3.9 keeps `d["k"]` as ast.Index
56
+ node = node.value
57
+ if isinstance(node, ast.Constant) and isinstance(node.value, str):
58
+ return node.value
59
+ return None
60
+
61
+
62
+ @dataclass(slots=True)
63
+ class ParamSinkEdge:
64
+ param_idx: int
65
+ param_name: str
66
+ sink_cwe: str
67
+ sink_name: str
68
+ lineno: int
69
+
70
+
71
+ @dataclass
72
+ class FunctionSummary:
73
+ qualname: str
74
+ file_path: str
75
+ lineno: int
76
+ params: list[str] = field(default_factory=list)
77
+ tainted_returns: set[int] = field(default_factory=set) # indices of params that reach 'return'
78
+ param_sinks: list[ParamSinkEdge] = field(default_factory=list) # params that hit an internal sink
79
+ is_sanitizer: bool = False
80
+ # True when the signature opens with self/cls, i.e. params excludes a bound receiver.
81
+ # Callers that invoke the method unbound (Class.method(instance, ...)) must skip one
82
+ # positional argument so parameter indices stay aligned with params.
83
+ takes_receiver: bool = False
84
+
85
+
86
+ class FunctionSummarizer:
87
+ """Pass 1.5: Computes taint contracts for all indexed functions."""
88
+
89
+ def __init__(self, indexer: GlobalSymbolIndex):
90
+ self.indexer = indexer
91
+ self.summaries: dict[tuple[str, str], FunctionSummary] = {} # (mod_name, func_name) -> Summary
92
+
93
+ def build_all_summaries(self) -> dict[tuple[str, str], FunctionSummary]:
94
+ for mod_name, mod_idx in self.indexer.modules.items():
95
+ tree = self.indexer._ast_cache.get(mod_name)
96
+ if not tree:
97
+ continue
98
+ self.summarize_module(mod_name, mod_idx.file_path, tree)
99
+
100
+ return self.summaries
101
+
102
+ def summarize_module(self, mod_name: str, file_path, tree: ast.AST) -> list[FunctionSummary]:
103
+ """Summarise one module's top-level functions and methods; returns what it created.
104
+
105
+ The streaming indexer calls this as each file is parsed, so the tree can be released
106
+ immediately; `build_all_summaries` calls the same code over the cached trees, which
107
+ keeps insertion order (and therefore every downstream iteration) identical.
108
+ """
109
+ path_str = str(file_path)
110
+ created: list[FunctionSummary] = []
111
+ for stmt in tree.body:
112
+ if isinstance(stmt, (ast.FunctionDef, ast.AsyncFunctionDef)):
113
+ summary = self._summarize_function(stmt, mod_name, path_str)
114
+ self.summaries[(mod_name, stmt.name)] = summary
115
+ created.append(summary)
116
+ elif isinstance(stmt, ast.ClassDef):
117
+ for item in stmt.body:
118
+ if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
119
+ qual = f"{stmt.name}.{item.name}"
120
+ summary = self._summarize_function(
121
+ item, mod_name, path_str,
122
+ qualname=qual, is_method=True,
123
+ )
124
+ self.summaries[(mod_name, qual)] = summary
125
+ created.append(summary)
126
+ return created
127
+
128
+ def _summarize_function(
129
+ self,
130
+ node: ast.FunctionDef | ast.AsyncFunctionDef,
131
+ mod_name: str,
132
+ file_path: str,
133
+ qualname: Optional[str] = None,
134
+ is_method: bool = False,
135
+ ) -> FunctionSummary:
136
+ name = qualname or node.name
137
+ takes_receiver = bool(
138
+ is_method
139
+ and not _has_static_decorator(node)
140
+ and node.args.args
141
+ and node.args.args[0].arg in ("self", "cls")
142
+ )
143
+ params = [a.arg for a in (node.args.args[1:] if takes_receiver else node.args.args)]
144
+ kw_containers, kw_slots = self._kwarg_slots(node, params)
145
+ params = params + kw_slots
146
+ param_to_idx = {p: i for i, p in enumerate(params)}
147
+
148
+ summary = FunctionSummary(
149
+ qualname=name,
150
+ file_path=file_path,
151
+ lineno=node.lineno,
152
+ params=params,
153
+ takes_receiver=takes_receiver,
154
+ )
155
+
156
+ # Sanitizer heuristic
157
+ if any(san in name.lower() for san in KNOWN_SANITIZERS):
158
+ summary.is_sanitizer = True
159
+
160
+ # Intra-function variable flow tracking
161
+ # Maps local_var -> set of param indices it was derived from
162
+ alias_map: dict[str, set[int]] = {p: {i} for i, p in enumerate(params)}
163
+ # Collecting the sanitized locals and the Return nodes inside the sweep below replaces
164
+ # two extra full traversals of the same body. The walk order is identical to the
165
+ # dedicated passes it replaces (same `for stmt in node.body` / `ast.walk(stmt)` nesting),
166
+ # so the add/discard sequence for `sanitized` is unchanged and every Return is still
167
+ # evaluated against the finished alias_map by the post-loop check.
168
+ returns: list[ast.Return] = []
169
+ sanitized: Set[str] = set()
170
+
171
+ for stmt in node.body:
172
+ for sub in ast.walk(stmt):
173
+ # 1. Track assignments: local_var = param
174
+ if isinstance(sub, ast.Assign):
175
+ callee = (
176
+ self._callee_name(sub.value.func)
177
+ if isinstance(sub.value, ast.Call)
178
+ else None
179
+ )
180
+ produced_by_sanitizer = callee in KNOWN_SANITIZERS
181
+ for target in sub.targets:
182
+ if isinstance(target, ast.Name):
183
+ if produced_by_sanitizer:
184
+ sanitized.add(target.id)
185
+ else:
186
+ sanitized.discard(target.id)
187
+
188
+ val_params = self._resolve_referenced_params(sub.value, alias_map, kw_containers)
189
+ if val_params:
190
+ for target in sub.targets:
191
+ if isinstance(target, ast.Name):
192
+ alias_map.setdefault(target.id, set()).update(val_params)
193
+
194
+ # 2. Track Returns: return param / return expr(param)
195
+ elif isinstance(sub, ast.Return) and sub.value is not None:
196
+ returns.append(sub)
197
+ ret_params = self._resolve_referenced_params(sub.value, alias_map, kw_containers)
198
+ summary.tainted_returns.update(ret_params)
199
+
200
+ # 3. Track Sinks: sink_call(param)
201
+ elif isinstance(sub, ast.Call):
202
+ call_name = ""
203
+ if isinstance(sub.func, ast.Name):
204
+ call_name = sub.func.id
205
+ elif isinstance(sub.func, ast.Attribute):
206
+ call_name = sub.func.attr
207
+
208
+ cwe = KNOWN_SINKS.get(call_name)
209
+ if cwe:
210
+ for position, arg in enumerate(sub.args):
211
+ # DB-API semantics: execute(operation, parameters) interpolates
212
+ # only the operation slot into the statement, so taint that reaches
213
+ # the parameters slot is bound by the driver and not injectable.
214
+ if cwe == "CWE-89" and position > 0:
215
+ continue
216
+ arg_params = self._resolve_referenced_params(arg, alias_map, kw_containers)
217
+ for p_idx in arg_params:
218
+ edge = ParamSinkEdge(
219
+ param_idx=p_idx,
220
+ param_name=params[p_idx],
221
+ sink_cwe=cwe,
222
+ sink_name=call_name,
223
+ lineno=getattr(sub, "lineno", stmt.lineno),
224
+ )
225
+ summary.param_sinks.append(edge)
226
+
227
+ # Body-level sanitizer evidence: the name heuristic above misses helpers such as
228
+ # `format_command` that sanitize through a call rather than through their own name.
229
+ if not summary.is_sanitizer and params and not summary.param_sinks:
230
+ propagating = [
231
+ ret.value
232
+ for ret in returns
233
+ if self._resolve_referenced_params(ret.value, alias_map, kw_containers)
234
+ ]
235
+ if propagating and all(
236
+ self._is_sanitized_expr(expr, sanitized) for expr in propagating
237
+ ):
238
+ summary.is_sanitizer = True
239
+
240
+ return summary
241
+
242
+ @staticmethod
243
+ def _callee_name(node: ast.AST) -> Optional[str]:
244
+ if isinstance(node, ast.Name):
245
+ return node.id
246
+ if isinstance(node, ast.Attribute):
247
+ return node.attr
248
+ return None
249
+
250
+ def _is_sanitized_expr(self, expr: ast.AST, sanitized_locals: Set[str]) -> bool:
251
+ if isinstance(expr, ast.Call):
252
+ return self._callee_name(expr.func) in KNOWN_SANITIZERS
253
+ if isinstance(expr, ast.Name):
254
+ return expr.id in sanitized_locals
255
+ return False
256
+
257
+ def _resolve_referenced_params(
258
+ self,
259
+ expr: ast.AST,
260
+ alias_map: dict[str, set[int]],
261
+ kw_containers: frozenset[str] = frozenset(),
262
+ ) -> set[int]:
263
+ referenced: set[int] = set()
264
+ for node in ast.walk(expr):
265
+ if isinstance(node, ast.Name) and node.id in alias_map:
266
+ referenced.update(alias_map[node.id])
267
+ elif kw_containers:
268
+ slot = self._kwarg_slot(node, kw_containers)
269
+ if slot is not None and f"{slot[0]}[{slot[1]}]" in alias_map:
270
+ referenced.update(alias_map[f"{slot[0]}[{slot[1]}]"])
271
+ return referenced
272
+
273
+ @staticmethod
274
+ def _kwarg_slot(node: ast.AST, kw_containers: frozenset[str]) -> Optional[tuple[str, str]]:
275
+ """(container, literal key) for `kwargs["k"]` / `kwargs.get("k")` reads."""
276
+ if isinstance(node, ast.Subscript) and isinstance(node.value, ast.Name):
277
+ if node.value.id in kw_containers:
278
+ key = _const_str(node.slice)
279
+ return (node.value.id, key) if key is not None else None
280
+ return None
281
+ if (isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute)
282
+ and node.func.attr in ("get", "pop") and node.args
283
+ and isinstance(node.func.value, ast.Name)
284
+ and node.func.value.id in kw_containers):
285
+ key = _const_str(node.args[0])
286
+ return (node.func.value.id, key) if key is not None else None
287
+ return None
288
+
289
+ @staticmethod
290
+ def _kwarg_slots(
291
+ node: ast.FunctionDef | ast.AsyncFunctionDef,
292
+ params: list[str],
293
+ ) -> tuple[frozenset[str], list[str]]:
294
+ """Per-key contract slots for a `**kwargs` parameter.
295
+
296
+ Django signal receivers take their payload through `**kwargs`, so a receiver such as
297
+ `def on_event(sender, **kwargs): os.system(kwargs["payload"])` has no positional
298
+ parameter to bind the emission keyword onto. Only the literal keys the body actually
299
+ reads become slots, which keeps each payload key tracked on its own instead of tainting
300
+ the whole mapping.
301
+ """
302
+ if node.args.kwarg is None:
303
+ return frozenset(), []
304
+ container = node.args.kwarg.arg
305
+ if container in params:
306
+ return frozenset(), []
307
+ slots: list[str] = []
308
+ seen = {container}
309
+ for sub in ast.walk(node):
310
+ slot = FunctionSummarizer._kwarg_slot(sub, frozenset({container}))
311
+ if slot is None:
312
+ continue
313
+ virtual = f"{slot[0]}[{slot[1]}]"
314
+ if virtual not in seen:
315
+ seen.add(virtual)
316
+ slots.append(virtual)
317
+ return frozenset({container}), slots
318
+
319
+
320
+ if __name__ == "__main__":
321
+ import time
322
+
323
+ target_dir = sys.argv[1] if len(sys.argv) > 1 else "."
324
+ print(f"[*] Building Symbol Index for: {target_dir}")
325
+ indexer = GlobalSymbolIndex(target_dir).build()
326
+
327
+ print("[*] Extracting Function Taint Contracts...")
328
+ t0 = time.perf_counter()
329
+ summarizer = FunctionSummarizer(indexer)
330
+ contracts = summarizer.build_all_summaries()
331
+ elapsed = (time.perf_counter() - t0) * 1000
332
+
333
+ total_funcs = len(contracts)
334
+ funcs_with_sinks = sum(1 for c in contracts.values() if c.param_sinks)
335
+ funcs_with_returns = sum(1 for c in contracts.values() if c.tainted_returns)
336
+
337
+ print("\n--- FUNCTION TAINT CONTRACTS SUMMARY ---")
338
+ print(f"Total Functions Summarized: {total_funcs}")
339
+ print(f"Functions Propagating to Return: {funcs_with_returns}")
340
+ print(f"Functions Leading to Sinks: {funcs_with_sinks}")
341
+ print(f"Contract Analysis Time: {elapsed:.2f} ms")
342
+
343
+ # Sample dangerous sink contracts
344
+ if funcs_with_sinks > 0:
345
+ print("\n[+] Top Identified Sink Contracts:")
346
+ count = 0
347
+ for (m, f), c in contracts.items():
348
+ for s in c.param_sinks:
349
+ print(f" • {m}.{f}(param '{s.param_name}') -> {s.sink_name} [{s.sink_cwe}] at line {s.lineno}")
350
+ count += 1
351
+ if count >= 5:
352
+ break
353
+ if count >= 5:
354
+ break
html_auditor.py ADDED
@@ -0,0 +1,274 @@
1
+ """HTML / Jinja / Django template security auditor for TimeCodeSecurity.
2
+
3
+ Performs concrete HTML-node analysis over server-side templates using the standard
4
+ library ``html.parser``. Three rules are implemented:
5
+
6
+ * CWE-353 -- Missing Subresource Integrity (SRI) on externally hosted subresources.
7
+ * CWE-352 -- State-changing ``<form>`` without a CSRF token in its body.
8
+ * CWE-79 -- Django ``{{ value|safe }}`` output: the ``safe`` filter turns off the
9
+ auto-escaping that otherwise protects every template variable.
10
+
11
+ The rules are deterministic: findings are derived from parsed tag nodes, their
12
+ attribute maps, and the raw character data contained between an opening and
13
+ closing ``<form>`` tag. No path allow-listing is performed. The CSRF and SRI rules read
14
+ parsed nodes only; the ``|safe`` rule scans the character text of those nodes, because the
15
+ Django expression is markup content rather than a tag or attribute.
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ import re
21
+ from html.parser import HTMLParser
22
+ from typing import Any, Dict, List, Optional, Sequence, Tuple
23
+
24
+ TEMPLATE_SUFFIXES: Tuple[str, ...] = (".html", ".htm", ".jinja", ".jinja2", ".j2", ".dtl")
25
+
26
+ # A subresource is externally hosted when its URL carries an explicit scheme or is
27
+ # protocol-relative. Local and framework-static assets are out of scope for SRI.
28
+ EXTERNAL_URL_PREFIXES: Tuple[str, ...] = ("http://", "https://", "//")
29
+
30
+ # HTML form methods that mutate server state and therefore require CSRF protection.
31
+ STATE_CHANGING_FORM_METHODS = frozenset({"post", "put", "patch", "delete"})
32
+
33
+ # Django/Jinja CSRF token markers. ``csrfmiddlewaretoken`` covers the rendered
34
+ # <input type="hidden"> form of the token as well as the template tag itself.
35
+ CSRF_TOKEN_MARKERS: Tuple[str, ...] = ("csrf_token", "csrfmiddlewaretoken")
36
+
37
+ # Django's ``safe`` filter declares a variable to be trusted HTML and stops the template engine
38
+ # from escaping it, which is exactly how a stored or reflected XSS reaches the browser.
39
+ UNESCAPED_OUTPUT_RE = re.compile(r"\{\{\s*([^{}]+?)\s*\|\s*safe\s*\}\}")
40
+
41
+ # Text inside these tags is sample code shown to the reader, not markup the template renders, so
42
+ # a ``|safe`` written there documents a vulnerability instead of creating one.
43
+ VERBATIM_TAGS = frozenset({"pre", "code", "textarea", "samp", "kbd"})
44
+
45
+ # Expressions that never carry client HTML: Django's own CSRF token, and ``form.<field>`` widget
46
+ # renders, whose markup the framework builds and escapes itself, so ``|safe`` on them is a no-op.
47
+ ALWAYS_SAFE_EXPRESSION_ROOTS = frozenset({"csrf_token", "csrfmiddlewaretoken"})
48
+
49
+ # .. except when the render reaches into bound data: ``form.field.value`` *is* the submitted
50
+ # request text, and marking that safe reproduces it raw, so those expressions stay reported.
51
+ FORM_USER_DATA_SEGMENTS = frozenset({"value", "data", "initial"})
52
+
53
+ UNESCAPED_OUTPUT_MESSAGE = (
54
+ "CWE-79: Unescaped dynamic content marked safe or rendered directly in HTTP response"
55
+ )
56
+
57
+
58
+ def is_template_path(path: str) -> bool:
59
+ """Return True when *path* carries a server-side template suffix."""
60
+ lowered = str(path).lower()
61
+ return lowered.endswith(TEMPLATE_SUFFIXES)
62
+
63
+
64
+ def _normalize_attrs(attrs: Sequence[Tuple[str, Optional[str]]]) -> Dict[str, str]:
65
+ """Fold an HTMLParser attribute list into a lowercase-keyed string map."""
66
+ normalized: Dict[str, str] = {}
67
+ for key, value in attrs:
68
+ if key is None:
69
+ continue
70
+ normalized[key.lower()] = value if value is not None else ""
71
+ return normalized
72
+
73
+
74
+ def _is_external_url(url: Optional[str]) -> bool:
75
+ if not url:
76
+ return False
77
+ return url.strip().startswith(EXTERNAL_URL_PREFIXES)
78
+
79
+
80
+ class TemplateSecurityAuditor(HTMLParser):
81
+ """Collects CWE-353, CWE-352 and CWE-79 findings from a single template document."""
82
+
83
+ def __init__(self, file_path: str) -> None:
84
+ super().__init__(convert_charrefs=True)
85
+ self.file_path = file_path
86
+ self.findings: List[Dict[str, Any]] = []
87
+ # Each frame is [start_line, csrf_token_seen] for an open state-changing form.
88
+ self._form_frames: List[List[Any]] = []
89
+ # How deep inside <pre>/<code>/<textarea> the parser currently sits.
90
+ self._verbatim_depth = 0
91
+ self._reported: set = set()
92
+
93
+ # ── emission ──────────────────────────────────────────────────────────
94
+ def _emit(self, line: int, cwe: str, severity: str, category: str, message: str) -> None:
95
+ identity = (line, cwe, category)
96
+ if identity in self._reported:
97
+ return
98
+ self._reported.add(identity)
99
+ self.findings.append({
100
+ "file": self.file_path,
101
+ "line": max(1, int(line)),
102
+ "cwe": cwe,
103
+ "severity": severity,
104
+ "category": category,
105
+ "message": message,
106
+ })
107
+
108
+ # ── CWE-353: Subresource Integrity ────────────────────────────────────
109
+ def _check_subresource_integrity(self, line: int, tag: str, attr_map: Dict[str, str], url_attr: str) -> None:
110
+ url = attr_map.get(url_attr)
111
+ if not _is_external_url(url):
112
+ return
113
+ if attr_map.get("integrity", "").strip():
114
+ return
115
+
116
+ crossorigin = attr_map.get("crossorigin", "").strip()
117
+ crossorigin_note = (
118
+ f'crossorigin="{crossorigin}"' if crossorigin else "crossorigin attribute absent"
119
+ )
120
+ self._emit(
121
+ line=line,
122
+ cwe="CWE-353",
123
+ severity="MEDIUM",
124
+ category="MISSING_SUBRESOURCE_INTEGRITY",
125
+ message=(
126
+ f"CWE-353: Missing Subresource Integrity (SRI) on external <{tag} {url_attr}>"
127
+ f" loading {url.strip()} ({crossorigin_note}); add integrity=<hash> so the"
128
+ f" browser can reject a tampered CDN response"
129
+ ),
130
+ )
131
+
132
+ # ── CWE-79: Django "safe" output ──────────────────────────────────────
133
+ @staticmethod
134
+ def _is_trusted_expression(expression: str) -> bool:
135
+ """True when a ``|safe`` expression cannot carry client-controlled markup."""
136
+ root = re.match(r"[A-Za-z_][A-Za-z0-9_]*", expression)
137
+ if not root:
138
+ return False
139
+ name = root.group(0).lower()
140
+ if name in ALWAYS_SAFE_EXPRESSION_ROOTS:
141
+ return True
142
+ if name != "form":
143
+ return False
144
+ segments = [segment.lower() for segment in expression.split(".")]
145
+ return not any(segment in FORM_USER_DATA_SEGMENTS for segment in segments[1:])
146
+
147
+ def _check_unescaped_output(self, line: int, data: str) -> None:
148
+ """Report ``{{ value|safe }}``: the filter switches off the escaping that protects
149
+ every other template variable, so the value lands in the page as raw HTML."""
150
+ if self._verbatim_depth:
151
+ return
152
+ for match in UNESCAPED_OUTPUT_RE.finditer(data):
153
+ expression = match.group(1).strip()
154
+ if self._is_trusted_expression(expression):
155
+ continue
156
+ self._emit(
157
+ line=line + data[:match.start()].count("\n"),
158
+ cwe="CWE-79",
159
+ severity="HIGH",
160
+ category="CROSS_SITE_SCRIPTING",
161
+ message=UNESCAPED_OUTPUT_MESSAGE,
162
+ )
163
+
164
+ # ── HTMLParser hooks ──────────────────────────────────────────────────
165
+ def handle_starttag(self, tag: str, attrs, self_closing: bool = False) -> None:
166
+ line = self.getpos()[0]
167
+ attr_map = _normalize_attrs(attrs)
168
+ lowered = tag.lower()
169
+
170
+ if lowered in VERBATIM_TAGS and not self_closing:
171
+ self._verbatim_depth += 1
172
+
173
+ if lowered == "script":
174
+ self._check_subresource_integrity(line, "script", attr_map, "src")
175
+ elif lowered == "link":
176
+ if "stylesheet" in attr_map.get("rel", "").lower():
177
+ self._check_subresource_integrity(line, "link", attr_map, "href")
178
+ elif lowered == "form":
179
+ if attr_map.get("method", "").strip().lower() in STATE_CHANGING_FORM_METHODS:
180
+ self._form_frames.append([line, False])
181
+
182
+ if self._form_frames and lowered in ("input", "button"):
183
+ # The token also arrives pre-rendered as <input type="hidden"
184
+ # name="csrfmiddlewaretoken" value="...">. Attribute values are never handed to
185
+ # handle_data, so without this check a protected form is reported as vulnerable.
186
+ if attr_map.get("name", "").strip().lower() in CSRF_TOKEN_MARKERS:
187
+ self._form_frames[-1][1] = True
188
+
189
+ def handle_startendtag(self, tag: str, attrs) -> None:
190
+ # Self-closing form/script tags still carry the same attributes. A self-closing
191
+ # <code/> opens no region, so it must not bump the depth counter.
192
+ self.handle_starttag(tag, attrs, self_closing=True)
193
+
194
+ def handle_data(self, data: str) -> None:
195
+ if not data:
196
+ return
197
+ # getpos() is the offset where this character run began, so a run spanning several
198
+ # lines is anchored by counting the newlines that precede the match inside it.
199
+ self._check_csrf_token(self.getpos()[0], data)
200
+ self._check_unescaped_output(self.getpos()[0], data)
201
+
202
+ def _check_csrf_token(self, line: int, data: str) -> None:
203
+ if not self._form_frames:
204
+ return
205
+ # Django's tag is case-preserving but template authors do write `{% CSRF_TOKEN %}`,
206
+ # and a case-sensitive match then exonerates nothing: a protected form gets reported.
207
+ lowered = data.lower()
208
+ for marker in CSRF_TOKEN_MARKERS:
209
+ if marker in lowered:
210
+ # Attribute the token to the form that actually encloses it. Marking every
211
+ # open frame let one {% csrf_token %} exonerate unrelated forms that were
212
+ # left open by malformed or nested markup.
213
+ self._form_frames[-1][1] = True
214
+ return
215
+
216
+ def handle_endtag(self, tag: str) -> None:
217
+ lowered = tag.lower()
218
+ if lowered in VERBATIM_TAGS:
219
+ # An unclosed <pre> would otherwise keep the counter positive and hide every
220
+ # finding below it, so the depth is clamped at zero.
221
+ self._verbatim_depth = max(0, self._verbatim_depth - 1)
222
+ if lowered != "form" or not self._form_frames:
223
+ return
224
+ line, has_csrf = self._form_frames.pop()
225
+ if has_csrf:
226
+ return
227
+ self._emit(
228
+ line=line,
229
+ cwe="CWE-352",
230
+ severity="HIGH",
231
+ category="CSRF_MISSING_PROTECTION",
232
+ message=(
233
+ "CWE-352: Cross-Site Request Forgery - state-changing <form> submitted without a"
234
+ " CSRF token; render {% csrf_token %} inside the form body"
235
+ ),
236
+ )
237
+
238
+ def close(self) -> None:
239
+ """Flush forms left open by malformed markup, then release parser state."""
240
+ super().close()
241
+ while self._form_frames:
242
+ line, has_csrf = self._form_frames.pop()
243
+ if has_csrf:
244
+ continue
245
+ self._emit(
246
+ line=line,
247
+ cwe="CWE-352",
248
+ severity="HIGH",
249
+ category="CSRF_MISSING_PROTECTION",
250
+ message=(
251
+ "CWE-352: Cross-Site Request Forgery - state-changing <form> submitted without a"
252
+ " CSRF token; render {% csrf_token %} inside the form body"
253
+ ),
254
+ )
255
+
256
+
257
+ def audit_template(file_path: str, source: str) -> List[Dict[str, Any]]:
258
+ """Audit a single template document and return its findings."""
259
+ auditor = TemplateSecurityAuditor(file_path)
260
+ try:
261
+ auditor.feed(source)
262
+ except Exception:
263
+ # A malformed template must never abort a scan; partial findings are kept.
264
+ pass
265
+ auditor.close()
266
+ return auditor.findings
267
+
268
+
269
+ def audit_templates(files: Dict[str, str]) -> List[Dict[str, Any]]:
270
+ """Audit a mapping of ``{file_path: source}`` templates, sorted deterministically."""
271
+ findings: List[Dict[str, Any]] = []
272
+ for file_path in sorted(files):
273
+ findings.extend(audit_template(file_path, files[file_path]))
274
+ return sorted(findings, key=lambda item: (item["file"], item["line"], item["cwe"]))