@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
@@ -23,12 +23,29 @@ import sys
23
23
  import json
24
24
  import time
25
25
  import ssl
26
+ import tempfile
26
27
  import urllib.request
27
28
  import urllib.error
28
29
  import urllib.parse
29
30
  import argparse
31
+ import fnmatch
32
+ import uuid
33
+ import secrets
30
34
  from typing import Dict, Any, List, Optional
31
35
 
36
+ from pentest_scope_guard import (
37
+ PentestScopeGuard,
38
+ PentestRateLimiter,
39
+ PentestScopeError,
40
+ PathContainmentError,
41
+ ConsentGrant,
42
+ create_consent_grant,
43
+ is_consent_grant,
44
+ resolve_contained_path,
45
+ mask_secrets,
46
+ _GLOBAL_CONSUMED_NONCES,
47
+ )
48
+
32
49
  # Enforce UTF-8 stdout encoding for Windows/macOS/Linux compatibility
33
50
  if hasattr(sys.stdout, 'reconfigure'):
34
51
  try:
@@ -39,6 +56,7 @@ if hasattr(sys.stdout, 'reconfigure'):
39
56
 
40
57
  SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
41
58
  HUB_ROOT = os.path.abspath(os.path.join(SCRIPT_DIR, ".."))
59
+ QA_HUB_ROOT = HUB_ROOT
42
60
  REPORTS_DIR = os.path.join(HUB_ROOT, "reports")
43
61
 
44
62
  if SCRIPT_DIR not in sys.path:
@@ -73,6 +91,8 @@ ALARM_SEVERITY = {
73
91
  "SLA_TIMEOUT": "LOW",
74
92
  "AUTH_BYPASS": "CRITICAL",
75
93
  "CONNECTION_ERROR": "MEDIUM",
94
+ "DANGEROUS_REDIRECT_BLOCKED": "CRITICAL",
95
+ "SCOPE_BLOCKED": "CRITICAL",
76
96
  }
77
97
  SEVERITY_LEVELS = ["INFO", "LOW", "MEDIUM", "HIGH", "CRITICAL"]
78
98
 
@@ -103,7 +123,14 @@ class ApiFuzzer:
103
123
  timeout_sec: float = 10.0,
104
124
  sla_ms: float = 3000.0,
105
125
  verify_ssl: bool = True,
106
- insecure: bool = False
126
+ insecure: bool = False,
127
+ scope_guard: Optional[PentestScopeGuard] = None,
128
+ rate_limiter: Optional[PentestRateLimiter] = None,
129
+ max_requests: int = 500,
130
+ allow_internal: bool = False,
131
+ allow_loopback: bool = True,
132
+ consent: Any = False,
133
+ dry_run: bool = False,
107
134
  ):
108
135
  self.base_url = base_url.rstrip("/")
109
136
  self.spec_path = spec_path_or_url
@@ -112,27 +139,16 @@ class ApiFuzzer:
112
139
  self.sla_ms = sla_ms
113
140
  self.insecure = insecure or (not verify_ssl)
114
141
  self.verify_ssl = not self.insecure
115
-
116
- # Environment Allowlist Guard (F2 Safety Discipline)
117
- # Prevents accidental fuzzing or stress bombardment against production environments
118
- parsed = urllib.parse.urlparse(self.base_url)
119
- host = (parsed.hostname or "").lower().strip()
120
- is_safe_env = self._is_safe_non_prod_host(host)
121
- allowed_hosts = {
122
- h.strip().lower() for h in os.environ.get("SYNAPSE_ALLOW_PROD_HOSTS", "").split(",") if h.strip()
123
- }
124
- is_host_specifically_allowed = host in allowed_hosts
125
- global_override = os.environ.get("SYNAPSE_ALLOW_PROD_FUZZ") in ("1", "true", "TRUE")
126
-
127
- if host and not is_safe_env and not (is_host_specifically_allowed or global_override):
128
- raise PermissionError(
129
- f"[SAFETY FIREWALL - REJECTED] Target host '{host}' is not in the allowed non-production environment allowlist "
130
- "(localhost, private IP, .local/.internal, or verified dev/staging/qa/test subdomain). "
131
- f"To authorize this host specifically, set SYNAPSE_ALLOW_PROD_HOSTS='{host}' or SYNAPSE_ALLOW_PROD_FUZZ=1 if authorized."
132
- )
133
- if host and not is_safe_env and global_override and not is_host_specifically_allowed:
134
- print(f" ⚠️ [SECURITY WARNING] SYNAPSE_ALLOW_PROD_FUZZ=1 global override active for host '{host}'. "
135
- f"Prefer setting SYNAPSE_ALLOW_PROD_HOSTS='{host}' for host-scoped permission.")
142
+ self.max_requests = max(1, int(max_requests))
143
+ self.consent = consent
144
+ self.dry_run = bool(dry_run)
145
+
146
+ # Wire unified scope guard and rate limiter (narrow loopback opt-in for local test harnesses)
147
+ self.scope_guard = scope_guard or PentestScopeGuard(
148
+ allow_internal=allow_internal,
149
+ allow_loopback=allow_loopback
150
+ )
151
+ self.rate_limiter = rate_limiter or self.scope_guard.rate_limiter
136
152
 
