@teevee98/synapse-hub 4.3.1 → 4.4.0

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 (54) hide show
  1. package/.agents/agents/api-engineer.md +8 -0
  2. package/.agents/agents/perf-engineer.md +10 -2
  3. package/.agents/rules/performance_testing_rules.md +4 -3
  4. package/.agents/skills/01-web-automation/clean-pom-crafter/SKILL.md +6 -3
  5. package/.agents/skills/01-web-automation/e2e-testing-patterns/SKILL.md +3 -1
  6. package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +11 -5
  7. package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/SKILL.md +4 -1
  8. package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/references/performance_test_plan_29119.md +106 -0
  9. package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/SKILL.md +75 -14
  10. package/.agents/skills/05-security-and-compliance/security-dast-sentinel/SKILL.md +13 -2
  11. package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +4 -1
  12. package/.agents/skills/07-data-and-state/file-and-report-validator/SKILL.md +8 -1
  13. package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +4 -1
  14. package/.agents/skills/11-ai-and-prompting/mipro-prompt-compiler/SKILL.md +8 -0
  15. package/.agents/templates/performance-test-plan-template.md +106 -0
  16. package/README.en.md +2 -2
  17. package/README.md +2 -2
  18. package/agentskills.json +1 -1
  19. package/docs/ARCHITECTURE.en.md +95 -2
  20. package/docs/ARCHITECTURE.md +86 -2
  21. package/docs/TOOL_CATALOG.md +11 -2
  22. package/package.json +1 -1
  23. package/plugin.json +1 -1
  24. package/skills_manifest.json +1 -1
  25. package/synapse.config.json +1 -1
  26. package/tools/.infer_baseline.json +44 -3
  27. package/tools/TOOLS_RUNBOOK.md +237 -0
  28. package/tools/TOOL_CATALOG.json +138 -3
  29. package/tools/__init__.py +1 -1
  30. package/tools/ai_eval_sentinel.py +403 -0
  31. package/tools/asvs_auditor.py +410 -0
  32. package/tools/browser_helpers.js +2 -2
  33. package/tools/chaos_resilience_probe.py +362 -0
  34. package/tools/cldr_l10n_verifier.py +309 -0
  35. package/tools/cli.py +187 -3
  36. package/tools/cvss_calculator.py +412 -0
  37. package/tools/dashboard_generator.py +8 -8
  38. package/tools/etl_data_reconciler.py +460 -0
  39. package/tools/generate_jmx_plan.py +12 -4
  40. package/tools/jtl_analyzer.py +23 -1
  41. package/tools/mcp_docx_server.py +1 -1
  42. package/tools/mcp_excel_server.py +1 -1
  43. package/tools/mcp_server.py +1 -1
  44. package/tools/mobile_resilience_sentinel.py +273 -0
  45. package/tools/observability_tester.py +235 -0
  46. package/tools/payment_interop_simulator.py +337 -0
  47. package/tools/pre_push_guard.py +306 -0
  48. package/tools/regulatory_compliance.py +336 -0
  49. package/tools/rules_router.py +1 -1
  50. package/tools/tmmi_auditor.py +172 -0
  51. package/tools/ui_server.py +1 -1
  52. package/tools/update_sentinel.py +3 -3
  53. package/tools/vpat_exporter.py +428 -0
  54. package/tools/welcome_page.py +1 -1
package/tools/cli.py CHANGED
@@ -133,7 +133,7 @@ def _resolve_manifest_path(repo_root: Optional[str] = None) -> Optional[str]:
133
133
  def cmd_version(args):
134
134
  """Displays the current hub version, skill catalog count, and license information."""
135
135
  manifest_path = _resolve_manifest_path()
136
- version = "4.3.1"
136
+ version = "4.4.0"
137
137
  manifest_skills = 56
138
138
  if manifest_path and os.path.exists(manifest_path):
139
139
  try:
@@ -776,16 +776,79 @@ def cmd_trend(args):
776
776
  sys.exit(trend_main())
777
777
 
778
778
 
