@teevee98/synapse-hub 4.1.3 → 4.2.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 (206) hide show
  1. package/.agents/rules/git-push-protocol.md +2 -2
  2. package/.agents/skills/01-web-automation/auth-session-and-cookie-manager/SKILL.md +6 -1
  3. package/.agents/skills/01-web-automation/bats-testing-patterns/SKILL.md +6 -1
  4. package/.agents/skills/01-web-automation/clean-pom-crafter/SKILL.md +8 -3
  5. package/.agents/skills/01-web-automation/clean-pom-crafter/examples/standard_test_case.groovy +3 -0
  6. package/.agents/skills/01-web-automation/clean-pom-crafter/references/pom_patterns.groovy +3 -0
  7. package/.agents/skills/01-web-automation/e2e-testing-patterns/SKILL.md +6 -1
  8. package/.agents/skills/01-web-automation/e2e-testing-patterns/examples/playwright_sharded_config.ts +3 -0
  9. package/.agents/skills/01-web-automation/katalon-cli-runner/SKILL.md +6 -1
  10. package/.agents/skills/01-web-automation/lam-script-generator/SKILL.md +6 -1
  11. package/.agents/skills/01-web-automation/mobile-appium-som/SKILL.md +6 -1
  12. package/.agents/skills/01-web-automation/mobile-appium-som/examples/BaseScreen.java +2 -2
  13. package/.agents/skills/01-web-automation/mobile-appium-som/examples/LoginScreen.java +2 -2
  14. package/.agents/skills/01-web-automation/mobile-appium-som/examples/TC_MobileLogin.java +2 -2
  15. package/.agents/skills/01-web-automation/playwright-live-interaction/SKILL.md +7 -2
  16. package/.agents/skills/01-web-automation/playwright-webapp-testing/SKILL.md +6 -1
  17. package/.agents/skills/01-web-automation/playwright-webapp-testing/examples/server_lifecycle_playwright.py +3 -0
  18. package/.agents/skills/01-web-automation/web-agent-gym-benchmarking/SKILL.md +6 -1
  19. package/.agents/skills/02-test-design/architecture-decision-records/SKILL.md +6 -1
  20. package/.agents/skills/02-test-design/gherkin-to-suite/SKILL.md +6 -1
  21. package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +6 -1
  22. package/.agents/skills/02-test-design/review-spec/SKILL.md +4 -1
  23. package/.agents/skills/02-test-design/tot-exploratory-testing/SKILL.md +6 -1
  24. package/.agents/skills/03-api-and-contracts/api-network-mocking-interception/SKILL.md +6 -1
  25. package/.agents/skills/03-api-and-contracts/api-spec-to-e2e-matrix/SKILL.md +6 -1
  26. package/.agents/skills/03-api-and-contracts/consumer-driven-contract-testing/SKILL.md +7 -2
  27. package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/SKILL.md +7 -2
  28. package/.agents/skills/04-performance-and-load/lean-impact-scoreboard/SKILL.md +4 -1
  29. package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/SKILL.md +6 -1
  30. package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/examples/playwright_cwv_profiler_fixture.ts +3 -0
  31. package/.agents/skills/05-security-and-compliance/security-dast-sentinel/SKILL.md +6 -1
  32. package/.agents/skills/05-security-and-compliance/security-dast-sentinel/references/dast_recipes.ts +3 -0
  33. package/.agents/skills/05-security-and-compliance/skillspector-security-guard/SKILL.md +6 -1
  34. package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +6 -1
  35. package/.agents/skills/06-healing-and-resilience/agentless-qa-repair/SKILL.md +6 -1
  36. package/.agents/skills/06-healing-and-resilience/antigravity-test-sentinel/SKILL.md +6 -1
  37. package/.agents/skills/06-healing-and-resilience/failure-autopsy-and-healing/SKILL.md +7 -2
  38. package/.agents/skills/06-healing-and-resilience/flaky-test-sentinel-and-quarantine/SKILL.md +6 -1
  39. package/.agents/skills/06-healing-and-resilience/self-healing-locator/SKILL.md +6 -1
  40. package/.agents/skills/06-healing-and-resilience/systematic-debugging/SKILL.md +6 -1
  41. package/.agents/skills/06-healing-and-resilience/test-driven-development/SKILL.md +6 -1
  42. package/.agents/skills/06-healing-and-resilience/verification-before-completion/SKILL.md +6 -1
  43. package/.agents/skills/06-healing-and-resilience/visual-regression-sentinel/SKILL.md +6 -1
  44. package/.agents/skills/07-data-and-state/db-state-verifier-and-seeder/SKILL.md +6 -1
  45. package/.agents/skills/07-data-and-state/file-and-report-validator/SKILL.md +6 -1
  46. package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +6 -1
  47. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/SKILL.md +6 -1
  48. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/examples/refactored_page_sample.groovy +3 -0
  49. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/examples/refactored_playwright_pom.ts +3 -0
  50. package/.agents/skills/08-code-quality/graphify-impact-analyzer/SKILL.md +6 -1
  51. package/.agents/skills/08-code-quality/lean-code-ladder/SKILL.md +6 -1
  52. package/.agents/skills/08-code-quality/repo-quality-audit/SKILL.md +4 -1
  53. package/.agents/skills/08-code-quality/senior-code-review/SKILL.md +4 -1
  54. package/.agents/skills/08-code-quality/surgical-coding-principles/SKILL.md +6 -1
  55. package/.agents/skills/08-code-quality/technical-debt-harvester/SKILL.md +4 -1
  56. package/.agents/skills/09-ci-and-devops/github-actions-templates/SKILL.md +6 -1
  57. package/.agents/skills/10-agent-orchestration/actor-qa-swarm/SKILL.md +6 -1
  58. package/.agents/skills/10-agent-orchestration/agent-orchestration-multi-agent-optimize/SKILL.md +6 -1
  59. package/.agents/skills/10-agent-orchestration/event-stream-qa-orchestrator/SKILL.md +6 -1
  60. package/.agents/skills/10-agent-orchestration/persistent-planning-files/SKILL.md +6 -1
  61. package/.agents/skills/10-agent-orchestration/qa-memory-os/SKILL.md +6 -1
  62. package/.agents/skills/11-ai-and-prompting/meta-prompt-crafter/SKILL.md +6 -1
  63. package/.agents/skills/11-ai-and-prompting/mipro-prompt-compiler/SKILL.md +6 -1
  64. package/.agents/skills/11-ai-and-prompting/qa-aci-interface/SKILL.md +6 -1
  65. package/.agents/skills/11-ai-and-prompting/qa-aci-interface/examples/surgical_code_window_walkthrough.md +1 -1
  66. package/.agents/skills/11-ai-and-prompting/token-and-context-optimizer/SKILL.md +6 -1
  67. package/AGENTS.md +7 -1
  68. package/LICENSE +5 -5
  69. package/NOTICE +1 -1
  70. package/README.en.md +4 -4
  71. package/README.md +4 -4
  72. package/agentskills.json +1 -1
  73. package/docs/ARCHITECTURE.en.md +2 -2
  74. package/docs/ARCHITECTURE.md +11 -2
  75. package/docs/CLI_REFERENCE.en.md +6 -4
  76. package/docs/CLI_REFERENCE.md +1 -1
  77. package/docs/CONTRIBUTING.en.md +1 -1
  78. package/docs/CONTRIBUTING.md +2 -2
  79. package/docs/PERFORMANCE_AUDIT_REPORT.md +2 -2
  80. package/docs/TOOL_CATALOG.md +6 -2
  81. package/docs/research/agent_skill_training_analysis.md +1 -1
  82. package/package.json +1 -1
  83. package/plugin.json +1 -1
  84. package/scripts/generate_skill_examples.py +3 -0
  85. package/scripts/package_dist.py +3 -0
  86. package/skills_manifest.json +320 -55
  87. package/synapse.config.json +1 -1
  88. package/templates/ui/index.html +2 -2
  89. package/tools/.infer_baseline.json +3 -796
  90. package/tools/TOOL_CATALOG.json +63 -3
  91. package/tools/__init__.py +4 -1
  92. package/tools/agent_canary.py +3 -0
  93. package/tools/analyze_project.py +3 -0
  94. package/tools/api_drift_sentinel.py +3 -0
  95. package/tools/api_fuzzer.py +182 -118
  96. package/tools/ast_cache.py +4 -2
  97. package/tools/author_integrity.py +174 -12
  98. package/tools/auto_heal.py +7 -2
  99. package/tools/autogen_qa_broker.py +14 -15
  100. package/tools/benchmark_swarm_context.py +119 -18
  101. package/tools/break_ui_generator.py +233 -0
  102. package/tools/browser_helpers.js +2 -2
  103. package/tools/bug_reporter.py +3 -0
  104. package/tools/build_consolidated_report.py +3 -0
  105. package/tools/bump_version.py +4 -1
  106. package/tools/cache_resolver.py +7 -3
  107. package/tools/check_env.py +3 -0
  108. package/tools/check_version_sync.py +21 -50
  109. package/tools/ci_healing_hook.py +3 -0
  110. package/tools/cli.py +116 -22
  111. package/tools/config_decoupler.py +3 -0
  112. package/tools/core/__init__.py +3 -0
  113. package/tools/core/bm25_retriever.py +218 -0
  114. package/tools/core/file_lock.py +23 -14
  115. package/tools/core/i18n.py +13 -11
  116. package/tools/core/memory_bus.py +6 -3
  117. package/tools/core/process_supervisor.py +28 -18
  118. package/tools/core/provider_usage_adapter.py +317 -0
  119. package/tools/core/token_estimator.py +83 -18
  120. package/tools/count_tokens.py +16 -7
  121. package/tools/coverage_reporter.py +245 -0
  122. package/tools/create_mock_docx.py +3 -0
  123. package/tools/dashboard_generator.py +17 -15
  124. package/tools/db_sandbox.py +150 -5
  125. package/tools/debt_harvester.py +2 -2
  126. package/tools/diagram_architect.py +3 -0
  127. package/tools/distill_log.py +22 -2
  128. package/tools/distill_skill.py +191 -0
  129. package/tools/e2e_flow_prober.py +3 -0
  130. package/tools/export_postman_collection.py +3 -0
  131. package/tools/flaky_detector.py +3 -0
  132. package/tools/fsm_enforcer.py +2 -2
  133. package/tools/fuzz_payloads.py +3 -0
  134. package/tools/generate_allure_report.py +3 -0
  135. package/tools/generate_api_matrix.py +3 -0
  136. package/tools/generate_jmx_plan.py +3 -0
  137. package/tools/generate_tc_from_story.py +3 -0
  138. package/tools/generate_test_reports.py +3 -0
  139. package/tools/git_pre_commit_guard.py +25 -3
  140. package/tools/git_worktree_manager.py +3 -0
  141. package/tools/heal/__init__.py +3 -0
  142. package/tools/heal_pr_automator.py +3 -0
  143. package/tools/heuristic_locator_matcher.py +3 -0
  144. package/tools/hub_publisher.py +3 -3
  145. package/tools/humanize_linter.py +3 -0
  146. package/tools/infer_linter.py +19 -9
  147. package/tools/init_config.py +6 -9
  148. package/tools/jtl_analyzer.py +3 -0
  149. package/tools/lint/__init__.py +3 -0
  150. package/tools/lint_ai_docs.py +3 -0
  151. package/tools/lookup_tc.py +3 -0
  152. package/tools/lookup_xpath.py +3 -0
  153. package/tools/matrix_sharder.py +3 -0
  154. package/tools/mcp/__init__.py +3 -0
  155. package/tools/mcp_docx_server.py +1 -1
  156. package/tools/mcp_excel_server.py +4 -1
  157. package/tools/mcp_server.py +78 -15
  158. package/tools/md_to_xlsx.py +3 -0
  159. package/tools/mechanical_ui_gate.py +3 -0
  160. package/tools/micro_mutator.py +93 -19
  161. package/tools/network_mock_shield.py +3 -0
  162. package/tools/newman_analyzer.py +3 -0
  163. package/tools/omni_emitter.py +3 -0
  164. package/tools/omni_parser.py +3 -0
  165. package/tools/omni_transpiler.py +3 -0
  166. package/tools/output_formatter.py +3 -0
  167. package/tools/package_release.py +6 -6
  168. package/tools/pairwise_generator.py +3 -0
  169. package/tools/pentest_scope_guard.py +401 -58
  170. package/tools/perf/__init__.py +3 -0
  171. package/tools/perf/benchmark_perf_runner.py +42 -0
  172. package/tools/pinpoint_failure.py +3 -0
  173. package/tools/project_state.py +3 -0
  174. package/tools/repo_map.py +3 -0
  175. package/tools/report/__init__.py +3 -0
  176. package/tools/rules_router.py +426 -34
  177. package/tools/runaway_stopper.py +3 -0
  178. package/tools/safety_firewall.py +3 -0
  179. package/tools/security_scanner.py +80 -0
  180. package/tools/senior_code_review.py +14 -0
  181. package/tools/setup_project.py +9 -4
  182. package/tools/skill_canonical_digest.py +244 -0
  183. package/tools/skill_collision_guard.py +2 -2
  184. package/tools/skill_profiles.py +77 -7
  185. package/tools/skillspector.py +2 -1
  186. package/tools/slide_deck_exporter.py +477 -0
  187. package/tools/smart_visual_masker.py +3 -0
  188. package/tools/sync_skills_manifest.py +166 -0
  189. package/tools/task_memory_manager.py +260 -0
  190. package/tools/telemetry_correlator.py +3 -0
  191. package/tools/template_excel_exporter.py +2 -2
  192. package/tools/test_impact.py +3 -0
  193. package/tools/trace_data_flow.py +3 -0
  194. package/tools/traffic_session_converter.py +3 -0
  195. package/tools/ui_server.py +2 -2
  196. package/tools/universal_ir.py +3 -0
  197. package/tools/update_sentinel.py +15 -9
  198. package/tools/validate_groovy_scripts.py +3 -0
  199. package/tools/validate_host_interop.py +485 -0
  200. package/tools/validate_skills_schema.py +282 -0
  201. package/tools/verify_all.py +600 -63
  202. package/tools/visual_diff_canvas.py +3 -0
  203. package/tools/visual_som_helper.py +3 -0
  204. package/tools/watch_mode.py +4 -4
  205. package/tools/wcag_audit.py +3 -0
  206. package/tools/welcome_page.py +2 -2
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "schema_version": "1.0.0",
3
- "updated_at": "2026-11-13T16:17:55.180336+00:00",
4
- "total_tools": 121,
5
- "stable_count": 121,
3
+ "updated_at": "2026-11-15T03:21:02.088778+00:00",
4
+ "total_tools": 125,
5
+ "stable_count": 125,
6
6
  "experimental_count": 0,