137
153
  # Prepare SSL context (support self-signed staging certificates via explicit --insecure flag)
138
154
  self.ssl_context = ssl.create_default_context()
@@ -141,90 +157,30 @@ class ApiFuzzer:
141
157
  self.ssl_context.check_hostname = False
142
158
  self.ssl_context.verify_mode = ssl.CERT_NONE
143
159
 
160
+ # Hardened transport opener with SafeRedirectHandler
161
+ self.opener = self.scope_guard.create_safe_opener(
162
+ timeout_sec=self.timeout_sec,
163
+ ssl_context=self.ssl_context
164
+ )
165
+
166
+ # Validate target base_url before proceeding (Fail-closed)
167
+ # When dry_run=True, skip live DNS lookups and network validation
168
+ if not self.dry_run:
169
+ ok, reason = self.scope_guard.validate_target(self.base_url, actor="ApiFuzzer.__init__")
170
+ if not ok:
171
+ raise PermissionError(
172
+ f"[SAFETY FIREWALL - REJECTED] Target base URL '{self.base_url}' is not permitted by pentest scope guard: {reason}"
173
+ )
174
+
144
175
  @staticmethod
145
176
  def _is_safe_non_prod_host(host: str) -> bool:
146
177
  """
147
- Validates whether a hostname strictly belongs to a local, private, or non-production environment.
148
- Prevents substring false positives on production domains like 'devex.com', 'contest.gov', or 'attestation-bank.com'.
178
+ Deprecated: Replaced by PentestScopeGuard. Enforces strict allowlist validation
179
+ without loose subdomain heuristics.
149
180
  """
150
- if not host:
151
- return False
152
-
153
- host = host.lower().strip()
154
-
155
- # 0. User-specified explicit host allowlist via SYNAPSE_ALLOWED_HOSTS
156
- allowed_env = os.environ.get("SYNAPSE_ALLOWED_HOSTS", "").strip()
157
- if allowed_env:
158
- for item in allowed_env.split(","):
159
- pattern = item.strip().lower()
160
- if pattern:
161
- if pattern.startswith("*.") and (host.endswith(pattern[1:]) or host == pattern[2:]):
162
- return True
163
- if host == pattern:
164
- return True
165
-
166
- # 1. Exact loopback / special names
167
- if host in ("localhost", "127.0.0.1", "::1", "0.0.0.0"): # nosec B104
168
- return True
169
-
170
- # 2. Check IP address (loopback or private RFC 1918, disallowing link-local metadata like 169.254.169.254)
171
- try:
172
- import ipaddress
173
- ip = ipaddress.ip_address(host)
174
- if ip.is_link_local or ip in ipaddress.ip_network("169.254.0.0/16"):
175
- return False
176
- return ip.is_loopback or ip.is_private
177
- except ValueError:
178
- ip = None # host is a domain name, not an IP literal
179
-
180
- # 2b. DNS resolution check (anti-SSRF / DNS rebinding against cloud metadata 169.254.0.0/16)
181
- try:
182
- import socket
183
- import ipaddress
184
- addr_info = socket.getaddrinfo(host, None, socket.AF_UNSPEC, socket.SOCK_STREAM)
185
- for _, _, _, _, sockaddr in addr_info:
186
- resolved_ip = ipaddress.ip_address(sockaddr[0])
187
- if resolved_ip.is_link_local or resolved_ip in ipaddress.ip_network("169.254.0.0/16"):
188
- return False
189
- except (socket.gaierror, OSError) as dns_err:
190
- # Offline test environment or unresolvable mock domain; fall through to lexical verification
191
- _dns_unresolved = str(dns_err)
192
-
193
- # 3. Special-use TLDs (RFC 6761 / RFC 2606)
194
- if any(host.endswith(tld) for tld in (".local", ".localhost", ".internal", ".test")):
195
- return True
196
-
197
- labels = host.split('.')
198
-
199
- # 4. Reject production markers anywhere in hostname (e.g. prod-test.bank.com)
200
- if any(re.search(r'(?:^|[-_])(prod|production)(?:$|[-_])', lbl) for lbl in labels):
201
- return False
202
-
203
- # 5. Prevent domain spoofing (e.g. bank.com.test.evil.io where public TLD appears in subdomains)
204
- common_public_tlds = {
205
- 'com', 'org', 'net', 'edu', 'gov', 'mil', 'io', 'co', 'vn', 'uk', 'de',
206
- 'fr', 'jp', 'cn', 'ru', 'br', 'in', 'ca', 'au', 'info', 'biz'
207
- }
208
- if any(lbl in common_public_tlds for lbl in labels[:-2]):
209
- return False
210
-
211
- # 6. Apex domains (e.g. bank-test.com, test.com) cannot be assumed non-prod without explicit config
212
- if len(labels) < 3:
213
- return False
214
-
215
- # 7. Subdomain verification (must be in leading subdomains preceding the root domain)
216
- subdomain_labels = labels[:-2]
217
- safe_exact_tokens = {"dev", "development", "staging", "qa", "test", "sandbox", "uat", "local", "internal"}
218
- safe_sub_regex = re.compile(
219
- 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]+)*$",
220
- re.IGNORECASE
221
- )
222
-
223
- for sub in subdomain_labels:
224
- if sub in safe_exact_tokens or safe_sub_regex.match(sub):
225
- return True
226
-
227
- return False
181
+ guard = PentestScopeGuard(allow_internal=True)
182
+ ok, _ = guard.validate_target(f"http://{host}")
183
+ return ok
228
184
 
