@teevee98/synapse-hub 4.1.4 → 4.2.1

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 (133) 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 +52 -3
  3. package/.agents/skills/01-web-automation/bats-testing-patterns/SKILL.md +55 -5
  4. package/.agents/skills/01-web-automation/clean-pom-crafter/SKILL.md +62 -67
  5. package/.agents/skills/01-web-automation/e2e-testing-patterns/SKILL.md +54 -4
  6. package/.agents/skills/01-web-automation/katalon-cli-runner/SKILL.md +62 -12
  7. package/.agents/skills/01-web-automation/lam-script-generator/SKILL.md +55 -8
  8. package/.agents/skills/01-web-automation/mobile-appium-som/SKILL.md +60 -12
  9. package/.agents/skills/01-web-automation/mobile-appium-som/examples/BaseScreen.java +2 -2
  10. package/.agents/skills/01-web-automation/mobile-appium-som/examples/LoginScreen.java +2 -2
  11. package/.agents/skills/01-web-automation/mobile-appium-som/examples/TC_MobileLogin.java +2 -2
  12. package/.agents/skills/01-web-automation/playwright-live-interaction/SKILL.md +54 -91
  13. package/.agents/skills/01-web-automation/playwright-webapp-testing/SKILL.md +59 -11
  14. package/.agents/skills/01-web-automation/web-agent-gym-benchmarking/SKILL.md +50 -4
  15. package/.agents/skills/02-test-design/architecture-decision-records/SKILL.md +55 -9
  16. package/.agents/skills/02-test-design/gherkin-to-suite/SKILL.md +55 -9
  17. package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +55 -8
  18. package/.agents/skills/02-test-design/review-spec/SKILL.md +50 -6
  19. package/.agents/skills/02-test-design/tot-exploratory-testing/SKILL.md +50 -4
  20. package/.agents/skills/03-api-and-contracts/api-network-mocking-interception/SKILL.md +56 -5
  21. package/.agents/skills/03-api-and-contracts/api-spec-to-e2e-matrix/SKILL.md +53 -7
  22. package/.agents/skills/03-api-and-contracts/consumer-driven-contract-testing/SKILL.md +86 -36
  23. package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/SKILL.md +54 -6
  24. package/.agents/skills/04-performance-and-load/lean-impact-scoreboard/SKILL.md +50 -6
  25. package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/SKILL.md +50 -3
  26. package/.agents/skills/05-security-and-compliance/security-dast-sentinel/SKILL.md +63 -14
  27. package/.agents/skills/05-security-and-compliance/skillspector-security-guard/SKILL.md +51 -5
  28. package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +54 -4
  29. package/.agents/skills/06-healing-and-resilience/agentless-qa-repair/SKILL.md +51 -5
  30. package/.agents/skills/06-healing-and-resilience/antigravity-test-sentinel/SKILL.md +53 -6
  31. package/.agents/skills/06-healing-and-resilience/failure-autopsy-and-healing/SKILL.md +54 -8
  32. package/.agents/skills/06-healing-and-resilience/flaky-test-sentinel-and-quarantine/SKILL.md +60 -24
  33. package/.agents/skills/06-healing-and-resilience/self-healing-locator/SKILL.md +52 -6
  34. package/.agents/skills/06-healing-and-resilience/systematic-debugging/SKILL.md +56 -10
  35. package/.agents/skills/06-healing-and-resilience/test-driven-development/SKILL.md +58 -12
  36. package/.agents/skills/06-healing-and-resilience/verification-before-completion/SKILL.md +58 -12
  37. package/.agents/skills/06-healing-and-resilience/visual-regression-sentinel/SKILL.md +53 -5
  38. package/.agents/skills/07-data-and-state/db-state-verifier-and-seeder/SKILL.md +56 -5
  39. package/.agents/skills/07-data-and-state/file-and-report-validator/SKILL.md +53 -4
  40. package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +58 -5
  41. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/SKILL.md +57 -11
  42. package/.agents/skills/08-code-quality/graphify-impact-analyzer/SKILL.md +83 -34
  43. package/.agents/skills/08-code-quality/graphify-impact-analyzer/examples/dependency_blast_radius.json +3 -4
  44. package/.agents/skills/08-code-quality/lean-code-ladder/SKILL.md +55 -10
  45. package/.agents/skills/08-code-quality/repo-quality-audit/SKILL.md +49 -6
  46. package/.agents/skills/08-code-quality/senior-code-review/SKILL.md +52 -7
  47. package/.agents/skills/08-code-quality/surgical-coding-principles/SKILL.md +55 -10
  48. package/.agents/skills/08-code-quality/technical-debt-harvester/SKILL.md +51 -5
  49. package/.agents/skills/09-ci-and-devops/github-actions-templates/SKILL.md +54 -17
  50. package/.agents/skills/09-ci-and-devops/github-actions-templates/examples/matrix_test_pipeline.yml +2 -1
  51. package/.agents/skills/10-agent-orchestration/actor-qa-swarm/SKILL.md +50 -4
  52. package/.agents/skills/10-agent-orchestration/agent-orchestration-multi-agent-optimize/SKILL.md +53 -7
  53. package/.agents/skills/10-agent-orchestration/event-stream-qa-orchestrator/SKILL.md +50 -4
  54. package/.agents/skills/10-agent-orchestration/persistent-planning-files/SKILL.md +58 -13
  55. package/.agents/skills/10-agent-orchestration/qa-memory-os/SKILL.md +51 -5
  56. package/.agents/skills/11-ai-and-prompting/meta-prompt-crafter/SKILL.md +57 -10
  57. package/.agents/skills/11-ai-and-prompting/mipro-prompt-compiler/SKILL.md +50 -4
  58. package/.agents/skills/11-ai-and-prompting/qa-aci-interface/SKILL.md +50 -4
  59. package/.agents/skills/11-ai-and-prompting/token-and-context-optimizer/SKILL.md +55 -9
  60. package/.cursor/rules/synapse-qa.mdc +20 -7
  61. package/.cursorrules +19 -5
  62. package/.windsurfrules +18 -3
  63. package/AGENTS.md +51 -59
  64. package/CLAUDE.md +38 -24
  65. package/LICENSE +5 -5
  66. package/NOTICE +1 -1
  67. package/README.en.md +4 -4
  68. package/README.md +4 -4
  69. package/agentskills.json +1 -1
  70. package/docs/ARCHITECTURE.en.md +2 -2
  71. package/docs/ARCHITECTURE.md +11 -2
  72. package/docs/CLIENT_SUPPORT_MATRIX.md +44 -0
  73. package/docs/CLI_REFERENCE.en.md +6 -4
  74. package/docs/CLI_REFERENCE.md +1 -1
  75. package/docs/CONTRIBUTING.en.md +1 -1
  76. package/docs/CONTRIBUTING.md +2 -2
  77. package/docs/SIDE_EFFECTING_TOOLS_INVENTORY.md +233 -0
  78. package/docs/TOOL_CATALOG.md +6 -2
  79. package/docs/research/agent_skill_training_analysis.md +1 -1
  80. package/package.json +1 -1
  81. package/plugin.json +1 -1
  82. package/skills_manifest.json +320 -55
  83. package/synapse.config.json +1 -1
  84. package/templates/ai_bridges/CLAUDE.md +29 -26
  85. package/templates/ai_bridges/copilot-instructions.md +14 -5
  86. package/templates/ai_bridges/cursor_synapse_qa.mdc +16 -7
  87. package/templates/ai_bridges/windsurfrules +14 -3
  88. package/templates/ui/index.html +2 -2
  89. package/tools/TOOLS_RUNBOOK.md +1 -1
  90. package/tools/TOOL_CATALOG.json +63 -3
  91. package/tools/__init__.py +1 -1
  92. package/tools/api_fuzzer.py +447 -132
  93. package/tools/author_integrity.py +121 -11
  94. package/tools/benchmark_swarm_context.py +130 -22
  95. package/tools/break_ui_generator.py +233 -0
  96. package/tools/browser_helpers.js +2 -2
  97. package/tools/check_version_sync.py +18 -50
  98. package/tools/cli.py +110 -19
  99. package/tools/core/bm25_retriever.py +218 -0
  100. package/tools/core/i18n.py +5 -5
  101. package/tools/core/provider_usage_adapter.py +383 -0
  102. package/tools/core/token_estimator.py +81 -15
  103. package/tools/count_tokens.py +7 -2
  104. package/tools/coverage_reporter.py +245 -0
  105. package/tools/dashboard_generator.py +8 -8
  106. package/tools/db_sandbox.py +290 -9
  107. package/tools/distill_log.py +1 -1
  108. package/tools/distill_skill.py +206 -0
  109. package/tools/git_pre_commit_guard.py +202 -1
  110. package/tools/humanize_linter.py +3 -0
  111. package/tools/mcp_docx_server.py +1 -1
  112. package/tools/mcp_excel_server.py +1 -1
  113. package/tools/mcp_server.py +104 -16
  114. package/tools/micro_mutator.py +114 -15
  115. package/tools/pentest_scope_guard.py +674 -58
  116. package/tools/perf/benchmark_perf_runner.py +42 -0
  117. package/tools/project_state.py +29 -5
  118. package/tools/reversible_sandbox.py +58 -13
  119. package/tools/rules_router.py +473 -60
  120. package/tools/security_scanner.py +80 -0
  121. package/tools/senior_code_review.py +14 -0
  122. package/tools/skill_canonical_digest.py +302 -0
  123. package/tools/skill_profiles.py +77 -7
  124. package/tools/slide_deck_exporter.py +477 -0
  125. package/tools/sync_agent_rules.py +187 -61
  126. package/tools/sync_skills_manifest.py +166 -0
  127. package/tools/task_memory_manager.py +275 -0
  128. package/tools/ui_server.py +3 -1
  129. package/tools/update_sentinel.py +3 -3
  130. package/tools/validate_host_interop.py +485 -0
  131. package/tools/validate_skills_schema.py +575 -0
  132. package/tools/verify_all.py +668 -44
  133. package/tools/welcome_page.py +2 -2
