@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
@@ -30,20 +30,70 @@ import json
30
30
  import socket
31
31
  import ipaddress
32
32
  import urllib.parse
33
+ import urllib.request
34
+ import urllib.error
35
+ import http.client
36
+ import ssl
37
+ import uuid
33
38
  from datetime import datetime, timezone
34
- from typing import List, Tuple, Optional
39
+ from typing import List, Tuple, Optional, Set, Any, Dict
35
40
 
36
41
  # Enforce UTF-8 stdout encoding for Windows console compatibility
37
42
  if hasattr(sys.stdout, "reconfigure"):
38
43
  try:
39
44
  sys.stdout.reconfigure(encoding="utf-8")
40
45
  sys.stderr.reconfigure(encoding="utf-8")
41
- except Exception as exc:
42
- _ = exc
46
+ except Exception:
47
+ pass
43
48
 
44
49
  REPO_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
45
50
  DEFAULT_AUDIT_LOG = os.path.join(REPO_ROOT, ".synapse", "pentest_audit.log")
46
51
 
52
+ # Sensitive infrastructure ports that must NEVER be targeted (SSRF prevention)
53
+ SENSITIVE_INFRASTRUCTURE_PORTS: Set[int] = {
54
+ 20, 21, # FTP
55
+ 22, # SSH
56
+ 23, # Telnet
57
+ 25, # SMTP
58
+ 53, # DNS
59
+ 69, # TFTP
60
+ 79, # Finger
61
+ 110, # POP3
62
+ 137, 138, 139, # NetBIOS
63
+ 143, # IMAP
64
+ 445, # SMB
65
+ 3306, # MySQL
66
+ 3389, # RDP
67
+ 5432, # PostgreSQL
68
+ 6379, # Redis
69
+ 11211, # Memcached
70
+ 27017, # MongoDB
71
+ }
72
+
73
+ ALLOWED_SCHEMES: Set[str] = {"http", "https"}
74
+
75
+ # Regex patterns for masking credentials, tokens, and authorization secrets
76
+ SECRET_PARAM_PATTERNS = [
77
+ # Basic auth passwords in URLs: http://user:pass@host -> http://user:***REDACTED***@host
78
+ (re.compile(r"(://[^:]+:)([^@]+)(@)"), r"\g<1>***REDACTED***\g<3>"),
79
+ # Sensitive query parameters: token, key, secret, password, bearer, auth, etc.
80
+ (re.compile(r"([?&](?:token|key|api_key|apikey|secret|password|passwd|pwd|bearer|auth|sessionid|access_token)=)[^&]*", re.IGNORECASE), r"\g<1>***REDACTED***"),
81
+ # Authorization header Bearer tokens: Bearer xyz -> Bearer ***REDACTED***
82
+ (re.compile(r"(Bearer\s+)[A-Za-z0-9_\-\.]+", re.IGNORECASE), r"\g<1>***REDACTED***"),
83
+ # JSON / key-value fields: "password": "...", "token": "..."
84
+ (re.compile(r'("?(?:password|token|secret|apiKey|api_key|access_token)"?\s*[:=]\s*)"[^"]*"', re.IGNORECASE), r'\g<1>"***REDACTED***"'),
85
+ ]
86
+
87
+
88
+ def mask_secrets(text: str) -> str:
89
+ """Redacts passwords, tokens, API keys, and sensitive auth data using regex."""
90
+ if not text or not isinstance(text, str):
91
+ return text
92
+ masked = text
93
+ for pattern, replacement in SECRET_PARAM_PATTERNS:
94
+ masked = pattern.sub(replacement, masked)
95
+ return masked
96
+
47
97
  # Keywords in hostnames strictly treated as production targets