229
185
  def load_spec(self) -> Dict[str, Any]:
230
186
  """Loads OpenAPI or Swagger specification from file or URL."""
@@ -256,14 +212,47 @@ class ApiFuzzer:
256
212
  }
257
213
 
258
214
  if self.spec_path.startswith(("http://", "https://")):
215
+ if self.dry_run:
216
+ # Offline mock spec when dry_run=True: zero network and DNS requests
217
+ return {
218
+ "paths": {
219
+ "/api/v1/dry_run_endpoint": {
220
+ "get": {
221
+ "summary": "Dry run offline endpoint",
222
+ "responses": {"200": {"description": "OK"}}
223
+ }
224
+ }
225
+ }
226
+ }
227
+ # Validate spec URL with scope guard before network dispatch
228
+ ok, reason = self.scope_guard.validate_target(self.spec_path, actor="ApiFuzzer.load_spec")
229
+ if not ok:
230
+ raise PermissionError(f"[PENTEST SCOPE GUARD] Disallowed OpenAPI spec URL '{self.spec_path}': {reason}")
259
231
  req = urllib.request.Request(self.spec_path, headers={"User-Agent": "AgentQA-Fuzzer/2.0"})
260
- with urllib.request.urlopen(req, context=self.ssl_context, timeout=10.0) as resp: # nosec B310
261
- raw = resp.read().decode("utf-8")
262
- return json.loads(raw)
232
+ try:
233
+ with self.opener.open(req, timeout=10.0) as resp:
234
+ raw = resp.read().decode("utf-8")
235
+ return json.loads(raw)
236
+ except PentestScopeError as pse:
237
+ raise PermissionError(f"[PENTEST SCOPE GUARD] Redirect blocked during load_spec: {pse}")
263
238
  else:
264
- if not os.path.exists(self.spec_path):
239
+ # Validate that local spec path does not traverse outside workspace or temporary directories
240
+ allowed_roots = [os.path.abspath(os.getcwd()), QA_HUB_ROOT, tempfile.gettempdir()]
241
+
242
+ contained_path = None
243
+ for root in allowed_roots:
244
+ try:
245
+ contained_path = resolve_contained_path(root, self.spec_path)
246
+ break
247
+ except PathContainmentError:
248
+ continue
249
+
250
+ if contained_path is None:
251
+ raise PathContainmentError(f"OpenAPI spec path '{self.spec_path}' escapes designated containment roots.")
252
+
253
+ if not os.path.exists(contained_path):
265
254
  raise FileNotFoundError(f"OpenAPI spec not found: {self.spec_path}")
266
- with open(self.spec_path, "r", encoding="utf-8") as f:
255
+ with open(contained_path, "r", encoding="utf-8") as f:
267
256
  return json.load(f)
268
257
 
269
258
  def extract_fuzz_targets(self, spec: Dict[str, Any]) -> List[Dict[str, Any]]:
@@ -432,7 +421,7 @@ class ApiFuzzer:
432
421
 
433
422
  return mutations
434
423
 
435
- def execute_request(self, mutation: Dict[str, Any], dry_run: bool = False) -> Dict[str, Any]:
424
+ def execute_request(self, mutation: Dict[str, Any], dry_run: bool = False, consent: Optional[Any] = None) -> Dict[str, Any]:
436
425
  """Dispatches HTTP mutation and evaluates the three-alarm Oracle."""
437
426
  url = f"{self.base_url}{mutation['path']}"
438
427
  method = mutation["method"]
@@ -440,12 +429,12 @@ class ApiFuzzer:
440
429
  if method in ("POST", "PUT", "PATCH") and mutation.get("body") is not None:
441
430
  body_data = json.dumps(mutation["body"]).encode("utf-8")
442
431
 
443
- if dry_run:
432
+ if dry_run or self.dry_run:
444
433
  # Deterministic offline mock for CI & local checks