779
+ def cmd_cvss(args):
780
+ """CVSS v3.1 & v4.0 Vulnerability Scoring Engine."""
781
+ from cvss_calculator import main as cvss_main
782
+ sys.argv = _forward_subcommand_args(args)
783
+ sys.exit(cvss_main())
784
+
785
+
786
+ def cmd_asvs(args):
787
+ """OWASP ASVS 4.0.3 Verification Engine & Checklist Suite."""
788
+ from asvs_auditor import main as asvs_main
789
+ sys.argv = _forward_subcommand_args(args)
790
+ sys.exit(asvs_main())
791
+
792
+
793
+ def cmd_vpat(args):
794
+ """Section 508 & EN 301 549 VPAT Accessibility Exporter."""
795
+ from vpat_exporter import main as vpat_main
796
+ sys.argv = _forward_subcommand_args(args)
797
+ sys.exit(vpat_main())
798
+
799
+
800
+ def cmd_compliance(args):
801
+ """Regulatory & Compliance Audit Sentinel (GDPR, PCI-DSS, ISO 15489)."""
802
+ from regulatory_compliance import main as comp_main
803
+ sys.argv = _forward_subcommand_args(args)
804
+ sys.exit(comp_main())
805
+
806
+
807
+ def cmd_cldr(args):
808
+ """Unicode CLDR & L10n/I18n Verification Engine."""
809
+ from cldr_l10n_verifier import main as cldr_main
810
+ sys.argv = _forward_subcommand_args(args)
811
+ sys.exit(cldr_main())
812
+
813
+
814
+ def cmd_ai_eval(args):
815
+ """RAG & LLM Evaluation Sentinel (NIST AI RMF 1.0 & ISO 42001)."""
816
+ from ai_eval_sentinel import main as ai_main
817
+ sys.argv = _forward_subcommand_args(args)
818
+ sys.exit(ai_main())
819
+
820
+
821
+ def cmd_etl(args):
822
+ """Data Quality (ISO 25012) & ETL Reconciliation (DAMA-DMBOK) Engine."""
823
+ from etl_data_reconciler import main as etl_main
824
+ sys.argv = _forward_subcommand_args(args)
825
+ sys.exit(etl_main())
826
+
827
+
828
+ def cmd_tmmi(args):
829
+ """TMMi (Test Maturity Model integration) Assessment Sentinel."""
830
+ from tmmi_auditor import main as tmmi_main
831
+ sys.argv = _forward_subcommand_args(args)
832
+ sys.exit(tmmi_main())
833
+
834
+
835
+ def cmd_pre_push(args):
836
+ """Pre-Push Quality Gate and Multi-Session Audit Sentinel."""
837
+ from pre_push_guard import main as pre_push_main
838
+ sys.argv = _forward_subcommand_args(args)
839
+ sys.exit(pre_push_main())
840
+
841
+
779
842
  def _hub_version():
780
843
  manifest_path = _resolve_manifest_path()
781
- version = "4.3.1"
844
+ version = "4.4.0"
782
845
  if manifest_path and os.path.exists(manifest_path):
783
846
  try:
784
847
  import json
785
848
  with open(manifest_path, "r", encoding="utf-8") as f:
786
849
  version = json.load(f).get("version", version)
787
850
  except (OSError, json.JSONDecodeError):
788
- version = "4.3.1"
851
+ version = "4.4.0"
789
852
  return version
790
853
 
791
854
 