7
7
  "tools": [
8
8
  {
@@ -375,6 +375,21 @@
375
375
  ],
376
376
  "description": "Cross-Platform Token & Cost Auditor (Synapse-Hub)"
377
377
  },
378
+ {
379
+ "file": "tools/coverage_reporter.py",
380
+ "command": "python tools/coverage_reporter.py",
381
+ "category": "Auxiliary Utilities",
382
+ "owner_role": "orchestrator",
383
+ "status": "stable",
384
+ "risk_level": "read_only",
385
+ "inputs": [
386
+ "CLI options"
387
+ ],
388
+ "outputs": [
389
+ "Artifacts / Telemetry"
390
+ ],
391
+ "description": "tools/coverage_reporter.py — Standardized Coverage Metrics & Roadmap Evaluator"
392
+ },
378
393
  {
379
394
  "file": "tools/create_mock_docx.py",
380
395
  "command": "python tools/create_mock_docx.py",
@@ -1427,6 +1442,21 @@
1427
1442
  ],
1428
1443
  "description": "Zero-command automated project bootstrap tailoring AI agent rules to the target stack."
1429
1444
  },
1445
+ {
1446
+ "file": "tools/skill_canonical_digest.py",
1447
+ "command": "python tools/skill_canonical_digest.py",
1448
+ "category": "Auxiliary Utilities",
1449
+ "owner_role": "orchestrator",
1450
+ "status": "stable",
1451
+ "risk_level": "read_only",
1452
+ "inputs": [
1453
+ "CLI options"
1454
+ ],
1455
+ "outputs": [
1456
+ "Artifacts / Telemetry"
1457
+ ],
1458
+ "description": "tools/skill_canonical_digest.py — Single Source of Truth for Skill Canonical Digest & Lockfile Integrity"
1459
+ },
1430
1460
  {
1431
1461
  "file": "tools/skill_collision_guard.py",
1432
1462
  "command": "python tools/skill_collision_guard.py",
@@ -1579,6 +1609,21 @@
1579
1609
  ],