445
434
  return {
446
435
  "name": mutation["name"],
447
436
  "type": mutation["type"],
448
- "url": url,
437
+ "url": mask_secrets(url),
449
438
  "method": method,
450
439
  "status_code": 400 if mutation["type"] != "BASELINE" else 200,
451
440
  "duration_ms": 42.5,
@@ -455,6 +444,238 @@ class ApiFuzzer:
455
444
  "response_preview": '{"status": "handled_by_dry_run"}'
456
445
  }
457
446
 
447
+ # Consent verification: active live testing requires explicit granular consent before network dispatch
448
+ effective_consent = self.consent if consent is None else consent
449
+
450
+ # 1. Reject missing or generic boolean consent
451
+ if effective_consent is None or isinstance(effective_consent, bool) or not effective_consent:
452
+ return {
453
+ "name": mutation.get("name", "unnamed"),
454
+ "type": mutation.get("type", "UNKNOWN"),
455
+ "url": mask_secrets(url),
456
+ "method": method,
457
+ "status_code": -5,
458
+ "duration_ms": 0.0,
459
+ "verdict": "FAIL",
460
+ "severity": "CRITICAL",
461
+ "alarms": ["CONSENT_REQUIRED: Active API request rejected. Granular ConsentGrant required (binding action='http:fuzz', canonical target, caller_session, nonce, expiry)."],
462
+ "response_preview": "Active request blocked: missing consent."
463
+ }
464
+
465
+ # 2. Extract attributes from ConsentGrant or scoped dict
466
+ if is_consent_grant(effective_consent):
467
+ c_target = effective_consent.target
468
+ c_method = effective_consent.method
469
+ c_path = effective_consent.path_pattern
470
+ c_expiry = effective_consent.expiry
471
+ c_nonce = effective_consent.nonce
472
+ elif isinstance(effective_consent, dict):
473
+ c_target = effective_consent.get("target") or effective_consent.get("target_sandbox") or effective_consent.get("base_url")
474
+ c_method = effective_consent.get("method")
475
+ c_path = effective_consent.get("path") or effective_consent.get("path_pattern")
476
+ c_expiry = effective_consent.get("expiry")
477
+ c_nonce = effective_consent.get("nonce")
478
+ c_session = effective_consent.get("caller_session") or effective_consent.get("session") or effective_consent.get("session_id")
479
+ # Check target, method, and path mismatch before rejecting incomplete dict fields
480
+ if c_target and not (url.startswith(c_target.rstrip("/")) or self.base_url == c_target.rstrip("/")):
481
+ return {
482
+ "name": mutation.get("name", "unnamed"),
483
+ "type": mutation.get("type", "UNKNOWN"),
484
+ "url": mask_secrets(url),
485
+ "method": method,
486
+ "status_code": -5,
487
+ "duration_ms": 0.0,
488
+ "verdict": "FAIL",
489
+ "severity": "CRITICAL",
490
+ "alarms": [f"CONSENT_MISMATCH: Scoped consent target '{c_target}' does not authorize target URL '{mask_secrets(url)}'."],
491
+ "response_preview": "Active request blocked: consent target mismatch."
492
+ }
493
+
494
+ if c_method and c_method.upper() != method.upper():
495
+ return {
496
+ "name": mutation.get("name", "unnamed"),
497
+ "type": mutation.get("type", "UNKNOWN"),
498
+ "url": mask_secrets(url),
499
+ "method": method,
500
+ "status_code": -5,
501
+ "duration_ms": 0.0,
502
+ "verdict": "FAIL",
503
+ "severity": "CRITICAL",
504
+ "alarms": [f"CONSENT_MISMATCH: Scoped consent method '{c_method}' does not authorize mutation method '{method}'."],
505
+ "response_preview": "Active request blocked: consent method mismatch."
506
+ }
507
+
508
+ if c_path:
509
+ m_path = mutation.get("path", "")
510
+ if c_path != m_path and not fnmatch.fnmatch(m_path, c_path):
511
+ return {
512
+ "name": mutation.get("name", "unnamed"),
513
+ "type": mutation.get("type", "UNKNOWN"),
514
+ "url": mask_secrets(url),
515
+ "method": method,
516
+ "status_code": -5,
517
+ "duration_ms": 0.0,
518
+ "verdict": "FAIL",
519
+ "severity": "CRITICAL",
520
+ "alarms": [f"CONSENT_MISMATCH: Scoped consent path '{c_path}' does not authorize mutation path '{m_path}'."],
521
+ "response_preview": "Active request blocked: consent path mismatch."
522
+ }
523
+
524
+ if not c_target or not c_nonce or c_expiry is None or not c_session:
525
+ return {
526
+ "name": mutation.get("name", "unnamed"),
527
+ "type": mutation.get("type", "UNKNOWN"),
528
+ "url": mask_secrets(url),
529
+ "method": method,
530
+ "status_code": -5,
531
+ "duration_ms": 0.0,
532
+ "verdict": "FAIL",
533
+ "severity": "CRITICAL",
534
+ "alarms": ["CONSENT_REQUIRED: Granular grant dictionary missing mandatory fields (action, target, caller_session, nonce, expiry)."],
535
+ "response_preview": "Active request blocked: missing mandatory consent fields."
536
+ }
537
+ else:
538
+ return {
539
+ "name": mutation.get("name", "unnamed"),
540
+ "type": mutation.get("type", "UNKNOWN"),
541
+ "url": mask_secrets(url),
542
+ "method": method,
543
+ "status_code": -5,
544
+ "duration_ms": 0.0,
545
+ "verdict": "FAIL",
546
+ "severity": "CRITICAL",
547
+ "alarms": ["CONSENT_REQUIRED: Invalid consent type. Expected ConsentGrant or scoped grant dict."],
548
+ "response_preview": "Active request blocked: missing consent."
549
+ }
550
+
551
+ # 3. Check expiration
552
+ if c_expiry is not None:
553
+ try:
554
+ if time.time() > float(c_expiry):
555
+ return {
556
+ "name": mutation.get("name", "unnamed"),
557
+ "type": mutation.get("type", "UNKNOWN"),
558
+ "url": mask_secrets(url),
559
+ "method": method,
560
+ "status_code": -5,
561
+ "duration_ms": 0.0,
562
+ "verdict": "FAIL",
563
+ "severity": "CRITICAL",
564
+ "alarms": ["CONSENT_EXPIRED: Consent grant has expired."],
565
+ "response_preview": "Active request blocked: consent expired."
566
+ }
567
+ except (ValueError, TypeError) as exp_err:
568
+ return {
569
+ "name": mutation.get("name", "unnamed"),
570
+ "type": mutation.get("type", "UNKNOWN"),
571
+ "url": mask_secrets(url),
572
+ "method": method,
573
+ "status_code": -5,
574
+ "duration_ms": 0.0,
575
+ "verdict": "FAIL",
576
+ "severity": "CRITICAL",
577
+ "alarms": [f"CONSENT_INVALID_EXPIRY: {exp_err}"],
578
+ "response_preview": "Active request blocked: consent expiry invalid."
579
+ }
580
+
581
+ # 4. Check nonce replay
582
+ if c_nonce:
583
+ if hasattr(self.scope_guard, "consumed_nonces") and c_nonce in self.scope_guard.consumed_nonces:
584
+ return {
585
+ "name": mutation.get("name", "unnamed"),
586
+ "type": mutation.get("type", "UNKNOWN"),
587
+ "url": mask_secrets(url),
588
+ "method": method,
589
+ "status_code": -5,
590
+ "duration_ms": 0.0,
591
+ "verdict": "FAIL",
592
+ "severity": "CRITICAL",
593
+ "alarms": ["CONSENT_REPLAYED: Replay attack detected. Consent nonce has already been consumed."],
594
+ "response_preview": "Active request blocked: consent replayed."
595
+ }
596
+
597
+ # 5. Check target mismatch
598
+ if c_target and not (url.startswith(c_target.rstrip("/")) or self.base_url == c_target.rstrip("/")):
599
+ return {
600
+ "name": mutation.get("name", "unnamed"),
601
+ "type": mutation.get("type", "UNKNOWN"),
602
+ "url": mask_secrets(url),
603
+ "method": method,
604
+ "status_code": -5,
605
+ "duration_ms": 0.0,
606
+ "verdict": "FAIL",
607
+ "severity": "CRITICAL",
608
+ "alarms": [f"CONSENT_MISMATCH: Scoped consent target '{c_target}' does not authorize target URL '{mask_secrets(url)}'."],
609
+ "response_preview": "Active request blocked: consent target mismatch."
610
+ }
611
+
612
+ # 6. Check method mismatch
613
+ if c_method and c_method.upper() != method.upper():
614
+ return {
615
+ "name": mutation.get("name", "unnamed"),
616
+ "type": mutation.get("type", "UNKNOWN"),
617
+ "url": mask_secrets(url),
618
+ "method": method,
619
+ "status_code": -5,
620
+ "duration_ms": 0.0,
621
+ "verdict": "FAIL",
622
+ "severity": "CRITICAL",
623
+ "alarms": [f"CONSENT_MISMATCH: Scoped consent method '{c_method}' does not authorize mutation method '{method}'."],
624
+ "response_preview": "Active request blocked: consent method mismatch."
625
+ }
626
+
627
+ # 7. Check path mismatch
628
+ if c_path:
629
+ m_path = mutation.get("path", "")
630
+ if c_path != m_path and not fnmatch.fnmatch(m_path, c_path):
631
+ return {
632
+ "name": mutation.get("name", "unnamed"),
633
+ "type": mutation.get("type", "UNKNOWN"),
634
+ "url": mask_secrets(url),
635
+ "method": method,
636
+ "status_code": -5,
637
+ "duration_ms": 0.0,
638
+ "verdict": "FAIL",
639
+ "severity": "CRITICAL",
640
+ "alarms": [f"CONSENT_MISMATCH: Scoped consent path '{c_path}' does not authorize mutation path '{m_path}'."],
641
+ "response_preview": "Active request blocked: consent path mismatch."
642
+ }
643
+
644
+ # 8. Verify with PentestScopeGuard
645
+ if not self.scope_guard.verify_consent(effective_consent, expected_action="http:fuzz", expected_target=self.base_url):
646
+ return {
647
+ "name": mutation.get("name", "unnamed"),
648
+ "type": mutation.get("type", "UNKNOWN"),
649
+ "url": mask_secrets(url),
650
+ "method": method,
651
+ "status_code": -5,
652
+ "duration_ms": 0.0,
653
+ "verdict": "FAIL",
654
+ "severity": "CRITICAL",
655
+ "alarms": ["CONSENT_REQUIRED: Consent verification failed against pentest scope guard."],
656
+ "response_preview": "Active request blocked: missing consent."
657
+ }
658
+
659
+ # Mark nonce consumed
660
+ if c_nonce and hasattr(self.scope_guard, "consumed_nonces"):
661
+ self.scope_guard.consumed_nonces.add(c_nonce)
662
+
663
+ # Check target URL with PentestScopeGuard before network dispatch (Consent NEVER bypasses host scope guard)
664
+ ok, scope_reason = self.scope_guard.validate_target(url, actor="ApiFuzzer.execute_request")
665
+ if not ok:
666
+ return {
667
+ "name": mutation["name"],
668
+ "type": mutation["type"],
669
+ "url": mask_secrets(url),
670
+ "method": method,
671
+ "status_code": -3,
672
+ "duration_ms": 0.0,
673
+ "verdict": "FAIL",
674
+ "severity": "CRITICAL",
675
+ "alarms": [f"SCOPE_BLOCKED: Request target blocked by pentest scope guard: {scope_reason}"],
676
+ "response_preview": mask_secrets(scope_reason)
677
+ }
678
+
458
679
  req = urllib.request.Request(
459
680
  url=url,
460
681
  data=body_data,
@@ -466,11 +687,16 @@ class ApiFuzzer:
466
687
  status_code = 0
467
688
  response_body = ""
468
689
  duration_ms = 0.0
690
+ redirect_blocked = False
469
691
 
470
692
  try:
471
- with urllib.request.urlopen(req, context=self.ssl_context, timeout=self.timeout_sec) as resp: # nosec B310
693
+ with self.opener.open(req, timeout=self.timeout_sec) as resp:
472
694
  status_code = resp.getcode()
473
695
  response_body = resp.read().decode("utf-8", errors="replace")
696
+ except PentestScopeError as pse:
697
+ status_code = -4
698
+ response_body = str(pse)
699
+ redirect_blocked = True
474
700
  except urllib.error.HTTPError as he:
475
701
  status_code = he.code
476
702
  try:
@@ -491,6 +717,9 @@ class ApiFuzzer:
491
717
  # ----------------------------------------------------
492
718
  alarms = []
493
719
 
720
+ if redirect_blocked:
721
+ alarms.append(f"DANGEROUS_REDIRECT_BLOCKED: {response_body}")
722
+
494
723
  # Alarm 1: HTTP 500 / 502 / 503 Internal Server Error
495
724
  if status_code in (500, 502, 503):
496
725
  alarms.append(f"HTTP_{status_code}_SERVER_CRASH: Unhandled backend exception / server panic")
@@ -512,7 +741,7 @@ class ApiFuzzer:
512
741
 
513
742
  # Alarm 5: Target unreachable - an endpoint that could not be tested
514
743
  # must NEVER be reported as PASS (Truth Anchor discipline).
515
- if status_code < 0:
744
+ if status_code < 0 and not redirect_blocked:
516
745
  alarms.append("CONNECTION_ERROR: Target unreachable or transport failure - endpoint could not be verified")
517
746
 
518
747
  verdict = "FAIL" if alarms else "PASS"
@@ -526,18 +755,55 @@ class ApiFuzzer:
526
755
  return {
527
756
  "name": mutation["name"],
528
757
  "type": mutation["type"],
529
- "url": url,
758
+ "url": mask_secrets(url),
530
759
  "method": method,
531
760
  "status_code": status_code,
532
761
  "duration_ms": duration_ms,
533
762
  "verdict": verdict,
534
763
  "severity": severity,
535
764
  "alarms": alarms,
536
- "response_preview": response_body[:300]
765
+ "response_preview": mask_secrets(response_body[:300])
537
766
  }
538
767
 
539
- def run_fuzz_suite(self, dry_run: bool = False) -> Dict[str, Any]:
768
+ def run_fuzz_suite(self, dry_run: bool = False, consent: Any = False) -> Dict[str, Any]:
540
769
  """Runs the complete fuzzing suite against all extracted targets."""
770
+ effective_dry_run = dry_run or self.dry_run
771
+ parent_nonce = None
772
+ # Consent validation: active live testing requires explicit consent
773
+ if not effective_dry_run:
774
+ effective_consent = self.consent if consent is False else consent
775
+ has_consent = self.scope_guard.verify_consent(
776
+ effective_consent,
777
+ expected_action="http:fuzz",
778
+ expected_target=self.base_url,
779
+ mark_consumed=False # Do not burn session nonce during pre-flight check!
780
+ )
781
+ if not has_consent:
782
+ raise PermissionError(
783
+ "Active API fuzzing requires explicit consent. Provide a valid granular ConsentGrant "
784
+ "(or pass --confirm-pentest-scope on CLI), or set dry_run=True to preview safely."
785
+ )
786
+
787
+ # Extract parent session grant attributes for deriving child request grants
788
+ if is_consent_grant(effective_consent):
789
+ parent_action = effective_consent.action
790
+ parent_target = effective_consent.target
791
+ parent_session = effective_consent.caller_session
792
+ parent_nonce = effective_consent.nonce
793
+ parent_expiry = effective_consent.expiry
794
+ elif isinstance(effective_consent, dict):
795
+ parent_action = effective_consent.get("action") or effective_consent.get("operation") or "http:fuzz"
796
+ parent_target = effective_consent.get("target") or effective_consent.get("target_sandbox") or effective_consent.get("base_url") or self.base_url
797
+ parent_session = effective_consent.get("caller_session") or effective_consent.get("session") or f"cli_{os.getpid()}"
798
+ parent_nonce = effective_consent.get("nonce")
799
+ parent_expiry = effective_consent.get("expiry") or (time.time() + 300.0)
800
+ else:
801
+ parent_action = "http:fuzz"
802
+ parent_target = self.base_url
803
+ parent_session = f"cli_{os.getpid()}"
804
+ parent_nonce = secrets.token_hex(16)
805
+ parent_expiry = time.time() + 300.0
806
+
541
807
  spec = self.load_spec()
542
808
  targets = self.extract_fuzz_targets(spec)
543
809
 
@@ -545,35 +811,70 @@ class ApiFuzzer:
545
811
  for t in targets:
546
812
  all_mutations.extend(self.generate_mutations(t))
547
813
 
814
+ total_generated = len(all_mutations)
815
+ volume_capped = False
816
+ if len(all_mutations) > self.max_requests:
817
+ all_mutations = all_mutations[:self.max_requests]
818
+ volume_capped = True
819
+
548
820
  results = []
549
821
  total_failures = 0
550
822
 
551
823
  print(f"\n{BOLD}{CYAN}======================================================================{RESET}")
552
824
  print(f"{BOLD}{CYAN} ENTERPRISE AUTONOMOUS API FUZZING & CHAOS BREAKER {RESET}")
553
825
  print(f"{BOLD}{CYAN}======================================================================{RESET}")
554
- print(f" Target Base URL : {self.base_url}")
555
- print(f" Spec Source : {self.spec_path or 'Default Archetype'}")
826
+ print(f" Target Base URL : {mask_secrets(self.base_url)}")
827
+ print(f" Spec Source : {mask_secrets(self.spec_path or 'Default Archetype')}")
556
828
  print(f" Total Endpoints : {len(targets)}")
557
- print(f" Total Mutations : {len(all_mutations)}")
829
+ print(f" Total Mutations : {len(all_mutations)} (capped from {total_generated})" if volume_capped else f" Total Mutations : {len(all_mutations)}")
558
830
  print(f" SLA Threshold : {self.sla_ms} ms")
559
- print(f" Mode : {'DRY-RUN (Air-Gapped / Deterministic)' if dry_run else 'LIVE STAGING ATTACK'}\n")
831
+ print(f" Rate Limit Max : {self.rate_limiter.max_req_per_sec} req/s")
832
+ print(f" Mode : {'DRY-RUN (Air-Gapped / Deterministic)' if effective_dry_run else 'LIVE STAGING ATTACK'}\n")
560
833
 
561
- for idx, m in enumerate(all_mutations, start=1):
562
- res = self.execute_request(m, dry_run=dry_run)
563
- results.append(res)
564
-
565
- status_str = f"{GREEN}PASS{RESET}" if res["verdict"] == "PASS" else f"{RED}ALARM{RESET}"
566
- sys.stdout.write(f" [{idx:03d}/{len(all_mutations):03d}] {status_str} | HTTP {res['status_code']} ({res['duration_ms']}ms) | {m['name']}\n")
567
- if res["alarms"]:
568
- total_failures += 1
569
- for alarm in res["alarms"]:
570
- print(f" 👉 {RED}{BOLD}[DEFECT]{RESET} {alarm}")
834
+ try:
835
+ for idx, m in enumerate(all_mutations, start=1):
836
+ if not effective_dry_run:
837
+ self.rate_limiter.acquire()
838
+ sub_nonce = f"{parent_nonce}:sub_{idx}_{uuid.uuid4().hex[:8]}" if parent_nonce else secrets.token_hex(16)
839
+ child_grant = ConsentGrant(
840
+ action=parent_action,
841
+ target=parent_target,
842
+ caller_session=parent_session,
843
+ nonce=sub_nonce,
844
+ expiry=float(parent_expiry),
845
+ method=m.get("method"),
846
+ path_pattern=m.get("path")
847
+ )
848
+ res = self.execute_request(m, dry_run=False, consent=child_grant)
849
+ else:
850
+ res = self.execute_request(m, dry_run=True, consent=None)
851
+
852
+ results.append(res)
853
+
854
+ if not effective_dry_run and res["status_code"] > 0:
855
+ self.rate_limiter.record_response(res["status_code"])
856
+
857
+ status_str = f"{GREEN}PASS{RESET}" if res["verdict"] == "PASS" else f"{RED}ALARM{RESET}"
858
+ sys.stdout.write(f" [{idx:03d}/{len(all_mutations):03d}] {status_str} | HTTP {res['status_code']} ({res['duration_ms']}ms) | {m['name']}\n")
859
+ if res["alarms"]:
860
+ total_failures += 1
861
+ for alarm in res["alarms"]:
862
+ print(f" 👉 {RED}{BOLD}[DEFECT]{RESET} {alarm}")
863
+ finally:
864
+ if not effective_dry_run and parent_nonce:
865
+ clean_p_nonce = str(parent_nonce).strip()
866
+ if hasattr(self.scope_guard, "consumed_nonces"):
867
+ self.scope_guard.consumed_nonces.add(clean_p_nonce)
868
+ _GLOBAL_CONSUMED_NONCES.add(clean_p_nonce)
571
869
 
572
870
  scorecard = {
573
- "base_url": self.base_url,
871
+ "base_url": mask_secrets(self.base_url),
574
872
  "timestamp": time.strftime("%Y-%m-%d %H:%M:%S"),
575
873
  "mode": "ACTIVE",
576
874
  "total_mutations": len(all_mutations),
875
+ "total_generated": total_generated,
876
+ "volume_capped": volume_capped,
877
+ "max_requests": self.max_requests,
577
878
  "passed": len(all_mutations) - total_failures,
578
879
  "failed": total_failures,
579
880
  "sla_ms": self.sla_ms,
@@ -727,6 +1028,8 @@ def main():
727
1028
  help="active = live fuzzing (default); passive = offline spec audit, zero traffic")
728
1029
  parser.add_argument("--insecure", action="store_true", help="Explicitly bypass TLS certificate verification (for staging/self-signed certs)")
729
1030
  parser.add_argument("--dry-run", action="store_true", help="Simulate mutation generation without live requests")
1031
+ parser.add_argument("--max-requests", type=int, default=500, help="Max requests volume ceiling (default: 500)")
1032
+ parser.add_argument("--confirm-pentest-scope", action="store_true", help="Explicit human consent acknowledgement for live fuzzing")
730
1033
  parser.add_argument("--json", action="store_true", help="Output summary in JSON format")
731
1034
 
732
1035
  args = parser.parse_args()
@@ -735,12 +1038,24 @@ def main():
735
1038
  if args.token:
736
1039
  headers["Authorization"] = f"Bearer {args.token}"
737
1040
 
1041
+ grant = None
1042
+ if args.confirm_pentest_scope:
1043
+ grant = create_consent_grant(
1044
+ action="http:fuzz",
1045
+ target=args.base_url,
1046
+ caller_session=f"cli_{os.getpid()}",
1047
+ ttl_seconds=300
1048
+ )
1049
+
738
1050
  fuzzer = ApiFuzzer(
739
1051
  base_url=args.base_url,
740
1052
  spec_path_or_url=args.spec,
741
1053
  headers=headers,
742
1054
  sla_ms=args.sla_ms,
743
- insecure=args.insecure
1055
+ insecure=args.insecure,
1056
+ max_requests=args.max_requests,
1057
+ dry_run=args.dry_run,
1058
+ consent=grant
744
1059
  )
745
1060
 
746
1061
  if args.mode == "passive":
@@ -751,7 +1066,7 @@ def main():
751
1066
  blocking = int(severity_dict.get("HIGH", 0)) + int(severity_dict.get("CRITICAL", 0))
752
1067
  return 1 if blocking > 0 else 0
753
1068
 
754
- scorecard = fuzzer.run_fuzz_suite(dry_run=args.dry_run)
1069
+ scorecard = fuzzer.run_fuzz_suite(dry_run=args.dry_run, consent=grant)
755
1070
  if args.json:
756
1071
  print(json.dumps(scorecard, indent=2))
757
1072