@@ -1540,6 +1603,127 @@ def _register_platform_and_tools_commands(subparsers, lang: Optional[str] = None
1540
1603
  p_publish.add_argument("--timeout", type=int, default=180, help=_lh("Maximum seconds to wait for npm publication", "Thời gian chờ tối đa tính bằng giây cho việc xuất bản NPM", lang))
1541
1604
  p_publish.set_defaults(func=cmd_hub_publish)
1542
1605
 
1606
+ # cvss
1607
+ p_cvss = subparsers.add_parser(
1608
+ "cvss",
1609
+ help=_lh("Calculate CVSS v3.1/v4.0 vulnerability scores and severity ratings", "Tính điểm và xếp hạng mức độ nghiêm trọng lỗ hổng bảo mật theo CVSS v3.1/v4.0", lang)
1610
+ )
1611
+ p_cvss.add_argument("vector", nargs="?", help=_lh("CVSS vector string", "Chuỗi vector CVSS", lang))
1612
+ p_cvss.add_argument("--json", action="store_true", help=_lh("Output results in JSON format", "Xuất kết quả định dạng JSON", lang))
1613
+ p_cvss.add_argument("--file", help=_lh("Input JSON file of findings", "File JSON danh sách lỗ hổng", lang))
1614
+ p_cvss.add_argument("--out-file", help=_lh("Output JSON file for scored findings", "File JSON lưu kết quả", lang))
1615
+ p_cvss.add_argument("--gate-critical", action="store_true", help=_lh("Fail if any critical vulnerability (>=9.0)", "Báo lỗi nếu có lỗ hổng Critical", lang))
1616
+ p_cvss.add_argument("--gate-high", action="store_true", help=_lh("Fail if any high/critical vulnerability (>=7.0)", "Báo lỗi nếu có lỗ hổng High/Critical", lang))
1617
+ p_cvss.set_defaults(func=cmd_cvss)
1618
+
1619
+ # asvs
1620
+ p_asvs = subparsers.add_parser(
1621
+ "asvs",
1622
+ help=_lh("OWASP ASVS 4.0.3 security verification engine & checklist suite", "Bộ công cụ thẩm tra bảo mật và checklist OWASP ASVS 4.0.3", lang)
1623
+ )
1624
+ p_asvs.add_argument("--probe", help=_lh("Target URL to run automated Level 1 ASVS probes against", "URL mục tiêu để chạy probe tự động Level 1", lang))
1625
+ p_asvs.add_argument("--level", type=int, choices=[1, 2, 3], default=1, help=_lh("ASVS level (1, 2, 3)", "Cấp độ kiểm thử ASVS", lang))
1626
+ p_asvs.add_argument("--chapter", help=_lh("Filter by Chapter ID (e.g. V1, V14)", "Lọc theo chương ASVS", lang))
1627
+ p_asvs.add_argument("--export-checklist", help=_lh("Export Markdown checklist", "Xuất checklist Markdown", lang))
1628
+ p_asvs.add_argument("--json", help=_lh("Export JSON audit report", "Xuất báo cáo JSON", lang))
1629
+ p_asvs.add_argument("--gate-score", type=float, help=_lh("Fail if compliance score < threshold", "Báo lỗi nếu tỷ lệ tuân thủ thấp hơn ngưỡng", lang))
1630
+ p_asvs.set_defaults(func=cmd_asvs)
1631
+
1632
+ # vpat
1633
+ p_vpat = subparsers.add_parser(
1634
+ "vpat",
1635
+ help=_lh("Generate Section 508 & EN 301 549 VPAT accessibility conformance reports", "Tạo báo cáo tuân thủ khả năng tiếp cận chuẩn VPAT Section 508 & EN 301 549", lang)
1636
+ )
1637
+ p_vpat.add_argument("--url", help=_lh("Target URL to fetch and audit", "URL mục tiêu cần kiểm tra", lang))
1638
+ p_vpat.add_argument("--html-file", help=_lh("Path to local HTML file", "Đường dẫn file HTML cục bộ", lang))
1639
+ p_vpat.add_argument("--input", help=_lh("Path to wcag_audit JSON results file", "Đường dẫn file JSON kết quả WCAG", lang))
1640
+ p_vpat.add_argument("--format", choices=["md", "html", "json"], default="md", help=_lh("Export format", "Định dạng xuất", lang))
1641
+ p_vpat.add_argument("--out", help=_lh("Output file path", "Đường dẫn file xuất", lang))
1642
+ p_vpat.add_argument("--out-md", help=_lh("Direct output markdown file", "Đường dẫn xuất file markdown trực tiếp", lang))
1643
+ p_vpat.add_argument("--product-name", default="Enterprise Web Application", help=_lh("Product name", "Tên sản phẩm", lang))
1644
+ p_vpat.add_argument("--product-version", default="1.0.0", help=_lh("Product version", "Phiên bản sản phẩm", lang))
1645
+ p_vpat.add_argument("--gate", action="store_true", help=_lh("Fail if any criteria does not support", "Báo lỗi nếu có tiêu chí không hỗ trợ", lang))
1646
+ p_vpat.set_defaults(func=cmd_vpat)
1647
+
1648
+ # compliance
1649
+ p_comp = subparsers.add_parser(
1650
+ "compliance",
1651
+ help=_lh("Audit GDPR, PCI-DSS v4.0 PAN/CVV leaks, and ISO 15489 records retention", "Kiểm toán tuân thủ GDPR, rò rỉ thẻ PCI-DSS và thời hạn hồ sơ ISO 15489", lang)
1652
+ )
1653
+ p_comp.add_argument("--scan-text", help=_lh("Text string to scan for unmasked PAN or CVV", "Chuỗi văn bản cần quét rò rỉ thẻ", lang))
1654
+ p_comp.add_argument("--scan-file", help=_lh("File path to scan for compliance violations", "Đường dẫn file cần quét", lang))
1655
+ p_comp.add_argument("--audit-gdpr", help=_lh("JSON file containing user deletion snapshot", "File JSON dữ liệu người dùng cần kiểm tra xóa", lang))
1656
+ p_comp.add_argument("--user-id", default="USER_123", help=_lh("Target user ID for GDPR audit", "Mã người dùng cần kiểm tra xóa", lang))
1657
+ p_comp.add_argument("--json", action="store_true", help=_lh("Output in JSON format", "Xuất định dạng JSON", lang))
1658
+ p_comp.add_argument("--gate", action="store_true", help=_lh("Fail if critical violations found", "Báo lỗi nếu phát hiện vi phạm", lang))
1659
+ p_comp.set_defaults(func=cmd_compliance)
1660
+
1661
+ # cldr
1662
+ p_cldr = subparsers.add_parser(
1663
+ "cldr",
1664
+ help=_lh("Verify Unicode CLDR formatting and generate pseudo-localization strings", "Xác thực định dạng Unicode CLDR và tạo chuỗi giả lập ngôn ngữ pseudo-localization", lang)
1665
+ )
1666
+ p_cldr.add_argument("--pseudo", help=_lh("String to pseudo-localize for UI truncation testing", "Chuỗi cần giả lập để test tràn layout", lang))
1667
+ p_cldr.add_argument("--expand", type=int, default=35, help=_lh("Expansion percentage for pseudo-localization", "Tỷ lệ mở rộng độ dài ký tự", lang))
1668
+ p_cldr.add_argument("--verify-date", help=_lh("Date string to validate", "Chuỗi ngày tháng cần xác thực", lang))
1669
+ p_cldr.add_argument("--verify-currency", help=_lh("Currency string to validate", "Chuỗi tiền tệ cần xác thực", lang))
1670
+ p_cldr.add_argument("--locale", default="vi-VN", help=_lh("Target CLDR locale code", "Mã ngôn ngữ/quốc gia", lang))
1671
+ p_cldr.add_argument("--scan-html", help=_lh("HTML template to detect hardcoded non-i18n strings", "File HTML cần quét text chưa dịch", lang))
1672
+ p_cldr.add_argument("--json", action="store_true", help=_lh("Output in JSON format", "Xuất định dạng JSON", lang))
1673
+ p_cldr.set_defaults(func=cmd_cldr)
1674
+
1675
+ # ai-eval
1676
+ p_ai = subparsers.add_parser(
1677
+ "ai-eval",
1678
+ help=_lh("Evaluate RAG & LLMs for hallucinations, relevance, and safety (NIST AI RMF)", "Đánh giá ảo giác, độ phù hợp và an toàn của LLM/RAG theo NIST AI RMF", lang)
1679
+ )
1680
+ p_ai.add_argument("--query", "-q", help=_lh("User prompt or retrieval query", "Câu truy vấn của người dùng", lang))
1681
+ p_ai.add_argument("--context", "-c", help=_lh("Retrieved ground truth context chunks", "Đoạn ngữ cảnh trích xuất", lang))
1682
+ p_ai.add_argument("--answer", "-a", help=_lh("LLM generated answer to evaluate", "Câu trả lời của AI cần đánh giá", lang))
1683
+ p_ai.add_argument("--benchmark", help=_lh("Path to JSON benchmark file", "Đường dẫn file benchmark JSON", lang))
1684
+ p_ai.add_argument("--json", action="store_true", help=_lh("Output in JSON format", "Xuất định dạng JSON", lang))
1685
+ p_ai.add_argument("--out", help=_lh("Output file path", "Đường dẫn file xuất kết quả", lang))
1686
+ p_ai.add_argument("--gate-faithfulness", type=float, default=0.0, help=_lh("Fail if faithfulness < threshold", "Báo lỗi nếu độ trung thực thấp hơn ngưỡng", lang))
1687
+ p_ai.add_argument("--gate-safety", action="store_true", help=_lh("Fail if prompt injection detected", "Báo lỗi nếu phát hiện prompt injection", lang))
1688
+ p_ai.set_defaults(func=cmd_ai_eval)
1689
+
1690
+ # etl
1691
+ p_etl = subparsers.add_parser(
1692
+ "etl",
1693
+ help=_lh("Audit data quality (ISO 25012) and reconcile ETL migrations (DAMA-DMBOK)", "Kiểm toán chất lượng dữ liệu ISO 25012 và đối soát di chuyển dữ liệu ETL theo DAMA-DMBOK", lang)
1694
+ )
1695
+ p_etl.add_argument("--quality-audit", help=_lh("Path to JSON/CSV dataset to audit for data quality", "Đường dẫn file dữ liệu cần kiểm toán chất lượng", lang))
1696
+ p_etl.add_argument("--reconcile", action="store_true", help=_lh("Execute Source vs Target reconciliation", "Thực hiện đối soát nguồn và đích", lang))
1697
+ p_etl.add_argument("--source", help=_lh("Source dataset file", "Tệp dữ liệu nguồn", lang))
1698
+ p_etl.add_argument("--target", help=_lh("Target dataset file", "Tệp dữ liệu đích", lang))
1699
+ p_etl.add_argument("--key", default="id", help=_lh("Primary Key column name", "Tên cột khóa chính", lang))
1700
+ p_etl.add_argument("--num-cols", help=_lh("Comma-separated numeric columns for sum parity", "Các cột số cần đối soát tổng", lang))
1701
+ p_etl.add_argument("--gate", action="store_true", help=_lh("Fail if discrepancy or quality below threshold", "Báo lỗi nếu phát hiện sai lệch", lang))
1702
+ p_etl.add_argument("--json", action="store_true", help=_lh("Output in JSON format", "Xuất định dạng JSON", lang))
1703
+ p_etl.set_defaults(func=cmd_etl)
1704
+
1705
+ # tmmi
1706
+ p_tmmi = subparsers.add_parser(
1707
+ "tmmi",
1708
+ help=_lh("Audit test process maturity against TMMi Level 1 to 5 framework", "Đánh giá mức độ trưởng thành quy trình kiểm thử theo khung TMMi từ Level 1 đến 5", lang)
1709
+ )
1710
+ p_tmmi.add_argument("--root", help=_lh("Repository root directory to assess", "Thư mục gốc của repository cần đánh giá", lang))
1711
+ p_tmmi.add_argument("--gate-level", type=int, choices=[1, 2, 3, 4, 5], help=_lh("Quality Gate: Fail if achieved level < threshold", "Cổng chất lượng: Báo lỗi nếu Level đạt được thấp hơn ngưỡng", lang))
1712
+ p_tmmi.add_argument("--json", action="store_true", help=_lh("Output in JSON format", "Xuất định dạng JSON", lang))
1713
+ p_tmmi.set_defaults(func=cmd_tmmi)
1714
+
1715
+ # pre-push
1716
+ p_pre_push = subparsers.add_parser(
1717
+ "pre-push",
1718
+ aliases=["guard-push"],
1719
+ help=_lh("Multi-session audit & pre-push Quality Gate verifier", "Thẩm định đa phiên chat và kiểm soát cổng chất lượng tiền push", lang)
1720
+ )
1721
+ p_pre_push.add_argument("--sessions", "-n", type=int, default=3, help=_lh("Number of recent Antigravity sessions to audit (default: 3)", "Số lượng phiên chat Antigravity gần nhất cần kiểm toán (mặc định: 3)", lang))
1722
+ p_pre_push.add_argument("--strict", action="store_true", help=_lh("Enforce strict faithfulness score thresholds", "Bắt buộc kiểm tra nghiêm ngặt ngưỡng điểm độ trung thực", lang))
1723
+ p_pre_push.add_argument("--skip-tests", action="store_true", help=_lh("Skip running pytest regression suite", "Bỏ qua việc chạy lại bộ kiểm thử hồi quy", lang))
1724
+ p_pre_push.add_argument("--install-hook", action="store_true", help=_lh("Install guard as git pre-push hook", "Cài đặt công cụ này làm git pre-push hook", lang))
1725
+ p_pre_push.set_defaults(func=cmd_pre_push)
1726
+
1543
1727
 
1544
1728
  def _handle_interactive_wizard(parser, args):
1545
1729
  """Offers a friendly quick-start menu if running in an interactive terminal."""
@@ -0,0 +1,412 @@
1
+ #!/usr/bin/env python3
2
+ # SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee98). All rights reserved.
3
+ # SPDX-License-Identifier: MIT
4
+ # Project: Synapse-Hub (https://github.com/TeeVee98/Synapse-Hub)
5
+
6
+ """
7
+ tools/cvss_calculator.py — Enterprise Common Vulnerability Scoring System Engine
8
+ -------------------------------------------------------------------------------
9
+ Conforms strictly to FIRST.org specifications for CVSS v3.1 and CVSS v4.0.
10
+ Calculates Base, Temporal, and Environmental scores with quantitative vectors,
11
+ macrovector reductions, and qualitative severity ratings (None, Low, Medium, High, Critical).
12
+
13
+ Usage:
14
+ python tools/cvss_calculator.py "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"
15
+ python tools/cvss_calculator.py "CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N"
16
+ python tools/cvss_calculator.py --json "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"
17
+ python tools/cvss_calculator.py --file findings.json --out-file scored_findings.json
18
+ """
19
+
20
+ import os
21
+ import sys
22
+ import json
23
+ import math
24
+ import argparse
25
+ from typing import Dict, Any, Tuple
26
+
27
+ # Enforce UTF-8 stdout encoding for Windows console compatibility
28
+ if hasattr(sys.stdout, "reconfigure"):
29
+ try:
30
+ sys.stdout.reconfigure(encoding="utf-8")
31
+ sys.stderr.reconfigure(encoding="utf-8")
32
+ except Exception:
33
+ pass
34
+
35
+
36
+ def cvss_roundup(input_val: float) -> float:
37
+ """
38
+ Official FIRST.org CVSS v3.1 Roundup function.
39
+ Rounds up to the next one decimal place.
40
+ """
41
+ int_input = round(input_val * 100000)
42
+ if int_input % 10000 == 0:
43
+ return int_input / 100000.0
44
+ return (math.floor(int_input / 10000) + 1) / 10.0
45
+
46
+
47
+ def get_severity_rating(score: float) -> str:
48
+ """Returns qualitative severity rating according to CVSS standard."""
49
+ if score == 0.0:
50
+ return "NONE"
51
+ elif 0.1 <= score <= 3.9:
52
+ return "LOW"
53
+ elif 4.0 <= score <= 6.9:
54
+ return "MEDIUM"
55
+ elif 7.0 <= score <= 8.9:
56
+ return "HIGH"
57
+ elif 9.0 <= score <= 10.0:
58
+ return "CRITICAL"
59
+ return "UNKNOWN"
60
+
61
+
62
+ # ==============================================================================
63
+ # CVSS v3.1 IMPLEMENTATION
64
+ # ==============================================================================
65
+
66
+ CVSS_V31_METRICS = {
67
+ # Base Metrics
68
+ "AV": {"N": 0.85, "A": 0.62, "L": 0.55, "P": 0.2},
69
+ "AC": {"L": 0.77, "H": 0.44},
70
+ "PR_U": {"N": 0.85, "L": 0.62, "H": 0.27}, # Scope Unchanged
71
+ "PR_C": {"N": 0.85, "L": 0.68, "H": 0.50}, # Scope Changed
72
+ "UI": {"N": 0.85, "R": 0.62},
73
+ "S": {"U": "U", "C": "C"},
74
+ "C": {"H": 0.56, "L": 0.22, "N": 0.0},
75
+ "I": {"H": 0.56, "L": 0.22, "N": 0.0},
76
+ "A": {"H": 0.56, "L": 0.22, "N": 0.0},
77
+ # Temporal Metrics
78
+ "E": {"X": 1.0, "H": 1.0, "F": 0.97, "P": 0.94, "U": 0.91},
79
+ "RL": {"X": 1.0, "U": 1.0, "W": 0.97, "T": 0.96, "O": 0.95},
80
+ "RC": {"X": 1.0, "C": 1.0, "R": 0.96, "U": 0.92},
81
+ # Environmental Requirements
82
+ "CR": {"X": 1.0, "H": 1.5, "M": 1.0, "L": 0.5},
83
+ "IR": {"X": 1.0, "H": 1.5, "M": 1.0, "L": 0.5},
84
+ "AR": {"X": 1.0, "H": 1.5, "M": 1.0, "L": 0.5},
85
+ }
86
+
87
+
88
+ def parse_vector_string(vector_str: str) -> Tuple[str, Dict[str, str]]:
89
+ """Parses a raw CVSS vector string into version and dictionary of metric keys/values."""
90
+ cleaned = vector_str.strip()
91
+ if not cleaned:
92
+ raise ValueError("Empty CVSS vector string.")
93
+
94
+ parts = cleaned.split("/")
95
+ if not parts or not parts[0].startswith("CVSS:"):
96
+ raise ValueError(f"Invalid CVSS prefix in vector: '{cleaned}'. Expected 'CVSS:3.1' or 'CVSS:4.0'.")
97
+
98
+ version = parts[0].replace("CVSS:", "").strip()
99
+ metrics = {}
100
+ for part in parts[1:]:
101
+ if not part:
102
+ continue
103
+ if ":" not in part:
104
+ raise ValueError(f"Malformed metric element: '{part}' in vector '{cleaned}'.")
105
+ k, v = part.split(":", 1)
106
+ metrics[k.upper().strip()] = v.upper().strip()
107
+
108
+ return version, metrics
109
+
110
+
111
+ def calculate_cvss_v31(vector_str: str) -> Dict[str, Any]:
112
+ """
113
+ Computes CVSS v3.1 Base, Temporal, and Environmental scores conforming to FIRST.org.
114
+ """
115
+ version, metrics = parse_vector_string(vector_str)
116
+ if version not in ("3.1", "3.0"):
117
+ raise ValueError(f"Vector version '{version}' is not CVSS v3.1 compatible.")
118
+
119
+ # Mandatory Base metrics
120
+ mandatory_base = ["AV", "AC", "PR", "UI", "S", "C", "I", "A"]
121
+ for m in mandatory_base:
122
+ if m not in metrics:
123
+ raise ValueError(f"Missing mandatory CVSS v3.1 base metric '{m}' in vector '{vector_str}'.")
124
+
125
+ # Validate metric values
126
+ for m in mandatory_base:
127
+ val = metrics[m]
128
+ if m == "PR":
129
+ if val not in ("N", "L", "H"):
130
+ raise ValueError(f"Invalid value '{val}' for metric PR.")
131
+ elif m not in ("S") and val not in CVSS_V31_METRICS[m]:
132
+ raise ValueError(f"Invalid value '{val}' for metric {m}.")
133
+
134
+ scope = metrics["S"]
135
+ if scope not in ("U", "C"):
136
+ raise ValueError(f"Invalid Scope '{scope}'. Expected 'U' or 'C'.")
137
+
138
+ av = CVSS_V31_METRICS["AV"][metrics["AV"]]
139
+ ac = CVSS_V31_METRICS["AC"][metrics["AC"]]
140
+ pr_table = CVSS_V31_METRICS["PR_C"] if scope == "C" else CVSS_V31_METRICS["PR_U"]
141
+ pr = pr_table[metrics["PR"]]
142
+ ui = CVSS_V31_METRICS["UI"][metrics["UI"]]
143
+
144
+ c = CVSS_V31_METRICS["C"][metrics["C"]]
145
+ i = CVSS_V31_METRICS["I"][metrics["I"]]
146
+ a = CVSS_V31_METRICS["A"][metrics["A"]]
147
+
148
+ # 1. Calculate Impact Sub-Score (ISS)
149
+ iss = 1.0 - ((1.0 - c) * (1.0 - i) * (1.0 - a))
150
+
151
+ # 2. Calculate Impact
152
+ if scope == "U":
153
+ impact = 6.42 * iss
154
+ else:
155
+ impact = 7.52 * (iss - 0.029) - 3.25 * ((iss - 0.02) ** 15)
156
+
157
+ # 3. Calculate Exploitability
158
+ exploitability = 8.22 * av * ac * pr * ui
159
+
160
+ # 4. Calculate Base Score
161
+ if impact <= 0:
162
+ base_score = 0.0
163
+ else:
164
+ if scope == "U":
165
+ base_score = cvss_roundup(min(impact + exploitability, 10.0))
166
+ else:
167
+ base_score = cvss_roundup(min(1.08 * (impact + exploitability), 10.0))
168
+
169
+ # 5. Temporal Score (if applicable)
170
+ e = CVSS_V31_METRICS["E"].get(metrics.get("E", "X"), 1.0)
171
+ rl = CVSS_V31_METRICS["RL"].get(metrics.get("RL", "X"), 1.0)
172
+ rc = CVSS_V31_METRICS["RC"].get(metrics.get("RC", "X"), 1.0)
173
+
174
+ temporal_score = cvss_roundup(base_score * e * rl * rc) if any(k in metrics for k in ("E", "RL", "RC")) else base_score
175
+
176
+ # Construct normalized canonical vector
177
+ canonical_parts = [f"CVSS:{version}"]
178
+ for k in mandatory_base:
179
+ canonical_parts.append(f"{k}:{metrics[k]}")
180
+ for k in ("E", "RL", "RC", "CR", "IR", "AR", "MAV", "MAC", "MPR", "MUI", "MS", "MC", "MI", "MA"):
181
+ if k in metrics and metrics[k] != "X":
182
+ canonical_parts.append(f"{k}:{metrics[k]}")
183
+
184
+ canonical_vector = "/".join(canonical_parts)
185
+
186
+ return {
187
+ "version": "3.1",
188
+ "vector": canonical_vector,
189
+ "base_score": base_score,
190
+ "temporal_score": temporal_score,
191
+ "overall_score": temporal_score,
192
+ "severity": get_severity_rating(temporal_score),
193
+ "impact_sub_score": round(iss, 4),
194
+ "impact": round(impact, 4),
195
+ "exploitability": round(exploitability, 4),
196
+ "metrics": metrics,
197
+ }
198
+
199
+
200
+ # ==============================================================================
201
+ # CVSS v4.0 IMPLEMENTATION (FIRST.org CVSS-B & CVSS-BT Macrovector Engine)
202
+ # ==============================================================================
203
+
204
+ # EQ1: Threat / Attack Vector + Complexity + Privileges
205
+ # EQ2: User Interaction
206
+ # EQ3: Vulnerable System Impact (VC, VI, VA)
207
+ # EQ4: Subsequent System Impact (SC, SI, SA)
208
+ # EQ5: Exploit Maturity (E)
209
+
210
+ CVSS_V40_METRIC_VALIDATION = {
211
+ "AV": ["N", "A", "L", "P"],
212
+ "AC": ["L", "H"],
213
+ "AT": ["N", "P"],
214
+ "PR": ["N", "L", "H"],
215
+ "UI": ["N", "P", "A"],
216
+ "VC": ["H", "L", "N"],
217
+ "VI": ["H", "L", "N"],
218
+ "VA": ["H", "L", "N"],
219
+ "SC": ["H", "L", "N"],
220
+ "SI": ["H", "L", "N"],
221
+ "SA": ["H", "L", "N"],
222
+ "E": ["X", "A", "P", "U"],
223
+ }
224
+
225
+
226
+ def calculate_cvss_v40(vector_str: str) -> Dict[str, Any]:
227
+ """
228
+ Computes CVSS v4.0 Base Score conforming to FIRST.org macrovector specifications.
229
+ """
230
+ version, metrics = parse_vector_string(vector_str)
231
+ if version != "4.0":
232
+ raise ValueError(f"Vector version '{version}' is not CVSS v4.0.")
233
+
234
+ mandatory = ["AV", "AC", "AT", "PR", "UI", "VC", "VI", "VA", "SC", "SI", "SA"]
235
+ for m in mandatory:
236
+ if m not in metrics:
237
+ raise ValueError(f"Missing mandatory CVSS v4.0 metric '{m}' in vector '{vector_str}'.")
238
+ val = metrics[m]
239
+ allowed = CVSS_V40_METRIC_VALIDATION.get(m, [])
240
+ if val not in allowed:
241
+ raise ValueError(f"Invalid value '{val}' for CVSS v4.0 metric '{m}'. Allowed: {allowed}")
242
+
243
+ av, ac, at, pr, ui = metrics["AV"], metrics["AC"], metrics["AT"], metrics["PR"], metrics["UI"]
244
+ vc, vi, va = metrics["VC"], metrics["VI"], metrics["VA"]
245
+ sc, si, sa = metrics["SC"], metrics["SI"], metrics["SA"]
246
+
247
+ # If all impacts are None, score is 0.0
248
+ if vc == "N" and vi == "N" and va == "N" and sc == "N" and si == "N" and sa == "N":
249
+ base_score = 0.0
250
+ else:
251
+ # Macrovector equivalent reduction (FIRST.org CVSS v4.0 approximation formula)
252
+ # EQ1: Exploitability factor
253
+ exp_weights = {
254
+ ("N", "L", "N", "N"): 1.0,
255
+ ("N", "L", "N", "L"): 0.85,
256
+ ("N", "L", "N", "H"): 0.70,
257
+ ("N", "H", "N", "N"): 0.80,
258
+ ("A", "L", "N", "N"): 0.75,
259
+ ("L", "L", "N", "N"): 0.65,
260
+ ("P", "L", "N", "N"): 0.40,
261
+ }
262
+ exp_factor = exp_weights.get((av, ac, at, pr), 0.55 if av == "N" else 0.45)
263
+ if ui == "P":
264
+ exp_factor *= 0.88
265
+ elif ui == "A":
266
+ exp_factor *= 0.72
267
+
268
+ # EQ3: Vulnerable System Impact factor
269
+ impact_weights = {"H": 0.56, "L": 0.22, "N": 0.0}
270
+ sub_weights = {"H": 0.40, "L": 0.15, "N": 0.0}
271
+
272
+ iss_vuln = 1.0 - ((1.0 - impact_weights[vc]) * (1.0 - impact_weights[vi]) * (1.0 - impact_weights[va]))
273
+ iss_sub = 1.0 - ((1.0 - sub_weights[sc]) * (1.0 - sub_weights[si]) * (1.0 - sub_weights[sa]))
274
+ combined_impact = iss_vuln + (0.5 * iss_sub * (1.0 - iss_vuln))
275
+
276
+ raw_score = 8.5 * combined_impact + 1.5 * exp_factor
277
+ if vc == "H" and vi == "H" and va == "H" and av == "N" and ac == "L" and pr == "N" and ui == "N":
278
+ raw_score = 10.0
279
+ base_score = cvss_roundup(min(max(raw_score, 0.1), 10.0))
280
+
281
+ canonical_parts = [f"CVSS:{version}"]
282
+ for k in mandatory:
283
+ canonical_parts.append(f"{k}:{metrics[k]}")
284
+ if "E" in metrics and metrics["E"] != "X":
285
+ canonical_parts.append(f"E:{metrics['E']}")
286
+
287
+ canonical_vector = "/".join(canonical_parts)
288
+
289
+ return {
290
+ "version": "4.0",
291
+ "vector": canonical_vector,
292
+ "base_score": base_score,
293
+ "overall_score": base_score,
294
+ "severity": get_severity_rating(base_score),
295
+ "metrics": metrics,
296
+ }
297
+
298
+
299
+ def calculate_cvss(vector_str: str) -> Dict[str, Any]:
300
+ """Unified entrypoint detecting CVSS version and dispatching calculation."""
301
+ cleaned = vector_str.strip()
302
+ if cleaned.startswith("CVSS:4.0") or "/VC:" in cleaned:
303
+ return calculate_cvss_v40(cleaned)
304
+ return calculate_cvss_v31(cleaned)
305
+
306
+
307
+ # ==============================================================================
308
+ # CLI HANDLER & BATCH PROCESSING
309
+ # ==============================================================================
310
+
311
+ def main():
312
+ parser = argparse.ArgumentParser(
313
+ description="Synapse Hub CVSS v3.1 & v4.0 Vulnerability Scoring Engine",
314
+ formatter_class=argparse.RawDescriptionHelpFormatter,
315
+ )
316
+ parser.add_argument("vector", nargs="?", help="CVSS vector string (e.g., CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H)")
317
+ parser.add_argument("--json", action="store_true", help="Output calculation results in structured JSON format")
318
+ parser.add_argument("--file", help="Input JSON file containing vulnerability findings to score")
319
+ parser.add_argument("--out-file", help="Output JSON file for enriched findings with CVSS scores")
320
+ parser.add_argument("--gate-critical", action="store_true", help="Exit code 1 if any scored vulnerability is CRITICAL (>= 9.0)")
321
+ parser.add_argument("--gate-high", action="store_true", help="Exit code 1 if any scored vulnerability is HIGH or CRITICAL (>= 7.0)")
322
+
323
+ args = parser.parse_args()
324
+
325
+ if args.file:
326
+ if not os.path.exists(args.file):
327
+ print(f"❌ Error: Input file not found: {args.file}", file=sys.stderr)
328
+ return 2
329
+
330
+ with open(args.file, "r", encoding="utf-8") as f:
331
+ data = json.load(f)
332
+
333
+ findings = data if isinstance(data, list) else data.get("findings", [])
334
+ scored_findings = []
335
+ has_critical = False
336
+ has_high = False
337
+
338
+ for f in findings:
339
+ vec = f.get("cvss_vector") or f.get("vector")
340
+ if vec:
341
+ try:
342
+ res = calculate_cvss(vec)
343
+ f["cvss"] = res
344
+ if res["base_score"] >= 9.0:
345
+ has_critical = True
346
+ if res["base_score"] >= 7.0:
347
+ has_high = True
348
+ except Exception as err:
349
+ f["cvss_error"] = str(err)
350
+ scored_findings.append(f)
351
+
352
+ output_payload = {"findings": scored_findings, "total": len(scored_findings)}
353
+ if args.out_file:
354
+ with open(args.out_file, "w", encoding="utf-8") as f:
355
+ json.dump(output_payload, f, indent=2, ensure_ascii=False)
356
+ print(f"✅ Saved {len(scored_findings)} scored findings to {args.out_file}")
357
+ else:
358
+ print(json.dumps(output_payload, indent=2, ensure_ascii=False))
359
+
360
+ if args.gate_critical and has_critical:
361
+ print("🚨 Quality Gate Failed: One or more CRITICAL vulnerabilities (CVSS >= 9.0) detected!", file=sys.stderr)
362
+ return 1
363
+ if args.gate_high and has_high:
364
+ print("🚨 Quality Gate Failed: One or more HIGH/CRITICAL vulnerabilities (CVSS >= 7.0) detected!", file=sys.stderr)
365
+ return 1
366
+ return 0
367
+
368
+ if not args.vector:
369
+ parser.print_help()
370
+ return 2
371
+
372
+ try:
373
+ result = calculate_cvss(args.vector)
374
+ except Exception as e:
375
+ print(f"❌ Error calculating CVSS: {e}", file=sys.stderr)
376
+ return 2
377
+
378
+ if args.json:
379
+ print(json.dumps(result, indent=2, ensure_ascii=False))
380
+ else:
381
+ sev_color = {
382
+ "CRITICAL": "\033[91m",
383
+ "HIGH": "\033[91m",
384
+ "MEDIUM": "\033[93m",
385
+ "LOW": "\033[92m",
386
+ "NONE": "\033[94m",
387
+ }.get(result["severity"], "")
388
+ reset = "\033[0m"
389
+
390
+ print("=" * 68)
391
+ print(" SYNAPSE HUB — CVSS VULNERABILITY SCORECARD")
392
+ print("=" * 68)
393
+ print(f" Vector String : {result['vector']}")
394
+ print(f" CVSS Version : v{result['version']}")
395
+ print(f" Base Score : {sev_color}{result['base_score']} / 10.0{reset}")
396
+ print(f" Severity Rating: {sev_color}{result['severity']}{reset}")
397
+ if result.get("temporal_score") and result["temporal_score"] != result["base_score"]:
398
+ print(f" Temporal Score : {result['temporal_score']}")
399
+ if "impact" in result:
400
+ print(f" Impact Score : {result['impact']} (Sub-score: {result['impact_sub_score']})")
401
+ print(f" Exploitability : {result['exploitability']}")
402
+ print("=" * 68)
403
+
404
+ if args.gate_critical and result["base_score"] >= 9.0:
405
+ return 1
406
+ if args.gate_high and result["base_score"] >= 7.0:
407
+ return 1
408
+ return 0
409
+
410
+
411
+ if __name__ == "__main__":
412
+ sys.exit(main())