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
tcs_cli.py ADDED
@@ -0,0 +1,2086 @@
1
+ #!/usr/bin/env python3
2
+ """
3
+ TimeCodeSecurity Standalone CLI Scanner.
4
+ Recursively analyzes Python source code for security vulnerabilities,
5
+ applies deterministic inline suppressions, and outputs standard JSON or OASIS SARIF v2.1.0.
6
+ """
7
+
8
+ import sys
9
+ import os
10
+ import ast
11
+ import json
12
+ import argparse
13
+ import dataclasses
14
+ from pathlib import Path
15
+ from typing import Dict, List, Any, Optional, Set
16
+
17
+ from ast_scanner import TaintTracker, render_proof_graph_ascii, ProofNodeType
18
+ from suppression_resolver import resolve_suppressions
19
+ from sarif_adapter import (
20
+ SARIF_SCHEMA_URI,
21
+ SARIF_VERSION,
22
+ TOOL_INFORMATION_URI,
23
+ TOOL_NAME,
24
+ TOOL_VERSION,
25
+ to_sarif,
26
+ )
27
+ from sarif_exporter import atomic_write_text
28
+ from rule_engine import GLOBAL_RULE_REGISTRY, get_active_cwe_count
29
+ from benchmark.manifest import ALL_44_CWES
30
+ from manifest_parser import parse_manifest, DependencyRecord
31
+ from osv_client import OSVClient
32
+ from version_matcher import match_dependencies, SCAFinding
33
+ from secret_scanner import scan_text, SecretFinding
34
+ from secret_filters import filter_findings, FilterConfig
35
+ from ci_reporter import format_github_annotations, generate_step_summary
36
+ from config_loader import load_config, TCSConfig, ConfigValidationError
37
+ from staged_scanner import (
38
+ get_git_repo_root,
39
+ get_staged_git_files,
40
+ build_staged_dependency_closure,
41
+ filter_findings_for_staged,
42
+ recompute_summary_metrics,
43
+ )
44
+ from sca_reachability.engine import analyze_dependency_reachability
45
+
46
+ try:
47
+ from js_scanner import (
48
+ JsTsScanner,
49
+ JS_TS_EXTENSIONS,
50
+ js_ts_available,
51
+ run_js_ts_scan_isolated,
52
+ warn_js_ts_unavailable,
53
+ )
54
+ _JS_TS_SCANNER_AVAILABLE = True
55
+ except ImportError:
56
+ _JS_TS_SCANNER_AVAILABLE = False
57
+ JS_TS_EXTENSIONS = frozenset()
58
+
59
+ def js_ts_available() -> bool:
60
+ return False
61
+
62
+ def run_js_ts_scan_isolated(target, base_dir=None, skipped_files=None):
63
+ return []
64
+
65
+ def warn_js_ts_unavailable() -> None:
66
+ print("[TimeCodeSecurity-JS] WARNING: js_scanner is not importable; JS/TS scanning is disabled.",
67
+ file=sys.stderr)
68
+
69
+
70
+ try:
71
+ from importlib.metadata import version as _get_version
72
+ __version__ = _get_version("time-code-security")
73
+ except Exception:
74
+ __version__ = "2.0.0"
75
+
76
+
77
+ IGNORED_DIRS = {
78
+ ".git",
79
+ ".github",
80
+ ".venv",
81
+ "venv",
82
+ "env",
83
+ "node_modules",
84
+ "__pycache__",
85
+ ".pytest_cache",
86
+ ".mypy_cache",
87
+ ".tox",
88
+ "build",
89
+ "dist",
90
+ ".idea",
91
+ ".vscode"
92
+ }
93
+
94
+ MAX_FILE_SIZE_BYTES = 5 * 1024 * 1024 # 5 MB
95
+ MAX_LINE_LENGTH_CHARS = 10000
96
+ BINARY_PREFIX_BYTES = 8192
97
+
98
+ # Test orchestration seam: invoked immediately before stale-source check
99
+ _PRE_WRITE_HOOK: Optional[Any] = None
100
+
101
+
102
+ def check_file_resilience(file_path: Path, display_path: str) -> Optional[str]:
103
+ """
104
+ Guards against resource exhaustion / DoS vectors:
105
+ 1. Giant files (> 5MB)
106
+ 2. Binary blobs (NUL bytes in prefix)
107
+ 3. Pathological minified one-liners (> 10,000 characters)
108
+
109
+ Returns warning string if file must be skipped, or None if safe.
110
+ """
111
+ try:
112
+ st = file_path.stat()
113
+ if st.st_size > MAX_FILE_SIZE_BYTES:
114
+ return f"Skipping file exceeding size limit (5MB): {display_path}"
115
+ except (OSError, ValueError) as e:
116
+ return f"Skipping inaccessible file/symlink: {display_path} ({e})"
117
+
118
+ try:
119
+ with open(file_path, "rb") as f:
120
+ chunk = f.read(BINARY_PREFIX_BYTES)
121
+ if b"\x00" in chunk:
122
+ return f"Skipping binary file: {display_path}"
123
+ except (OSError, ValueError) as e:
124
+ return f"Skipping unreadable file: {display_path} ({e})"
125
+
126
+ try:
127
+ with open(file_path, "r", encoding="utf-8", errors="replace") as f:
128
+ for line in f:
129
+ if len(line) > MAX_LINE_LENGTH_CHARS:
130
+ return f"Skipping minified file exceeding line length limit (10000): {display_path}"
131
+ except (OSError, ValueError) as e:
132
+ return f"Skipping unreadable file: {display_path} ({e})"
133
+
134
+ return None
135
+
136
+
137
+ # Recorded as soon as the CLI knows its artifact destination, so that a crash anywhere in
138
+ # the scan still leaves Code Scanning a valid artifact to upload instead of failing
139
+ # with "Path does not exist".
140
+ OUTPUT_TARGET: Dict[str, str] = {}
141
+ # Kept as an alias: the SARIF destination is the one CI gates on.
142
+ SARIF_OUTPUT_TARGET = OUTPUT_TARGET
143
+
144
+
145
+ def _minimal_sarif_document() -> Dict[str, Any]:
146
+ """A structurally valid SARIF 2.1.0 run carrying zero results."""
147
+ return {
148
+ "$schema": SARIF_SCHEMA_URI,
149
+ "version": SARIF_VERSION,
150
+ "runs": [
151
+ {
152
+ "tool": {
153
+ "driver": {
154
+ "name": TOOL_NAME,
155
+ "version": TOOL_VERSION,
156
+ "informationUri": TOOL_INFORMATION_URI,
157
+ "rules": [],
158
+ }
159
+ },
160
+ "results": [],
161
+ }
162
+ ],
163
+ }
164
+
165
+
166
+ def ensure_output_artifact(reason: str) -> None:
167
+ """Write the fallback document for the requested format if the real one never landed.
168
+
169
+ A missing or 0-byte artifact is worse than an empty one: the SARIF uploader fails with
170
+ "Path does not exist" and JSON consumers die on JSONDecodeError, hiding the real error.
171
+ """
172
+ target = OUTPUT_TARGET.get("path")
173
+ if not target:
174
+ return
175
+ out_path = Path(os.path.expanduser(str(target))).resolve()
176
+ if out_path.is_file() and out_path.stat().st_size > 0:
177
+ return
178
+ if OUTPUT_TARGET.get("format") == "json":
179
+ document: Dict[str, Any] = {
180
+ "status": "incomplete",
181
+ "error": reason,
182
+ "findings": [],
183
+ "summary": {
184
+ "total_files": 0,
185
+ "lines_scanned": 0,
186
+ "total_findings": 0,
187
+ "security_score": None,
188
+ "risk_level": "UNKNOWN",
189
+ },
190
+ "syntax_errors": [],
191
+ "skipped_files": [],
192
+ }
193
+ label = "JSON"
194
+ else:
195
+ document = _minimal_sarif_document()
196
+ label = "SARIF"
197
+ try:
198
+ atomic_write_text(out_path, json.dumps(document, indent=2) + "\n")
199
+ print(f"[WARN] Wrote fallback {label} artifact to {target} ({reason})", file=sys.stderr)
200
+ except OSError as exc:
201
+ print(f"[ERROR] Could not write fallback {label} artifact '{target}': {exc}", file=sys.stderr)
202
+
203
+
204
+ def ensure_sarif_artifact(reason: str) -> None:
205
+ ensure_output_artifact(reason)
206
+
207
+
208
+ def format_confidence(conf_val: Any = None, conf_label: Optional[str] = None) -> str:
209
+ """Format confidence display string safely without NaN%."""
210
+ if conf_val is None and conf_label is None:
211
+ return "HIGH (PATTERN_MATCH)"
212
+
213
+ if isinstance(conf_val, dict):
214
+ finding = conf_val
215
+ conf_val = finding.get("confidence")
216
+ conf_label = finding.get("confidence_label") or finding.get("confidence")
217
+
218
+ if isinstance(conf_val, str):
219
+ val_str = conf_val.strip()
220
+ if "nan" in val_str.lower():
221
+ return "HIGH (PATTERN_MATCH)"
222
+ if "PATTERN_MATCH" in val_str or "HIGH" in val_str:
223
+ return val_str
224
+ try:
225
+ num = float(val_str)
226
+ label = conf_label if (conf_label and not isinstance(conf_label, (int, float))) else ("CONFIRMED" if num >= 1.0 else "POTENTIAL")
227
+ if "PATTERN_MATCH" in str(label):
228
+ return str(label)
229
+ return f"{label} ({int(num * 100)}%)"
230
+ except (ValueError, TypeError):
231
+ return val_str
232
+
233
+ if isinstance(conf_val, (int, float)):
234
+ import math
235
+ if math.isnan(conf_val):
236
+ return "HIGH (PATTERN_MATCH)"
237
+ label = conf_label if (conf_label and not isinstance(conf_label, (int, float))) else ("CONFIRMED" if conf_val >= 1.0 else "POTENTIAL")
238
+ if "PATTERN_MATCH" in str(label):
239
+ return str(label)
240
+ return f"{label} ({int(conf_val * 100)}%)"
241
+
242
+ if conf_label and isinstance(conf_label, str):
243
+ if "nan" in conf_label.lower():
244
+ return "HIGH (PATTERN_MATCH)"
245
+ return conf_label
246
+
247
+ return "CONFIRMED (100%)"
248
+
249
+
250
+ def extract_remediation_advice(cwe: str, sink_symbol: str) -> str:
251
+ remediations = {
252
+ "CWE-95": "Avoid passing untrusted input to eval(). Use ast.literal_eval() for parsing Python literals, or parse structured data using json.loads().",
253
+ "CWE-78": "Avoid shell execution with dynamic input. Use subprocess.run() with an argument list and shell=False, e.g., subprocess.run(['cmd', arg], shell=False). If shell execution is required, escape dynamic arguments using import shlex; shlex.quote(param). Never generate .replace() character blacklists.",
254
+ "CWE-89": "Use parameterized SQL queries with bind variables instead of string concatenation/formatting, e.g., cursor.execute('SELECT * FROM tbl WHERE id = ?', (user_id,)).",
255
+ "CWE-22": "Enforce canonical pathlib.Path resolution with containment verification (if not target_path.is_relative_to(base_dir): raise ValueError) or sanitize untrusted filenames using werkzeug.utils.secure_filename / os.path.basename. Avoid os.path.abspath without boundary checks.",
256
+ "CWE-502": "Do not deserialize untrusted data with pickle. Use safe serialization formats such as JSON (json.loads), Protocol Buffers, or messagepack.",
257
+ "CWE-1336": "Avoid passing user input directly into render_template_string(). Use standard render_template() with parameterized template context variables to enforce auto-escaping.",
258
+ "CWE-918": "Validate URL with is_safe_url() or check against an allowlist before making requests. Avoid making HTTP requests directly to user-supplied URLs.",
259
+ "CWE-611": "Use defusedxml.ElementTree.parse() / defusedxml.ElementTree.fromstring() instead of xml.etree. Never parse untrusted XML with entity expansion enabled.",
260
+ "CWE-601": "Validate redirect target with is_safe_redirect_url() or ensure it is a relative path before calling redirect().",
261
+ "CWE-327": "Use hashlib.sha256() / sha512() or bcrypt/argon2 instead of MD5/SHA1/DES. Avoid broken cryptographic hashes.",
262
+ "CWE-328": "Use hashlib.sha256() / sha512() or bcrypt/argon2 instead of weak cryptographic hashes.",
263
+ "CWE-338": "Use secrets.token_hex(), secrets.token_urlsafe(), or secrets.choice() instead of random module for security-sensitive tokens.",
264
+ # These two tell the fix generator what the audit actually accepts: registry sanitizer names
265
+ # from SANITIZER_REGISTRY['CWE-117'] and the CSRF guards matched at
266
+ # ast_scanner.py:13524-13562. Keep them in sync with the scanner.
267
+ "CWE-117": "Strip CR/LF from untrusted values before they reach the logger, either with a registry sanitizer call - sanitize_log_input(value), sanitize_log_message(value), replace_crlf(value) or re_sub_crlf(value), e.g. log.info('login for %s', sanitize_log_input(user_id)) - or by removing the control characters outright (value.replace('\\r', '').replace('\\n', '') / re.sub(r'[\\r\\n]', '', value)). A look-alike sanitizer is still reported whatever the variable is named: user_id.strip() or truncated values such as sanitized_user_id = user_id[:64] do not clear the finding.",
268
+ "CWE-352": "Guard every state-changing view: decorate it with @csrf_protect, validate a FlaskForm with form.validate_on_submit(), or enable CSRF module-wide (CSRFProtect(app) with WTF_CSRF_ENABLED / CSRF_ENABLED set to True). Removing @csrf_exempt alone is not a fix - the POST/PUT route is then reported for having no CSRF protection.",
269
+ "CWE-295": "Enable SSL/TLS certificate verification (verify=True or default) and remove AutoAddPolicy. Never set verify=False.",
270
+ "CWE-400": "Escape regex input with re.escape() and enforce chunked/bounded reads with safe_read_chunked() or read(MAX_SIZE).",
271
+ "CWE-776": "Escape regex input with re.escape() and enforce chunked/bounded reads with safe_read_chunked().",
272
+ "CWE-1333": "Escape regex input with re.escape() before compilation to prevent Regular Expression Denial of Service (ReDoS)."
273
+ }
274
+ if cwe in remediations:
275
+ return remediations[cwe]
276
+ rule = GLOBAL_RULE_REGISTRY.get_rule(cwe)
277
+ if rule and rule.remediation:
278
+ return rule.remediation
279
+ return "Sanitize input parameters and enforce strict input validation against an explicit allow-list before passing to dangerous operations."
280
+
281
+
282
+ def configured_rule_ids(config: Optional[TCSConfig]) -> Optional[Set[str]]:
283
+ """Rule ids narrowed by .tcs.yml, or None when the run uses the full engine taxonomy.
284
+
285
+ `None` means "do not filter": the SARIF driver then advertises every registered rule and
286
+ the JSON report lists the documented supported CWE set, instead of the six-rule subset
287
+ that previously made `tcs_cli.py` look narrower than `cli.py scan`.
288
+ """
289
+ if config is None or (not config.rules.enabled and not config.rules.disabled):
290
+ return None
291
+ return set(config.effective_rules)
292
+
293
+
294
+ def advertised_rule_ids(config: Optional[TCSConfig]) -> List[str]:
295
+ narrowed = configured_rule_ids(config)
296
+ if narrowed is not None:
297
+ return sorted(narrowed)
298
+ return sorted({cwe for cwe, _ in ALL_44_CWES} | {r.cwe_id for r in GLOBAL_RULE_REGISTRY.all_rules()})
299
+
300
+
301
+ def consolidate_with_cli_profile(findings: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
302
+ """Collapse CWE families per (file, line) exactly the way `cli.py scan` does.
303
+
304
+ Both entry points read the same engine edges, so matching the emitted site set is
305
+ what makes finding counts and SARIF results comparable across the two CLIs. The
306
+ collapsed ids stay visible: `consolidated_from` is carried onto the surviving
307
+ finding rather than silently dropped.
308
+ """
309
+ if not findings:
310
+ return findings
311
+ from cli import consolidate_findings # noqa: PLC0415 - shared consolidation rules
312
+
313
+ survivors = consolidate_findings([
314
+ {"file": f["file"], "line": f["line_number"], "cwe": f["cwe"],
315
+ "severity": f["severity"], "category": f["category"], "message": f["cwe"]}
316
+ for f in findings
317
+ ])
318
+ kept = {(s["file"], s["line"], s["cwe"]): s for s in survivors}
319
+ merged = []
320
+ for finding in findings:
321
+ site = kept.get((finding["file"], finding["line_number"], finding["cwe"]))
322
+ if site is None:
323
+ continue
324
+ finding["severity"] = site["severity"]
325
+ if site.get("consolidated_from"):
326
+ finding["consolidated_from"] = site["consolidated_from"]
327
+ merged.append(finding)
328
+ return merged
329
+
330
+
331
+ def execute_tcs_scan(
332
+ normalized_files: Dict[str, str],
333
+ config: Optional[TCSConfig] = None,
334
+ audit_all: bool = False,
335
+ secrets: bool = False
336
+ ) -> Dict[str, Any]:
337
+ """
338
+ Executes AST taint tracking, resolves suppressions, and computes risk scores.
339
+ Uses relative filepaths as keys.
340
+ """
341
+ syntax_errors = []
342
+ for fpath, code in normalized_files.items():
343
+ try:
344
+ ast.parse(code, filename=fpath)
345
+ except SyntaxError as se:
346
+ syntax_errors.append(f"{fpath}:{se.lineno}: {se.msg}")
347
+
348
+ tracker = TaintTracker(files=normalized_files, audit_all=audit_all)
349
+ sources, sinks, edges = tracker.analyze()
350
+
351
+ sinks_by_id = {s.id: s for s in sinks}
352
+ sources_by_id = {s.id: s for s in sources}
353
+
354
+ findings = []
355
+ seen_vulns = set()
356
+ vuln_idx = 1
357
+
358
+ for edge in edges:
359
+ sink = sinks_by_id.get(edge.target_id)
360
+ if not sink:
361
+ continue
362
+
363
+ cwe = sink.metadata.get("cwe", "UNKNOWN_CWE")
364
+ if config is not None and not config.is_rule_enabled(cwe):
365
+ continue
366
+ category = sink.metadata.get("sink_type", "UNKNOWN_VULNERABILITY")
367
+ confidence_val = float(edge.confidence)
368
+ # `cli.py scan` grades a flow CONFIRMED from the edge kind, not the numeric
369
+ # confidence; mirroring it here keeps severity identical across both CLIs.
370
+ confidence_label = "CONFIRMED" if edge.kind == "CONFIRMED_DATA_FLOW" else "POTENTIAL"
371
+
372
+ rule = GLOBAL_RULE_REGISTRY.get_rule(cwe)
373
+ severity = rule.get_severity(confidence_label).upper() if rule else "HIGH"
374
+
375
+ source_node = sources_by_id.get(edge.source_id)
376
+ sink_loc = sink.location
377
+ source_loc = source_node.location if source_node else None
378
+
379
+ dedup_key = (sink_loc.file, sink_loc.line_start, cwe)
380
+ if dedup_key in seen_vulns:
381
+ continue
382
+ seen_vulns.add(dedup_key)
383
+
384
+ target_file_content = normalized_files.get(sink_loc.file, "")
385
+ target_lines = target_file_content.splitlines()
386
+ offending_snippet = ""
387
+ if 1 <= sink_loc.line_start <= len(target_lines):
388
+ offending_snippet = target_lines[sink_loc.line_start - 1].strip()
389
+
390
+ transform_raw = edge.transform or ""
391
+
392
+ # Resolve source information
393
+ src_sym = None
394
+ src_file = None
395
+ src_line_no = None
396
+
397
+ if source_node:
398
+ src_sym = source_node.symbol
399
+ src_file = source_loc.file if source_loc else sink_loc.file
400
+ src_line_no = source_loc.line_start if source_loc else sink_loc.line_start
401
+ elif getattr(edge, "proof_graph", None) and edge.proof_graph.nodes:
402
+ first_node = edge.proof_graph.nodes[0]
403
+ if first_node.node_type == ProofNodeType.SOURCE or getattr(first_node.node_type, "value", str(first_node.node_type)) == "source":
404
+ src_sym = first_node.symbol
405
+ src_file = first_node.file_path or sink_loc.file
406
+ src_line_no = first_node.start_line or sink_loc.line_start
407
+
408
+ # If source is missing or generic "User Input", standardize to user_input ({func_name})
409
+ if not src_sym or src_sym in ("User Input", "USER_INPUT", "Untrusted Input Origin"):
410
+ func_name = "handler"
411
+ if getattr(edge, "proof_graph", None) and edge.proof_graph.nodes:
412
+ sc = edge.proof_graph.nodes[0].scope_id or ""
413
+ if ":" in sc:
414
+ sc_cand = sc.split(":")[-1]
415
+ if sc_cand and sc_cand not in ("global", "module"):
416
+ func_name = sc_cand
417
+ if func_name == "handler" and hasattr(sink, "scope_id") and sink.scope_id:
418
+ if ":" in sink.scope_id:
419
+ sc_cand = sink.scope_id.split(":")[-1]
420
+ if sc_cand and sc_cand not in ("global", "module"):
421
+ func_name = sc_cand
422
+ src_sym = f"user_input ({func_name})"
423
+ if not src_file:
424
+ src_file = sink_loc.file
425
+ if src_line_no is None:
426
+ src_line_no = max(1, sink_loc.line_start - 1)
427
+
428
+ trace_steps = [f"Source: {src_sym} ({src_file}:{src_line_no})"]
429
+
430
+ if transform_raw:
431
+ parts = [p.strip() for p in transform_raw.split("->")]
432
+ for p in parts:
433
+ if p.startswith("SRC-") or p == "binary_op" or not p:
434
+ continue
435
+ # Replace bracketed path/join operators with readable os.path.join()
436
+ if p in ("[join]", "[path_join]", "[join_unknown]", "[join_internal]", "[os.path.join]") or (p.startswith("[") and "join" in p.lower()):
437
+ join_step = f"Variable / Flow: os.path.join() ({sink_loc.file}:{sink_loc.line_start})"
438
+ if join_step not in trace_steps:
439
+ trace_steps.append(join_step)
440
+ continue
441
+ if p.startswith("[") and p.endswith("]"):
442
+ op_name = p[1:-1]
443
+ op_step = f"Variable / Flow: {op_name}()"
444
+ if op_step not in trace_steps:
445
+ trace_steps.append(op_step)
446
+ continue
447
+
448
+ # Normalize return steps to avoid integer leakage (e.g. return:target.py:13 -> return (L13))
449
+ if p.startswith("return:"):
450
+ ret_parts = p.split(":")
451
+ if len(ret_parts) >= 2 and ret_parts[-1].isdigit():
452
+ clean_p = f"return (L{ret_parts[-1]})"
453
+ else:
454
+ clean_p = "return"
455
+ elif p.startswith("return_from:"):
456
+ clean_p = f"return_from {p.split(':')[-1]}()"
457
+ elif p.isdigit():
458
+ clean_p = f"return (L{p})"
459
+ else:
460
+ clean_p = p.split(":")[-1] if ":" in p else p
461
+ if clean_p.isdigit():
462
+ clean_p = f"return (L{clean_p})"
463
+
464
+ # Skip untainted string literals (quoted paths like "/var/www/uploads")
465
+ if clean_p.startswith('"') or clean_p.startswith("'") or clean_p.startswith("/"):
466
+ continue
467
+
468
+ var_step = f"Variable / Flow: {clean_p}"
469
+ if clean_p and var_step not in trace_steps:
470
+ trace_steps.append(var_step)
471
+
472
+ trace_steps.append(f"Sink: {sink.symbol} ({sink_loc.file}:{sink_loc.line_start})")
473
+
474
+ snk_sym = sink.symbol
475
+ snk_line = f"L{sink_loc.line_start}"
476
+ src_line_str = f"L{src_line_no}" if src_line_no is not None else "L?"
477
+
478
+ flow_summary = f"[{src_sym} ({src_line_str})] -> [Tainted Dataflow] -> [{snk_sym} ({snk_line})]"
479
+ remediation = extract_remediation_advice(cwe, sink.symbol)
480
+
481
+ findings.append({
482
+ "id": f"TimeCodeSecurity-VULN-{vuln_idx:03d}",
483
+ "category": category,
484
+ "cwe": cwe,
485
+ "severity": severity,
486
+ "confidence": confidence_val,
487
+ "confidence_label": confidence_label,
488
+ "file": sink_loc.file,
489
+ "line_number": sink_loc.line_start,
490
+ "sink_symbol": sink.symbol,
491
+ "source_symbol": src_sym if (source_node or src_sym) else "USER_INPUT",
492
+ "source_line": src_line_no,
493
+ "source_file": src_file,
494
+ "code_snippet": offending_snippet,
495
+ "flow_trace": trace_steps,
496
+ "flow_trace_summary": flow_summary,
497
+ "remediation": remediation,
498
+ "proof_graph": edge.proof_graph.to_dict() if edge.proof_graph else None,
499
+ "proof_graph_ascii": render_proof_graph_ascii(edge.proof_graph) if edge.proof_graph else None,
500
+ "discovery_mode": "STANDARD_SCAN"
501
+ })
502
+ vuln_idx += 1
503
+
504
+ findings = consolidate_with_cli_profile(findings)
505
+ vuln_idx = len(findings) + 1
506
+
507
+ secret_findings_list = []
508
+ if secrets:
509
+ from secret_scanner import scan_text
510
+ from secret_filters import filter_findings, FilterConfig
511
+ filter_cfg = FilterConfig()
512
+ for fpath, code in normalized_files.items():
513
+ raw_sec = scan_text(code, filename=fpath)
514
+ passed_sec = filter_findings(raw_sec, file_path=fpath, config=filter_cfg)
515
+ for sf in passed_sec:
516
+ sec_dict = {
517
+ "id": f"TimeCodeSecurity-SEC-{vuln_idx:03d}",
518
+ "category": "HARDCODED_SECRET",
519
+ "cwe": "CWE-798",
520
+ "severity": "HIGH",
521
+ "confidence": 1.0,
522
+ "confidence_label": "CONFIRMED",
523
+ "file": sf.file,
524
+ "line_number": sf.line_number,
525
+ "column_start": sf.column_start,
526
+ "column_end": sf.column_end,
527
+ "masked_value": sf.masked_value,
528
+ "secret_type": sf.secret_type,
529
+ "detector": sf.detector,
530
+ "pattern": getattr(sf, "pattern", None) or sf.detector or "hardcoded_credential_variable",
531
+ "code_snippet": sf.context or "",
532
+ "flow_trace": [f"Secret: {sf.secret_type} ({sf.file}:{sf.line_number})"],
533
+ "flow_trace_summary": f"[{sf.secret_type} (L{sf.line_number})] -> [Hardcoded Secret] -> [CWE-798]",
534
+ "remediation": "Revoke and rotate the exposed credential immediately. Store secrets in environment variables or a dedicated secret management service.",
535
+ "proof_graph": None,
536
+ "proof_graph_ascii": None,
537
+ "discovery_mode": "STANDARD_SCAN",
538
+ "is_secret": True
539
+ }
540
+ findings.append(sec_dict)
541
+ vuln_idx += 1
542
+ secret_findings_list.append(sec_dict)
543
+
544
+ suppression_enabled = True if config is None else config.suppression.enabled
545
+ if suppression_enabled:
546
+ findings = resolve_suppressions(findings, normalized_files)
547
+ else:
548
+ for f in findings:
549
+ f["suppressed"] = False
550
+ f["suppression_justification"] = None
551
+ f["suppression_kind"] = None
552
+ f["active"] = True
553
+
554
+ total_files = len(normalized_files)
555
+ lines_scanned = sum(len(c.splitlines()) for c in normalized_files.values())
556
+ total_vulnerabilities = len(findings)
557
+
558
+ active_findings = [f for f in findings if not f.get("suppressed", False)]
559
+ suppressed_findings = [f for f in findings if f.get("suppressed", False)]
560
+ active_vulnerabilities = len(active_findings)
561
+ suppressed_vulnerabilities = len(suppressed_findings)
562
+
563
+ critical_count = sum(1 for f in active_findings if f["severity"] == "CRITICAL")
564
+ high_count = sum(1 for f in active_findings if f["severity"] == "HIGH")
565
+ medium_count = sum(1 for f in active_findings if f["severity"] == "MEDIUM")
566
+ low_count = sum(1 for f in active_findings if f["severity"] == "LOW")
567
+
568
+ security_score = max(0, 100 - (critical_count * 25 + high_count * 15 + medium_count * 5))
569
+
570
+ if active_vulnerabilities == 0:
571
+ risk_level = "CLEAN"
572
+ risk_message = f"NO VULNERABILITIES DETECTED within current TimeCodeSecurity analysis scope ({get_active_cwe_count()} supported CWE classes)."
573
+ elif critical_count > 0:
574
+ risk_level = "CRITICAL"
575
+ risk_message = "CRITICAL RISK: Arbitrary code execution or high-impact injection detected."
576
+ elif high_count > 0:
577
+ risk_level = "HIGH"
578
+ risk_message = "HIGH RISK: Injection or data traversal vulnerabilities detected."
579
+ elif medium_count > 0:
580
+ risk_level = "MEDIUM"
581
+ risk_message = "MEDIUM RISK: Potential data-flow flaws detected."
582
+ else:
583
+ risk_level = "LOW"
584
+ risk_message = "LOW RISK: Minor security notices."
585
+
586
+ scan_filename = list(normalized_files.keys())[0] if len(normalized_files) == 1 else "target.py"
587
+
588
+ return {
589
+ "status": "success",
590
+ "syntax_errors": syntax_errors,
591
+ "enabled_rules": advertised_rule_ids(config),
592
+ "summary": {
593
+ "total_files": total_files,
594
+ "lines_scanned": lines_scanned,
595
+ "total_vulnerabilities": total_vulnerabilities,
596
+ "active_vulnerabilities": active_vulnerabilities,
597
+ "suppressed_vulnerabilities": suppressed_vulnerabilities,
598
+ "critical_count": critical_count,
599
+ "high_count": high_count,
600
+ "medium_count": medium_count,
601
+ "low_count": low_count,
602
+ "security_score": security_score,
603
+ "score_label": "Security Health Score",
604
+ "risk_level": risk_level,
605
+ "risk_message": risk_message,
606
+ "target_file": scan_filename,
607
+ "filename": scan_filename,
608
+ "scope_filename": scan_filename
609
+ },
610
+ "scope": {
611
+ "target_file": scan_filename,
612
+ "filename": scan_filename,
613
+ "total_files": total_files,
614
+ "lines_scanned": lines_scanned
615
+ },
616
+ "findings": findings
617
+ }
618
+ if secrets:
619
+ ret["secret_findings"] = secret_findings_list
620
+ return ret
621
+
622
+
623
+ SECRET_EXTS = {".py", ".env", ".json", ".yaml", ".yml", ".toml", ".ini", ".conf", ".txt",
624
+ ".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"}
625
+
626
+
627
+ def engine_file_key(path: Path) -> str:
628
+ """File identity handed to the AST engine.
629
+
630
+ `cli.py scan` keys modules by their path relative to the working directory, and the
631
+ tracker's cross-module resolution follows those keys, so both CLIs must key files the
632
+ same way or they can disagree on findings. SARIF URIs are resolved against %SRCROOT%
633
+ (the working directory), which makes the same spelling correct there too.
634
+ """
635
+ from cli import _file_key # noqa: PLC0415 - single source of the keying rule
636
+
637
+ return _file_key(path, Path.cwd().resolve())
638
+
639
+
640
+
641
+ def discover_python_files(
642
+ target_path: Path,
643
+ base_dir: Path,
644
+ sca_active: bool = False,
645
+ secrets_active: bool = False,
646
+ skipped_files: Optional[List[str]] = None,
647
+ ) -> Dict[str, str]:
648
+ """
649
+ Recursively discovers Python files, ignoring non-code or virtual env folders.
650
+ Guards against symlink loops, giant files, binary blobs, and minified bundles.
651
+ Returns mapping of POSIX relative paths to text contents.
652
+ """
653
+ normalized_files: Dict[str, str] = {}
654
+ manifest_names = {"requirements.txt", "pipfile.lock", "poetry.lock", "pyproject.toml"}
655
+
656
+ if target_path.is_file():
657
+ if target_path.suffix.lower() != ".py":
658
+ if sca_active and target_path.name.lower() in manifest_names:
659
+ return {}
660
+ if secrets_active and (
661
+ target_path.suffix.lower() in SECRET_EXTS
662
+ or target_path.name.lower().startswith(".env")
663
+ ):
664
+ return {}
665
+ print(f"[ERROR] Target is not a Python file: {target_path}", file=sys.stderr)
666
+ sys.exit(2)
667
+ try:
668
+ rel_path = target_path.relative_to(base_dir).as_posix()
669
+ except ValueError:
670
+ rel_path = target_path.name
671
+
672
+ skip_reason = check_file_resilience(target_path, rel_path)
673
+ if skip_reason:
674
+ print(f"[WARN] {skip_reason}", file=sys.stderr)
675
+ if skipped_files is not None:
676
+ skipped_files.append(skip_reason)
677
+ return normalized_files
678
+
679
+ try:
680
+ normalized_files[engine_file_key(target_path)] = target_path.read_text(encoding="utf-8")
681
+ except (OSError, UnicodeDecodeError, ValueError) as e:
682
+ print(f"[WARN] Skipping unreadable file: {target_path} ({e})", file=sys.stderr)
683
+ if skipped_files is not None:
684
+ skipped_files.append(f"Skipping unreadable file: {rel_path} ({e})")
685
+ return normalized_files
686
+
687
+ visited_dirs: Set[str] = set()
688
+ for root, dirs, files in os.walk(target_path, followlinks=False):
689
+ real_root = os.path.realpath(root)
690
+ if real_root in visited_dirs:
691
+ dirs[:] = []
692
+ continue
693
+ visited_dirs.add(real_root)
694
+
695
+ # Modify dirs in place to prune ignored folders and directory symlinks
696
+ pruned_dirs = []
697
+ for d in dirs:
698
+ dir_full = os.path.join(root, d)
699
+ if os.path.islink(dir_full):
700
+ continue
701
+ if d not in IGNORED_DIRS and not d.startswith("."):
702
+ pruned_dirs.append(d)
703
+ dirs[:] = pruned_dirs
704
+
705
+ for fname in files:
706
+ if fname.endswith(".py") and fname != "tcs_cli.py":
707
+ full_file = Path(root) / fname
708
+ try:
709
+ rel_path = full_file.relative_to(target_path).as_posix()
710
+ except ValueError:
711
+ try:
712
+ rel_path = full_file.relative_to(base_dir).as_posix()
713
+ except ValueError:
714
+ rel_path = full_file.name
715
+
716
+ skip_reason = check_file_resilience(full_file, rel_path)
717
+ if skip_reason:
718
+ print(f"[WARN] {skip_reason}", file=sys.stderr)
719
+ if skipped_files is not None:
720
+ skipped_files.append(skip_reason)
721
+ continue
722
+
723
+ try:
724
+ normalized_files[engine_file_key(full_file)] = full_file.read_text(encoding="utf-8")
725
+ except (OSError, UnicodeDecodeError, ValueError) as e:
726
+ print(f"[WARN] Skipping unreadable file: {full_file} ({e})", file=sys.stderr)
727
+ if skipped_files is not None:
728
+ skipped_files.append(f"Skipping unreadable file: {rel_path} ({e})")
729
+
730
+ return normalized_files
731
+
732
+
733
+ def discover_secret_files(
734
+ target_path: Path,
735
+ base_dir: Path,
736
+ skipped_files: Optional[List[str]] = None,
737
+ ) -> List[Path]:
738
+ """
739
+ Discovers text/configuration files to scan for hardcoded secrets and credentials.
740
+ Supports .py, .env, .json, .yaml, .yml, .toml, .ini, .conf, .txt.
741
+ Guards against symlink loops, giant files, binary blobs, and minified bundles.
742
+ """
743
+ discovered: List[Path] = []
744
+
745
+ if target_path.is_file():
746
+ if target_path.suffix.lower() in SECRET_EXTS or target_path.name.lower().startswith(".env"):
747
+ rel_name = target_path.name
748
+ skip_reason = check_file_resilience(target_path, rel_name)
749
+ if skip_reason:
750
+ print(f"[WARN] {skip_reason}", file=sys.stderr)
751
+ if skipped_files is not None:
752
+ skipped_files.append(skip_reason)
753
+ else:
754
+ discovered.append(target_path)
755
+ return discovered
756
+
757
+ visited_dirs: Set[str] = set()
758
+ for root, dirs, files in os.walk(target_path, followlinks=False):
759
+ real_root = os.path.realpath(root)
760
+ if real_root in visited_dirs:
761
+ dirs[:] = []
762
+ continue
763
+ visited_dirs.add(real_root)
764
+
765
+ pruned_dirs = []
766
+ for d in dirs:
767
+ dir_full = os.path.join(root, d)
768
+ if os.path.islink(dir_full):
769
+ continue
770
+ if d not in IGNORED_DIRS and not d.startswith("."):
771
+ pruned_dirs.append(d)
772
+ dirs[:] = pruned_dirs
773
+
774
+ for fname in files:
775
+ p = Path(root) / fname
776
+ if p.suffix.lower() in SECRET_EXTS or fname.lower().startswith(".env"):
777
+ if fname != "tcs_cli.py":
778
+ try:
779
+ rel_path = p.relative_to(target_path).as_posix()
780
+ except ValueError:
781
+ try:
782
+ rel_path = p.relative_to(base_dir).as_posix()
783
+ except ValueError:
784
+ rel_path = p.name
785
+
786
+ skip_reason = check_file_resilience(p, rel_path)
787
+ if skip_reason:
788
+ print(f"[WARN] {skip_reason}", file=sys.stderr)
789
+ if skipped_files is not None:
790
+ skipped_files.append(skip_reason)
791
+ continue
792
+ discovered.append(p)
793
+
794
+ discovered.sort()
795
+ return discovered
796
+
797
+
798
+ def discover_manifest_files(
799
+ target_path: Path,
800
+ base_dir: Path,
801
+ skipped_files: Optional[List[str]] = None,
802
+ ) -> List[Path]:
803
+ """
804
+ Discovers supported dependency manifests within the target scope.
805
+ Supported filenames: requirements.txt, Pipfile.lock, poetry.lock.
806
+ Guards against symlink loops, giant files, binary blobs, and minified bundles.
807
+ """
808
+ manifest_names = {"requirements.txt", "pipfile.lock", "poetry.lock", "pyproject.toml"}
809
+ discovered: List[Path] = []
810
+
811
+ if target_path.is_file():
812
+ if target_path.name.lower() in manifest_names:
813
+ skip_reason = check_file_resilience(target_path, target_path.name)
814
+ if skip_reason:
815
+ print(f"[WARN] {skip_reason}", file=sys.stderr)
816
+ if skipped_files is not None:
817
+ skipped_files.append(skip_reason)
818
+ else:
819
+ discovered.append(target_path)
820
+ return discovered
821
+
822
+ visited_dirs: Set[str] = set()
823
+ for root, dirs, files in os.walk(target_path, followlinks=False):
824
+ real_root = os.path.realpath(root)
825
+ if real_root in visited_dirs:
826
+ dirs[:] = []
827
+ continue
828
+ visited_dirs.add(real_root)
829
+
830
+ pruned_dirs = []
831
+ for d in dirs:
832
+ dir_full = os.path.join(root, d)
833
+ if os.path.islink(dir_full):
834
+ continue
835
+ if d not in IGNORED_DIRS and not d.startswith("."):
836
+ pruned_dirs.append(d)
837
+ dirs[:] = pruned_dirs
838
+
839
+ for fname in files:
840
+ if fname.lower() in manifest_names:
841
+ p = Path(root) / fname
842
+ try:
843
+ rel_path = p.relative_to(target_path).as_posix()
844
+ except ValueError:
845
+ try:
846
+ rel_path = p.relative_to(base_dir).as_posix()
847
+ except ValueError:
848
+ rel_path = p.name
849
+
850
+ skip_reason = check_file_resilience(p, rel_path)
851
+ if skip_reason:
852
+ print(f"[WARN] {skip_reason}", file=sys.stderr)
853
+ if skipped_files is not None:
854
+ skipped_files.append(skip_reason)
855
+ continue
856
+ discovered.append(p)
857
+
858
+ discovered.sort()
859
+ return discovered
860
+
861
+
862
+ def format_reachability_section(reachability_findings: List[Dict[str, Any]]) -> str:
863
+ if not reachability_findings:
864
+ return ""
865
+
866
+ reachable_count = sum(1 for f in reachability_findings if f.get("reachability_classification") == "REACHABLE_API_USE")
867
+ active_count = sum(1 for f in reachability_findings if f.get("reachability_classification") == "DEPENDENCY_ACTIVE")
868
+ dormant_count = sum(1 for f in reachability_findings if f.get("reachability_classification") == "DEPENDENCY_DORMANT")
869
+ transitive_count = sum(1 for f in reachability_findings if f.get("reachability_classification") == "TRANSITIVE_VULNERABLE")
870
+
871
+ lines = [
872
+ "=" * 55,
873
+ "VECTOR C: DEPENDENCY REACHABILITY ANALYSIS",
874
+ "=" * 55,
875
+ f"[Status Summary: {reachable_count} Reachable | {active_count} Active | {dormant_count} Dormant | {transitive_count} Transitive]",
876
+ ""
877
+ ]
878
+
879
+ for rf in reachability_findings:
880
+ pkg = rf.get("package_name", "")
881
+ ver = rf.get("declared_version") or "unknown"
882
+ cls = rf.get("reachability_classification", "")
883
+ adv_id = rf.get("advisory_id", "")
884
+ sev = rf.get("severity", "UNKNOWN")
885
+ imp_status = rf.get("import_status", "")
886
+ imp_ev = rf.get("import_evidence") or {}
887
+ file_loc = imp_ev.get("file", "-")
888
+ line_loc = imp_ev.get("line", "-")
889
+ loc_str = f"{file_loc}:{line_loc}" if file_loc != "-" else "-"
890
+ call_path = rf.get("call_path", [])
891
+ path_str = " -> ".join(call_path) if call_path else "None"
892
+ depth = rf.get("call_depth", 0)
893
+ edge = rf.get("edge_type", "UNRESOLVED_EDGE")
894
+ limitations = rf.get("limitations", [])
895
+
896
+ desc = ""
897
+ if cls == "REACHABLE_API_USE":
898
+ desc = " (CRITICAL / High Alert)"
899
+ elif cls == "DEPENDENCY_ACTIVE":
900
+ desc = " (Imported, no known vulnerable API called)"
901
+ elif cls == "DEPENDENCY_DORMANT":
902
+ desc = " (Declared in manifest, never imported)"
903
+ elif cls == "TRANSITIVE_VULNERABLE":
904
+ desc = " (Transitive dependency, not imported directly)"
905
+
906
+ lines.append(f"- [PKG] {pkg} ({ver}) -> {cls}{desc}")
907
+ lines.append(f" Advisory: {adv_id} ({sev})")
908
+ lines.append(f" Import State: {imp_status} ({loc_str})")
909
+ lines.append(f" Call Path: {path_str} (Depth: {depth}, Edge: {edge})")
910
+ if limitations:
911
+ lines.append(f" Limitations: {'; '.join(limitations)}")
912
+ lines.append("")
913
+
914
+ return "\n".join(lines).rstrip()
915
+
916
+
917
+ def format_table(
918
+ results: Dict[str, Any],
919
+ findings: List[Dict[str, Any]],
920
+ sca_findings: Optional[List[Any]] = None,
921
+ sca_enabled: bool = False,
922
+ secret_findings: Optional[List[Any]] = None,
923
+ secrets_enabled: bool = False,
924
+ reachability_findings: Optional[List[Any]] = None,
925
+ reachability_enabled: bool = False
926
+ ) -> str:
927
+ """Renders human-readable tabular scan report for console display."""
928
+ summary = results.get("summary", {})
929
+ total_files = summary.get("total_files", 0)
930
+ lines_scanned = summary.get("lines_scanned", 0)
931
+ score = summary.get("security_score", 100)
932
+ risk_level = summary.get("risk_level", "CLEAN")
933
+
934
+ sca_list = [f.to_dict() if hasattr(f, "to_dict") else dict(f) for f in (sca_findings or [])] if sca_enabled else []
935
+ sec_list = [dataclasses.asdict(f) if hasattr(f, "__dataclass_fields__") else (f.to_dict() if hasattr(f, "to_dict") else dict(f)) for f in (secret_findings or [])] if secrets_enabled else []
936
+
937
+ if not sca_enabled and not secrets_enabled:
938
+ lines = [
939
+ "=" * 88,
940
+ "TimeCodeSecurity AST Security Scan Report",
941
+ "=" * 88,
942
+ f"Scanned Files: {total_files} | Total Lines: {lines_scanned} | Security Score: {score}/100 ({risk_level})",
943
+ f"Total Findings Displayed: {len(findings)}",
944
+ "-" * 88
945
+ ]
946
+
947
+ if not findings:
948
+ if results.get("unresolved_dependencies"):
949
+ lines.append("PARTIAL ANALYSIS: Analysis incomplete due to unresolved / deleted dependencies.")
950
+ lines.append("\n[UNRESOLVED DEPENDENCIES]")
951
+ for unres_item in results.get("unresolved_dependencies", []):
952
+ lines.append(f" {unres_item}")
953
+ else:
954
+ lines.append("No security vulnerabilities detected.")
955
+ if results.get("syntax_errors") or results.get("skipped_files"):
956
+ lines.append("\n[PARSER & RESOURCE WARNINGS (SKIPPED FILES)]")
957
+ for err in results.get("syntax_errors", []):
958
+ lines.append(f" Skipping AST analysis for unparseable file: {err}")
959
+ for skip in results.get("skipped_files", []):
960
+ lines.append(f" {skip}")
961
+ if reachability_enabled and reachability_findings:
962
+ lines.append("\n" + format_reachability_section(reachability_findings))
963
+ lines.append("=" * 88)
964
+ return "\n".join(lines)
965
+
966
+ lines.append(f"{'ID':<14} | {'SEVERITY':<8} | {'CWE':<9} | {'STATUS':<10} | {'LOCATION':<22} | {'SINK':<15}")
967
+ lines.append("-" * 88)
968
+ for f in findings:
969
+ fid = f.get("id", "")
970
+ sev = f.get("severity", "MEDIUM")
971
+ cwe = f.get("cwe", "")
972
+ status = "SUPPRESSED" if f.get("suppressed") else "ACTIVE"
973
+ loc = f"{f.get('file', '')}:{f.get('line_number', '')}"
974
+ sink = f.get("sink_symbol", "")
975
+ lines.append(f"{fid:<14} | {sev:<8} | {cwe:<9} | {status:<10} | {loc:<22} | {sink:<15}")
976
+
977
+ lines.append("-" * 88)
978
+ lines.append("\nFINDING DETAILS:")
979
+ for f in findings:
980
+ fid = f.get("id", "")
981
+ cwe = f.get("cwe", "")
982
+ cat = f.get("category", "")
983
+ status = "SUPPRESSED" if f.get("suppressed") else "ACTIVE"
984
+ lines.append(f"\n[{fid}] {cwe} ({cat}) - Status: {status}")
985
+ lines.append(f" Location: {f.get('file', '')}:{f.get('line_number', '')}")
986
+ lines.append(f" Severity: {f.get('severity', '')} (Confidence: {format_confidence(f.get('confidence'), f.get('confidence_label'))})")
987
+ if f.get("code_snippet"):
988
+ lines.append(f" Code Snippet: {f.get('code_snippet')}")
989
+ if f.get("flow_trace_summary"):
990
+ lines.append(f" Flow Summary: {f.get('flow_trace_summary')}")
991
+ if f.get("flow_trace"):
992
+ lines.append(" Dataflow Trace:")
993
+ for step in f.get("flow_trace"):
994
+ lines.append(f" - {step}")
995
+ if f.get("suppressed") and f.get("suppression_justification"):
996
+ lines.append(f" Justification:{f.get('suppression_justification')}")
997
+ if f.get("remediation"):
998
+ lines.append(f" Remediation: {f.get('remediation')}")
999
+
1000
+ if results.get("syntax_errors") or results.get("skipped_files"):
1001
+ lines.append("\n[PARSER & RESOURCE WARNINGS (SKIPPED FILES)]")
1002
+ for err in results.get("syntax_errors", []):
1003
+ lines.append(f" Skipping AST analysis for unparseable file: {err}")
1004
+ for skip in results.get("skipped_files", []):
1005
+ lines.append(f" {skip}")
1006
+
1007
+ if reachability_enabled and reachability_findings:
1008
+ lines.append("\n" + format_reachability_section(reachability_findings))
1009
+
1010
+ lines.append("=" * 88)
1011
+ return "\n".join(lines)
1012
+
1013
+ # ---------------------------------------------------------
1014
+ # Unified Multi-Engine Report (SAST, SCA, Secrets)
1015
+ # ---------------------------------------------------------
1016
+ sep = "=" * 105
1017
+ dash_sep = "-" * 105
1018
+
1019
+ title_parts = ["SAST"]
1020
+ if sca_enabled:
1021
+ title_parts.append("SCA")
1022
+ if secrets_enabled:
1023
+ title_parts.append("SECRETS")
1024
+ title_str = " + ".join(title_parts)
1025
+
1026
+ count_parts = [f"Total SAST Findings: {len(findings)}"]
1027
+ if sca_enabled:
1028
+ count_parts.append(f"Total SCA Findings: {len(sca_list)}")
1029
+ if secrets_enabled:
1030
+ count_parts.append(f"Total Secret Findings: {len(sec_list)}")
1031
+ count_str = " | ".join(count_parts)
1032
+
1033
+ lines = [
1034
+ sep,
1035
+ f"TimeCodeSecurity Security Scan Report ({title_str})",
1036
+ sep,
1037
+ f"Scanned Files: {total_files} | Total Lines: {lines_scanned} | Security Score: {score}/100 ({risk_level})",
1038
+ count_str,
1039
+ dash_sep
1040
+ ]
1041
+
1042
+ if not findings and not sca_list and not sec_list:
1043
+ if results.get("unresolved_dependencies"):
1044
+ lines.append("PARTIAL ANALYSIS: Analysis incomplete due to unresolved / deleted dependencies.")
1045
+ lines.append("\n[UNRESOLVED DEPENDENCIES]")
1046
+ for unres_item in results.get("unresolved_dependencies", []):
1047
+ lines.append(f" {unres_item}")
1048
+ else:
1049
+ lines.append("No security vulnerabilities detected.")
1050
+ if results.get("syntax_errors") or results.get("skipped_files"):
1051
+ lines.append("\n[PARSER & RESOURCE WARNINGS (SKIPPED FILES)]")
1052
+ for err in results.get("syntax_errors", []):
1053
+ lines.append(f" Skipping AST analysis for unparseable file: {err}")
1054
+ for skip in results.get("skipped_files", []):
1055
+ lines.append(f" {skip}")
1056
+ if reachability_enabled and reachability_findings:
1057
+ lines.append("\n" + format_reachability_section(reachability_findings))
1058
+ lines.append(sep)
1059
+ return "\n".join(lines)
1060
+
1061
+ if findings:
1062
+ lines.append("\n[SAST CODE ANALYSIS FINDINGS]")
1063
+ lines.append(f"{'ID':<14} | {'SEVERITY':<8} | {'CWE':<9} | {'STATUS':<10} | {'LOCATION':<22} | {'SINK':<15}")
1064
+ lines.append(dash_sep)
1065
+ for f in findings:
1066
+ fid = f.get("id", "")
1067
+ sev = f.get("severity", "MEDIUM")
1068
+ cwe = f.get("cwe", "")
1069
+ status = "SUPPRESSED" if f.get("suppressed") else "ACTIVE"
1070
+ loc = f"{f.get('file', '')}:{f.get('line_number', '')}"
1071
+ sink = f.get("sink_symbol", "")
1072
+ lines.append(f"{fid:<14} | {sev:<8} | {cwe:<9} | {status:<10} | {loc:<22} | {sink:<15}")
1073
+
1074
+ if sca_list:
1075
+ lines.append("\n[SCA DEPENDENCY VULNERABILITIES]")
1076
+ if reachability_enabled:
1077
+ lines.append(f"{'PACKAGE':<16} | {'STATUS':<11} | {'REACHABILITY':<20} | {'INSTALLED / SPEC':<18} | {'VULN ID':<16} | {'SEVERITY':<8} | {'LOCATION':<20}")
1078
+ lines.append(dash_sep)
1079
+ for sf in sca_list:
1080
+ pkg = str(sf.get("package_name", ""))[:16]
1081
+ status = str(sf.get("status", ""))[:11]
1082
+ vid = str(sf.get("vulnerability_id", ""))[:16]
1083
+ reach_str = "-"
1084
+ if reachability_findings:
1085
+ norm_p = pkg.lower().replace("_", "-")
1086
+ for rf in reachability_findings:
1087
+ if rf.get("package_name", "").lower().replace("_", "-") == norm_p and (rf.get("advisory_id") == vid or not rf.get("advisory_id")):
1088
+ reach_str = str(rf.get("reachability_classification", "-"))
1089
+ break
1090
+ reach_str = reach_str[:20]
1091
+ ver_spec = str(sf.get("installed_version") or sf.get("requested_specifier") or "-")[:18]
1092
+ sev = str(sf.get("severity", "UNKNOWN"))[:8]
1093
+ loc_str = f"{sf.get('manifest_source', '')}:{sf.get('line_number') or '?'}"[:20]
1094
+ lines.append(f"{pkg:<16} | {status:<11} | {reach_str:<20} | {ver_spec:<18} | {vid:<16} | {sev:<8} | {loc_str:<20}")
1095
+ else:
1096
+ lines.append(f"{'PACKAGE':<16} | {'STATUS':<11} | {'INSTALLED / SPEC':<18} | {'VULN ID':<16} | {'SEVERITY':<8} | {'FIXED':<10} | {'LOCATION':<20}")
1097
+ lines.append(dash_sep)
1098
+ for sf in sca_list:
1099
+ pkg = str(sf.get("package_name", ""))[:16]
1100
+ status = str(sf.get("status", ""))[:11]
1101
+ ver_spec = str(sf.get("installed_version") or sf.get("requested_specifier") or "-")[:18]
1102
+ vid = str(sf.get("vulnerability_id", ""))[:16]
1103
+ sev = str(sf.get("severity", "UNKNOWN"))[:8]
1104
+ fixed = str(sf.get("fixed_version") or "-")[:10]
1105
+ loc_str = f"{sf.get('manifest_source', '')}:{sf.get('line_number') or '?'}"[:20]
1106
+ lines.append(f"{pkg:<16} | {status:<11} | {ver_spec:<18} | {vid:<16} | {sev:<8} | {fixed:<10} | {loc_str:<20}")
1107
+
1108
+ if sec_list:
1109
+ lines.append("\n[SECRET SCANNING FINDINGS (CWE-798)]")
1110
+ lines.append(f"{'TYPE':<18} | {'MASKED VALUE':<24} | {'LOCATION':<22} | {'CONFIDENCE':<10} | {'DETECTOR':<16}")
1111
+ lines.append(dash_sep)
1112
+ for sf in sec_list:
1113
+ stype = str(sf.get("secret_type", ""))[:18]
1114
+ mv = str(sf.get("masked_value", ""))[:24]
1115
+ loc = f"{sf.get('file', '')}:{sf.get('line_number', '')}"[:22]
1116
+ conf = str(format_confidence(sf.get("confidence"), sf.get("confidence_label")))[:10]
1117
+ det = str(sf.get("detector", ""))[:16]
1118
+ lines.append(f"{stype:<18} | {mv:<24} | {loc:<22} | {conf:<10} | {det:<16}")
1119
+
1120
+ lines.append(dash_sep)
1121
+ lines.append("\nFINDING DETAILS:")
1122
+
1123
+ if findings:
1124
+ for f in findings:
1125
+ fid = f.get("id", "")
1126
+ cwe = f.get("cwe", "")
1127
+ cat = f.get("category", "")
1128
+ status = "SUPPRESSED" if f.get("suppressed") else "ACTIVE"
1129
+ lines.append(f"\n[SAST:{fid}] {cwe} ({cat}) - Status: {status}")
1130
+ lines.append(f" Location: {f.get('file', '')}:{f.get('line_number', '')}")
1131
+ lines.append(f" Severity: {f.get('severity', '')} (Confidence: {format_confidence(f.get('confidence'), f.get('confidence_label'))})")
1132
+ if f.get("code_snippet"):
1133
+ lines.append(f" Code Snippet: {f.get('code_snippet')}")
1134
+ if f.get("flow_trace_summary"):
1135
+ lines.append(f" Flow Summary: {f.get('flow_trace_summary')}")
1136
+ if f.get("flow_trace"):
1137
+ lines.append(" Dataflow Trace:")
1138
+ for step in f.get("flow_trace"):
1139
+ lines.append(f" - {step}")
1140
+ if f.get("suppressed") and f.get("suppression_justification"):
1141
+ lines.append(f" Justification:{f.get('suppression_justification')}")
1142
+ if f.get("remediation"):
1143
+ lines.append(f" Remediation: {f.get('remediation')}")
1144
+
1145
+ if sca_list:
1146
+ for sf in sca_list:
1147
+ vid = sf.get("vulnerability_id", "")
1148
+ pkg = sf.get("package_name", "")
1149
+ status = sf.get("status", "")
1150
+ sev = sf.get("severity", "UNKNOWN")
1151
+ cvss = sf.get("cvss_score")
1152
+ cvss_str = str(cvss) if cvss is not None else "N/A"
1153
+ ver_desc = sf.get("installed_version") or sf.get("requested_specifier") or "unspecified"
1154
+ fixed = sf.get("fixed_version") or "None / Unknown"
1155
+ matched_range = sf.get("matched_range", "")
1156
+ loc = f"{sf.get('manifest_source', '')}:{sf.get('line_number') or '?'}"
1157
+ summary = sf.get("summary", "")
1158
+
1159
+ # Look up reachability classification if reachability analysis was performed
1160
+ reach_desc = ""
1161
+ if reachability_enabled and reachability_findings:
1162
+ norm_p = pkg.lower().replace("_", "-")
1163
+ for rf in reachability_findings:
1164
+ if rf.get("package_name", "").lower().replace("_", "-") == norm_p and (rf.get("advisory_id") == vid or not rf.get("advisory_id")):
1165
+ r_cls = rf.get("reachability_classification")
1166
+ if r_cls == "REACHABLE_API_USE":
1167
+ reach_desc = "REACHABLE_API_USE (CRITICAL / High Alert)"
1168
+ elif r_cls == "DEPENDENCY_ACTIVE":
1169
+ reach_desc = "DEPENDENCY_ACTIVE (Imported, no known vulnerable API called)"
1170
+ elif r_cls == "DEPENDENCY_DORMANT":
1171
+ reach_desc = "DEPENDENCY_DORMANT (Declared in manifest, never imported)"
1172
+ elif r_cls:
1173
+ reach_desc = str(r_cls)
1174
+ break
1175
+
1176
+ lines.append(f"\n[SCA:{vid}] {pkg} ({ver_desc}) - Status: {status}")
1177
+ lines.append(f" Package: {pkg}")
1178
+ lines.append(f" Vulnerability: {vid}")
1179
+ lines.append(f" Status: {status}")
1180
+ if reach_desc:
1181
+ lines.append(f" Reachability: {reach_desc}")
1182
+ lines.append(f" Severity: {sev} (CVSS: {cvss_str})")
1183
+ lines.append(f" Installed/Spec: {ver_desc}")
1184
+ lines.append(f" Fixed Version: {fixed}")
1185
+ lines.append(f" Matched Range: {matched_range}")
1186
+ lines.append(f" Location: {loc}")
1187
+ lines.append(f" Summary: {summary}")
1188
+
1189
+ if sec_list:
1190
+ for sf in sec_list:
1191
+ stype = sf.get("secret_type", "")
1192
+ mv = sf.get("masked_value", "")
1193
+ loc = f"{sf.get('file', '')}:{sf.get('line_number', '')}"
1194
+ cols = f"Cols {sf.get('column_start', 1)}-{sf.get('column_end', 1)}"
1195
+ det = sf.get("detector", "")
1196
+ conf = sf.get("confidence", "HIGH")
1197
+ ctx = sf.get("context", "")
1198
+
1199
+ lines.append(f"\n[SECRET:CWE-798] {stype} - Location: {loc} ({cols})")
1200
+ lines.append(f" Type: {stype}")
1201
+ lines.append(f" Masked Value: {mv}")
1202
+ lines.append(f" Location: {loc} ({cols})")
1203
+ lines.append(f" Confidence: {format_confidence(sf.get('confidence'), sf.get('confidence_label'))}")
1204
+ lines.append(f" Detector: {det}")
1205
+ if ctx:
1206
+ lines.append(f" Context: {ctx}")
1207
+ lines.append(" Remediation: Never commit hardcoded secrets or credentials to source control. Revoke and rotate this secret immediately.")
1208
+
1209
+ if results.get("syntax_errors") or results.get("skipped_files"):
1210
+ lines.append("\n[PARSER & RESOURCE WARNINGS (SKIPPED FILES)]")
1211
+ for err in results.get("syntax_errors", []):
1212
+ lines.append(f" Skipping AST analysis for unparseable file: {err}")
1213
+ for skip in results.get("skipped_files", []):
1214
+ lines.append(f" {skip}")
1215
+
1216
+ if reachability_enabled and reachability_findings:
1217
+ lines.append("\n" + format_reachability_section(reachability_findings))
1218
+
1219
+ lines.append(sep)
1220
+ return "\n".join(lines)
1221
+
1222
+
1223
+ def _generate_audit_report(results_or_findings: Any, code_snippet: str = "") -> str:
1224
+ """Generate plaintext audit report with formatted confidence."""
1225
+ if isinstance(results_or_findings, dict) and "findings" in results_or_findings:
1226
+ sec_findings = results_or_findings.get("secret_findings") or [f for f in results_or_findings.get("findings", []) if f.get("is_secret") or f.get("cwe") == "CWE-798"]
1227
+ sast_findings = [f for f in results_or_findings.get("findings", []) if not (f.get("is_secret") or f.get("cwe") == "CWE-798")]
1228
+ return format_table(
1229
+ results_or_findings,
1230
+ sast_findings,
1231
+ secret_findings=sec_findings,
1232
+ secrets_enabled=bool(sec_findings)
1233
+ )
1234
+ if isinstance(results_or_findings, list):
1235
+ sec_findings = [f for f in results_or_findings if f.get("is_secret") or f.get("cwe") == "CWE-798"]
1236
+ sast_findings = [f for f in results_or_findings if not (f.get("is_secret") or f.get("cwe") == "CWE-798")]
1237
+ results = {
1238
+ "summary": {
1239
+ "total_files": 1,
1240
+ "lines_scanned": len(code_snippet.splitlines()) if code_snippet else 1,
1241
+ "security_score": 0 if results_or_findings else 100,
1242
+ "risk_level": "CRITICAL" if any(f.get("severity") == "CRITICAL" for f in results_or_findings) else ("HIGH" if results_or_findings else "CLEAN"),
1243
+ },
1244
+ "findings": sast_findings,
1245
+ "secret_findings": sec_findings,
1246
+ }
1247
+ return format_table(
1248
+ results,
1249
+ sast_findings,
1250
+ secret_findings=sec_findings,
1251
+ secrets_enabled=bool(sec_findings)
1252
+ )
1253
+ return str(results_or_findings)
1254
+
1255
+
1256
+ generate_audit_report = _generate_audit_report
1257
+
1258
+
1259
+ from remediation import (
1260
+ PatchStatus,
1261
+ RemediationRecord,
1262
+ ProjectRemediationResult,
1263
+ format_remediation_section,
1264
+ remediate_project,
1265
+ RemediationEngine,
1266
+ RuleDispatcher,
1267
+ RemediationVerifier,
1268
+ )
1269
+
1270
+
1271
+ def discover_remediation_findings(
1272
+ files: Dict[str, str],
1273
+ config: Optional[TCSConfig],
1274
+ conservative_findings: List[Dict[str, Any]],
1275
+ start_vuln_idx: int = 1
1276
+ ) -> List[Dict[str, Any]]:
1277
+ """
1278
+ Dedicated Remediation-Oriented Discovery Pass (v1.0.1).
1279
+
1280
+ Discovers findings eligible for automated remediation when conservative scan
1281
+ classified the flow as uncalled function parameter / POTENTIAL taint.
1282
+
1283
+ Hard Invariants:
1284
+ 1. Reuses existing execute_tcs_scan(files, config=config, audit_all=True) as candidate discovery feeder.
1285
+ 2. UNKNOWN findings are NEVER auto-remediated (strictly prohibited).
1286
+ 3. POTENTIAL findings are eligible ONLY for explicitly approved CWE patterns (CWE-89, CWE-78, CWE-22).
1287
+ 4. Strict Semantic Correlation: Reuses RemediationVerifier.is_matching_finding to avoid duplicate admission.
1288
+ 5. Full 7-Stage Verification Gate: Transformer success, syntax validation, semantic re-scan,
1289
+ target disappearance, and negative space check must ALL pass before candidate is admitted.
1290
+ 6. Candidate Provenance: Admitted findings preserve their original confidence (CONFIRMED/POTENTIAL)
1291
+ and record discovery_mode = "REMEDIATION_DISCOVERY".
1292
+ """
1293
+ if not files:
1294
+ return []
1295
+
1296
+ discovery_scan_results = execute_tcs_scan(files, config=config, audit_all=True)
1297
+ candidate_findings = discovery_scan_results.get("findings", [])
1298
+ if not candidate_findings:
1299
+ return []
1300
+
1301
+ verifier = RemediationVerifier()
1302
+ engine = RemediationEngine(verifier=verifier)
1303
+ admitted: List[Dict[str, Any]] = []
1304
+ vuln_idx = start_vuln_idx
1305
+
1306
+ for cf in candidate_findings:
1307
+ # Strict semantic duplicate check against existing conservative findings & already admitted candidates
1308
+ is_dup = any(verifier.is_matching_finding(cf, ef) for ef in conservative_findings)
1309
+ if not is_dup:
1310
+ is_dup = any(verifier.is_matching_finding(cf, af) for af in admitted)
1311
+ if is_dup:
1312
+ continue
1313
+
1314
+ # Strict UNKNOWN Policy: UNKNOWN is NEVER auto-remediated under any circumstances
1315
+ conf_label = str(cf.get("confidence_label", "")).strip().upper()
1316
+ status_label = str(cf.get("status", "")).strip().upper()
1317
+ if conf_label == "UNKNOWN" or status_label == "UNKNOWN" or float(cf.get("confidence", 0.0)) <= 0.0:
1318
+ continue
1319
+
1320
+ # Confidence gating: only CONFIRMED and approved POTENTIAL
1321
+ if conf_label not in ("CONFIRMED", "POTENTIAL"):
1322
+ continue
1323
+
1324
+ # Explicit CWE-specific policy: only CWE-89, CWE-78, CWE-22 are supported for automated remediation
1325
+ cwe = str(cf.get("cwe", "")).strip().upper()
1326
+ if cwe not in ("CWE-89", "CWE-78", "CWE-22"):
1327
+ continue
1328
+
1329
+ # Dispatcher check
1330
+ transformer = engine.dispatcher.get_transformer(cwe=cwe)
1331
+ if not transformer:
1332
+ continue
1333
+
1334
+ # Complete 7-stage verification gate via engine.remediate
1335
+ rel_file = cf.get("file")
1336
+ source_code = files.get(rel_file)
1337
+ if source_code is None:
1338
+ continue
1339
+
1340
+ try:
1341
+ rec = engine.remediate(cf, source_code, file_path=rel_file)
1342
+ except Exception:
1343
+ continue
1344
+
1345
+ if rec.patch_status == PatchStatus.SUCCESS and rec.verification_passed and rec.patched_source:
1346
+ admitted_finding = dict(cf)
1347
+ admitted_finding["id"] = f"TimeCodeSecurity-VULN-{vuln_idx:03d}"
1348
+ admitted_finding["discovery_mode"] = "REMEDIATION_DISCOVERY"
1349
+ admitted_finding["confidence"] = cf.get("confidence", 0.50)
1350
+ admitted_finding["confidence_label"] = conf_label
1351
+ admitted.append(admitted_finding)
1352
+ vuln_idx += 1
1353
+
1354
+ return admitted
1355
+
1356
+
1357
+ def main(argv: Optional[List[str]] = None):
1358
+ parser = argparse.ArgumentParser(
1359
+ description="TimeCodeSecurity SAST & SCA Scanner CLI",
1360
+ prog="tcs"
1361
+ )
1362
+ parser.add_argument(
1363
+ "--version",
1364
+ action="version",
1365
+ version=__version__,
1366
+ help="Show program's version number and exit"
1367
+ )
1368
+ parser.add_argument(
1369
+ "targets",
1370
+ nargs="*",
1371
+ default=[],
1372
+ help="Target Python file, manifest, or directory to scan"
1373
+ )
1374
+ parser.add_argument(
1375
+ "--config",
1376
+ help="Path to .tcs.yml configuration file"
1377
+ )
1378
+ parser.add_argument(
1379
+ "--format",
1380
+ choices=["table", "json", "sarif"],
1381
+ default=None,
1382
+ help="Output format: table, json, or sarif (default: table or configured in .tcs.yml)"
1383
+ )
1384
+ parser.add_argument(
1385
+ "--exclude-suppressed",
1386
+ action="store_true",
1387
+ help="Exclude suppressed findings from display, export, and exit code calculation"
1388
+ )
1389
+ parser.add_argument(
1390
+ "-o", "--output",
1391
+ help="Write formatted scan output to specified file path instead of stdout"
1392
+ )
1393
+ parser.add_argument(
1394
+ "--sca",
1395
+ dest="sca",
1396
+ action="store_true",
1397
+ default=None,
1398
+ help="Enable Software Composition Analysis (SCA) for dependency manifests"
1399
+ )
1400
+ parser.add_argument(
1401
+ "--no-sca",
1402
+ dest="sca",
1403
+ action="store_false",
1404
+ help="Disable Software Composition Analysis (SCA)"
1405
+ )
1406
+ parser.add_argument(
1407
+ "--sca-offline",
1408
+ action="store_true",
1409
+ help="Enforce offline SCA analysis using local OSV cache only (requires --sca)"
1410
+ )
1411
+ parser.add_argument(
1412
+ "--sca-cache",
1413
+ help="Path to local OSV cache JSON file"
1414
+ )
1415
+ parser.add_argument(
1416
+ "--sca-reachability",
1417
+ action="store_true",
1418
+ help="Enable Vector C AST-grounded dependency reachability analysis"
1419
+ )
1420
+ parser.add_argument(
1421
+ "--secrets",
1422
+ dest="secrets",
1423
+ action="store_true",
1424
+ default=None,
1425
+ help="Enable Secret and Credential Scanning (CWE-798)"
1426
+ )
1427
+ parser.add_argument(
1428
+ "--no-secrets",
1429
+ dest="secrets",
1430
+ action="store_false",
1431
+ help="Disable Secret and Credential Scanning (CWE-798)"
1432
+ )
1433
+ parser.add_argument(
1434
+ "--github-actions",
1435
+ action="store_true",
1436
+ help="Enable GitHub Actions workflow annotations and step summary generation"
1437
+ )
1438
+ parser.add_argument(
1439
+ "--step-summary-file",
1440
+ help="Path to Step Summary Markdown output file (defaults to $GITHUB_STEP_SUMMARY)"
1441
+ )
1442
+ parser.add_argument(
1443
+ "--include-js",
1444
+ dest="include_js",
1445
+ action="store_true",
1446
+ default=False,
1447
+ help="Also run the tree-sitter JS/TS scanner (CWE-79/CWE-95 in .js/.jsx/.ts/.tsx). "
1448
+ "Off by default so this entry point stays identical to cli.py scan"
1449
+ )
1450
+ parser.add_argument(
1451
+ "--strict",
1452
+ action="store_true",
1453
+ help="Treat syntax errors as fatal (exit code 2)"
1454
+ )
1455
+ parser.add_argument(
1456
+ "--staged",
1457
+ action="store_true",
1458
+ help="Scan only git-staged changes with full cross-file semantic dependency closure"
1459
+ )
1460
+ parser.add_argument(
1461
+ "--audit-all",
1462
+ action="store_true",
1463
+ help="Emit speculative POTENTIAL findings for unresolved function parameters without known taint bindings"
1464
+ )
1465
+ parser.add_argument(
1466
+ "--fix", "--remediate",
1467
+ dest="fix",
1468
+ action="store_true",
1469
+ default=False,
1470
+ help="Generate automated AST remediation patches for eligible vulnerabilities"
1471
+ )
1472
+ parser.add_argument(
1473
+ "--dry-run",
1474
+ action="store_true",
1475
+ default=False,
1476
+ help="Preview remediation patches without modifying files (default behavior for --fix)"
1477
+ )
1478
+ parser.add_argument(
1479
+ "--write",
1480
+ action="store_true",
1481
+ default=False,
1482
+ help="Authorize writing verified remediation patches to disk"
1483
+ )
1484
+
1485
+ args = parser.parse_args(argv)
1486
+
1487
+ fix_active = getattr(args, "fix", False) or getattr(args, "remediate", False)
1488
+ args.fix = fix_active
1489
+ args.remediate = fix_active
1490
+
1491
+ if args.output:
1492
+ OUTPUT_TARGET["path"] = str(args.output)
1493
+ OUTPUT_TARGET["format"] = getattr(args, "format", "").lower()
1494
+
1495
+ if args.dry_run and args.write:
1496
+ print("[ERROR] Cannot specify both --dry-run and --write.", file=sys.stderr)
1497
+ sys.exit(2)
1498
+
1499
+ if getattr(args, "staged", False) and fix_active:
1500
+ print("Error: --fix/--remediate is currently not supported with --staged mode. Run on working tree targets directly.", file=sys.stderr)
1501
+ sys.exit(2)
1502
+
1503
+ raw_targets = [t for t in args.targets if t != "scan"]
1504
+ if len(raw_targets) == 0:
1505
+ args.target = "scan" if "scan" in args.targets else None
1506
+ else:
1507
+ args.target = raw_targets[0]
1508
+
1509
+ # Load configuration
1510
+ try:
1511
+ config = load_config(args.config, base_dir=Path.cwd())
1512
+ except ConfigValidationError as cve:
1513
+ print(f"[ERROR] Configuration error: {cve}", file=sys.stderr)
1514
+ sys.exit(2)
1515
+
1516
+ # Resolve CLI precedence: CLI explicit > .tcs.yml > built-in defaults
1517
+ if args.sca is not None:
1518
+ active_sca = args.sca
1519
+ elif config is not None:
1520
+ active_sca = config.scan.sca
1521
+ else:
1522
+ active_sca = False
1523
+
1524
+ if args.secrets is not None:
1525
+ active_secrets = args.secrets
1526
+ elif getattr(args, "audit_all", False):
1527
+ active_secrets = True
1528
+ elif config is not None:
1529
+ active_secrets = config.scan.secrets
1530
+ else:
1531
+ active_secrets = False
1532
+
1533
+ if args.format is not None:
1534
+ active_format = args.format
1535
+ elif config is not None:
1536
+ active_format = config.output.format
1537
+ else:
1538
+ active_format = "table"
1539
+
1540
+ args.sca = active_sca
1541
+ args.secrets = active_secrets
1542
+ args.format = active_format
1543
+
1544
+ if args.sca_offline and not args.sca:
1545
+ print("[ERROR] --sca-offline requires --sca to be enabled.", file=sys.stderr)
1546
+ sys.exit(2)
1547
+
1548
+ base_dir = Path.cwd().resolve()
1549
+ all_skipped_files: List[str] = []
1550
+ staged_unresolved_deps: List[str] = []
1551
+
1552
+ if args.staged:
1553
+ if args.target is None or args.target == "scan":
1554
+ target = base_dir
1555
+ else:
1556
+ target = Path(os.path.expanduser(str(args.target))).resolve()
1557
+ if not target.exists():
1558
+ print(f"[ERROR] Target path does not exist: {args.target}", file=sys.stderr)
1559
+ sys.exit(2)
1560
+
1561
+ repo_root = get_git_repo_root(target if target.is_dir() else target.parent)
1562
+ if repo_root is None:
1563
+ print(f"[WARN] --staged requested but '{target}' is not in a git repository.", file=sys.stderr)
1564
+ files = {}
1565
+ results = {
1566
+ "status": "success",
1567
+ "syntax_errors": [],
1568
+ "enabled_rules": advertised_rule_ids(config),
1569
+ "summary": {
1570
+ "total_files": 0,
1571
+ "lines_scanned": 0,
1572
+ "total_vulnerabilities": 0,
1573
+ "active_vulnerabilities": 0,
1574
+ "suppressed_vulnerabilities": 0,
1575
+ "critical_count": 0,
1576
+ "high_count": 0,
1577
+ "medium_count": 0,
1578
+ "low_count": 0,
1579
+ "security_score": 100,
1580
+ "score_label": "Security Health Score",
1581
+ "risk_level": "CLEAN",
1582
+ "risk_message": f"NO VULNERABILITIES DETECTED within current TimeCodeSecurity analysis scope ({get_active_cwe_count()} supported CWE classes)."
1583
+ },
1584
+ "findings": [],
1585
+ "skipped_files": []
1586
+ }
1587
+ else:
1588
+ staged_py, staged_d, staged_r, non_py = get_staged_git_files(repo_root)
1589
+ if not staged_py:
1590
+ print("[INFO] No staged Python files to scan.", file=sys.stderr)
1591
+ files = {}
1592
+ results = {
1593
+ "status": "success",
1594
+ "syntax_errors": [],
1595
+ "enabled_rules": advertised_rule_ids(config),
1596
+ "summary": {
1597
+ "total_files": 0,
1598
+ "lines_scanned": 0,
1599
+ "total_vulnerabilities": 0,
1600
+ "active_vulnerabilities": 0,
1601
+ "suppressed_vulnerabilities": 0,
1602
+ "critical_count": 0,
1603
+ "high_count": 0,
1604
+ "medium_count": 0,
1605
+ "low_count": 0,
1606
+ "security_score": 100,
1607
+ "score_label": "Security Health Score",
1608
+ "risk_level": "CLEAN",
1609
+ "risk_message": f"NO VULNERABILITIES DETECTED within current TimeCodeSecurity analysis scope ({get_active_cwe_count()} supported CWE classes)."
1610
+ },
1611
+ "findings": [],
1612
+ "skipped_files": []
1613
+ }
1614
+ else:
1615
+ files, staged_set, unres = build_staged_dependency_closure(
1616
+ repo_root, staged_py, staged_deleted=staged_d
1617
+ )
1618
+ staged_unresolved_deps = unres
1619
+ for u in unres:
1620
+ print(f"[ERROR] Unresolved dependency: {u}", file=sys.stderr)
1621
+ if unres:
1622
+ print("[ERROR] Staged changes contain unresolved/deleted dependencies; analysis cannot prove CLEAN.", file=sys.stderr)
1623
+ try:
1624
+ results = execute_tcs_scan(files, config=config, audit_all=getattr(args, "audit_all", False))
1625
+ except Exception as e:
1626
+ print(f"[ERROR] Scan execution failed: {e}", file=sys.stderr)
1627
+ sys.exit(2)
1628
+ raw_findings = results.get("findings", [])
1629
+ affected_findings = filter_findings_for_staged(raw_findings, staged_set)
1630
+ results["findings"] = affected_findings
1631
+ results["summary"] = recompute_summary_metrics(
1632
+ results["summary"],
1633
+ affected_findings,
1634
+ total_files=len(files),
1635
+ lines_scanned=sum(len(c.splitlines()) for c in files.values())
1636
+ )
1637
+ if unres:
1638
+ results["status"] = "partial_analysis"
1639
+ results["unresolved_dependencies"] = unres
1640
+ if results["summary"]["active_vulnerabilities"] == 0:
1641
+ results["summary"]["risk_level"] = "PARTIAL_ANALYSIS"
1642
+ results["summary"]["risk_message"] = (
1643
+ f"PARTIAL ANALYSIS: {len(unres)} unresolved dependency(ies) detected in staged changes; "
1644
+ f"safety cannot be verified."
1645
+ )
1646
+ results["summary"]["security_score"] = 0
1647
+ else:
1648
+ if not args.target:
1649
+ print("[ERROR] Target path is required when --staged is not specified.", file=sys.stderr)
1650
+ parser.print_help(sys.stderr)
1651
+ sys.exit(2)
1652
+
1653
+ target = Path(os.path.expanduser(str(args.target))).resolve()
1654
+ if not target.exists():
1655
+ print(f"[ERROR] Target path does not exist: {args.target}", file=sys.stderr)
1656
+ sys.exit(2)
1657
+
1658
+ files = discover_python_files(target, base_dir, sca_active=args.sca, secrets_active=args.secrets, skipped_files=all_skipped_files)
1659
+ if not files and not args.sca and not args.secrets:
1660
+ print(f"[WARN] No Python (*.py) files found in: {args.target}", file=sys.stderr)
1661
+
1662
+ try:
1663
+ results = execute_tcs_scan(files, config=config, audit_all=getattr(args, "audit_all", False))
1664
+ except Exception as e:
1665
+ print(f"[ERROR] Scan execution failed: {e}", file=sys.stderr)
1666
+ sys.exit(2)
1667
+
1668
+ # ---------------------------------------------------------
1669
+ # JS/TS Tree-sitter Security Scanner (Vector E)
1670
+ # ---------------------------------------------------------
1671
+ # js_scanner no longer warns at import time (a Python-only scan must stay quiet), so the
1672
+ # explicit --include-js request is what makes the missing grammar worth reporting here.
1673
+ if getattr(args, "include_js", False) and not js_ts_available():
1674
+ warn_js_ts_unavailable()
1675
+ if _JS_TS_SCANNER_AVAILABLE and js_ts_available() and getattr(args, "include_js", False):
1676
+ try:
1677
+ _js_scanner_inst = JsTsScanner()
1678
+ _js_findings = run_js_ts_scan_isolated(
1679
+ target, base_dir=base_dir, skipped_files=all_skipped_files
1680
+ )
1681
+ if _js_findings:
1682
+ # Re-number IDs to continue from where Python scan left off
1683
+ _py_count = len(results.get("findings", []))
1684
+ for _i, _jf in enumerate(_js_findings):
1685
+ _jf["id"] = f"TimeCodeSecurity-JS-{_py_count + _i + 1:03d}"
1686
+ results["findings"] = results.get("findings", []) + _js_findings
1687
+ # Recompute summary metrics to include JS findings
1688
+ _js_lines = sum(
1689
+ len(p.read_bytes().split(b"\n"))
1690
+ for p in _js_scanner_inst._discover_js_files(target, None)
1691
+ if p.exists()
1692
+ )
1693
+ results["summary"] = recompute_summary_metrics(
1694
+ original_summary=results.get("summary", {}),
1695
+ filtered_findings=results["findings"],
1696
+ total_files=results["summary"].get("total_files", 0) + len(
1697
+ [f for f in _js_findings if f.get("file")]
1698
+ ),
1699
+ lines_scanned=results["summary"].get("lines_scanned", 0) + _js_lines,
1700
+ )
1701
+ print(
1702
+ f"[TimeCodeSecurity-JS] Tree-sitter JS/TS scan: {len(_js_findings)} finding(s) in {target}",
1703
+ file=sys.stderr,
1704
+ )
1705
+ except Exception as _js_err:
1706
+ print(f"[TimeCodeSecurity-JS] WARNING: JS/TS scan failed: {_js_err}", file=sys.stderr)
1707
+
1708
+ results["skipped_files"] = all_skipped_files
1709
+
1710
+ if results.get("syntax_errors"):
1711
+ for err in results["syntax_errors"]:
1712
+ print(f"[WARN] Skipping AST analysis for unparseable file: {err}", file=sys.stderr)
1713
+ if getattr(args, "strict", False):
1714
+ print("[ERROR] Strict mode enabled and syntax errors encountered. Aborting.", file=sys.stderr)
1715
+ sys.exit(2)
1716
+
1717
+ # ---------------------------------------------------------
1718
+ # Software Composition Analysis (SCA) - (if requested)
1719
+ # ---------------------------------------------------------
1720
+ sca_findings: List[SCAFinding] = []
1721
+ manifest_files: List[Path] = []
1722
+ all_deps: List[DependencyRecord] = []
1723
+ if args.sca:
1724
+ manifest_files = discover_manifest_files(target, base_dir, skipped_files=all_skipped_files)
1725
+ for mf in manifest_files:
1726
+ if target.is_dir():
1727
+ try:
1728
+ rel_mf = mf.relative_to(target).as_posix()
1729
+ except ValueError:
1730
+ try:
1731
+ rel_mf = mf.relative_to(base_dir).as_posix()
1732
+ except ValueError:
1733
+ rel_mf = mf.name
1734
+ else:
1735
+ rel_mf = mf.name
1736
+
1737
+ parse_res = parse_manifest(str(mf))
1738
+ for dep in parse_res.dependencies:
1739
+ if dep.source != rel_mf:
1740
+ dep = dataclasses.replace(dep, source=rel_mf)
1741
+ all_deps.append(dep)
1742
+
1743
+ if all_deps:
1744
+ package_names = [dep.name for dep in all_deps]
1745
+ raw_cache = args.sca_cache or os.environ.get("TCS_OSV_CACHE")
1746
+ if raw_cache:
1747
+ cache_file = str(Path(os.path.expanduser(str(raw_cache))).resolve())
1748
+ else:
1749
+ cache_dir = (Path.home() / ".tcs").resolve()
1750
+ cache_dir.mkdir(parents=True, exist_ok=True)
1751
+ cache_file = str(cache_dir / "osv_cache.json")
1752
+ osv_client = OSVClient(cache_file=cache_file, offline_mode=args.sca_offline)
1753
+ osv_results = osv_client.query_packages(package_names)
1754
+ sca_findings = match_dependencies(all_deps, osv_results)
1755
+
1756
+ # ---------------------------------------------------------
1757
+ # Secret Scanning Analysis (if requested)
1758
+ # ---------------------------------------------------------
1759
+ secret_findings: List[SecretFinding] = []
1760
+ secret_files: List[Path] = []
1761
+
1762
+ if args.secrets:
1763
+ secret_files = discover_secret_files(target, base_dir, skipped_files=all_skipped_files)
1764
+ filter_cfg = FilterConfig()
1765
+ for sf in secret_files:
1766
+ if target.is_dir():
1767
+ try:
1768
+ rel_sf = sf.relative_to(target).as_posix()
1769
+ except ValueError:
1770
+ try:
1771
+ rel_sf = sf.relative_to(base_dir).as_posix()
1772
+ except ValueError:
1773
+ rel_sf = sf.name
1774
+ else:
1775
+ rel_sf = sf.name
1776
+
1777
+ try:
1778
+ content = sf.read_text(encoding="utf-8", errors="replace")
1779
+ except Exception as e:
1780
+ print(f"[WARN] Unable to read secret target '{sf}': {e}", file=sys.stderr)
1781
+ continue
1782
+
1783
+ raw_findings = scan_text(content, filename=rel_sf)
1784
+ passed_findings = filter_findings(raw_findings, file_path=rel_sf, config=filter_cfg)
1785
+ secret_findings.extend(passed_findings)
1786
+
1787
+ # ---------------------------------------------------------
1788
+ # Dedicated Remediation Discovery Pass (--fix without --audit-all)
1789
+ # ---------------------------------------------------------
1790
+ if args.fix and not getattr(args, "audit_all", False):
1791
+ admitted = discover_remediation_findings(
1792
+ files=files,
1793
+ config=config,
1794
+ conservative_findings=results.get("findings", []),
1795
+ start_vuln_idx=len(results.get("findings", [])) + 1
1796
+ )
1797
+ if admitted:
1798
+ all_combined = list(results.get("findings", [])) + admitted
1799
+ results["findings"] = all_combined
1800
+ results["summary"] = recompute_summary_metrics(
1801
+ original_summary=results.get("summary", {}),
1802
+ filtered_findings=all_combined,
1803
+ total_files=len(files),
1804
+ lines_scanned=sum(len(c.splitlines()) for c in files.values())
1805
+ )
1806
+
1807
+ all_findings = results.get("findings", [])
1808
+ if args.exclude_suppressed:
1809
+ effective_findings = [f for f in all_findings if not f.get("suppressed", False)]
1810
+ else:
1811
+ effective_findings = all_findings
1812
+
1813
+ export_data = dict(results)
1814
+ export_data["findings"] = effective_findings
1815
+ if args.exclude_suppressed:
1816
+ summary_copy = dict(results.get("summary", {}))
1817
+ summary_copy["total_vulnerabilities"] = len(effective_findings)
1818
+ summary_copy["suppressed_vulnerabilities"] = 0
1819
+ summary_copy["active_vulnerabilities"] = len(effective_findings)
1820
+ export_data["summary"] = summary_copy
1821
+
1822
+ if args.sca:
1823
+ serialized_sca = [f.to_dict() if hasattr(f, "to_dict") else dict(f) for f in sca_findings]
1824
+ export_data["sca_findings"] = serialized_sca
1825
+ summary_copy = dict(export_data.get("summary", {}))
1826
+ summary_copy["manifests_scanned"] = len(manifest_files)
1827
+ summary_copy["sca_vulnerabilities"] = len(sca_findings)
1828
+ summary_copy["sca_confirmed"] = sum(1 for f in sca_findings if (getattr(f, "status", None) or f.get("status")) == "CONFIRMED")
1829
+ summary_copy["sca_potential"] = sum(1 for f in sca_findings if (getattr(f, "status", None) or f.get("status")) == "POTENTIAL")
1830
+ summary_copy["sca_unresolved"] = sum(1 for f in sca_findings if (getattr(f, "status", None) or f.get("status")) == "UNRESOLVED")
1831
+ export_data["summary"] = summary_copy
1832
+
1833
+ if args.secrets:
1834
+ serialized_secrets = [
1835
+ {
1836
+ "secret_type": sf.secret_type,
1837
+ "masked_value": sf.masked_value,
1838
+ "file": sf.file,
1839
+ "line_number": sf.line_number,
1840
+ "column_start": sf.column_start,
1841
+ "column_end": sf.column_end,
1842
+ "confidence": "HIGH" if "HIGH" in str(sf.confidence) else str(sf.confidence),
1843
+ "detector": sf.detector,
1844
+ "context": sf.context,
1845
+ "cwe": "CWE-798"
1846
+ }
1847
+ for sf in secret_findings
1848
+ ]
1849
+ export_data["secret_findings"] = serialized_secrets
1850
+ summary_copy = dict(export_data.get("summary", {}))
1851
+ summary_copy["secrets_scanned"] = len(secret_files)
1852
+ summary_copy["secrets_scanned_files"] = len(secret_files)
1853
+ summary_copy["secrets_detected"] = len(secret_findings)
1854
+ export_data["summary"] = summary_copy
1855
+
1856
+ export_data["skipped_files"] = all_skipped_files
1857
+ if all_skipped_files:
1858
+ summary_copy = dict(export_data.get("summary", {}))
1859
+ summary_copy["skipped_files_count"] = len(all_skipped_files)
1860
+ export_data["summary"] = summary_copy
1861
+
1862
+ if staged_unresolved_deps:
1863
+ export_data["status"] = "partial_analysis"
1864
+ export_data["unresolved_dependencies"] = staged_unresolved_deps
1865
+
1866
+ # ---------------------------------------------------------
1867
+ # Vector C Reachability Analysis (if requested)
1868
+ # ---------------------------------------------------------
1869
+ reachability_findings: List[Dict[str, Any]] = []
1870
+ if getattr(args, "sca_reachability", False):
1871
+ cand_manifests = []
1872
+ cand_sources = []
1873
+ if target.is_dir():
1874
+ for mf_name in ("poetry.lock", "requirements.txt"):
1875
+ mf_candidate = target / mf_name
1876
+ if mf_candidate.exists():
1877
+ cand_manifests.append(mf_candidate)
1878
+ for root, dirs, files_in_dir in os.walk(target, followlinks=False):
1879
+ dirs[:] = [d for d in dirs if d not in IGNORED_DIRS and not d.startswith(".")]
1880
+ for f in files_in_dir:
1881
+ if f.endswith(".py") and f != "tcs_cli.py":
1882
+ cand_sources.append(Path(root) / f)
1883
+ else:
1884
+ if target.name in ("poetry.lock", "requirements.txt"):
1885
+ cand_manifests.append(target)
1886
+ for root, dirs, files_in_dir in os.walk(target.parent, followlinks=False):
1887
+ dirs[:] = [d for d in dirs if d not in IGNORED_DIRS and not d.startswith(".")]
1888
+ for f in files_in_dir:
1889
+ if f.endswith(".py") and f != "tcs_cli.py":
1890
+ cand_sources.append(Path(root) / f)
1891
+ elif target.suffix == ".py":
1892
+ cand_sources.append(target)
1893
+ for mf_name in ("poetry.lock", "requirements.txt"):
1894
+ mf_candidate = target.parent / mf_name
1895
+ if mf_candidate.exists():
1896
+ cand_manifests.append(mf_candidate)
1897
+
1898
+ if not cand_manifests and manifest_files:
1899
+ cand_manifests = list(manifest_files)
1900
+ if not cand_sources and files:
1901
+ cand_sources = [Path(f) for f in files.keys() if f != "tcs_cli.py"]
1902
+
1903
+ if cand_manifests and cand_sources:
1904
+ selected_mf = cand_manifests[0]
1905
+ try:
1906
+ live_adv = sca_findings if sca_findings else None
1907
+ rf_objs = analyze_dependency_reachability(selected_mf, cand_sources, live_advisories=live_adv)
1908
+ reachability_findings = [f.to_dict() if hasattr(f, "to_dict") else dict(f) for f in rf_objs]
1909
+ except Exception as e:
1910
+ print(f"[WARN] Vector C reachability analysis failed: {e}", file=sys.stderr)
1911
+
1912
+ export_data["sca_reachability_findings"] = reachability_findings
1913
+
1914
+ # ---------------------------------------------------------
1915
+ # Vector D Remediation Engine (delegated to remediation.orchestrator)
1916
+ # ---------------------------------------------------------
1917
+ remediation_res: Optional[ProjectRemediationResult] = None
1918
+ remediation_records: List[RemediationRecord] = []
1919
+ written_files: List[str] = []
1920
+ stale_files: List[str] = []
1921
+ unwritten_eligible_files: List[str] = []
1922
+ remediation_candidates = [f for f in effective_findings if not f.get("suppressed", False)]
1923
+ findings_by_file: Dict[str, List[Dict[str, Any]]] = {}
1924
+
1925
+ if args.fix:
1926
+ remediation_res = remediate_project(
1927
+ files=files,
1928
+ effective_findings=effective_findings,
1929
+ target=target,
1930
+ base_dir=base_dir,
1931
+ is_write=args.write,
1932
+ pre_write_hook=_PRE_WRITE_HOOK
1933
+ )
1934
+ export_data["remediations"] = [rec.to_dict() for rec in remediation_res.remediation_records]
1935
+ export_data["remediation_summary"] = remediation_res.summary
1936
+ remediation_records = remediation_res.remediation_records
1937
+ written_files = remediation_res.written_files
1938
+ stale_files = remediation_res.stale_files
1939
+ unwritten_eligible_files = remediation_res.unwritten_eligible_files
1940
+ remediation_candidates = getattr(remediation_res, "remediation_candidates", remediation_candidates)
1941
+ findings_by_file = getattr(remediation_res, "findings_by_file", findings_by_file)
1942
+
1943
+ if args.format.lower() == "sarif":
1944
+ try:
1945
+ sarif_doc = to_sarif(export_data, enabled_rule_ids=configured_rule_ids(config))
1946
+ except Exception as exc:
1947
+ print(f"[ERROR] SARIF conversion failed: {exc}", file=sys.stderr)
1948
+ sarif_doc = _minimal_sarif_document()
1949
+ output_text = json.dumps(sarif_doc, indent=2)
1950
+ elif args.format.lower() == "json":
1951
+ output_text = json.dumps(export_data, indent=2)
1952
+ else:
1953
+ output_text = format_table(
1954
+ results,
1955
+ effective_findings,
1956
+ sca_findings=sca_findings,
1957
+ sca_enabled=args.sca,
1958
+ secret_findings=secret_findings,
1959
+ secrets_enabled=args.secrets,
1960
+ reachability_findings=reachability_findings,
1961
+ reachability_enabled=args.sca_reachability
1962
+ )
1963
+ if args.fix:
1964
+ output_text += "\n\n" + format_remediation_section(
1965
+ remediation_records,
1966
+ written_files=written_files,
1967
+ is_write=args.write
1968
+ )
1969
+
1970
+ if args.output:
1971
+ out_path = Path(os.path.expanduser(str(args.output))).resolve()
1972
+ atomic_write_text(out_path, output_text)
1973
+ print(f"[TimeCodeSecurity CLI] Results written to: {args.output} (Format: {args.format})", file=sys.stderr)
1974
+ else:
1975
+ print(output_text)
1976
+
1977
+ # ---------------------------------------------------------
1978
+ # GitHub Actions Workflow Commands & Step Summary
1979
+ # ---------------------------------------------------------
1980
+ if args.github_actions:
1981
+ annotations = format_github_annotations(export_data)
1982
+ for ann in annotations:
1983
+ print(ann, file=sys.stderr)
1984
+
1985
+ summary_file = args.step_summary_file or os.environ.get("GITHUB_STEP_SUMMARY")
1986
+ if summary_file:
1987
+ try:
1988
+ summary_md = generate_step_summary(export_data)
1989
+ sum_path = Path(os.path.expanduser(str(summary_file))).resolve()
1990
+ sum_path.parent.mkdir(parents=True, exist_ok=True)
1991
+ with open(sum_path, "a", encoding="utf-8") as f:
1992
+ f.write(summary_md)
1993
+ except Exception as e:
1994
+ print(f"[ERROR] Failed to write Step Summary to '{summary_file}': {e}", file=sys.stderr)
1995
+ sys.exit(2)
1996
+
1997
+ # Human status summary to stderr
1998
+ summary = results.get("summary", {})
1999
+ total = summary.get("total_vulnerabilities", 0)
2000
+ active = summary.get("active_vulnerabilities", 0)
2001
+ suppressed = summary.get("suppressed_vulnerabilities", 0)
2002
+ score = summary.get("security_score", 100)
2003
+ risk = summary.get("risk_level", "CLEAN")
2004
+
2005
+ if not args.sca and not args.secrets:
2006
+ print(
2007
+ f"[TimeCodeSecurity CLI] Scanned {len(files)} files | Findings: {total} (Active: {active}, Suppressed: {suppressed}) | Score: {score}/100 ({risk})",
2008
+ file=sys.stderr
2009
+ )
2010
+ elif args.sca and not args.secrets:
2011
+ sca_count = len(sca_findings)
2012
+ sca_confirmed = sum(1 for f in sca_findings if (getattr(f, "status", None) or f.get("status")) == "CONFIRMED")
2013
+ sca_potential = sum(1 for f in sca_findings if (getattr(f, "status", None) or f.get("status")) == "POTENTIAL")
2014
+ sca_unresolved = sum(1 for f in sca_findings if (getattr(f, "status", None) or f.get("status")) == "UNRESOLVED")
2015
+ print(
2016
+ f"[TimeCodeSecurity CLI] Scanned {len(files)} files, {len(manifest_files)} manifests | SAST: {total} (Active: {active}, Suppressed: {suppressed}) | SCA: {sca_count} (Confirmed: {sca_confirmed}, Potential: {sca_potential}, Unresolved: {sca_unresolved}) | Score: {score}/100 ({risk})",
2017
+ file=sys.stderr
2018
+ )
2019
+ else:
2020
+ status_items = [f"{len(files)} files"]
2021
+ if args.sca:
2022
+ status_items.append(f"{len(manifest_files)} manifests")
2023
+ if args.secrets:
2024
+ status_items.append(f"{len(secret_files)} secret files")
2025
+
2026
+ findings_items = [f"Findings: {total} (Active: {active}, Suppressed: {suppressed})"]
2027
+ if args.sca:
2028
+ sca_count = len(sca_findings)
2029
+ sca_confirmed = sum(1 for f in sca_findings if (getattr(f, "status", None) or f.get("status")) == "CONFIRMED")
2030
+ sca_potential = sum(1 for f in sca_findings if (getattr(f, "status", None) or f.get("status")) == "POTENTIAL")
2031
+ sca_unresolved = sum(1 for f in sca_findings if (getattr(f, "status", None) or f.get("status")) == "UNRESOLVED")
2032
+ findings_items.append(f"SCA: {sca_count} (Confirmed: {sca_confirmed}, Potential: {sca_potential}, Unresolved: {sca_unresolved})")
2033
+ if args.secrets:
2034
+ findings_items.append(f"Secrets: {len(secret_findings)} (CWE-798)")
2035
+
2036
+ print(
2037
+ f"[TimeCodeSecurity CLI] Scanned {', '.join(status_items)} | {' | '.join(findings_items)} | Score: {score}/100 ({risk})",
2038
+ file=sys.stderr
2039
+ )
2040
+
2041
+ if args.fix:
2042
+ if args.write:
2043
+ success_rems = sum(1 for r in remediation_records if r.patch_status == PatchStatus.SUCCESS and r.original_file in written_files)
2044
+ print(f"[TimeCodeSecurity REMEDIATION] Wrote {len(written_files)} verified file(s) ({success_rems} patch(es) applied).", file=sys.stderr)
2045
+ else:
2046
+ success_rems = sum(1 for r in remediation_records if r.patch_status == PatchStatus.SUCCESS)
2047
+ print(f"[TimeCodeSecurity REMEDIATION] Dry-run preview: {success_rems} verified patch(es) available. Run with --write to apply.", file=sys.stderr)
2048
+
2049
+ has_sast_failure = len(effective_findings) > 0
2050
+ has_sca_failure = (len(sca_findings) > 0) if args.sca else False
2051
+ has_secret_failure = (len(secret_findings) > 0) if args.secrets else False
2052
+
2053
+ if args.fix:
2054
+ total_eligible = len(remediation_candidates)
2055
+ all_remediated = (
2056
+ total_eligible > 0
2057
+ and len(remediation_records) == total_eligible
2058
+ and all(r.patch_status == PatchStatus.SUCCESS and r.verification_passed for r in remediation_records)
2059
+ and len(stale_files) == 0
2060
+ and len(unwritten_eligible_files) == 0
2061
+ and len(written_files) == len(findings_by_file)
2062
+ )
2063
+ if args.write and all_remediated and not has_sca_failure and not has_secret_failure:
2064
+ sys.exit(0)
2065
+ elif total_eligible == 0 and not has_sast_failure and not has_sca_failure and not has_secret_failure:
2066
+ sys.exit(0)
2067
+ else:
2068
+ sys.exit(1)
2069
+ else:
2070
+ if has_sast_failure or has_sca_failure or has_secret_failure:
2071
+ sys.exit(1)
2072
+ elif staged_unresolved_deps:
2073
+ sys.exit(2)
2074
+ else:
2075
+ sys.exit(0)
2076
+
2077
+
2078
+ if __name__ == "__main__":
2079
+ try:
2080
+ main()
2081
+ except SystemExit as se:
2082
+ sys.exit(se.code)
2083
+ except Exception as exc:
2084
+ print(f"[ERROR] Internal unhandled exception: {exc}", file=sys.stderr)
2085
+ ensure_sarif_artifact(f"unhandled exception: {exc}")
2086
+ sys.exit(2)