1580
1610
  "description": "tools/sync_agent_rules.py — Synchronizes AGENTS.md single-source rules to all AI bridges"
1581
1611
  },
1612
+ {
1613
+ "file": "tools/sync_skills_manifest.py",
1614
+ "command": "python tools/sync_skills_manifest.py",
1615
+ "category": "Auxiliary Utilities",
1616
+ "owner_role": "orchestrator",
1617
+ "status": "stable",
1618
+ "risk_level": "read_only",
1619
+ "inputs": [
1620
+ "CLI options"
1621
+ ],
1622
+ "outputs": [
1623
+ "Artifacts / Telemetry"
1624
+ ],
1625
+ "description": "tools/sync_skills_manifest.py — Synchronize Skill Policies & Frontmatter into Manifest"
1626
+ },
1582
1627
  {
1583
1628
  "file": "tools/telemetry_correlator.py",
1584
1629
  "command": "python tools/telemetry_correlator.py",
@@ -1821,6 +1866,21 @@
1821
1866
  ],
1822
1867
  "description": "Pre-check validator for Groovy scripts and POM keywords in enterprise test suites."
1823
1868
  },
1869
+ {
1870
+ "file": "tools/validate_skills_schema.py",
1871
+ "command": "python tools/validate_skills_schema.py",
1872
+ "category": "Auxiliary Utilities",
1873
+ "owner_role": "orchestrator",
1874
+ "status": "stable",
1875
+ "risk_level": "read_only",
1876
+ "inputs": [
1877
+ "CLI options"
1878
+ ],
1879
+ "outputs": [
1880
+ "Artifacts / Telemetry"
1881
+ ],
1882
+ "description": "tools/validate_skills_schema.py — Standalone Skill Schema & Policy Validator"
1883
+ },
1824
1884
  {
1825
1885
  "file": "tools/verify_all.py",
1826
1886
  "command": "python tools/verify_all.py",
package/tools/__init__.py CHANGED
@@ -1,3 +1,6 @@
1
+ # SPDX-FileCopyrightText: © 2026 Thế Vị (@TeeVee98) <https://github.com/TeeVee98/Synapse-Hub>
2
+ # SPDX-License-Identifier: MIT
3
+
1
4
  """
2
5
  Synapse Hub — Enterprise AI Agent Quality Engineering & Automated Testing Tooling Suite.
3
6
  ========================================================================================
@@ -14,7 +17,7 @@ Domain Packages:
14
17
  - tools.mcp: Model Context Protocol servers (core QA and Excel manipulation).
15
18
  """
16
19
 
17
- __version__ = "4.1.3"
20
+ __version__ = "4.2.0"
18
21
  __author__ = "Thế Vị (@TeeVee98)"
19
22
 
20
23
  # Expose domain packages
@@ -1,4 +1,7 @@
1
1
  #!/usr/bin/env python3
2
+ # SPDX-FileCopyrightText: © 2026 Thế Vị (@TeeVee98) <https://github.com/TeeVee98/Synapse-Hub>
3
+ # SPDX-License-Identifier: MIT
4
+
2
5
  """
3
6
  ENTERPRISE AUTONOMOUS AGENT Canary & Mutation Testing Arena
4
7
  -------------------------------------------------------
@@ -1,4 +1,7 @@
1
1
  #!/usr/bin/env python3
2
+ # SPDX-FileCopyrightText: © 2026 Thế Vị (@TeeVee98) <https://github.com/TeeVee98/Synapse-Hub>
3
+ # SPDX-License-Identifier: MIT
4
+
2
5
  """
3
6
  Enterprise QA Project Analyzer & Intelligence Aggregator
4
7
  ---------------------------------------------------------
@@ -1,4 +1,7 @@
1
1
  #!/usr/bin/env python3
2
+ # SPDX-FileCopyrightText: © 2026 Thế Vị (@TeeVee98) <https://github.com/TeeVee98/Synapse-Hub>
3
+ # SPDX-License-Identifier: MIT
4
+
2
5
  """
3
6
  Enterprise API Contract Drift & Breaking Change Sentinel
4
7
  ---------------------------------------------------------
@@ -1,4 +1,7 @@
1
1
  #!/usr/bin/env python3
2
+ # SPDX-FileCopyrightText: © 2026 Thế Vị (@TeeVee98) <https://github.com/TeeVee98/Synapse-Hub>
3
+ # SPDX-License-Identifier: MIT
4
+
2
5
  # -*- coding: utf-8 -*-
3
6
  """
4
7
  Enterprise Autonomous API Fuzzing & Chaos Breaker
@@ -26,6 +29,13 @@ import urllib.parse
26
29
  import argparse
27
30
  from typing import Dict, Any, List, Optional
28
31
 
32
+ from pentest_scope_guard import (
33
+ PentestScopeGuard,
34
+ PentestRateLimiter,
35
+ PentestScopeError,
36
+ mask_secrets,
37
+ )
38
+
29
39
  # Enforce UTF-8 stdout encoding for Windows/macOS/Linux compatibility
30
40
  if hasattr(sys.stdout, 'reconfigure'):
31
41
  try:
@@ -70,6 +80,8 @@ ALARM_SEVERITY = {
70
80
  "SLA_TIMEOUT": "LOW",
71
81
  "AUTH_BYPASS": "CRITICAL",
72
82
  "CONNECTION_ERROR": "MEDIUM",
83
+ "DANGEROUS_REDIRECT_BLOCKED": "CRITICAL",
84
+ "SCOPE_BLOCKED": "CRITICAL",
73
85
  }
74
86
  SEVERITY_LEVELS = ["INFO", "LOW", "MEDIUM", "HIGH", "CRITICAL"]
75
87
 
@@ -100,7 +112,13 @@ class ApiFuzzer:
100
112
  timeout_sec: float = 10.0,
101
113
  sla_ms: float = 3000.0,
102
114
  verify_ssl: bool = True,
103
- insecure: bool = False
115
+ insecure: bool = False,
116
+ scope_guard: Optional[PentestScopeGuard] = None,
117
+ rate_limiter: Optional[PentestRateLimiter] = None,
118
+ max_requests: int = 500,
119
+ allow_internal: bool = False,
120
+ allow_loopback: bool = True,
121
+ consent: Any = False,
104
122
  ):