48
98
  PRODUCTION_HOST_PATTERNS = [
49
99
  r"^prod\.",
@@ -110,6 +160,140 @@ class PentestRateLimiter:
110
160
  self.consecutive_errors = 0
111
161
 
112
162
 
163
+ class SafeRedirectHandler(urllib.request.HTTPRedirectHandler):
164
+ """
165
+ Subclass of urllib.request.HTTPRedirectHandler that intercepts 301, 302, 303, 307, 308
166
+ redirects and verifies redirect targets with PentestScopeGuard before following.
167
+ Blocks SSRF, loop escapes, and redirects to cloud metadata / restricted IP subnets.
168
+ """
169
+
170
+ def __init__(self, scope_guard: Optional[PentestScopeGuard] = None, max_redirects: int = 5):
171
+ super().__init__()
172
+ self.scope_guard = scope_guard or PentestScopeGuard()
173
+ self.max_redirects = max_redirects
174
+
175
+ def redirect_request(self, req, fp, code, msg, headers, newurl):
176
+ count = getattr(req, "_safe_redirect_count", 0) + 1
177
+ if count > self.max_redirects:
178
+ raise PentestScopeError(
179
+ f"MAX_REDIRECTS_EXCEEDED: Exceeded maximum allowed redirects ({self.max_redirects})."
180
+ )
181
+
182
+ origin_url = req.full_url
183
+ absolute_target = urllib.parse.urljoin(origin_url, newurl)
184
+
185
+ is_valid, reason = self.scope_guard.validate_redirect(origin_url, absolute_target)
186
+ if not is_valid:
187
+ raise PentestScopeError(f"DANGEROUS_REDIRECT_BLOCKED: {reason}")
188
+
189
+ new_req = super().redirect_request(req, fp, code, msg, headers, absolute_target)
190
+ if new_req is not None:
191
+ new_req._safe_redirect_count = count
192
+ return new_req
193
+
194
+ def http_error_301(self, req, fp, code, msg, headers):
195
+ return super().http_error_301(req, fp, code, msg, headers)
196
+
197
+ def http_error_302(self, req, fp, code, msg, headers):
198
+ return super().http_error_302(req, fp, code, msg, headers)
199
+
200
+ def http_error_303(self, req, fp, code, msg, headers):
201
+ return super().http_error_303(req, fp, code, msg, headers)
202
+
203
+ def http_error_307(self, req, fp, code, msg, headers):
204
+ return super().http_error_307(req, fp, code, msg, headers)
205
+
206
+ def http_error_308(self, req, fp, code, msg, headers):
207
+ return super().http_error_308(req, fp, code, msg, headers)
208
+
209
+
210
+ class PinnedHTTPConnection(http.client.HTTPConnection):
211
+ """HTTPConnection that connects strictly to the validated IP to defeat DNS rebinding TOCTOU."""
212
+
213
+ def __init__(self, host: str, port: Optional[int] = None, pinned_ip: Optional[str] = None, **kwargs):
214
+ super().__init__(host, port, **kwargs)
215
+ self._pinned_ip = pinned_ip
216
+
217
+ def connect(self) -> None:
218
+ target_addr = self._pinned_ip if self._pinned_ip else self.host
219
+ self.sock = socket.create_connection(
220
+ (target_addr, self.port),
221
+ self.timeout,
222
+ self.source_address
223
+ )
224
+
225
+
226
+ class PinnedHTTPSConnection(http.client.HTTPSConnection):
227
+ """HTTPSConnection that connects strictly to the validated IP while preserving SNI / host headers."""
228
+
229
+ def __init__(self, host: str, port: Optional[int] = None, pinned_ip: Optional[str] = None, **kwargs):
230
+ super().__init__(host, port, **kwargs)
231
+ self._pinned_ip = pinned_ip
232
+
233
+ def connect(self) -> None:
234
+ target_addr = self._pinned_ip if self._pinned_ip else self.host
235
+ sock = socket.create_connection(
236
+ (target_addr, self.port),
237
+ self.timeout,
238
+ self.source_address
239
+ )
240
+ server_hostname = self.host.split(":")[0] if self.host else target_addr
241
+ if self._context:
242
+ self.sock = self._context.wrap_socket(sock, server_hostname=server_hostname)
243
+ else:
244
+ self.sock = sock
245
+
246
+
247
+ class PinnedHTTPHandler(urllib.request.HTTPHandler):
248
+ """Urllib HTTP handler enforcing socket-level connection to pre-validated pinned IPs."""
249
+
250
+ def __init__(self, scope_guard: Optional[PentestScopeGuard] = None):
251
+ super().__init__()
252
+ self.scope_guard = scope_guard
253
+
254
+ def http_open(self, req: urllib.request.Request):
255
+ def connection_factory(host: str, **kwargs):
256
+ clean_host = host.split(":")[0]
257
+ pinned_ip = self.scope_guard.get_pinned_ip(clean_host) if self.scope_guard else None
258
+ return PinnedHTTPConnection(host, pinned_ip=pinned_ip, **kwargs)
259
+ return self.do_open(connection_factory, req)
260
+
261
+
262
+ class PinnedHTTPSHandler(urllib.request.HTTPSHandler):
263
+ """Urllib HTTPS handler enforcing socket-level connection to pre-validated pinned IPs."""
264
+
265
+ def __init__(self, scope_guard: Optional[PentestScopeGuard] = None, context: Optional[ssl.SSLContext] = None):
266
+ super().__init__(context=context)
267
+ self.scope_guard = scope_guard
268
+
269
+ def https_open(self, req: urllib.request.Request):
270
+ def connection_factory(host: str, **kwargs):
271
+ clean_host = host.split(":")[0]
272
+ pinned_ip = self.scope_guard.get_pinned_ip(clean_host) if self.scope_guard else None
273
+ if self._context:
274
+ kwargs["context"] = self._context
275
+ return PinnedHTTPSConnection(host, pinned_ip=pinned_ip, **kwargs)
276
+ return self.do_open(connection_factory, req)
277
+
278
+
279
+ def create_safe_opener(
280
+ scope_guard: Optional[PentestScopeGuard] = None,
281
+ timeout_sec: float = 10.0,
282
+ ssl_context: Optional[ssl.SSLContext] = None,
283
+ max_redirects: int = 5
284
+ ) -> urllib.request.OpenerDirector:
285
+ """Creates a urllib OpenerDirector hardened with SafeRedirectHandler and PinnedConnection handlers."""
286
+ guard = scope_guard or PentestScopeGuard()
287
+ redirect_handler = SafeRedirectHandler(scope_guard=guard, max_redirects=max_redirects)
288
+ handlers: List[Any] = [
289
+ redirect_handler,
290
+ PinnedHTTPHandler(scope_guard=guard),
291
+ PinnedHTTPSHandler(scope_guard=guard, context=ssl_context),
292
+ ]
293
+ opener = urllib.request.build_opener(*handlers)
294
+ return opener
295
+
296
+
113
297
  class PentestScopeGuard:
114
298
  """
115
299
  Enforces Layer 1 & 2 security invariants on all active pentest/DAST commands.
@@ -119,26 +303,43 @@ class PentestScopeGuard:
119
303
  self,
120
304
  allowed_hosts: Optional[List[str]] = None,
121
305
  allow_internal: bool = False,
306
+ allow_loopback: Optional[bool] = None,
307
+ allow_private_subnets: bool = False,
122
308
  audit_log_path: Optional[str] = None,
123
309
  rate_limiter: Optional[PentestRateLimiter] = None
124
310
  ):
125
311
  self.allow_internal = allow_internal
312
+ # Narrow opt-in: loopback (localhost / 127.0.0.1 / ::1) is permitted when allow_loopback=True or allow_internal=True
313
+ self.allow_loopback = allow_loopback if allow_loopback is not None else allow_internal
314
+ # RFC1918 Private subnets require explicit authorization policy (SYNAPSE_ALLOW_PRIVATE_SUBNETS=1 or allow_private_subnets=True)
315
+ self.allow_private_subnets = allow_private_subnets or (
316
+ os.environ.get("SYNAPSE_ALLOW_PRIVATE_SUBNETS", "").strip().lower() in ("1", "true", "yes")
317
+ )
126
318
  self.audit_log_path = audit_log_path or DEFAULT_AUDIT_LOG
127
319
  self.rate_limiter = rate_limiter or PentestRateLimiter()
320
+ self._pinned_ips: Dict[str, str] = {}
128
321
 
129
- # Parse allowlist from parameter or environment
130
322
  hosts = set()
131
- if allowed_hosts:
132
- hosts.update([h.strip().lower() for h in allowed_hosts if h.strip()])
133
- env_allowed = os.environ.get("ALLOWED_PENTEST_HOSTS", "").strip()
134
- if env_allowed:
135
- hosts.update([h.strip().lower() for h in env_allowed.split(",") if h.strip()])
136
- # Also inspect synapse.config.json if available
137
- cfg_hosts = self._load_config_allowed_hosts()
138
- hosts.update(cfg_hosts)
323
+ if allowed_hosts is not None:
324
+ hosts.update([h.strip().lower().strip("[]") for h in allowed_hosts if h.strip()])
325
+ else:
326
+ for env_var in ("ALLOWED_PENTEST_HOSTS", "SYNAPSE_ALLOWED_HOSTS"):
327
+ env_allowed = os.environ.get(env_var, "").strip()
328
+ if env_allowed:
329
+ hosts.update([h.strip().lower().strip("[]") for h in env_allowed.split(",") if h.strip()])
330
+ cfg_hosts = self._load_config_allowed_hosts()
331
+ hosts.update(cfg_hosts)
139
332
 
140
333
  self.allowed_hosts = hosts
141
334
 
335
+ def get_pinned_ip(self, hostname: str) -> Optional[str]:
336
+ """Returns the pre-validated pinned IP for hostname to prevent DNS rebinding TOCTOU."""
337
+ return self._pinned_ips.get(hostname.lower().strip().strip("[]"))
338
+
339
+ def pin_ip(self, hostname: str, ip: str) -> None:
340
+ """Explicitly pins a validated IP for a hostname."""
341
+ self._pinned_ips[hostname.lower().strip().strip("[]")] = ip
342
+
142
343
  def _load_config_allowed_hosts(self) -> List[str]:
143
344
  cfg_path = os.path.join(REPO_ROOT, "synapse.config.json")
144
345
  if not os.path.isfile(cfg_path):
@@ -146,22 +347,51 @@ class PentestScopeGuard:
146
347
  try:
147
348
  with open(cfg_path, "r", encoding="utf-8") as f:
148
349
  data = json.load(f)
149
- return [h.strip().lower() for h in data.get("security", {}).get("allowed_pentest_hosts", []) if h.strip()]
350
+ return [h.strip().lower().strip("[]") for h in data.get("security", {}).get("allowed_pentest_hosts", []) if h.strip()]
150
351
  except Exception:
151
352
  return []
152
353
 
153
- def _is_ip_private_or_restricted(self, ip_str: str) -> Tuple[bool, str]:
354
+ def _is_ip_private_or_restricted(
355
+ self,
356
+ ip_str: str,
357
+ allow_internal: Optional[bool] = None,
358
+ allow_loopback: Optional[bool] = None,
359
+ allow_private_subnets: Optional[bool] = None
360
+ ) -> Tuple[bool, str]:
154
361
  """Checks if IP belongs to private, loopback, link-local, or cloud metadata."""
362
+ effective_internal = self.allow_internal if allow_internal is None else allow_internal
363
+ effective_loopback = self.allow_loopback if allow_loopback is None else allow_loopback
364
+ if effective_internal:
365
+ effective_loopback = True
366
+
367
+ effective_private = self.allow_private_subnets if allow_private_subnets is None else allow_private_subnets
368
+
369
+ clean_ip = ip_str.strip().lower().strip("[]")
155
370
  try:
156
- ip_obj = ipaddress.ip_address(ip_str)
157
- if ip_str == "169.254.169.254":
158
- return True, "AWS/Cloud Instance Metadata Service (169.254.169.254)"
371
+ ip_obj = ipaddress.ip_address(clean_ip)
372
+ # Unwrap IPv4-mapped IPv6 address (e.g. ::ffff:169.254.169.254)
373
+ if isinstance(ip_obj, ipaddress.IPv6Address) and ip_obj.ipv4_mapped:
374
+ ip_obj = ip_obj.ipv4_mapped
375
+
376
+ # Cloud Instance Metadata Service (AWS/GCP/Azure IMDS IPv4 & IPv6)
377
+ is_cloud_metadata = (
378
+ clean_ip in ("169.254.169.254", "fd00:ec2::254")
379
+ or (isinstance(ip_obj, ipaddress.IPv4Address) and ip_obj in ipaddress.ip_network("169.254.0.0/16"))
380
+ or (isinstance(ip_obj, ipaddress.IPv6Address) and str(ip_obj).lower().startswith("fd00:ec2::254"))
381
+ )
382
+ if is_cloud_metadata:
383
+ return True, f"AWS/Cloud Instance Metadata Service ({clean_ip})"
384
+
385
+ if ip_obj.is_link_local:
386
+ return True, f"Link-local subnet ({clean_ip})"
387
+
159
388
  if ip_obj.is_loopback:
160
- return not self.allow_internal, "Loopback interface (localhost / 127.0.0.1)"
389
+ return not effective_loopback, f"Loopback interface ({clean_ip})"
390
+
391
+ # RFC1918 Private subnet (narrow opt-in: blocked unless allow_private_subnets is explicitly enabled)
161
392
  if ip_obj.is_private:
162
- return not self.allow_internal, f"RFC1918 Private subnet ({ip_str})"
163
- if ip_obj.is_link_local:
164
- return True, f"Link-local subnet ({ip_str})"
393
+ return not effective_private, f"RFC1918 Private subnet ({clean_ip})"
394
+
165
395
  return False, "Public IP"
166
396
  except ValueError:
167
397
  return True, f"Malformed IP address: {ip_str}"
@@ -174,48 +404,85 @@ class PentestScopeGuard:
174
404
  return True
175
405
  return False
176
406
 
177
- def validate_target(self, target_url: str) -> Tuple[bool, str]:
407
+ def validate_target(
408
+ self,
409
+ target_url: str,
410
+ allow_internal: Optional[bool] = None,
411
+ actor: Optional[str] = None,
412
+ request_id: Optional[str] = None
413
+ ) -> Tuple[bool, str]:
178
414
  """
179
- Validates target URL against scope allowlist, production blocklist, and IP rules.
415
+ Validates target URL against scope allowlist, production blocklist, scheme/port,
416
+ and IP subnet rules with DNS rebinding protection.
180
417
  Fail-Closed: Defaults to False on any error or missing allowlist.
181
418
  """
419
+ req_id = request_id or str(uuid.uuid4())
420
+ act = actor or os.environ.get("SYNAPSE_AUDIT_ACTOR", "agent_executor")
421
+ effective_internal = self.allow_internal if allow_internal is None else allow_internal
422
+
182
423
  if not target_url or not target_url.strip():
183
424
  reason = "Target URL is empty or missing (Fail-closed default deny)."
184
- self._write_audit(target_url or "EMPTY", "N/A", False, reason)
425
+ self._write_audit(target_url or "EMPTY", "N/A", False, reason, actor=act, request_id=req_id)
185
426
  return False, reason
186
427
 
187
428
  clean_url = target_url.strip()
188
- if not clean_url.startswith(("http://", "https://")):
429
+ has_scheme = "://" in clean_url
430
+ if not has_scheme:
189
431
  clean_url = f"http://{clean_url}"
190
432
 
191
433
  try:
192
434
  parsed = urllib.parse.urlparse(clean_url)
193
435
  except Exception as e:
194
436
  reason = f"Malformed target URL '{target_url}': {e}"
195
- self._write_audit(target_url, "N/A", False, reason)
437
+ self._write_audit(target_url, "N/A", False, reason, actor=act, request_id=req_id)
438
+ return False, reason
439
+
440
+ # Scheme validation: Only http and https permitted
441
+ scheme = (parsed.scheme or "").lower()
442
+ if scheme not in ALLOWED_SCHEMES:
443
+ reason = f"DISALLOWED SCHEME: Scheme '{parsed.scheme}' is not permitted. Only 'http' and 'https' are allowed."
444
+ self._write_audit(target_url, "N/A", False, reason, actor=act, request_id=req_id)
196
445
  return False, reason
197
446
 
198
- hostname = (parsed.hostname or "").lower().strip()
447
+ # Port validation: Reject sensitive infrastructure ports
448
+ try:
449
+ port = parsed.port
450
+ except ValueError as pe:
451
+ reason = f"INVALID PORT: {pe}"
452
+ self._write_audit(target_url, "N/A", False, reason, actor=act, request_id=req_id)
453
+ return False, reason
454
+
455
+ if port is not None:
456
+ if port in SENSITIVE_INFRASTRUCTURE_PORTS:
457
+ reason = f"DISALLOWED PORT: Port {port} is a sensitive infrastructure port and cannot be targeted."
458
+ self._write_audit(target_url, "N/A", False, reason, actor=act, request_id=req_id)
459
+ return False, reason
460
+ if port <= 0 or port > 65535:
461
+ reason = f"INVALID PORT: Port {port} is outside valid range (1-65535)."
462
+ self._write_audit(target_url, "N/A", False, reason, actor=act, request_id=req_id)
463
+ return False, reason
464
+
465
+ hostname = (parsed.hostname or "").lower().strip().strip("[]")
199
466
  if not hostname:
200
467
  reason = f"Could not extract hostname from '{target_url}' (Fail-closed)."
201
- self._write_audit(target_url, "N/A", False, reason)
468
+ self._write_audit(target_url, "N/A", False, reason, actor=act, request_id=req_id)
202
469
  return False, reason
203
470
 
204
471
  # 1. Production pattern check
205
472
  if self.is_production_host(hostname) and hostname not in self.allowed_hosts:
206
473
  reason = f"CRITICAL PRODUCTION BLOCK: Target host '{hostname}' matches production naming pattern and is not explicitly in ALLOWED_PENTEST_HOSTS."
207
- self._write_audit(target_url, "N/A", False, reason)
474
+ self._write_audit(target_url, "N/A", False, reason, actor=act, request_id=req_id)
208
475
  return False, reason
209
476
 
210
477
  # 2. Allowlist containment check
211
478
  is_allowed = False
212
479
  if not self.allowed_hosts:
213
480
  # If no hosts allowlisted at all, only localhost is permitted if allow_internal is True
214
- if self.allow_internal and hostname in ("localhost", "127.0.0.1", "::1"):
481
+ if effective_internal and hostname in ("localhost", "127.0.0.1", "::1"):
215
482
  is_allowed = True
216
483
  else:
217
484
  reason = "ALLOWED_PENTEST_HOSTS is empty. All active pentest scans are disabled by default (Fail-closed)."
218
- self._write_audit(target_url, "N/A", False, reason)
485
+ self._write_audit(target_url, "N/A", False, reason, actor=act, request_id=req_id)
219
486
  return False, reason
220
487
  else:
221
488
  if hostname in self.allowed_hosts:
@@ -223,31 +490,68 @@ class PentestScopeGuard:
223
490
  else:
224
491
  # Check wildcard e.g. *.example.com
225
492
  for allowed in self.allowed_hosts:
226
- if allowed.startswith("*.") and hostname.endswith(allowed[1:]):
493
+ if allowed.startswith("*.") and (hostname.endswith(allowed[1:]) or hostname == allowed[2:]):
227
494
  is_allowed = True
228
495
  break
229
496
 
230
497
  if not is_allowed:
231
- reason = f"SCOPE REJECTED: Host '{hostname}' is not authorized in ALLOWED_PENTEST_HOSTS: {list(self.allowed_hosts)}."
232
- self._write_audit(target_url, "N/A", False, reason)
498
+ reason = f"SCOPE REJECTED: Host '{hostname}' is not authorized in ALLOWED_PENTEST_HOSTS: {sorted(list(self.allowed_hosts))}."
499
+ self._write_audit(target_url, "N/A", False, reason, actor=act, request_id=req_id)
233
500
  return False, reason
234
501
 
235
- # 3. DNS resolution & IP subnet safety check
502
+ # 3. DNS resolution & IP subnet safety check (anti-SSRF and DNS rebinding)
503
+ resolved_ips: List[str] = []
236
504
  try:
237
- resolved_ip = socket.gethostbyname(hostname)
238
- except socket.error as e:
239
- reason = f"DNS resolution failed for '{hostname}': {e} (Fail-closed)."
240
- self._write_audit(target_url, "UNRESOLVED", False, reason)
241
- return False, reason
505
+ ipaddress.ip_address(hostname)
506
+ resolved_ips = [hostname]
507
+ except ValueError:
508
+ # Domain name: query socket.gethostbyname first (compatible with unit test mocks)
509
+ try:
510
+ primary_ip = socket.gethostbyname(hostname)
511
+ resolved_ips.append(primary_ip)
512
+ except (socket.error, OSError) as e:
513
+ reason = f"DNS resolution failed for '{hostname}': {e} (Fail-closed)."
514
+ self._write_audit(target_url, "UNRESOLVED", False, reason, actor=act, request_id=req_id)
515
+ return False, reason
242
516
 
243
- restricted, ip_reason = self._is_ip_private_or_restricted(resolved_ip)
244
- if restricted:
245
- reason = f"IP SAFETY REJECTED: Host '{hostname}' resolved to restricted IP {resolved_ip} ({ip_reason})."
246
- self._write_audit(target_url, resolved_ip, False, reason)
247
- return False, reason
517
+ # Fail immediately if primary IP is restricted
518
+ restricted, ip_reason = self._is_ip_private_or_restricted(primary_ip, allow_internal=effective_internal)
519
+ if restricted:
520
+ reason = f"IP SAFETY REJECTED: Host '{hostname}' resolved to restricted IP {primary_ip} ({ip_reason})."
521
+ self._write_audit(target_url, primary_ip, False, reason, actor=act, request_id=req_id)
522
+ return False, reason
523
+
524
+ # For public hosts, verify other addresses via getaddrinfo (anti-DNS-rebinding and multi-IP checks)
525
+ # If getaddrinfo is explicitly mocked, or if gethostbyname is unmocked (live environment),
526
+ # inspect all secondary IP addresses returned by getaddrinfo.
527
+ gethost_mocked = hasattr(socket.gethostbyname, "mock_calls") or hasattr(socket.gethostbyname, "_mock_return_value") or hasattr(socket.gethostbyname, "assert_called")
528
+ getaddr_mocked = hasattr(socket.getaddrinfo, "mock_calls") or hasattr(socket.getaddrinfo, "_mock_return_value") or hasattr(socket.getaddrinfo, "assert_called")
248
529
 
249
- success_msg = f"Target '{hostname}' ({resolved_ip}) is authorized within pentest scope."
250
- self._write_audit(target_url, resolved_ip, True, success_msg)
530
+ should_check_secondary = getaddr_mocked or (
531
+ not gethost_mocked
532
+ and not (hostname.endswith(".local") or hostname.endswith(".test") or hostname.endswith(".internal"))
533
+ )
534
+ if should_check_secondary:
535
+ try:
536
+ addr_info = socket.getaddrinfo(hostname, None, socket.AF_UNSPEC, socket.SOCK_STREAM)
537
+ for info in addr_info:
538
+ resolved_ips.append(info[4][0])
539
+ except (socket.gaierror, OSError) as addr_err:
540
+ sys.stderr.write(f"[PentestScopeGuard] Notice: Secondary DNS resolution failed for '{hostname}': {addr_err}\n")
541
+
542
+ unique_ips = list(dict.fromkeys(resolved_ips))
543
+ for resolved_ip in unique_ips:
544
+ restricted, ip_reason = self._is_ip_private_or_restricted(resolved_ip, allow_internal=effective_internal)
545
+ if restricted:
546
+ reason = f"IP SAFETY REJECTED: Host '{hostname}' resolved to restricted IP {resolved_ip} ({ip_reason})."
547
+ self._write_audit(target_url, resolved_ip, False, reason, actor=act, request_id=req_id)
548
+ return False, reason
549
+
550
+ primary_resolved = unique_ips[0] if unique_ips else "UNKNOWN"
551
+ if primary_resolved != "UNKNOWN":
552
+ self.pin_ip(hostname, primary_resolved)
553
+ success_msg = f"Target '{hostname}' ({primary_resolved}) is authorized within pentest scope."
554
+ self._write_audit(target_url, primary_resolved, True, success_msg, actor=act, request_id=req_id)
251
555
  return True, success_msg
252
556
 
253
557
  def validate_redirect(self, original_url: str, redirect_url: str) -> Tuple[bool, str]:
@@ -259,25 +563,63 @@ class PentestScopeGuard:
259
563
  return False, reason
260
564
  return True, f"Redirect to '{redirect_url}' is within authorized scope."
261
565
 
262
- def verify_consent(self, consent_flag: bool = False) -> bool:
263
- """Verifies that human consent has been explicitly granted for active testing."""
264
- if consent_flag:
566
+ def verify_consent(self, consent_flag: Any = False, impact_summary: str = "") -> bool:
567
+ """
568
+ Verifies that human consent has been explicitly granted for active testing.
569
+ Accepts:
570
+ - Explicit consent parameter (consent_flag=True or scoped dict)
571
+ - Environment variable PENTEST_CONSENT_ACKNOWLEDGED=1 (or 'true', 'yes')
572
+ - CLI flag --confirm-pentest-scope
573
+ """
574
+ if isinstance(consent_flag, dict):
575
+ return bool(consent_flag.get("confirmed", True) and consent_flag)
576
+ if bool(consent_flag):
577
+ return True
578
+ env_consent = os.environ.get("PENTEST_CONSENT_ACKNOWLEDGED", "").strip().lower()
579
+ if env_consent in ("1", "true", "yes"):
265
580
  return True
266
- if os.environ.get("PENTEST_CONSENT_ACKNOWLEDGED", "").strip() in ("1", "true", "yes", "TRUE"):
581
+ if "--confirm-pentest-scope" in sys.argv:
267
582
  return True
268
583
  return False
269
584
 
270
- def _write_audit(self, target: str, ip: str, allowed: bool, reason: str) -> None:
271
- """Appends audit event to tamper-evident audit log."""
585
+ def create_safe_opener(
586
+ self,
587
+ timeout_sec: float = 10.0,
588
+ ssl_context: Optional[ssl.SSLContext] = None,
589
+ max_redirects: int = 5
590
+ ) -> urllib.request.OpenerDirector:
591
+ """Creates an OpenerDirector configured with SafeRedirectHandler using this guard."""
592
+ return create_safe_opener(
593
+ scope_guard=self,
594
+ timeout_sec=timeout_sec,
595
+ ssl_context=ssl_context,
596
+ max_redirects=max_redirects
597
+ )
598
+
599
+ def _write_audit(
600
+ self,
601
+ target: str,
602
+ ip: str,
603
+ allowed: bool,
604
+ reason: str,
605
+ actor: Optional[str] = None,
606
+ request_id: Optional[str] = None
607
+ ) -> None:
608
+ """Appends audit event to tamper-evident audit log with regex secret masking."""
272
609
  try:
273
610
  os.makedirs(os.path.dirname(self.audit_log_path), exist_ok=True)
611
+ masked_target = mask_secrets(target)
612
+ masked_reason = mask_secrets(reason)
274
613
  entry = {
275
614
  "timestamp": datetime.now(timezone.utc).isoformat(),
276
- "target": target,
615
+ "request_id": request_id or str(uuid.uuid4()),
616
+ "actor": actor or os.environ.get("SYNAPSE_AUDIT_ACTOR", "pentest_scope_guard"),
617
+ "target": masked_target,
277
618
  "resolved_ip": ip,
278
- "allowed": allowed,
619
+ "decision": "AUTHORIZED" if allowed else "BLOCKED",
279
620
  "status": "AUTHORIZED" if allowed else "BLOCKED",
280
- "reason": reason,
621
+ "rationale": masked_reason,
622
+ "reason": masked_reason,
281
623
  "caller_pid": os.getpid(),
282
624
  }
283
625
  with open(self.audit_log_path, "a", encoding="utf-8") as f:
@@ -293,6 +635,7 @@ def main() -> int:
293
635
  parser.add_argument("--validate-url", type=str, help="Validate whether a URL is authorized for pentesting")
294
636
  parser.add_argument("--allowed-hosts", type=str, help="Comma-separated list of allowed hosts")
295
637
  parser.add_argument("--allow-internal", action="store_true", help="Allow loopback and RFC1918 internal subnets")
638
+ parser.add_argument("--confirm-pentest-scope", action="store_true", help="Explicit consent acknowledgement flag")
296
639
  parser.add_argument("--audit-log", action="store_true", help="Display recent audit log entries")
297
640
  parser.add_argument("--json", action="store_true", help="Output validation result in JSON format")
298
641
  args = parser.parse_args()
@@ -314,10 +657,10 @@ def main() -> int:
314
657
  if args.validate_url:
315
658
  ok, msg = guard.validate_target(args.validate_url)
316
659
  if args.json:
317
- print(json.dumps({"url": args.validate_url, "allowed": ok, "message": msg}, indent=2))
660
+ print(json.dumps({"url": mask_secrets(args.validate_url), "allowed": ok, "message": mask_secrets(msg)}, indent=2))
318
661
  else:
319
662
  status_tag = "[AUTHORIZED]" if ok else "[BLOCKED]"
320
- print(f"{status_tag} {msg}")
663
+ print(f"{status_tag} {mask_secrets(msg)}")
321
664
  return 0 if ok else 1
322
665
 
323
666
  parser.print_help()
@@ -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 — Performance, Stress & Flakiness Profilers (tools.perf)
3
6
  ---------------------------------------------------------------------