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
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"]))
|