105
123
  self.base_url = base_url.rstrip("/")
106
124
  self.spec_path = spec_path_or_url
@@ -109,27 +127,15 @@ class ApiFuzzer:
109
127
  self.sla_ms = sla_ms
110
128
  self.insecure = insecure or (not verify_ssl)
111
129
  self.verify_ssl = not self.insecure
130
+ self.max_requests = max(1, int(max_requests))
131
+ self.consent = consent
112
132
 
113
- # Environment Allowlist Guard (F2 Safety Discipline)
114
- # Prevents accidental fuzzing or stress bombardment against production environments
115
- parsed = urllib.parse.urlparse(self.base_url)
116
- host = (parsed.hostname or "").lower().strip()
117
- is_safe_env = self._is_safe_non_prod_host(host)
118
- allowed_hosts = {
119
- h.strip().lower() for h in os.environ.get("SYNAPSE_ALLOW_PROD_HOSTS", "").split(",") if h.strip()
120
- }
121
- is_host_specifically_allowed = host in allowed_hosts
122
- global_override = os.environ.get("SYNAPSE_ALLOW_PROD_FUZZ") in ("1", "true", "TRUE")
123
-
124
- if host and not is_safe_env and not (is_host_specifically_allowed or global_override):
125
- raise PermissionError(
126
- f"[SAFETY FIREWALL - REJECTED] Target host '{host}' is not in the allowed non-production environment allowlist "
127
- "(localhost, private IP, .local/.internal, or verified dev/staging/qa/test subdomain). "
128
- f"To authorize this host specifically, set SYNAPSE_ALLOW_PROD_HOSTS='{host}' or SYNAPSE_ALLOW_PROD_FUZZ=1 if authorized."
129
- )
130
- if host and not is_safe_env and global_override and not is_host_specifically_allowed:
131
- print(f" ⚠️ [SECURITY WARNING] SYNAPSE_ALLOW_PROD_FUZZ=1 global override active for host '{host}'. "
132
- f"Prefer setting SYNAPSE_ALLOW_PROD_HOSTS='{host}' for host-scoped permission.")
133
+ # Wire unified scope guard and rate limiter (narrow loopback opt-in for local test harnesses)
134
+ self.scope_guard = scope_guard or PentestScopeGuard(
135
+ allow_internal=allow_internal,
136
+ allow_loopback=allow_loopback
137
+ )
138
+ self.rate_limiter = rate_limiter or self.scope_guard.rate_limiter
133
139
 