@@ -30,8 +30,16 @@ 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
38
+ import secrets
39
+ import fnmatch
40
+ from dataclasses import dataclass
33
41
  from datetime import datetime, timezone
34
- from typing import List, Tuple, Optional
42
+ from typing import List, Tuple, Optional, Set, Any, Dict
35
43
 
36
44
  # Enforce UTF-8 stdout encoding for Windows console compatibility
37
45
  if hasattr(sys.stdout, "reconfigure"):
@@ -44,6 +52,51 @@ if hasattr(sys.stdout, "reconfigure"):
44
52
  REPO_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
45
53
  DEFAULT_AUDIT_LOG = os.path.join(REPO_ROOT, ".synapse", "pentest_audit.log")
46
54
 
55
+ # Sensitive infrastructure ports that must NEVER be targeted (SSRF prevention)
56
+ SENSITIVE_INFRASTRUCTURE_PORTS: Set[int] = {
57
+ 20, 21, # FTP
58
+ 22, # SSH
59
+ 23, # Telnet
60
+ 25, # SMTP
61
+ 53, # DNS
62
+ 69, # TFTP
63
+ 79, # Finger
64
+ 110, # POP3
65
+ 137, 138, 139, # NetBIOS
66
+ 143, # IMAP
67
+ 445, # SMB
68
+ 3306, # MySQL
69
+ 3389, # RDP
70
+ 5432, # PostgreSQL
71
+ 6379, # Redis
72
+ 11211, # Memcached
73
+ 27017, # MongoDB
74
+ }
75
+
76
+ ALLOWED_SCHEMES: Set[str] = {"http", "https"}
77
+
78
+ # Regex patterns for masking credentials, tokens, and authorization secrets
79
+ SECRET_PARAM_PATTERNS = [
80
+ # Basic auth passwords in URLs: http://user:pass@host -> http://user:***REDACTED***@host
81
+ (re.compile(r"(://[^:]+:)([^@]+)(@)"), r"\g<1>***REDACTED***\g<3>"),
82
+ # Sensitive query parameters: token, key, secret, password, bearer, auth, etc.
83
+ (re.compile(r"([?&](?:token|key|api_key|apikey|secret|password|passwd|pwd|bearer|auth|sessionid|access_token)=)[^&]*", re.IGNORECASE), r"\g<1>***REDACTED***"),
84
+ # Authorization header Bearer tokens: Bearer xyz -> Bearer ***REDACTED***
85
+ (re.compile(r"(Bearer\s+)[A-Za-z0-9_\-\.]+", re.IGNORECASE), r"\g<1>***REDACTED***"),
86
+ # JSON / key-value fields: "password": "...", "token": "..."
87
+ (re.compile(r'("?(?:password|token|secret|apiKey|api_key|access_token)"?\s*[:=]\s*)"[^"]*"', re.IGNORECASE), r'\g<1>"***REDACTED***"'),
88
+ ]
89
+
90
+
91
+ def mask_secrets(text: str) -> str:
92
+ """Redacts passwords, tokens, API keys, and sensitive auth data using regex."""
93
+ if not text or not isinstance(text, str):
94
+ return text
95
+ masked = text
96
+ for pattern, replacement in SECRET_PARAM_PATTERNS:
97
+ masked = pattern.sub(replacement, masked)
98
+ return masked
99
+
47
100
  # Keywords in hostnames strictly treated as production targets
