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
event_publisher.py ADDED
@@ -0,0 +1,345 @@
1
+ """
2
+ TimeCodeSecurity Application-Level Event Publisher.
3
+
4
+ Translates deterministic scanner output (ScanResult) into typed,
5
+ immutable SecurityDomainEvent instances and publishes them to the event bus.
6
+
7
+ Invariants:
8
+ - Never modifies the input ScanResult object.
9
+ - Never executes scanned source code or initiates network/database I/O.
10
+ - Defensive boundary: known high-risk raw secret patterns are rejected (masked values only).
11
+ - Produces deterministic dedupe keys based on semantic scan invariants.
12
+ - Supports dependency-injected clock and ID factories for test determinism.
13
+
14
+ Scan ID Contract:
15
+ - scan_id is supplied/owned by the application invocation boundary.
16
+ - Retries of the same logical scan MUST reuse the same scan_id.
17
+ - Different scan executions MUST receive different scan_id values.
18
+ - dedupe_key relies on this identity contract to ensure idempotent retry behavior.
19
+ - The event layer never generates a new scan_id automatically for a retry.
20
+ """
21
+
22
+ from __future__ import annotations
23
+
24
+ import datetime
25
+ import hashlib
26
+ import uuid
27
+ from typing import Mapping, Any, Optional, List, Tuple, Callable, Dict
28
+
29
+ from event_taxonomy import (
30
+ SecurityDomainEvent,
31
+ EventType,
32
+ ScanStatus,
33
+ EventSummary,
34
+ compute_dedupe_key,
35
+ freeze_data,
36
+ assert_no_raw_secrets
37
+ )
38
+ from event_bus import InMemoryEventBus, DispatchResult
39
+
40
+
41
+ class EventPublisher:
42
+ """
43
+ Adapter boundary between security scanner results and the domain event bus.
44
+ """
45
+
46
+ def __init__(
47
+ self,
48
+ bus: Optional[InMemoryEventBus] = None,
49
+ id_factory: Optional[Callable[[], str]] = None,
50
+ clock: Optional[Callable[[], str]] = None
51
+ ) -> None:
52
+ self.bus = bus or InMemoryEventBus()
53
+ self.id_factory = id_factory or (lambda: f"evt_{uuid.uuid4().hex}")
54
+ self.clock = clock or (lambda: datetime.datetime.now(datetime.timezone.utc).isoformat())
55
+
56
+ def _determine_scan_status(self, scan_result: Mapping[str, Any]) -> ScanStatus:
57
+ """
58
+ Derives terminal scan status strictly from supported ScanResult data.
59
+ """
60
+ raw_status = str(scan_result.get("status", "success")).lower()
61
+ syntax_errors = scan_result.get("syntax_errors")
62
+
63
+ if raw_status in ("failed", "error"):
64
+ return ScanStatus.FAILED
65
+ if syntax_errors and len(syntax_errors) > 0:
66
+ return ScanStatus.PARTIAL
67
+ return ScanStatus.SUCCESS
68
+
69
+ def _build_event_summary(
70
+ self,
71
+ scan_result: Mapping[str, Any],
72
+ active_findings: List[Mapping[str, Any]],
73
+ critical_findings: List[Mapping[str, Any]],
74
+ high_findings: List[Mapping[str, Any]],
75
+ secret_findings: List[Mapping[str, Any]],
76
+ sca_findings: List[Mapping[str, Any]]
77
+ ) -> EventSummary:
78
+ """
79
+ Constructs a machine-readable, typed EventSummary.
80
+ """
81
+ raw_summary = scan_result.get("summary", {})
82
+
83
+ sast_count = int(raw_summary.get("active_vulnerabilities", len(active_findings)))
84
+ sca_count = int(raw_summary.get("sca_vulnerabilities", len(sca_findings)))
85
+ secrets_count = int(raw_summary.get("secrets_detected", len(secret_findings)))
86
+ crit_count = int(raw_summary.get("critical_count", len(critical_findings)))
87
+ high_count = int(raw_summary.get("high_count", len(high_findings)))
88
+ med_count = int(raw_summary.get("medium_count", 0))
89
+ low_count = int(raw_summary.get("low_count", 0))
90
+ sec_score = int(raw_summary.get("security_score", 100))
91
+ risk_lvl = str(raw_summary.get("risk_level", "CLEAN"))
92
+ msg = str(raw_summary.get("risk_message", ""))
93
+ status = self._determine_scan_status(scan_result)
94
+
95
+ return EventSummary(
96
+ sast_findings=sast_count,
97
+ sca_findings=sca_count,
98
+ secret_findings=secrets_count,
99
+ total_findings=sast_count + sca_count + secrets_count,
100
+ critical_count=crit_count,
101
+ high_count=high_count,
102
+ medium_count=med_count,
103
+ low_count=low_count,
104
+ security_score=sec_score,
105
+ risk_level=risk_lvl,
106
+ scan_status=status,
107
+ message=msg
108
+ )
109
+
110
+ def build_events(
111
+ self,
112
+ scan_result: Mapping[str, Any],
113
+ repository: str,
114
+ scan_id: str,
115
+ metadata: Optional[Mapping[str, Any]] = None,
116
+ policy_thresholds: Optional[Mapping[str, Any]] = None
117
+ ) -> List[SecurityDomainEvent]:
118
+ """
119
+ Translates a ScanResult into a list of typed SecurityDomainEvent objects.
120
+ Does NOT modify the scan_result input.
121
+
122
+ Scan ID Contract:
123
+ - scan_id is supplied/owned by the application invocation boundary.
124
+ - Retries of the same logical scan MUST reuse the same scan_id.
125
+ - Different scan executions MUST receive different scan_id values.
126
+ - dedupe_key relies on this identity contract.
127
+ - The event layer never generates a new scan_id automatically for retries.
128
+ """
129
+ if not scan_id or not str(scan_id).strip():
130
+ raise ValueError(
131
+ "Field 'scan_id' must be a non-empty string owned by the caller/invocation boundary."
132
+ )
133
+ effective_scan_id = str(scan_id).strip()
134
+
135
+ events: List[SecurityDomainEvent] = []
136
+
137
+ # Extract findings without modifying scan_result
138
+ raw_findings = scan_result.get("findings", [])
139
+ active_findings = [f for f in raw_findings if not f.get("suppressed", False)]
140
+ critical_findings = [f for f in active_findings if f.get("severity") == "CRITICAL"]
141
+ high_findings = [f for f in active_findings if f.get("severity") == "HIGH"]
142
+ secret_findings = scan_result.get("secret_findings", [])
143
+ sca_findings = scan_result.get("sca_findings", [])
144
+
145
+ # Machine-readable summary
146
+ summary = self._build_event_summary(
147
+ scan_result,
148
+ active_findings,
149
+ critical_findings,
150
+ high_findings,
151
+ secret_findings,
152
+ sca_findings
153
+ )
154
+
155
+ high_risk_count = len(critical_findings) + len(high_findings)
156
+
157
+ # Base metadata
158
+ base_metadata: Dict[str, Any] = {
159
+ "files_scanned": scan_result.get("summary", {}).get("total_files", 0),
160
+ "lines_scanned": scan_result.get("summary", {}).get("lines_scanned", 0),
161
+ "active_vulnerabilities": summary.sast_findings,
162
+ "suppressed_vulnerabilities": scan_result.get("summary", {}).get("suppressed_vulnerabilities", 0),
163
+ "scan_status": summary.scan_status.value
164
+ }
165
+ if metadata:
166
+ base_metadata.update(dict(metadata))
167
+
168
+ # 1. Event: SCAN_COMPLETED (always emitted)
169
+ scan_completed_context = {
170
+ "sast": summary.sast,
171
+ "sca": summary.sca,
172
+ "secrets": summary.secrets,
173
+ "score": summary.security_score,
174
+ "risk_level": summary.risk_level,
175
+ "status": summary.scan_status.value
176
+ }
177
+ dedupe_scan_completed = compute_dedupe_key(
178
+ schema_version=1,
179
+ event_type=EventType.SCAN_COMPLETED,
180
+ repository=repository,
181
+ scan_id=effective_scan_id,
182
+ semantic_context=scan_completed_context
183
+ )
184
+ events.append(
185
+ SecurityDomainEvent(
186
+ schema_version=1,
187
+ event_id=self.id_factory(),
188
+ event_type=EventType.SCAN_COMPLETED,
189
+ timestamp=self.clock(),
190
+ repository=repository,
191
+ scan_id=effective_scan_id,
192
+ summary=summary,
193
+ high_risk_count=high_risk_count,
194
+ metadata=base_metadata,
195
+ dedupe_key=dedupe_scan_completed
196
+ )
197
+ )
198
+
199
+ # 2. Event: CRITICAL_FINDING_DETECTED (if active CRITICAL findings exist)
200
+ if critical_findings:
201
+ crit_fingerprints = sorted([
202
+ f"{f.get('cwe')}:{f.get('file')}:{f.get('line_number')}:{f.get('sink_symbol')}"
203
+ for f in critical_findings
204
+ ])
205
+ crit_context = {
206
+ "critical_count": len(critical_findings),
207
+ "findings": crit_fingerprints
208
+ }
209
+ dedupe_critical = compute_dedupe_key(
210
+ schema_version=1,
211
+ event_type=EventType.CRITICAL_FINDING_DETECTED,
212
+ repository=repository,
213
+ scan_id=effective_scan_id,
214
+ semantic_context=crit_context
215
+ )
216
+ crit_meta = dict(base_metadata)
217
+ crit_meta["critical_fingerprints"] = crit_fingerprints
218
+ events.append(
219
+ SecurityDomainEvent(
220
+ schema_version=1,
221
+ event_id=self.id_factory(),
222
+ event_type=EventType.CRITICAL_FINDING_DETECTED,
223
+ timestamp=self.clock(),
224
+ repository=repository,
225
+ scan_id=effective_scan_id,
226
+ summary=summary,
227
+ high_risk_count=high_risk_count,
228
+ metadata=crit_meta,
229
+ dedupe_key=dedupe_critical
230
+ )
231
+ )
232
+
233
+ # 3. Event: SECRETS_LEAK_DETECTED (if secret findings exist)
234
+ if secret_findings:
235
+ sec_fingerprints = sorted([
236
+ f"{sf.get('secret_type')}:{sf.get('file')}:{sf.get('line_number')}:{sf.get('detector')}:{sf.get('masked_value')}"
237
+ for sf in secret_findings
238
+ ])
239
+ sec_context = {
240
+ "secrets_count": len(secret_findings),
241
+ "secrets": sec_fingerprints
242
+ }
243
+ dedupe_secrets = compute_dedupe_key(
244
+ schema_version=1,
245
+ event_type=EventType.SECRETS_LEAK_DETECTED,
246
+ repository=repository,
247
+ scan_id=effective_scan_id,
248
+ semantic_context=sec_context
249
+ )
250
+ sec_meta = dict(base_metadata)
251
+ sec_meta["secret_fingerprints"] = sec_fingerprints
252
+ events.append(
253
+ SecurityDomainEvent(
254
+ schema_version=1,
255
+ event_id=self.id_factory(),
256
+ event_type=EventType.SECRETS_LEAK_DETECTED,
257
+ timestamp=self.clock(),
258
+ repository=repository,
259
+ scan_id=effective_scan_id,
260
+ summary=summary,
261
+ high_risk_count=high_risk_count,
262
+ metadata=sec_meta,
263
+ dedupe_key=dedupe_secrets
264
+ )
265
+ )
266
+
267
+ # 4. Event: POLICY_VIOLATION (if policy thresholds violated)
268
+ if policy_thresholds:
269
+ violations = []
270
+ min_score = policy_thresholds.get("min_security_score")
271
+ if min_score is not None and summary.security_score < int(min_score):
272
+ violations.append(f"Security score {summary.security_score} below minimum allowable {min_score}")
273
+
274
+ max_crit = policy_thresholds.get("max_critical")
275
+ if max_crit is not None and summary.critical_count > int(max_crit):
276
+ violations.append(f"Critical count {summary.critical_count} exceeds maximum allowable {max_crit}")
277
+
278
+ max_high = policy_thresholds.get("max_high")
279
+ if max_high is not None and summary.high_count > int(max_high):
280
+ violations.append(f"High count {summary.high_count} exceeds maximum allowable {max_high}")
281
+
282
+ forbidden_cwes = policy_thresholds.get("forbidden_cwes", [])
283
+ active_cwes = {f.get("cwe") for f in active_findings if f.get("cwe")}
284
+ breached_cwes = sorted(list(set(forbidden_cwes).intersection(active_cwes)))
285
+ if breached_cwes:
286
+ violations.append(f"Forbidden CWE classes detected: {', '.join(breached_cwes)}")
287
+
288
+ if violations:
289
+ policy_context = {
290
+ "violations": sorted(violations),
291
+ "violation_count": len(violations)
292
+ }
293
+ dedupe_policy = compute_dedupe_key(
294
+ schema_version=1,
295
+ event_type=EventType.POLICY_VIOLATION,
296
+ repository=repository,
297
+ scan_id=effective_scan_id,
298
+ semantic_context=policy_context
299
+ )
300
+ pol_meta = dict(base_metadata)
301
+ pol_meta["violations"] = violations
302
+ events.append(
303
+ SecurityDomainEvent(
304
+ schema_version=1,
305
+ event_id=self.id_factory(),
306
+ event_type=EventType.POLICY_VIOLATION,
307
+ timestamp=self.clock(),
308
+ repository=repository,
309
+ scan_id=effective_scan_id,
310
+ summary=summary,
311
+ high_risk_count=high_risk_count,
312
+ metadata=pol_meta,
313
+ dedupe_key=dedupe_policy
314
+ )
315
+ )
316
+
317
+ return events
318
+
319
+ def publish_scan_events(
320
+ self,
321
+ scan_result: Mapping[str, Any],
322
+ repository: str,
323
+ scan_id: str,
324
+ metadata: Optional[Mapping[str, Any]] = None,
325
+ policy_thresholds: Optional[Mapping[str, Any]] = None
326
+ ) -> List[Tuple[SecurityDomainEvent, List[DispatchResult]]]:
327
+ """
328
+ Builds domain events from scan_result and publishes each synchronously to the bus.
329
+ Returns pairs of (event, dispatch_results).
330
+ Does NOT modify the scan_result input.
331
+ """
332
+ events = self.build_events(
333
+ scan_result=scan_result,
334
+ repository=repository,
335
+ scan_id=scan_id,
336
+ metadata=metadata,
337
+ policy_thresholds=policy_thresholds
338
+ )
339
+
340
+ results: List[Tuple[SecurityDomainEvent, List[DispatchResult]]] = []
341
+ for event in events:
342
+ dispatch_results = self.bus.publish(event)
343
+ results.append((event, dispatch_results))
344
+
345
+ return results
event_taxonomy.py ADDED
@@ -0,0 +1,313 @@
1
+ """
2
+ TimeCodeSecurity Domain Event Taxonomy & Immutability Framework.
3
+
4
+ Defines the immutable SecurityDomainEvent, EventType, EventSummary,
5
+ and canonical deduplication key generation for Phase 15A.
6
+
7
+ Invariants:
8
+ - Defensive boundary: Known high-risk raw secret patterns are rejected before event construction.
9
+ (This defensive check does not replace the dedicated secret scanner engine).
10
+ - True immutability via frozen dataclasses, recursive container freezing, and strict type enforcement.
11
+ - Unsupported object types in metadata are deterministically rejected with TypeError.
12
+ - Machine-readable EventSummary with typed counts (sast, sca, secrets, etc.).
13
+ - Deterministic deduplication key independent of event_id and timestamp.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import json
19
+ import hashlib
20
+ import re
21
+ from dataclasses import dataclass, field
22
+ from enum import Enum
23
+ from types import MappingProxyType
24
+ from typing import Any, Mapping, Optional, Union, Dict, Tuple, Set, List
25
+
26
+
27
+ class EventType(str, Enum):
28
+ """Approved Phase 15A security domain event types."""
29
+ SCAN_COMPLETED = "SCAN_COMPLETED"
30
+ CRITICAL_FINDING_DETECTED = "CRITICAL_FINDING_DETECTED"
31
+ SECRETS_LEAK_DETECTED = "SECRETS_LEAK_DETECTED"
32
+ POLICY_VIOLATION = "POLICY_VIOLATION"
33
+
34
+
35
+ class ScanStatus(str, Enum):
36
+ """Terminal scan status classifications."""
37
+ SUCCESS = "SUCCESS"
38
+ PARTIAL = "PARTIAL"
39
+ FAILED = "FAILED"
40
+
41
+
42
+ def freeze_data(val: Any) -> Any:
43
+ """
44
+ Recursively transforms supported data structures into immutable proxies/tuples.
45
+
46
+ Supported immutable primitives:
47
+ - None
48
+ - bool
49
+ - int
50
+ - float
51
+ - str
52
+ - bytes
53
+
54
+ Supported containers:
55
+ - dict
56
+ - list
57
+ - tuple
58
+ - set
59
+ - frozenset
60
+ - MappingProxyType
61
+
62
+ For unsupported object types:
63
+ REJECT deterministically with TypeError.
64
+ """
65
+ if val is None:
66
+ return None
67
+ # Note: bool is a subclass of int in Python, so bool is covered
68
+ if isinstance(val, (bool, int, float, str, bytes)):
69
+ return val
70
+ if isinstance(val, MappingProxyType):
71
+ # Validate that existing mappingproxy contents are also deeply frozen
72
+ frozen_dict = {str(k): freeze_data(v) for k, v in val.items()}
73
+ return MappingProxyType(frozen_dict)
74
+ if isinstance(val, frozenset):
75
+ return frozenset(freeze_data(item) for item in val)
76
+ if isinstance(val, dict):
77
+ frozen_dict = {str(k): freeze_data(v) for k, v in val.items()}
78
+ return MappingProxyType(frozen_dict)
79
+ if isinstance(val, (list, tuple)):
80
+ return tuple(freeze_data(item) for item in val)
81
+ if isinstance(val, set):
82
+ return frozenset(freeze_data(item) for item in val)
83
+
84
+ raise TypeError(
85
+ f"Unsupported metadata type '{type(val).__name__}'. "
86
+ "SecurityDomainEvent metadata strictly supports immutable primitives (None, bool, int, float, str, bytes) "
87
+ "and standard containers (dict, list, tuple, set, frozenset, MappingProxyType)."
88
+ )
89
+
90
+
91
+ # Pattern for detecting known high-risk raw secret patterns during event construction
92
+ _KNOWN_SECRET_PATTERNS = [
93
+ re.compile(r"\b(AKIA|ABIA|ACCA|ASIA)[0-9A-Z]{16}\b"),
94
+ re.compile(r"\b(?:sk|rk)_(?:live|test)_[0-9a-zA-Z]{24,}\b"),
95
+ re.compile(r"\b(?:ghp|gho|ghu|ghs|ghr)_[0-9a-zA-Z]{36,}\b"),
96
+ re.compile(r"-----BEGIN (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----"),
97
+ ]
98
+
99
+
100
+ def assert_no_raw_secrets(data: Any, path: str = "root") -> None:
101
+ """
102
+ Defensive check: Known high-risk raw secret patterns are rejected before event construction.
103
+ (Does not duplicate or replace the dedicated secret scanner engine).
104
+ """
105
+ if isinstance(data, str):
106
+ for pattern in _KNOWN_SECRET_PATTERNS:
107
+ if pattern.search(data):
108
+ raise ValueError(
109
+ f"Security policy violation: Known high-risk raw secret pattern detected at '{path}'. "
110
+ "Secrets must be masked (e.g. 'AKIA****************') before constructing domain events."
111
+ )
112
+ elif isinstance(data, (dict, Mapping, MappingProxyType)):
113
+ for k, v in data.items():
114
+ assert_no_raw_secrets(v, f"{path}.{k}")
115
+ elif isinstance(data, (list, tuple, set, frozenset)):
116
+ for idx, item in enumerate(data):
117
+ assert_no_raw_secrets(item, f"{path}[{idx}]")
118
+
119
+
120
+ @dataclass(frozen=True)
121
+ class EventSummary:
122
+ """
123
+ Typed, immutable, machine-readable scan summary.
124
+ Allows policy engines and subscribers to evaluate metrics directly
125
+ without parsing human presentation strings.
126
+ """
127
+ sast_findings: int = 0
128
+ sca_findings: int = 0
129
+ secret_findings: int = 0
130
+ total_findings: int = 0
131
+ critical_count: int = 0
132
+ high_count: int = 0
133
+ medium_count: int = 0
134
+ low_count: int = 0
135
+ security_score: int = 100
136
+ risk_level: str = "CLEAN"
137
+ scan_status: ScanStatus = ScanStatus.SUCCESS
138
+ message: str = ""
139
+
140
+ @property
141
+ def sast(self) -> int:
142
+ return self.sast_findings
143
+
144
+ @property
145
+ def sca(self) -> int:
146
+ return self.sca_findings
147
+
148
+ @property
149
+ def secrets(self) -> int:
150
+ return self.secret_findings
151
+
152
+ def __getitem__(self, key: str) -> Any:
153
+ if key == "sast":
154
+ return self.sast_findings
155
+ if key == "sca":
156
+ return self.sca_findings
157
+ if key == "secrets":
158
+ return self.secret_findings
159
+ if hasattr(self, key):
160
+ val = getattr(self, key)
161
+ if isinstance(val, ScanStatus):
162
+ return val.value
163
+ return val
164
+ raise KeyError(key)
165
+
166
+ def get(self, key: str, default: Any = None) -> Any:
167
+ try:
168
+ return self[key]
169
+ except KeyError:
170
+ return default
171
+
172
+ def to_dict(self) -> Dict[str, Any]:
173
+ return {
174
+ "sast_findings": self.sast_findings,
175
+ "sca_findings": self.sca_findings,
176
+ "secret_findings": self.secret_findings,
177
+ "total_findings": self.total_findings,
178
+ "critical_count": self.critical_count,
179
+ "high_count": self.high_count,
180
+ "medium_count": self.medium_count,
181
+ "low_count": self.low_count,
182
+ "security_score": self.security_score,
183
+ "risk_level": self.risk_level,
184
+ "scan_status": self.scan_status.value if isinstance(self.scan_status, ScanStatus) else str(self.scan_status),
185
+ "message": self.message,
186
+ }
187
+
188
+
189
+ def compute_dedupe_key(
190
+ schema_version: int,
191
+ event_type: Union[EventType, str],
192
+ repository: str,
193
+ scan_id: str,
194
+ semantic_context: Optional[Mapping[str, Any]] = None
195
+ ) -> str:
196
+ """
197
+ Computes a deterministic SHA-256 deduplication key over canonical JSON.
198
+
199
+ Canonical Payload:
200
+ {
201
+ "event_type": str,
202
+ "repository": str,
203
+ "scan_id": str,
204
+ "schema_version": int,
205
+ "semantic_context": dict
206
+ }
207
+
208
+ Non-deterministic fields (event_id, timestamp) are strictly excluded.
209
+ Canonical JSON enforces sorted keys and minimal separators for determinism.
210
+ """
211
+ evt_type_str = event_type.value if isinstance(event_type, EventType) else str(event_type)
212
+ canonical_dict = {
213
+ "event_type": evt_type_str,
214
+ "repository": str(repository).strip(),
215
+ "scan_id": str(scan_id).strip(),
216
+ "schema_version": int(schema_version),
217
+ "semantic_context": dict(semantic_context) if semantic_context else {}
218
+ }
219
+ canonical_bytes = json.dumps(
220
+ canonical_dict,
221
+ sort_keys=True,
222
+ separators=(",", ":"),
223
+ ensure_ascii=True
224
+ ).encode("utf-8")
225
+ return hashlib.sha256(canonical_bytes).hexdigest()
226
+
227
+
228
+ @dataclass(frozen=True)
229
+ class SecurityDomainEvent:
230
+ """
231
+ Immutable security domain event.
232
+
233
+ Strict invariants:
234
+ - schema_version == 1
235
+ - event_type in EventType
236
+ - summary is an immutable EventSummary
237
+ - metadata is deeply frozen (MappingProxyType) and rejects unsupported mutable types
238
+ - dedupe_key is deterministic and excludes event_id and timestamp
239
+ """
240
+ schema_version: int
241
+ event_id: str
242
+ event_type: EventType
243
+ timestamp: str
244
+ repository: str
245
+ scan_id: str
246
+ summary: EventSummary
247
+ high_risk_count: int
248
+ metadata: Mapping[str, Any]
249
+ dedupe_key: str
250
+
251
+ def __post_init__(self) -> None:
252
+ # 1. Validate schema_version
253
+ if not isinstance(self.schema_version, int) or self.schema_version != 1:
254
+ raise ValueError(f"Unsupported schema_version: {self.schema_version}. Expected 1.")
255
+
256
+ # 2. Validate event_type
257
+ if not isinstance(self.event_type, EventType):
258
+ if isinstance(self.event_type, str):
259
+ try:
260
+ et = EventType(self.event_type)
261
+ object.__setattr__(self, "event_type", et)
262
+ except ValueError:
263
+ raise ValueError(f"Invalid event_type: '{self.event_type}'. Must be one of {[e.value for e in EventType]}.")
264
+ else:
265
+ raise ValueError(f"Invalid event_type: {self.event_type}. Expected EventType enum.")
266
+
267
+ # 3. Validate strings
268
+ for field_name in ["event_id", "timestamp", "repository", "scan_id"]:
269
+ val = getattr(self, field_name)
270
+ if not isinstance(val, str) or not val.strip():
271
+ raise ValueError(f"Field '{field_name}' must be a non-empty string.")
272
+
273
+ # 4. Validate summary
274
+ if not isinstance(self.summary, EventSummary):
275
+ if isinstance(self.summary, Mapping):
276
+ s_dict = dict(self.summary)
277
+ status_raw = s_dict.get("scan_status", ScanStatus.SUCCESS)
278
+ status_enum = ScanStatus(status_raw) if not isinstance(status_raw, ScanStatus) else status_raw
279
+ s_obj = EventSummary(
280
+ sast_findings=int(s_dict.get("sast_findings", s_dict.get("sast", 0))),
281
+ sca_findings=int(s_dict.get("sca_findings", s_dict.get("sca", 0))),
282
+ secret_findings=int(s_dict.get("secret_findings", s_dict.get("secrets", 0))),
283
+ total_findings=int(s_dict.get("total_findings", 0)),
284
+ critical_count=int(s_dict.get("critical_count", 0)),
285
+ high_count=int(s_dict.get("high_count", 0)),
286
+ medium_count=int(s_dict.get("medium_count", 0)),
287
+ low_count=int(s_dict.get("low_count", 0)),
288
+ security_score=int(s_dict.get("security_score", 100)),
289
+ risk_level=str(s_dict.get("risk_level", "CLEAN")),
290
+ scan_status=status_enum,
291
+ message=str(s_dict.get("message", "")),
292
+ )
293
+ object.__setattr__(self, "summary", s_obj)
294
+ else:
295
+ raise ValueError(f"Field 'summary' must be an EventSummary instance, got {type(self.summary).__name__}.")
296
+
297
+ # 5. Validate high_risk_count
298
+ if not isinstance(self.high_risk_count, int) or self.high_risk_count < 0:
299
+ raise ValueError(f"Field 'high_risk_count' must be a non-negative integer, got {self.high_risk_count}.")
300
+
301
+ # 6. Deeply freeze metadata (rejects unsupported object types)
302
+ frozen_meta = freeze_data(self.metadata if self.metadata is not None else {})
303
+ if not isinstance(frozen_meta, MappingProxyType):
304
+ frozen_meta = MappingProxyType(dict(frozen_meta) if isinstance(frozen_meta, Mapping) else {})
305
+ object.__setattr__(self, "metadata", frozen_meta)
306
+
307
+ # 7. Defensive check: known high-risk raw secret patterns are rejected
308
+ assert_no_raw_secrets(self.summary.to_dict(), "summary")
309
+ assert_no_raw_secrets(dict(self.metadata), "metadata")
310
+
311
+ # 8. Validate dedupe_key
312
+ if not isinstance(self.dedupe_key, str) or len(self.dedupe_key) != 64:
313
+ raise ValueError(f"Invalid dedupe_key: '{self.dedupe_key}'. Expected a 64-character SHA-256 hex digest.")