134
140
  # Prepare SSL context (support self-signed staging certificates via explicit --insecure flag)
135
141
  self.ssl_context = ssl.create_default_context()
@@ -138,90 +144,28 @@ class ApiFuzzer:
138
144
  self.ssl_context.check_hostname = False
139
145
  self.ssl_context.verify_mode = ssl.CERT_NONE
140
146
 
147
+ # Hardened transport opener with SafeRedirectHandler
148
+ self.opener = self.scope_guard.create_safe_opener(
149
+ timeout_sec=self.timeout_sec,
150
+ ssl_context=self.ssl_context
151
+ )
152
+
153
+ # Validate target base_url before proceeding (Fail-closed)
154
+ ok, reason = self.scope_guard.validate_target(self.base_url, actor="ApiFuzzer.__init__")
155
+ if not ok:
156
+ raise PermissionError(
157
+ f"[SAFETY FIREWALL - REJECTED] Target base URL '{self.base_url}' is not permitted by pentest scope guard: {reason}"
158
+ )
159
+
141
160
  @staticmethod
142
161
  def _is_safe_non_prod_host(host: str) -> bool:
143
162
  """
144
- Validates whether a hostname strictly belongs to a local, private, or non-production environment.
145
- Prevents substring false positives on production domains like 'devex.com', 'contest.gov', or 'attestation-bank.com'.
163
+ Deprecated: Replaced by PentestScopeGuard. Enforces strict allowlist validation
164
+ without loose subdomain heuristics.
146
165
  """
147
- if not host:
148
- return False
149
-
150
- host = host.lower().strip()
151
-
152
- # 0. User-specified explicit host allowlist via SYNAPSE_ALLOWED_HOSTS
153
- allowed_env = os.environ.get("SYNAPSE_ALLOWED_HOSTS", "").strip()
154
- if allowed_env:
155
- for item in allowed_env.split(","):
156
- pattern = item.strip().lower()
157
- if pattern:
158
- if pattern.startswith("*.") and (host.endswith(pattern[1:]) or host == pattern[2:]):
159
- return True
160
- if host == pattern:
161
- return True
162
-
163
- # 1. Exact loopback / special names
164
- if host in ("localhost", "127.0.0.1", "::1", "0.0.0.0"): # nosec B104
165
- return True
166
-
167
- # 2. Check IP address (loopback or private RFC 1918, disallowing link-local metadata like 169.254.169.254)
168
- try:
169
- import ipaddress
170
- ip = ipaddress.ip_address(host)
171
- if ip.is_link_local or ip in ipaddress.ip_network("169.254.0.0/16"):
172
- return False
173
- return ip.is_loopback or ip.is_private
174
- except ValueError:
175
- ip = None # host is a domain name, not an IP literal
176
-
177
- # 2b. DNS resolution check (anti-SSRF / DNS rebinding against cloud metadata 169.254.0.0/16)
178
- try:
179
- import socket
180
- import ipaddress
181
- addr_info = socket.getaddrinfo(host, None, socket.AF_UNSPEC, socket.SOCK_STREAM)
182
- for _, _, _, _, sockaddr in addr_info:
183
- resolved_ip = ipaddress.ip_address(sockaddr[0])
184
- if resolved_ip.is_link_local or resolved_ip in ipaddress.ip_network("169.254.0.0/16"):
185
- return False
186
- except (socket.gaierror, OSError) as dns_err:
187
- # Offline test environment or unresolvable mock domain; fall through to lexical verification
188
- _dns_unresolved = str(dns_err)
189
-
190
- # 3. Special-use TLDs (RFC 6761 / RFC 2606)
191
- if any(host.endswith(tld) for tld in (".local", ".localhost", ".internal", ".test")):
192
- return True
193
-
194
- labels = host.split('.')
195
-
196
- # 4. Reject production markers anywhere in hostname (e.g. prod-test.bank.com)
197
- if any(re.search(r'(?:^|[-_])(prod|production)(?:$|[-_])', lbl) for lbl in labels):
198
- return False
199
-
200
- # 5. Prevent domain spoofing (e.g. bank.com.test.evil.io where public TLD appears in subdomains)
201
- common_public_tlds = {
202
- 'com', 'org', 'net', 'edu', 'gov', 'mil', 'io', 'co', 'vn', 'uk', 'de',
203
- 'fr', 'jp', 'cn', 'ru', 'br', 'in', 'ca', 'au', 'info', 'biz'
204
- }
205
- if any(lbl in common_public_tlds for lbl in labels[:-2]):
206
- return False
207
-
208
- # 6. Apex domains (e.g. bank-test.com, test.com) cannot be assumed non-prod without explicit config
209
- if len(labels) < 3:
210
- return False
211
-
212
- # 7. Subdomain verification (must be in leading subdomains preceding the root domain)
213
- subdomain_labels = labels[:-2]
214
- safe_exact_tokens = {"dev", "development", "staging", "qa", "test", "sandbox", "uat", "local", "internal"}
215
- safe_sub_regex = re.compile(
216
- r"^(dev|development|staging|qa|test|sandbox|uat)(?:[-_][a-zA-Z0-9]+)*$|^(?:[a-zA-Z0-9]+[-_])+(dev|development|staging|qa|test|sandbox|uat)(?:[-_][a-zA-Z0-9]+)*$",
217
- re.IGNORECASE
218
- )
219
-
220
- for sub in subdomain_labels:
221
- if sub in safe_exact_tokens or safe_sub_regex.match(sub):
222
- return True
223
-
224
- return False
166
+ guard = PentestScopeGuard(allow_internal=True)
167
+ ok, _ = guard.validate_target(f"http://{host}")
168
+ return ok
225
169
 
