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