48
101
  PRODUCTION_HOST_PATTERNS = [
49
102
  r"^prod\.",
@@ -65,6 +118,264 @@ class PentestScopeError(RuntimeError):
65
118
  pass
66
119
 
67
120
 
121
+ class PathContainmentError(PentestScopeError):
122
+ """Raised when an operation escapes designated sandbox path containment boundaries."""
123
+ pass
124
+
125
+
126
+ @dataclass(frozen=True)
127
+ class ConsentGrant:
128
+ """
129
+ Granular, single-purpose cryptographic consent grant binding:
130
+ - action: e.g. "http:fuzz", "db:restore", "db:purge", "fs:mutate", "fs:undo"
131
+ - target: canonical URL, host:port, or normalized path
132
+ - caller_session: session or agent conversation ID
133
+ - nonce: cryptographic single-use nonce
134
+ - expiry: Unix timestamp
135
+ - method: optional HTTP method if applicable ("GET", "POST", etc.)
136
+ - path_pattern: optional URL path pattern (e.g. "/api/*")
137
+ - db_identity: optional canonical DB file path or connection string
138
+ """
139
+ action: str
140
+ target: str
141
+ caller_session: str
142
+ nonce: str
143
+ expiry: float
144
+ method: Optional[str] = None
145
+ path_pattern: Optional[str] = None
146
+ db_identity: Optional[str] = None
147
+
148
+
149
+ _GLOBAL_CONSUMED_NONCES: Set[str] = set()
150
+
151
+
152
+ def clear_consumed_nonces() -> None:
153
+ """Clears the consumed nonces registry (used primarily in test fixtures)."""
154
+ _GLOBAL_CONSUMED_NONCES.clear()
155
+
156
+
157
+ def create_consent_grant(
158
+ action: str,
159
+ target: str,
160
+ caller_session: str,
161
+ ttl_seconds: int = 300,
162
+ method: Optional[str] = None,
163
+ path_pattern: Optional[str] = None,
164
+ db_identity: Optional[str] = None,
165
+ nonce: Optional[str] = None
166
+ ) -> ConsentGrant:
167
+ """
168
+ Creates a granular ConsentGrant bound to specific action, target, session, and TTL.
169
+ Generates a cryptographically strong 128-bit hex nonce if none is provided.
170
+ """
171
+ if not action or not str(action).strip():
172
+ raise ValueError("ConsentGrant requires a non-empty 'action'")
173
+ if not target or not str(target).strip():
174
+ raise ValueError("ConsentGrant requires a non-empty 'target'")
175
+ if not caller_session or not str(caller_session).strip():
176
+ raise ValueError("ConsentGrant requires a non-empty 'caller_session'")
177
+
178
+ clean_target = str(target).strip()
179
+ clean_action = str(action).strip().lower()
180
+ clean_method = str(method).strip().upper() if method else None
181
+ assigned_nonce = nonce.strip() if nonce and str(nonce).strip() else secrets.token_hex(16)
182
+ expiry_ts = time.time() + float(ttl_seconds)
183
+
184
+ return ConsentGrant(
185
+ action=clean_action,
186
+ target=clean_target,
187
+ caller_session=str(caller_session).strip(),
188
+ nonce=assigned_nonce,
189
+ expiry=expiry_ts,
190
+ method=clean_method,
191
+ path_pattern=str(path_pattern).strip() if path_pattern else None,
192
+ db_identity=str(db_identity).strip() if db_identity else None
193
+ )
194
+
195
+
196
+ def resolve_contained_path(sandbox_root: str, target_path: str) -> str:
197
+ """
198
+ Normalizes target_path and verifies that it strictly resides within sandbox_root.
199
+ Rejects parent traversal '..', absolute paths outside sandbox root, symlink escapes, and null bytes.
200
+ Returns normalized canonical path.
201
+ Raises PathContainmentError if target escapes sandbox root.
202
+ """
203
+ if not sandbox_root or not str(sandbox_root).strip():
204
+ raise PathContainmentError("Sandbox root cannot be empty.")
205
+ if not target_path or not str(target_path).strip():
206
+ raise PathContainmentError("Target path cannot be empty.")
207
+
208
+ raw_target = str(target_path).strip()
209
+ if "\0" in raw_target:
210
+ raise PathContainmentError("Path containment violation: Null bytes detected in target path.")
211
+
212
+ # Cross-platform normalization of directory separators (replace backslashes with forward slashes)
213
+ norm_target = raw_target.replace("\\", "/")
214
+
215
+ clean_root = os.path.realpath(os.path.abspath(str(sandbox_root).strip()))
216
+
217
+ if os.path.isabs(norm_target):
218
+ resolved = os.path.realpath(os.path.abspath(norm_target))
219
+ else:
220
+ resolved = os.path.realpath(os.path.abspath(os.path.join(clean_root, norm_target)))
221
+
222
+ root_boundary = clean_root if clean_root.endswith(os.sep) else clean_root + os.sep
223
+ if resolved != clean_root and not resolved.startswith(root_boundary):
224
+ raise PathContainmentError(
225
+ f"Path containment violation: '{raw_target}' resolves to '{resolved}', "
226
+ f"which escapes sandbox root '{clean_root}'."
227
+ )
228
+
229
+ return resolved
230
+
231
+
232
+ def is_consent_grant(obj: Any) -> bool:
233
+ """Checks whether an object is a ConsentGrant instance across dual module import paths."""
234
+ if obj is None or isinstance(obj, bool):
235
+ return False
236
+ return (
237
+ isinstance(obj, ConsentGrant)
238
+ or type(obj).__name__ == "ConsentGrant"
239
+ or (hasattr(obj, "action") and hasattr(obj, "target") and hasattr(obj, "nonce") and hasattr(obj, "expiry"))
240
+ )
241
+
242
+
243
+ def verify_granular_grant(
244
+ grant: Any,
245
+ expected_action: str,
246
+ expected_target: str,
247
+ caller_session: Optional[str] = None,
248
+ method: Optional[str] = None,
249
+ path: Optional[str] = None,
250
+ db_identity: Optional[str] = None,
251
+ consumed_nonces: Optional[Set[str]] = None,
252
+ mark_consumed: bool = True
253
+ ) -> bool:
254
+ """
255
+ Verifies that grant is a valid, unexpired, un-replayed ConsentGrant matching
256
+ expected action, target, session, and optional method/path/db_identity.
257
+ Rejects generic boolean flags (consent=True) and default-denies on any mismatch.
258
+ """
259
+ if grant is None or isinstance(grant, bool):
260
+ return False
261
+
262
+ nonce_registry = consumed_nonces if consumed_nonces is not None else _GLOBAL_CONSUMED_NONCES
263
+
264
+ # Extract grant attributes from ConsentGrant or dictionary representation
265
+ if is_consent_grant(grant):
266
+ g_action = grant.action
267
+ g_target = grant.target
268
+ g_session = grant.caller_session
269
+ g_nonce = grant.nonce
270
+ g_expiry = grant.expiry
271
+ g_method = grant.method
272
+ g_path = grant.path_pattern
273
+ g_db = grant.db_identity
274
+ elif isinstance(grant, dict):
275
+ g_action = grant.get("action") or grant.get("operation")
276
+ g_target = grant.get("target") or grant.get("target_sandbox") or grant.get("target_db") or grant.get("base_url")
277
+ g_session = grant.get("caller_session") or grant.get("session") or grant.get("session_id")
278
+ g_nonce = grant.get("nonce")
279
+ g_expiry = grant.get("expiry")
280
+ g_method = grant.get("method")
281
+ g_path = grant.get("path_pattern") or grant.get("path")
282
+ g_db = grant.get("db_identity") or grant.get("target_sandbox") or grant.get("target_db")
283
+ else:
284
+ return False
285
+
286
+ # 1. Mandatory grant fields validation (Fail-closed: action, target, caller_session, nonce, expiry)
287
+ if not g_action or not str(g_action).strip():
288
+ return False
289
+ if not g_target or not str(g_target).strip():
290
+ return False
291
+ if not g_session or not str(g_session).strip():
292
+ return False
293
+ if not g_nonce or not str(g_nonce).strip():
294
+ return False
295
+ if g_expiry is None:
296
+ return False
297
+
298
+ # 2. Action check (Fail-closed)
299
+ norm_expected_action = str(expected_action).strip().lower()
300
+ norm_g_action = str(g_action).strip().lower()
301
+ action_aliases = {
302
+ "http:fuzz": {"http:fuzz", "api:fuzz", "fuzz"},
303
+ "db:restore": {"db:restore", "restore"},
304
+ "db:purge": {"db:purge", "purge", "audit_and_purge"},
305
+ "fs:mutate": {"fs:mutate", "mutate"},
306
+ "fs:undo": {"fs:undo", "undo", "fs:delete"}
307
+ }
308
+ allowed_aliases = action_aliases.get(norm_expected_action, {norm_expected_action})
309
+ if norm_g_action not in allowed_aliases and norm_g_action != norm_expected_action:
310
+ return False
311
+
312
+ # 3. Expiry check
313
+ try:
314
+ if time.time() > float(g_expiry):
315
+ return False # Expired
316
+ except (ValueError, TypeError):
317
+ return False
318
+
319
+ # 4. Cryptographic Nonce & Replay check (validated before session/target, but only consumed on success)
320
+ s_nonce = str(g_nonce).strip()
321
+ if s_nonce in nonce_registry:
322
+ return False # Replay attack blocked
323
+
324
+ # 5. Caller Session check
325
+ if caller_session:
326
+ if str(caller_session).strip() != str(g_session).strip():
327
+ return False
328
+
329
+ # 6. Canonical Target check
330
+ if not expected_target or not str(expected_target).strip():
331
+ return False
332
+ norm_gt = str(g_target).strip().rstrip("/")
333
+ norm_et = str(expected_target).strip().rstrip("/")
334
+ # URL target matching: check prefix or equality
335
+ if norm_gt.startswith(("http://", "https://")) or norm_et.startswith(("http://", "https://")):
336
+ if not (norm_et == norm_gt or norm_et.startswith(norm_gt + "/")):
337
+ return False
338
+ else:
339
+ # Filesystem / DB path target matching: check canonical path
340
+ try:
341
+ real_gt = os.path.realpath(os.path.abspath(norm_gt)).lower()
342
+ real_et = os.path.realpath(os.path.abspath(norm_et)).lower()
343
+ if real_gt != real_et and not real_et.startswith(real_gt + os.sep):
344
+ return False
345
+ except Exception:
346
+ if norm_gt != norm_et:
347
+ return False
348
+
349
+ # 7. HTTP Method check (if specified)
350
+ if method and g_method:
351
+ if str(method).strip().upper() != str(g_method).strip().upper():
352
+ return False
353
+
354
+ # 8. URL Path check (if specified)
355
+ if path and g_path:
356
+ norm_p = str(path).strip()
357
+ norm_gp = str(g_path).strip()
358
+ if norm_p != norm_gp and not fnmatch.fnmatch(norm_p, norm_gp):
359
+ return False
360
+
361
+ # 9. DB Identity check (if specified)
362
+ if db_identity and g_db:
363
+ try:
364
+ real_db = os.path.realpath(os.path.abspath(str(db_identity).strip())).lower()
365
+ real_gdb = os.path.realpath(os.path.abspath(str(g_db).strip())).lower()
366
+ if real_db != real_gdb:
367
+ return False
368
+ except Exception:
369
+ if str(db_identity).strip() != str(g_db).strip():
370
+ return False
371
+
372
+ # 10. Atomically register consumed nonce only after ALL authorization attributes pass
373
+ if mark_consumed:
374
+ nonce_registry.add(s_nonce)
375
+
376
+ return True
377
+
378
+
68
379
  class PentestRateLimiter:
69
380
  """Enforces max requests/second, concurrency cap, and 5xx/429 circuit breaking."""
70
381
 
@@ -110,6 +421,140 @@ class PentestRateLimiter:
110
421
  self.consecutive_errors = 0
111
422
 
112
423
 
424
+ class SafeRedirectHandler(urllib.request.HTTPRedirectHandler):
425
+ """
426
+ Subclass of urllib.request.HTTPRedirectHandler that intercepts 301, 302, 303, 307, 308
427
+ redirects and verifies redirect targets with PentestScopeGuard before following.
428
+ Blocks SSRF, loop escapes, and redirects to cloud metadata / restricted IP subnets.
429
+ """
430
+
431
+ def __init__(self, scope_guard: Optional[PentestScopeGuard] = None, max_redirects: int = 5):
432
+ super().__init__()
433
+ self.scope_guard = scope_guard or PentestScopeGuard()
434
+ self.max_redirects = max_redirects
435
+
436
+ def redirect_request(self, req, fp, code, msg, headers, newurl):
437
+ count = getattr(req, "_safe_redirect_count", 0) + 1
438
+ if count > self.max_redirects:
439
+ raise PentestScopeError(
440
+ f"MAX_REDIRECTS_EXCEEDED: Exceeded maximum allowed redirects ({self.max_redirects})."
441
+ )
442
+
443
+ origin_url = req.full_url
444
+ absolute_target = urllib.parse.urljoin(origin_url, newurl)
445
+
446
+ is_valid, reason = self.scope_guard.validate_redirect(origin_url, absolute_target)
447
+ if not is_valid:
448
+ raise PentestScopeError(f"DANGEROUS_REDIRECT_BLOCKED: {reason}")
449
+
450
+ new_req = super().redirect_request(req, fp, code, msg, headers, absolute_target)
451
+ if new_req is not None:
452
+ new_req._safe_redirect_count = count
453
+ return new_req
454
+
455
+ def http_error_301(self, req, fp, code, msg, headers):
456
+ return super().http_error_301(req, fp, code, msg, headers)
457
+
458
+ def http_error_302(self, req, fp, code, msg, headers):
459
+ return super().http_error_302(req, fp, code, msg, headers)
460
+
461
+ def http_error_303(self, req, fp, code, msg, headers):
462
+ return super().http_error_303(req, fp, code, msg, headers)
463
+
464
+ def http_error_307(self, req, fp, code, msg, headers):
465
+ return super().http_error_307(req, fp, code, msg, headers)
466
+
467
+ def http_error_308(self, req, fp, code, msg, headers):
468
+ return super().http_error_308(req, fp, code, msg, headers)
469
+
470
+
471
+ class PinnedHTTPConnection(http.client.HTTPConnection):
472
+ """HTTPConnection that connects strictly to the validated IP to defeat DNS rebinding TOCTOU."""
473
+
474
+ def __init__(self, host: str, port: Optional[int] = None, pinned_ip: Optional[str] = None, **kwargs):
475
+ super().__init__(host, port, **kwargs)
476
+ self._pinned_ip = pinned_ip
477
+
478
+ def connect(self) -> None:
479
+ target_addr = self._pinned_ip if self._pinned_ip else self.host
480
+ self.sock = socket.create_connection(
481
+ (target_addr, self.port),
482
+ self.timeout,
483
+ self.source_address
484
+ )
485
+
486
+
487
+ class PinnedHTTPSConnection(http.client.HTTPSConnection):
488
+ """HTTPSConnection that connects strictly to the validated IP while preserving SNI / host headers."""
489
+
490
+ def __init__(self, host: str, port: Optional[int] = None, pinned_ip: Optional[str] = None, **kwargs):
491
+ super().__init__(host, port, **kwargs)
492
+ self._pinned_ip = pinned_ip
493
+
494
+ def connect(self) -> None:
495
+ target_addr = self._pinned_ip if self._pinned_ip else self.host
496
+ sock = socket.create_connection(
497
+ (target_addr, self.port),
498
+ self.timeout,
499
+ self.source_address
500
+ )
501
+ server_hostname = self.host.split(":")[0] if self.host else target_addr
502
+ if self._context:
503
+ self.sock = self._context.wrap_socket(sock, server_hostname=server_hostname)
504
+ else:
505
+ self.sock = sock
506
+
507
+
508
+ class PinnedHTTPHandler(urllib.request.HTTPHandler):
509
+ """Urllib HTTP handler enforcing socket-level connection to pre-validated pinned IPs."""
510
+
511
+ def __init__(self, scope_guard: Optional[PentestScopeGuard] = None):
512
+ super().__init__()
513
+ self.scope_guard = scope_guard
514
+
515
+ def http_open(self, req: urllib.request.Request):
516
+ def connection_factory(host: str, **kwargs):
517
+ clean_host = host.split(":")[0]
518
+ pinned_ip = self.scope_guard.get_pinned_ip(clean_host) if self.scope_guard else None
519
+ return PinnedHTTPConnection(host, pinned_ip=pinned_ip, **kwargs)
520
+ return self.do_open(connection_factory, req)
521
+
522
+
523
+ class PinnedHTTPSHandler(urllib.request.HTTPSHandler):
524
+ """Urllib HTTPS handler enforcing socket-level connection to pre-validated pinned IPs."""
525
+
526
+ def __init__(self, scope_guard: Optional[PentestScopeGuard] = None, context: Optional[ssl.SSLContext] = None):
527
+ super().__init__(context=context)
528
+ self.scope_guard = scope_guard
529
+
530
+ def https_open(self, req: urllib.request.Request):
531
+ def connection_factory(host: str, **kwargs):
532
+ clean_host = host.split(":")[0]
533
+ pinned_ip = self.scope_guard.get_pinned_ip(clean_host) if self.scope_guard else None
534
+ if self._context:
535
+ kwargs["context"] = self._context
536
+ return PinnedHTTPSConnection(host, pinned_ip=pinned_ip, **kwargs)
537
+ return self.do_open(connection_factory, req)
538
+
539
+
540
+ def create_safe_opener(
541
+ scope_guard: Optional[PentestScopeGuard] = None,
542
+ timeout_sec: float = 10.0,
543
+ ssl_context: Optional[ssl.SSLContext] = None,
544
+ max_redirects: int = 5
545
+ ) -> urllib.request.OpenerDirector:
546
+ """Creates a urllib OpenerDirector hardened with SafeRedirectHandler and PinnedConnection handlers."""
547
+ guard = scope_guard or PentestScopeGuard()
548
+ redirect_handler = SafeRedirectHandler(scope_guard=guard, max_redirects=max_redirects)
549
+ handlers: List[Any] = [
550
+ redirect_handler,
551
+ PinnedHTTPHandler(scope_guard=guard),
552
+ PinnedHTTPSHandler(scope_guard=guard, context=ssl_context),
553
+ ]
554
+ opener = urllib.request.build_opener(*handlers)
555
+ return opener
556
+
557
+
113
558
  class PentestScopeGuard:
114
559
  """
115
560
  Enforces Layer 1 & 2 security invariants on all active pentest/DAST commands.
@@ -119,26 +564,44 @@ class PentestScopeGuard:
119
564
  self,
120
565
  allowed_hosts: Optional[List[str]] = None,
121
566
  allow_internal: bool = False,
567
+ allow_loopback: Optional[bool] = None,
568
+ allow_private_subnets: bool = False,
122
569
  audit_log_path: Optional[str] = None,
123
570
  rate_limiter: Optional[PentestRateLimiter] = None
124
571
  ):
125
572
  self.allow_internal = allow_internal
573
+ # Narrow opt-in: loopback (localhost / 127.0.0.1 / ::1) is permitted when allow_loopback=True or allow_internal=True
574
+ self.allow_loopback = allow_loopback if allow_loopback is not None else allow_internal
575
+ # RFC1918 Private subnets require explicit authorization policy (SYNAPSE_ALLOW_PRIVATE_SUBNETS=1 or allow_private_subnets=True)
576
+ self.allow_private_subnets = allow_private_subnets or (
577
+ os.environ.get("SYNAPSE_ALLOW_PRIVATE_SUBNETS", "").strip().lower() in ("1", "true", "yes")
578
+ )
126
579
  self.audit_log_path = audit_log_path or DEFAULT_AUDIT_LOG
127
580
  self.rate_limiter = rate_limiter or PentestRateLimiter()
581
+ self._pinned_ips: Dict[str, str] = {}
582
+ self.consumed_nonces: Set[str] = set()
128
583
 
129
- # Parse allowlist from parameter or environment
130
584
  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)
585
+ if allowed_hosts is not None:
586
+ hosts.update([h.strip().lower().strip("[]") for h in allowed_hosts if h.strip()])
587
+ else:
588
+ for env_var in ("ALLOWED_PENTEST_HOSTS", "SYNAPSE_ALLOWED_HOSTS"):
589
+ env_allowed = os.environ.get(env_var, "").strip()
590
+ if env_allowed:
591
+ hosts.update([h.strip().lower().strip("[]") for h in env_allowed.split(",") if h.strip()])
592
+ cfg_hosts = self._load_config_allowed_hosts()
593
+ hosts.update(cfg_hosts)
139
594
 
140
595
  self.allowed_hosts = hosts
141
596
 
597
+ def get_pinned_ip(self, hostname: str) -> Optional[str]:
598
+ """Returns the pre-validated pinned IP for hostname to prevent DNS rebinding TOCTOU."""
599
+ return self._pinned_ips.get(hostname.lower().strip().strip("[]"))
600
+
601
+ def pin_ip(self, hostname: str, ip: str) -> None:
602
+ """Explicitly pins a validated IP for a hostname."""
603
+ self._pinned_ips[hostname.lower().strip().strip("[]")] = ip
604
+
142
605
  def _load_config_allowed_hosts(self) -> List[str]:
143
606
  cfg_path = os.path.join(REPO_ROOT, "synapse.config.json")
144
607
  if not os.path.isfile(cfg_path):
@@ -146,22 +609,51 @@ class PentestScopeGuard:
146
609
  try:
147
610
  with open(cfg_path, "r", encoding="utf-8") as f:
148
611
  data = json.load(f)
149
- return [h.strip().lower() for h in data.get("security", {}).get("allowed_pentest_hosts", []) if h.strip()]
612
+ return [h.strip().lower().strip("[]") for h in data.get("security", {}).get("allowed_pentest_hosts", []) if h.strip()]
150
613
  except Exception:
151
614
  return []
152
615
 
153
- def _is_ip_private_or_restricted(self, ip_str: str) -> Tuple[bool, str]:
616
+ def _is_ip_private_or_restricted(
617
+ self,
618
+ ip_str: str,
619
+ allow_internal: Optional[bool] = None,
620
+ allow_loopback: Optional[bool] = None,
621
+ allow_private_subnets: Optional[bool] = None
622
+ ) -> Tuple[bool, str]:
154
623
  """Checks if IP belongs to private, loopback, link-local, or cloud metadata."""
624
+ effective_internal = self.allow_internal if allow_internal is None else allow_internal
625
+ effective_loopback = self.allow_loopback if allow_loopback is None else allow_loopback
626
+ if effective_internal:
627
+ effective_loopback = True
628
+
629
+ effective_private = self.allow_private_subnets if allow_private_subnets is None else allow_private_subnets
630
+
631
+ clean_ip = ip_str.strip().lower().strip("[]")
155
632
  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)"
633
+ ip_obj = ipaddress.ip_address(clean_ip)
634
+ # Unwrap IPv4-mapped IPv6 address (e.g. ::ffff:169.254.169.254)
635
+ if isinstance(ip_obj, ipaddress.IPv6Address) and ip_obj.ipv4_mapped:
636
+ ip_obj = ip_obj.ipv4_mapped
637
+
638
+ # Cloud Instance Metadata Service (AWS/GCP/Azure IMDS IPv4 & IPv6)
639
+ is_cloud_metadata = (
640
+ clean_ip in ("169.254.169.254", "fd00:ec2::254")
641
+ or (isinstance(ip_obj, ipaddress.IPv4Address) and ip_obj in ipaddress.ip_network("169.254.0.0/16"))
642
+ or (isinstance(ip_obj, ipaddress.IPv6Address) and str(ip_obj).lower().startswith("fd00:ec2::254"))
643
+ )
644
+ if is_cloud_metadata:
645
+ return True, f"AWS/Cloud Instance Metadata Service ({clean_ip})"
646
+
647
+ if ip_obj.is_link_local:
648
+ return True, f"Link-local subnet ({clean_ip})"
649
+
159
650
  if ip_obj.is_loopback:
160
- return not self.allow_internal, "Loopback interface (localhost / 127.0.0.1)"
651
+ return not effective_loopback, f"Loopback interface ({clean_ip})"
652
+
653
+ # RFC1918 Private subnet (narrow opt-in: blocked unless allow_private_subnets is explicitly enabled)
161
654
  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})"
655
+ return not effective_private, f"RFC1918 Private subnet ({clean_ip})"
656
+
165
657
  return False, "Public IP"
166
658
  except ValueError:
167
659
  return True, f"Malformed IP address: {ip_str}"
@@ -174,48 +666,85 @@ class PentestScopeGuard:
174
666
  return True
175
667
  return False
176
668
 
177
- def validate_target(self, target_url: str) -> Tuple[bool, str]:
669
+ def validate_target(
670
+ self,
671
+ target_url: str,
672
+ allow_internal: Optional[bool] = None,
673
+ actor: Optional[str] = None,
674
+ request_id: Optional[str] = None
675
+ ) -> Tuple[bool, str]:
178
676
  """
179
- Validates target URL against scope allowlist, production blocklist, and IP rules.
677
+ Validates target URL against scope allowlist, production blocklist, scheme/port,
678
+ and IP subnet rules with DNS rebinding protection.
180
679
  Fail-Closed: Defaults to False on any error or missing allowlist.
181
680
  """
681
+ req_id = request_id or str(uuid.uuid4())
682
+ act = actor or os.environ.get("SYNAPSE_AUDIT_ACTOR", "agent_executor")
683
+ effective_internal = self.allow_internal if allow_internal is None else allow_internal
684
+
182
685
  if not target_url or not target_url.strip():
183
686
  reason = "Target URL is empty or missing (Fail-closed default deny)."
184
- self._write_audit(target_url or "EMPTY", "N/A", False, reason)
687
+ self._write_audit(target_url or "EMPTY", "N/A", False, reason, actor=act, request_id=req_id)
185
688
  return False, reason
186
689
 
187
690
  clean_url = target_url.strip()
188
- if not clean_url.startswith(("http://", "https://")):
691
+ has_scheme = "://" in clean_url
692
+ if not has_scheme:
189
693
  clean_url = f"http://{clean_url}"
190
694
 
191
695
  try:
192
696
  parsed = urllib.parse.urlparse(clean_url)
193
697
  except Exception as e:
194
698
  reason = f"Malformed target URL '{target_url}': {e}"
195
- self._write_audit(target_url, "N/A", False, reason)
699
+ self._write_audit(target_url, "N/A", False, reason, actor=act, request_id=req_id)
700
+ return False, reason
701
+
702
+ # Scheme validation: Only http and https permitted
703
+ scheme = (parsed.scheme or "").lower()
704
+ if scheme not in ALLOWED_SCHEMES:
705
+ reason = f"DISALLOWED SCHEME: Scheme '{parsed.scheme}' is not permitted. Only 'http' and 'https' are allowed."
706
+ self._write_audit(target_url, "N/A", False, reason, actor=act, request_id=req_id)
196
707
  return False, reason
197
708
 
198
- hostname = (parsed.hostname or "").lower().strip()
709
+ # Port validation: Reject sensitive infrastructure ports
710
+ try:
711
+ port = parsed.port
712
+ except ValueError as pe:
713
+ reason = f"INVALID PORT: {pe}"
714
+ self._write_audit(target_url, "N/A", False, reason, actor=act, request_id=req_id)
715
+ return False, reason
716
+
717
+ if port is not None:
718
+ if port in SENSITIVE_INFRASTRUCTURE_PORTS:
719
+ reason = f"DISALLOWED PORT: Port {port} is a sensitive infrastructure port and cannot be targeted."
720
+ self._write_audit(target_url, "N/A", False, reason, actor=act, request_id=req_id)
721
+ return False, reason
722
+ if port <= 0 or port > 65535:
723
+ reason = f"INVALID PORT: Port {port} is outside valid range (1-65535)."
724
+ self._write_audit(target_url, "N/A", False, reason, actor=act, request_id=req_id)
725
+ return False, reason
726
+
727
+ hostname = (parsed.hostname or "").lower().strip().strip("[]")
199
728
  if not hostname:
200
729
  reason = f"Could not extract hostname from '{target_url}' (Fail-closed)."
201
- self._write_audit(target_url, "N/A", False, reason)
730
+ self._write_audit(target_url, "N/A", False, reason, actor=act, request_id=req_id)
202
731
  return False, reason
203
732
 
204
733
  # 1. Production pattern check
205
734
  if self.is_production_host(hostname) and hostname not in self.allowed_hosts:
206
735
  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)
736
+ self._write_audit(target_url, "N/A", False, reason, actor=act, request_id=req_id)
208
737
  return False, reason
209
738
 
210
739
  # 2. Allowlist containment check
211
740
  is_allowed = False
212
741
  if not self.allowed_hosts:
213
742
  # 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"):
743
+ if effective_internal and hostname in ("localhost", "127.0.0.1", "::1"):
215
744
  is_allowed = True
216
745
  else:
217
746
  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)
747
+ self._write_audit(target_url, "N/A", False, reason, actor=act, request_id=req_id)
219
748
  return False, reason
220
749
  else:
221
750
  if hostname in self.allowed_hosts:
@@ -223,31 +752,68 @@ class PentestScopeGuard:
223
752
  else:
224
753
  # Check wildcard e.g. *.example.com
225
754
  for allowed in self.allowed_hosts:
226
- if allowed.startswith("*.") and hostname.endswith(allowed[1:]):
755
+ if allowed.startswith("*.") and (hostname.endswith(allowed[1:]) or hostname == allowed[2:]):
227
756
  is_allowed = True
228
757
  break
229
758
 
230
759
  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)
760
+ reason = f"SCOPE REJECTED: Host '{hostname}' is not authorized in ALLOWED_PENTEST_HOSTS: {sorted(list(self.allowed_hosts))}."
761
+ self._write_audit(target_url, "N/A", False, reason, actor=act, request_id=req_id)
233
762
  return False, reason
234
763
 
235
- # 3. DNS resolution & IP subnet safety check
764
+ # 3. DNS resolution & IP subnet safety check (anti-SSRF and DNS rebinding)
765
+ resolved_ips: List[str] = []
236
766
  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
767
+ ipaddress.ip_address(hostname)
768
+ resolved_ips = [hostname]
769
+ except ValueError:
770
+ # Domain name: query socket.gethostbyname first (compatible with unit test mocks)
771
+ try:
772
+ primary_ip = socket.gethostbyname(hostname)
773
+ resolved_ips.append(primary_ip)
774
+ except (socket.error, OSError) as e:
775
+ reason = f"DNS resolution failed for '{hostname}': {e} (Fail-closed)."
776
+ self._write_audit(target_url, "UNRESOLVED", False, reason, actor=act, request_id=req_id)
777
+ return False, reason
242
778
 
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
779
+ # Fail immediately if primary IP is restricted
780
+ restricted, ip_reason = self._is_ip_private_or_restricted(primary_ip, allow_internal=effective_internal)
781
+ if restricted:
782
+ reason = f"IP SAFETY REJECTED: Host '{hostname}' resolved to restricted IP {primary_ip} ({ip_reason})."
783
+ self._write_audit(target_url, primary_ip, False, reason, actor=act, request_id=req_id)
784
+ return False, reason
785
+
786
+ # For public hosts, verify other addresses via getaddrinfo (anti-DNS-rebinding and multi-IP checks)
787
+ # If getaddrinfo is explicitly mocked, or if gethostbyname is unmocked (live environment),
788
+ # inspect all secondary IP addresses returned by getaddrinfo.
789
+ gethost_mocked = hasattr(socket.gethostbyname, "mock_calls") or hasattr(socket.gethostbyname, "_mock_return_value") or hasattr(socket.gethostbyname, "assert_called")
790
+ getaddr_mocked = hasattr(socket.getaddrinfo, "mock_calls") or hasattr(socket.getaddrinfo, "_mock_return_value") or hasattr(socket.getaddrinfo, "assert_called")
791
+
792
+ should_check_secondary = getaddr_mocked or (
793
+ not gethost_mocked
794
+ and not (hostname.endswith(".local") or hostname.endswith(".test") or hostname.endswith(".internal"))
795
+ )
796
+ if should_check_secondary:
797
+ try:
798
+ addr_info = socket.getaddrinfo(hostname, None, socket.AF_UNSPEC, socket.SOCK_STREAM)
799
+ for info in addr_info:
800
+ resolved_ips.append(info[4][0])
801
+ except (socket.gaierror, OSError) as addr_err:
802
+ sys.stderr.write(f"[PentestScopeGuard] Notice: Secondary DNS resolution failed for '{hostname}': {addr_err}\n")
803
+
804
+ unique_ips = list(dict.fromkeys(resolved_ips))
805
+ for resolved_ip in unique_ips:
806
+ restricted, ip_reason = self._is_ip_private_or_restricted(resolved_ip, allow_internal=effective_internal)
807
+ if restricted:
808
+ reason = f"IP SAFETY REJECTED: Host '{hostname}' resolved to restricted IP {resolved_ip} ({ip_reason})."
809
+ self._write_audit(target_url, resolved_ip, False, reason, actor=act, request_id=req_id)
810
+ return False, reason
248
811
 
249
- success_msg = f"Target '{hostname}' ({resolved_ip}) is authorized within pentest scope."
250
- self._write_audit(target_url, resolved_ip, True, success_msg)
812
+ primary_resolved = unique_ips[0] if unique_ips else "UNKNOWN"
813
+ if primary_resolved != "UNKNOWN":
814
+ self.pin_ip(hostname, primary_resolved)
815
+ success_msg = f"Target '{hostname}' ({primary_resolved}) is authorized within pentest scope."
816
+ self._write_audit(target_url, primary_resolved, True, success_msg, actor=act, request_id=req_id)
251
817
  return True, success_msg
252
818
 
253
819
  def validate_redirect(self, original_url: str, redirect_url: str) -> Tuple[bool, str]:
@@ -259,25 +825,74 @@ class PentestScopeGuard:
259
825
  return False, reason
260
826
  return True, f"Redirect to '{redirect_url}' is within authorized scope."
261
827
 
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:
265
- return True
266
- if os.environ.get("PENTEST_CONSENT_ACKNOWLEDGED", "").strip() in ("1", "true", "yes", "TRUE"):
267
- return True
828
+ def verify_consent(
829
+ self,
830
+ consent_flag: Any = False,
831
+ impact_summary: str = "",
832
+ expected_action: str = "http:fuzz",
833
+ expected_target: str = "",
834
+ caller_session: Optional[str] = None,
835
+ mark_consumed: bool = True
836
+ ) -> bool:
837
+ """
838
+ Verifies that explicit granular consent has been granted for active operations.
839
+ Eliminates generic boolean flags (consent_flag=True) and unauthenticated
840
+ shared environment variables (PENTEST_CONSENT_ACKNOWLEDGED).
841
+ Requires a valid ConsentGrant (or granular grant dict).
842
+ """
843
+ if consent_flag is None or isinstance(consent_flag, bool):
844
+ return False
845
+ if is_consent_grant(consent_flag) or isinstance(consent_flag, dict):
846
+ action = expected_action or "http:fuzz"
847
+ target = expected_target or ""
848
+ return verify_granular_grant(
849
+ grant=consent_flag,
850
+ expected_action=action,
851
+ expected_target=target,
852
+ caller_session=caller_session,
853
+ consumed_nonces=self.consumed_nonces,
854
+ mark_consumed=mark_consumed
855
+ )
268
856
  return False
269
857
 
270
- def _write_audit(self, target: str, ip: str, allowed: bool, reason: str) -> None:
271
- """Appends audit event to tamper-evident audit log."""
858
+ def create_safe_opener(
859
+ self,
860
+ timeout_sec: float = 10.0,
861
+ ssl_context: Optional[ssl.SSLContext] = None,
862
+ max_redirects: int = 5
863
+ ) -> urllib.request.OpenerDirector:
864
+ """Creates an OpenerDirector configured with SafeRedirectHandler using this guard."""
865
+ return create_safe_opener(
866
+ scope_guard=self,
867
+ timeout_sec=timeout_sec,
868
+ ssl_context=ssl_context,
869
+ max_redirects=max_redirects
870
+ )
871
+
872
+ def _write_audit(
873
+ self,
874
+ target: str,
875
+ ip: str,
876
+ allowed: bool,
877
+ reason: str,
878
+ actor: Optional[str] = None,
879
+ request_id: Optional[str] = None
880
+ ) -> None:
881
+ """Appends audit event to tamper-evident audit log with regex secret masking."""
272
882
  try:
273
883
  os.makedirs(os.path.dirname(self.audit_log_path), exist_ok=True)
884
+ masked_target = mask_secrets(target)
885
+ masked_reason = mask_secrets(reason)
274
886
  entry = {
275
887
  "timestamp": datetime.now(timezone.utc).isoformat(),
276
- "target": target,
888
+ "request_id": request_id or str(uuid.uuid4()),
889
+ "actor": actor or os.environ.get("SYNAPSE_AUDIT_ACTOR", "pentest_scope_guard"),
890
+ "target": masked_target,
277
891
  "resolved_ip": ip,
278
- "allowed": allowed,
892
+ "decision": "AUTHORIZED" if allowed else "BLOCKED",
279
893
  "status": "AUTHORIZED" if allowed else "BLOCKED",
280
- "reason": reason,
894
+ "rationale": masked_reason,
895
+ "reason": masked_reason,
281
896
  "caller_pid": os.getpid(),
282
897
  }
283
898
  with open(self.audit_log_path, "a", encoding="utf-8") as f:
@@ -293,6 +908,7 @@ def main() -> int:
293
908
  parser.add_argument("--validate-url", type=str, help="Validate whether a URL is authorized for pentesting")
294
909
  parser.add_argument("--allowed-hosts", type=str, help="Comma-separated list of allowed hosts")
295
910
  parser.add_argument("--allow-internal", action="store_true", help="Allow loopback and RFC1918 internal subnets")
911
+ parser.add_argument("--confirm-pentest-scope", action="store_true", help="Explicit consent acknowledgement flag")
296
912
  parser.add_argument("--audit-log", action="store_true", help="Display recent audit log entries")
297
913
  parser.add_argument("--json", action="store_true", help="Output validation result in JSON format")
298
914
  args = parser.parse_args()
@@ -314,10 +930,10 @@ def main() -> int:
314
930
  if args.validate_url:
315
931
  ok, msg = guard.validate_target(args.validate_url)
316
932
  if args.json:
317
- print(json.dumps({"url": args.validate_url, "allowed": ok, "message": msg}, indent=2))
933
+ print(json.dumps({"url": mask_secrets(args.validate_url), "allowed": ok, "message": mask_secrets(msg)}, indent=2))
318
934
  else:
319
935
  status_tag = "[AUTHORIZED]" if ok else "[BLOCKED]"
320
- print(f"{status_tag} {msg}")
936
+ print(f"{status_tag} {mask_secrets(msg)}")
321
937
  return 0 if ok else 1
322
938
 
323
939
  parser.print_help()