226
170
  def load_spec(self) -> Dict[str, Any]:
227
171
  """Loads OpenAPI or Swagger specification from file or URL."""
@@ -253,10 +197,17 @@ class ApiFuzzer:
253
197
  }
254
198
 
255
199
  if self.spec_path.startswith(("http://", "https://")):
200
+ # Validate spec URL with scope guard before network dispatch
201
+ ok, reason = self.scope_guard.validate_target(self.spec_path, actor="ApiFuzzer.load_spec")
202
+ if not ok:
203
+ raise PermissionError(f"[PENTEST SCOPE GUARD] Disallowed OpenAPI spec URL '{self.spec_path}': {reason}")
256
204
  req = urllib.request.Request(self.spec_path, headers={"User-Agent": "AgentQA-Fuzzer/2.0"})
257
- with urllib.request.urlopen(req, context=self.ssl_context, timeout=10.0) as resp: # nosec B310
258
- raw = resp.read().decode("utf-8")
259
- return json.loads(raw)
205
+ try:
206
+ with self.opener.open(req, timeout=10.0) as resp:
207
+ raw = resp.read().decode("utf-8")
208
+ return json.loads(raw)
209
+ except PentestScopeError as pse:
210
+ raise PermissionError(f"[PENTEST SCOPE GUARD] Redirect blocked during load_spec: {pse}")
260
211
  else:
261
212
  if not os.path.exists(self.spec_path):
262
213
  raise FileNotFoundError(f"OpenAPI spec not found: {self.spec_path}")
@@ -429,7 +380,7 @@ class ApiFuzzer:
429
380
 
430
381
  return mutations
431
382
 
432
- def execute_request(self, mutation: Dict[str, Any], dry_run: bool = False) -> Dict[str, Any]:
383
+ def execute_request(self, mutation: Dict[str, Any], dry_run: bool = False, consent: Optional[Any] = None) -> Dict[str, Any]:
433
384
  """Dispatches HTTP mutation and evaluates the three-alarm Oracle."""
434
385
  url = f"{self.base_url}{mutation['path']}"
435
386
  method = mutation["method"]
@@ -442,7 +393,7 @@ class ApiFuzzer:
442
393
  return {
443
394
  "name": mutation["name"],
444
395
  "type": mutation["type"],
445
- "url": url,
396
+ "url": mask_secrets(url),
446
397
  "method": method,
447
398
  "status_code": 400 if mutation["type"] != "BASELINE" else 200,
448
399
  "duration_ms": 42.5,
@@ -452,6 +403,83 @@ class ApiFuzzer:
452
403
  "response_preview": '{"status": "handled_by_dry_run"}'
453
404
  }
454
405
 
