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
secret_filters.py ADDED
@@ -0,0 +1,435 @@
1
+ """False-positive filtering, allowlisting, and policy engine for secret scanning.
2
+
3
+ Evaluates candidate SecretFinding objects against file path exclusions,
4
+ template and sample file rules, dummy/placeholder heuristics, mocking contexts,
5
+ and explicit allowlists.
6
+
7
+ Non-negotiable invariants:
8
+ - Zero raw secret exposure: operates exclusively on SecretFinding (which only
9
+ contains masked values and redacted context).
10
+ - Non-destructive: retained findings preserve exact line numbers, columns, and values.
11
+ - SAST / SCA Isolation: zero imports from ast_scanner, rule_engine, or manifest_parser.
12
+ - Zero network I/O.
13
+ """
14
+
15
+ from dataclasses import dataclass, field
16
+ import fnmatch
17
+ from functools import lru_cache
18
+ import os
19
+ import re
20
+ from typing import List, Optional, Set, Tuple
21
+
22
+ from secret_scanner import SecretFinding
23
+
24
+ __all__ = [
25
+ "FilterConfig",
26
+ "SuppressedFinding",
27
+ "FilterResult",
28
+ "filter_findings",
29
+ "evaluate_findings",
30
+ ]
31
+
32
+
33
+ def _load_master_rules_bank():
34
+ """Load master_rules_bank.py from the repository root (pure-data module).
35
+
36
+ Returns None on any failure so the filter still works if the bank is absent.
37
+ Kept local to the secret subsystem to honor the SAST/SCA isolation invariant.
38
+ """
39
+ import importlib.util
40
+
41
+ path = os.path.join(
42
+ os.path.dirname(os.path.abspath(__file__)), "master_rules_bank.py"
43
+ )
44
+ try:
45
+ spec = importlib.util.spec_from_file_location("_tcs_master_rules_bank_filters", path)
46
+ if spec is None or spec.loader is None:
47
+ return None
48
+ mod = importlib.util.module_from_spec(spec)
49
+ spec.loader.exec_module(mod)
50
+ return mod
51
+ except Exception:
52
+ return None
53
+
54
+
55
+ _MASTER_RULES_BANK = _load_master_rules_bank()
56
+
57
+ # Gitleaks allowlist signatures target RAW secret values, but this filter only ever
58
+ # sees masked values (raw secrets are never retained). They are therefore applied
59
+ # best-effort to the masked value; structural/high-confidence detectors are exempt
60
+ # so genuine secrets are never suppressed by a placeholder heuristic.
61
+ _GITLEAKS_STOPWORDS: Tuple[str, ...] = (
62
+ tuple(getattr(_MASTER_RULES_BANK, "GITLEAKS_STOPWORDS", ()) or ())
63
+ if _MASTER_RULES_BANK is not None
64
+ else ()
65
+ )
66
+ _GITLEAKS_ALLOWLIST_REGEXES: Tuple[str, ...] = (
67
+ tuple(getattr(_MASTER_RULES_BANK, "GITLEAKS_ALLOWLIST_REGEXES", ()) or ())
68
+ if _MASTER_RULES_BANK is not None
69
+ else ()
70
+ )
71
+
72
+
73
+ @lru_cache(maxsize=8)
74
+ def _compile_allowlist(patterns: Tuple[str, ...]) -> Tuple[re.Pattern, ...]:
75
+ compiled = []
76
+ for p in patterns:
77
+ try:
78
+ compiled.append(re.compile(p))
79
+ except re.error:
80
+ continue
81
+ return tuple(compiled)
82
+ # Secret types whose detection is structural/high-confidence and must never be
83
+ # suppressed by the Gitleaks placeholder allowlist.
84
+ _GITLEAKS_EXEMPT_TYPES = frozenset(
85
+ {"private_key", "jwt_token", "slack_webhook_url", "database_connection_string"}
86
+ )
87
+
88
+
89
+ @dataclass
90
+ class FilterConfig:
91
+ """Configuration container for secret false-positive filtering."""
92
+
93
+ ignored_paths: Tuple[str, ...] = (
94
+ "tests/",
95
+ "test/",
96
+ "spec/",
97
+ "specs/",
98
+ "fixtures/",
99
+ "fixture/",
100
+ "mock/",
101
+ "mocks/",
102
+ "vendor/",
103
+ ".git/",
104
+ "node_modules/",
105
+ "docs/",
106
+ "doc/",
107
+ )
108
+ ignored_filenames: Set[str] = field(
109
+ default_factory=lambda: {
110
+ ".env.example",
111
+ ".env.sample",
112
+ ".env.template",
113
+ ".env.test",
114
+ "sample.env",
115
+ "example.env",
116
+ "docker-compose.test.yml",
117
+ }
118
+ )
119
+ ignored_extensions: Tuple[str, ...] = (
120
+ ".md",
121
+ ".rst",
122
+ ".example",
123
+ ".sample",
124
+ )
125
+ dummy_patterns: Tuple[str, ...] = (
126
+ r"(?i)\b(dummy|fake|placeholder|example|test|sample|change_me|your_token_here|my_secret_token|your_password_here|your_secret_here|your_api_key_here|your_key_here)[\w]*",
127
+ r"(?i)<[^>]+>",
128
+ r"(?i)\binsert[_-][\w-]*\b",
129
+ r"(?i)\b(00000+|11111+|xxxxxx+|abcdef)\b",
130
+ r"AKIA0{10,}",
131
+ r"ghp_0{10,}",
132
+ r"xox[baprs]-0{10,}",
133
+ )
134
+ mock_context_patterns: Tuple[str, ...] = (
135
+ r"(?i)\b(mock\.patch|@patch|pytest\.fixture|unittest\.mock|magicmock|responses\.add|httpretty|requests_mock)\b",
136
+ )
137
+ allowlisted_entries: Set[str] = field(default_factory=set)
138
+ ignore_test_paths: bool = True
139
+ ignore_templates: bool = True
140
+ ignore_dummies: bool = True
141
+ ignore_mock_contexts: bool = True
142
+ min_entropy_threshold: Optional[float] = None
143
+ gitleaks_stopwords: Tuple[str, ...] = _GITLEAKS_STOPWORDS
144
+ gitleaks_allowlist_regexes: Tuple[str, ...] = _GITLEAKS_ALLOWLIST_REGEXES
145
+ ignore_gitleaks_allowlist: bool = True
146
+
147
+
148
+ @dataclass(frozen=True)
149
+ class SuppressedFinding:
150
+ """Audit record representing a suppressed secret finding."""
151
+
152
+ finding: SecretFinding
153
+ reason: str
154
+ filter_name: str
155
+
156
+
157
+ @dataclass(frozen=True)
158
+ class FilterResult:
159
+ """Result container separating retained and suppressed findings."""
160
+
161
+ retained: List[SecretFinding]
162
+ suppressed: List[SuppressedFinding]
163
+
164
+
165
+ def _normalize_path(path: str) -> str:
166
+ """Normalize file path for cross-platform matching."""
167
+ norm = path.replace("\\", "/").lower()
168
+ if norm.startswith("./"):
169
+ norm = norm[2:]
170
+ return norm
171
+
172
+
173
+ def _is_path_ignored(file_path: str, config: FilterConfig) -> Optional[Tuple[str, str]]:
174
+ """Check if a file path is ignored. Returns (filter_name, reason) if ignored."""
175
+ normalized = _normalize_path(file_path)
176
+ basename = os.path.basename(normalized)
177
+
178
+ # 1. Check template / sample filenames
179
+ if config.ignore_templates:
180
+ if basename in config.ignored_filenames:
181
+ return "PathFilter", "ignored_filename"
182
+ if any(basename.endswith(ext) for ext in config.ignored_extensions):
183
+ return "PathFilter", "ignored_extension"
184
+
185
+ # 2. Check path directories
186
+ if config.ignore_test_paths:
187
+ slash_path = f"/{normalized}"
188
+ for prefix in config.ignored_paths:
189
+ norm_prefix = prefix.lower()
190
+ if normalized.startswith(norm_prefix) or f"/{norm_prefix}" in slash_path:
191
+ return "PathFilter", "ignored_path"
192
+ if "*" in norm_prefix and fnmatch.fnmatch(normalized, norm_prefix):
193
+ return "PathFilter", "ignored_path"
194
+
195
+ return None
196
+
197
+
198
+ def _is_dummy_value(finding: SecretFinding, config: FilterConfig) -> bool:
199
+ """Check if the finding's masked value or context indicates a dummy/placeholder."""
200
+ if not config.ignore_dummies:
201
+ return False
202
+
203
+ # Exemption for explicit high-entropy credentials (e.g. AWS_SECRET_ACCESS_KEY, JWT_BEARER_TOKEN)
204
+ if finding.context and re.search(r"(?i)\b(aws_secret_access_key|jwt_bearer_token)\b", finding.context):
205
+ if re.search(r"(?i)(0{8,}|1{8,}|x{8,})$", finding.masked_value):
206
+ return True
207
+ return False
208
+
209
+ if finding.secret_type == "jwt_token":
210
+ return False
211
+
212
+ # Slack incoming-webhook URLs are secrets by structure (the full URL grants
213
+ # posting access), so a placeholder-looking token tail must not suppress them.
214
+ if finding.secret_type == "slack_webhook_url":
215
+ return False
216
+
217
+ # 1. Check masked value for repetitive dummy characters in unmasked suffix
218
+ # e.g., AKIA************0000 or ghp_****************************0000
219
+ mv = finding.masked_value
220
+ if re.search(r"(?i)(0{4,}|1{4,}|x{4,})$", mv):
221
+ return True
222
+
223
+ # 2. Check dummy patterns against masked value
224
+ for pattern in config.dummy_patterns:
225
+ if re.search(pattern, mv):
226
+ return True
227
+
228
+ # 3. Check dummy patterns against context
229
+ if finding.context:
230
+ for pattern in config.dummy_patterns:
231
+ if re.search(pattern, finding.context):
232
+ return True
233
+
234
+ # 4. Check database connection string for localhost/loopback or dummy dev credentials
235
+ if finding.secret_type == "database_connection_string":
236
+ mv_lower = mv.lower()
237
+ is_loopback = any(
238
+ f"@{h}" in mv_lower
239
+ for h in ("localhost", "127.0.0.1", "0.0.0.0", "::1")
240
+ )
241
+ if is_loopback:
242
+ # 4a. Masked creds indicate short dummy credentials (e.g., ****:****, :****)
243
+ if re.search(r"://(?:\*{1,4}:)?\*{1,4}@", mv):
244
+ return True
245
+ if re.search(
246
+ r"://(?:p\*{6}s:p\*{6}s|a\*{3}n:a\*{3}n|g\*{3}t:g\*{3}t|r\*{2}t:r\*{2}t)@",
247
+ mv_lower,
248
+ ):
249
+ return True
250
+ # 4b. Context or variable indicates dev/local/test/staging
251
+ if finding.context and re.search(
252
+ r"(?i)\b(dev|development|test|dummy|sample|staging)[\w]*",
253
+ finding.context,
254
+ ):
255
+ return True
256
+ if finding.context and re.search(
257
+ r"(?i)\b(local_[a-z0-9_]+|[a-z0-9_]+_local)\b",
258
+ finding.context,
259
+ ):
260
+ return True
261
+ # 4c. Database name is dev/test/db
262
+ if re.search(
263
+ r"/(db|dev|test|testdb)(?:[\"\'\s;]|$)",
264
+ mv_lower,
265
+ ):
266
+ return True
267
+ # 4d. Context contains common dummy credential pairs
268
+ if finding.context and re.search(
269
+ r"(?i)\b(user:pass|root:root|admin:admin|postgres:postgres|guest:guest|test:test)\b",
270
+ finding.context,
271
+ ):
272
+ return True
273
+
274
+ return False
275
+
276
+
277
+ def _is_gitleaks_suppressed(finding: SecretFinding, config: FilterConfig) -> bool:
278
+ """Suppress placeholder-looking findings via the Gitleaks allowlist/stopwords.
279
+
280
+ Gitleaks evaluates these against the RAW secret; this engine only retains the
281
+ masked value, so they are applied best-effort to the masked value. Structural
282
+ and pure-mask-artifact values are exempt to avoid suppressing genuine secrets.
283
+ """
284
+ if not config.ignore_gitleaks_allowlist:
285
+ return False
286
+
287
+ if finding.secret_type in _GITLEAKS_EXEMPT_TYPES:
288
+ return False
289
+
290
+ mv = finding.masked_value or ""
291
+ # A value that is nothing but mask characters carries no signal; never suppress
292
+ # a real (short) secret just because masking reduced it to asterisks.
293
+ if not mv or set(mv) <= {"*"}:
294
+ return False
295
+
296
+ for stopword in config.gitleaks_stopwords:
297
+ if stopword and stopword in mv:
298
+ return True
299
+
300
+ for pattern in _compile_allowlist(config.gitleaks_allowlist_regexes):
301
+ if pattern.search(mv):
302
+ return True
303
+
304
+ return False
305
+
306
+
307
+ def _is_mock_context(finding: SecretFinding, file_path: str, config: FilterConfig) -> bool:
308
+ """Check if the finding occurs within a test mock or fixture context."""
309
+ if not config.ignore_mock_contexts:
310
+ return False
311
+
312
+ # 1. Check finding.context
313
+ if finding.context:
314
+ for pattern in config.mock_context_patterns:
315
+ if re.search(pattern, finding.context):
316
+ return True
317
+
318
+ # 2. Check preceding lines if file exists on disk (e.g. preceding decorator)
319
+ if file_path and os.path.isfile(file_path):
320
+ try:
321
+ with open(file_path, "r", encoding="utf-8", errors="replace") as f:
322
+ lines = f.readlines()
323
+ idx = finding.line_number - 1
324
+ for offset in (1, 2, 3):
325
+ check_idx = idx - offset
326
+ if 0 <= check_idx < len(lines):
327
+ prev_line = lines[check_idx]
328
+ for pattern in config.mock_context_patterns:
329
+ if re.search(pattern, prev_line):
330
+ return True
331
+ except Exception:
332
+ pass
333
+
334
+ return False
335
+
336
+
337
+ def _is_allowlisted(finding: SecretFinding, file_path: str, config: FilterConfig) -> bool:
338
+ """Check if the finding matches an allowlist entry."""
339
+ if not config.allowlisted_entries:
340
+ return False
341
+
342
+ norm_path = _normalize_path(file_path)
343
+ location_key = f"{norm_path}:{finding.line_number}"
344
+ basename_key = f"{os.path.basename(norm_path)}:{finding.line_number}"
345
+
346
+ # Check exact masked value, location keys, detector-specific keys
347
+ candidates = {
348
+ finding.masked_value,
349
+ location_key,
350
+ basename_key,
351
+ f"{finding.detector}:{finding.masked_value}",
352
+ }
353
+ return bool(candidates.intersection(config.allowlisted_entries))
354
+
355
+
356
+ def evaluate_findings(
357
+ findings: List[SecretFinding],
358
+ file_path: str,
359
+ config: Optional[FilterConfig] = None,
360
+ ) -> FilterResult:
361
+ """Evaluate candidate findings against filter rules and return FilterResult."""
362
+ if config is None:
363
+ config = FilterConfig()
364
+
365
+ retained: List[SecretFinding] = []
366
+ suppressed: List[SuppressedFinding] = []
367
+
368
+ # File-level path check
369
+ path_rejection = _is_path_ignored(file_path, config)
370
+ if path_rejection:
371
+ filter_name, reason = path_rejection
372
+ for f in findings:
373
+ suppressed.append(
374
+ SuppressedFinding(finding=f, reason=reason, filter_name=filter_name)
375
+ )
376
+ return FilterResult(retained=retained, suppressed=suppressed)
377
+
378
+ # Finding-level checks
379
+ for f in findings:
380
+ # 1. Allowlist
381
+ if _is_allowlisted(f, file_path, config):
382
+ suppressed.append(
383
+ SuppressedFinding(
384
+ finding=f, reason="allowlisted", filter_name="AllowlistFilter"
385
+ )
386
+ )
387
+ continue
388
+
389
+ # 2. Dummy / Placeholder values
390
+ if _is_dummy_value(f, config):
391
+ suppressed.append(
392
+ SuppressedFinding(
393
+ finding=f,
394
+ reason="dummy_or_placeholder_value",
395
+ filter_name="DummyValueFilter",
396
+ )
397
+ )
398
+ continue
399
+
400
+ # 2b. Gitleaks allowlist / stopword signatures
401
+ if _is_gitleaks_suppressed(f, config):
402
+ suppressed.append(
403
+ SuppressedFinding(
404
+ finding=f,
405
+ reason="gitleaks_allowlist_or_stopword",
406
+ filter_name="GitleaksAllowlistFilter",
407
+ )
408
+ )
409
+ continue
410
+
411
+ # 3. Mock / Test fixture contexts
412
+ if _is_mock_context(f, file_path, config):
413
+ suppressed.append(
414
+ SuppressedFinding(
415
+ finding=f,
416
+ reason="mocking_or_test_fixture",
417
+ filter_name="ContextFilter",
418
+ )
419
+ )
420
+ continue
421
+
422
+ # Retained
423
+ retained.append(f)
424
+
425
+ return FilterResult(retained=retained, suppressed=suppressed)
426
+
427
+
428
+ def filter_findings(
429
+ findings: List[SecretFinding],
430
+ file_path: str,
431
+ config: Optional[FilterConfig] = None,
432
+ ) -> List[SecretFinding]:
433
+ """Filter candidate findings and return only retained findings."""
434
+ result = evaluate_findings(findings, file_path=file_path, config=config)
435
+ return result.retained