406
+ # Consent verification: active live testing requires explicit consent before network dispatch
407
+ effective_consent = self.consent if consent is None else consent
408
+ if not self.scope_guard.verify_consent(effective_consent):
409
+ return {
410
+ "name": mutation.get("name", "unnamed"),
411
+ "type": mutation.get("type", "UNKNOWN"),
412
+ "url": mask_secrets(url),
413
+ "method": method,
414
+ "status_code": -5,
415
+ "duration_ms": 0.0,
416
+ "verdict": "FAIL",
417
+ "severity": "CRITICAL",
418
+ "alarms": ["CONSENT_REQUIRED: Active API request rejected. Explicit consent required (--confirm-pentest-scope, consent=True, or scoped consent dict)."],
419
+ "response_preview": "Active request blocked: missing consent."
420
+ }
421
+
422
+ # Scoped consent check: verify target, method, path if specified in consent dict
423
+ if isinstance(effective_consent, dict):
424
+ c_target = effective_consent.get("target") or effective_consent.get("base_url")
425
+ if c_target and not (url.startswith(c_target.rstrip("/")) or self.base_url == c_target.rstrip("/")):
426
+ return {
427
+ "name": mutation.get("name", "unnamed"),
428
+ "type": mutation.get("type", "UNKNOWN"),
429
+ "url": mask_secrets(url),
430
+ "method": method,
431
+ "status_code": -5,
432
+ "duration_ms": 0.0,
433
+ "verdict": "FAIL",
434
+ "severity": "CRITICAL",
435
+ "alarms": [f"CONSENT_MISMATCH: Scoped consent target '{c_target}' does not authorize target URL '{mask_secrets(url)}'."],
436
+ "response_preview": "Active request blocked: consent target mismatch."
437
+ }
438
+ c_method = effective_consent.get("method")
439
+ if c_method and c_method.upper() != method.upper():
440
+ return {
441
+ "name": mutation.get("name", "unnamed"),
442
+ "type": mutation.get("type", "UNKNOWN"),
443
+ "url": mask_secrets(url),
444
+ "method": method,
445
+ "status_code": -5,
446
+ "duration_ms": 0.0,
447
+ "verdict": "FAIL",
448
+ "severity": "CRITICAL",
449
+ "alarms": [f"CONSENT_MISMATCH: Scoped consent method '{c_method}' does not authorize mutation method '{method}'."],
450
+ "response_preview": "Active request blocked: consent method mismatch."
451
+ }
452
+ c_path = effective_consent.get("path")
453
+ if c_path and c_path != mutation.get("path"):
454
+ return {
455
+ "name": mutation.get("name", "unnamed"),
456
+ "type": mutation.get("type", "UNKNOWN"),
457
+ "url": mask_secrets(url),
458
+ "method": method,
459
+ "status_code": -5,
460
+ "duration_ms": 0.0,
461
+ "verdict": "FAIL",
462
+ "severity": "CRITICAL",
463
+ "alarms": [f"CONSENT_MISMATCH: Scoped consent path '{c_path}' does not authorize mutation path '{mutation.get('path')}'."],
464
+ "response_preview": "Active request blocked: consent path mismatch."
465
+ }
466
+
467
+ # Check target URL with PentestScopeGuard before network dispatch (Consent NEVER bypasses host scope guard)
468
+ ok, scope_reason = self.scope_guard.validate_target(url, actor="ApiFuzzer.execute_request")
469
+ if not ok:
470
+ return {
471
+ "name": mutation["name"],
472
+ "type": mutation["type"],
473
+ "url": mask_secrets(url),
474
+ "method": method,
475
+ "status_code": -3,
476
+ "duration_ms": 0.0,
477
+ "verdict": "FAIL",
478
+ "severity": "CRITICAL",
479
+ "alarms": [f"SCOPE_BLOCKED: Request target blocked by pentest scope guard: {scope_reason}"],
480
+ "response_preview": mask_secrets(scope_reason)
481
+ }
482
+
455
483
  req = urllib.request.Request(
456
484
  url=url,
457
485
  data=body_data,
@@ -463,11 +491,16 @@ class ApiFuzzer:
463
491
  status_code = 0
464
492
  response_body = ""
465
493
  duration_ms = 0.0
494
+ redirect_blocked = False
466
495
 
467
496
  try:
468
- with urllib.request.urlopen(req, context=self.ssl_context, timeout=self.timeout_sec) as resp: # nosec B310
497
+ with self.opener.open(req, timeout=self.timeout_sec) as resp:
469
498
  status_code = resp.getcode()
470
499
  response_body = resp.read().decode("utf-8", errors="replace")
500
+ except PentestScopeError as pse:
501
+ status_code = -4
502
+ response_body = str(pse)
503
+ redirect_blocked = True
471
504
  except urllib.error.HTTPError as he:
472
505
  status_code = he.code
473
506
  try:
@@ -488,6 +521,9 @@ class ApiFuzzer:
488
521
  # ----------------------------------------------------
489
522
  alarms = []
490
523
 
524
+ if redirect_blocked:
525
+ alarms.append(f"DANGEROUS_REDIRECT_BLOCKED: {response_body}")
526
+
491
527
  # Alarm 1: HTTP 500 / 502 / 503 Internal Server Error
492
528
  if status_code in (500, 502, 503):
493
529
  alarms.append(f"HTTP_{status_code}_SERVER_CRASH: Unhandled backend exception / server panic")
@@ -509,7 +545,7 @@ class ApiFuzzer:
509
545
 
510
546
  # Alarm 5: Target unreachable - an endpoint that could not be tested
511
547
  # must NEVER be reported as PASS (Truth Anchor discipline).
512
- if status_code < 0:
548
+ if status_code < 0 and not redirect_blocked:
513
549
  alarms.append("CONNECTION_ERROR: Target unreachable or transport failure - endpoint could not be verified")
514
550
 
515
551
  verdict = "FAIL" if alarms else "PASS"
@@ -523,18 +559,27 @@ class ApiFuzzer:
523
559
  return {
524
560
  "name": mutation["name"],
525
561
  "type": mutation["type"],
526
- "url": url,
562
+ "url": mask_secrets(url),
527
563
  "method": method,
528
564
  "status_code": status_code,
529
565
  "duration_ms": duration_ms,
530
566
  "verdict": verdict,
531
567
  "severity": severity,
532
568
  "alarms": alarms,
533
- "response_preview": response_body[:300]
569
+ "response_preview": mask_secrets(response_body[:300])
534
570
  }
535
571
 
536
- def run_fuzz_suite(self, dry_run: bool = False) -> Dict[str, Any]:
572
+ def run_fuzz_suite(self, dry_run: bool = False, consent: Any = False) -> Dict[str, Any]:
537
573
  """Runs the complete fuzzing suite against all extracted targets."""
574
+ # Consent validation: active live testing requires explicit consent
575
+ if not dry_run:
576
+ has_consent = self.scope_guard.verify_consent(consent)
577
+ if not has_consent:
578
+ raise PermissionError(
579
+ "Active API fuzzing requires explicit consent. Set PENTEST_CONSENT_ACKNOWLEDGED=1, "
580
+ "pass --confirm-pentest-scope, or set dry_run=True to preview safely."
581
+ )
582
+
538
583
  spec = self.load_spec()
539
584
  targets = self.extract_fuzz_targets(spec)
540
585
 
@@ -542,23 +587,36 @@ class ApiFuzzer:
542
587
  for t in targets:
543
588
  all_mutations.extend(self.generate_mutations(t))
544
589
 
590
+ total_generated = len(all_mutations)
591
+ volume_capped = False
592
+ if len(all_mutations) > self.max_requests:
593
+ all_mutations = all_mutations[:self.max_requests]
594
+ volume_capped = True
595
+
545
596
  results = []
546
597
  total_failures = 0
547
598
 
548
599
  print(f"\n{BOLD}{CYAN}======================================================================{RESET}")
549
600
  print(f"{BOLD}{CYAN} ENTERPRISE AUTONOMOUS API FUZZING & CHAOS BREAKER {RESET}")
550
601
  print(f"{BOLD}{CYAN}======================================================================{RESET}")
551
- print(f" Target Base URL : {self.base_url}")
552
- print(f" Spec Source : {self.spec_path or 'Default Archetype'}")
602
+ print(f" Target Base URL : {mask_secrets(self.base_url)}")
603
+ print(f" Spec Source : {mask_secrets(self.spec_path or 'Default Archetype')}")
553
604
  print(f" Total Endpoints : {len(targets)}")
554
- print(f" Total Mutations : {len(all_mutations)}")
605
+ print(f" Total Mutations : {len(all_mutations)} (capped from {total_generated})" if volume_capped else f" Total Mutations : {len(all_mutations)}")
555
606
  print(f" SLA Threshold : {self.sla_ms} ms")
607
+ print(f" Rate Limit Max : {self.rate_limiter.max_req_per_sec} req/s")
556
608
  print(f" Mode : {'DRY-RUN (Air-Gapped / Deterministic)' if dry_run else 'LIVE STAGING ATTACK'}\n")
557
609
 
558
610
  for idx, m in enumerate(all_mutations, start=1):
559
- res = self.execute_request(m, dry_run=dry_run)
611
+ if not dry_run:
612
+ self.rate_limiter.acquire()
613
+
614
+ res = self.execute_request(m, dry_run=dry_run, consent=consent if not dry_run else None)
560
615
  results.append(res)
561
616
 
617
+ if not dry_run and res["status_code"] > 0:
618
+ self.rate_limiter.record_response(res["status_code"])
619
+
562
620
  status_str = f"{GREEN}PASS{RESET}" if res["verdict"] == "PASS" else f"{RED}ALARM{RESET}"
563
621
  sys.stdout.write(f" [{idx:03d}/{len(all_mutations):03d}] {status_str} | HTTP {res['status_code']} ({res['duration_ms']}ms) | {m['name']}\n")
564
622
  if res["alarms"]:
@@ -567,10 +625,13 @@ class ApiFuzzer:
567
625
  print(f" 👉 {RED}{BOLD}[DEFECT]{RESET} {alarm}")
568
626
 
569
627
  scorecard = {
570
- "base_url": self.base_url,
628
+ "base_url": mask_secrets(self.base_url),
571
629
  "timestamp": time.strftime("%Y-%m-%d %H:%M:%S"),
572
630
  "mode": "ACTIVE",
573
631
  "total_mutations": len(all_mutations),
632
+ "total_generated": total_generated,
633
+ "volume_capped": volume_capped,
634
+ "max_requests": self.max_requests,
574
635
  "passed": len(all_mutations) - total_failures,
575
636
  "failed": total_failures,
576
637
  "sla_ms": self.sla_ms,
@@ -724,6 +785,8 @@ def main():
724
785
  help="active = live fuzzing (default); passive = offline spec audit, zero traffic")
725
786
  parser.add_argument("--insecure", action="store_true", help="Explicitly bypass TLS certificate verification (for staging/self-signed certs)")
726
787
  parser.add_argument("--dry-run", action="store_true", help="Simulate mutation generation without live requests")
788
+ parser.add_argument("--max-requests", type=int, default=500, help="Max requests volume ceiling (default: 500)")
789
+ parser.add_argument("--confirm-pentest-scope", action="store_true", help="Explicit human consent acknowledgement for live fuzzing")
727
790
  parser.add_argument("--json", action="store_true", help="Output summary in JSON format")
728
791
 
729
792
  args = parser.parse_args()
@@ -737,7 +800,8 @@ def main():
737
800
  spec_path_or_url=args.spec,
738
801
  headers=headers,
739
802
  sla_ms=args.sla_ms,
740
- insecure=args.insecure
803
+ insecure=args.insecure,
804
+ max_requests=args.max_requests
741
805
  )
742
806
 
743
807
  if args.mode == "passive":
@@ -748,7 +812,7 @@ def main():
748
812
  blocking = int(severity_dict.get("HIGH", 0)) + int(severity_dict.get("CRITICAL", 0))
749
813
  return 1 if blocking > 0 else 0
750
814
 
751
- scorecard = fuzzer.run_fuzz_suite(dry_run=args.dry_run)
815
+ scorecard = fuzzer.run_fuzz_suite(dry_run=args.dry_run, consent=args.confirm_pentest_scope)
752
816
  if args.json:
753
817
  print(json.dumps(scorecard, indent=2))
754
818
 
@@ -96,7 +96,8 @@ class ASTValidationCache:
96
96
  self._entries = current_entries
97
97
  self._dirty = False
98
98
  except Exception as err:
99
- _ = err
99
+ import logging
100
+ logging.getLogger("ast_cache").debug("Failed to load ast cache: %s", err)
100
101
 
101
102
  def get_signature(self, file_path: str) -> Optional[Tuple[int, int]]:
102
103
  """Returns (mtime_ns, size) for fast freshness check."""
@@ -137,7 +138,8 @@ class ASTValidationCache:
137
138
  try:
138
139
  locked_json_write(self.cache_path, payload, indent=2, timeout=5.0, atomic=True)
139
140
  except Exception as err:
140
- _ = err
141
+ import logging
142
+ logging.getLogger("ast_cache").debug("Failed to load ast cache: %s", err)
141
143
 
142
144
 
143
145
  # Module-level singleton helper