@teevee98/synapse-hub 4.1.4 → 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 (116) 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/e2e-testing-patterns/SKILL.md +6 -1
  6. package/.agents/skills/01-web-automation/katalon-cli-runner/SKILL.md +6 -1
  7. package/.agents/skills/01-web-automation/lam-script-generator/SKILL.md +6 -1
  8. package/.agents/skills/01-web-automation/mobile-appium-som/SKILL.md +6 -1
  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 +7 -2
  13. package/.agents/skills/01-web-automation/playwright-webapp-testing/SKILL.md +6 -1
  14. package/.agents/skills/01-web-automation/web-agent-gym-benchmarking/SKILL.md +6 -1
  15. package/.agents/skills/02-test-design/architecture-decision-records/SKILL.md +6 -1
  16. package/.agents/skills/02-test-design/gherkin-to-suite/SKILL.md +6 -1
  17. package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +6 -1
  18. package/.agents/skills/02-test-design/review-spec/SKILL.md +4 -1
  19. package/.agents/skills/02-test-design/tot-exploratory-testing/SKILL.md +6 -1
  20. package/.agents/skills/03-api-and-contracts/api-network-mocking-interception/SKILL.md +6 -1
  21. package/.agents/skills/03-api-and-contracts/api-spec-to-e2e-matrix/SKILL.md +6 -1
  22. package/.agents/skills/03-api-and-contracts/consumer-driven-contract-testing/SKILL.md +7 -2
  23. package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/SKILL.md +7 -2
  24. package/.agents/skills/04-performance-and-load/lean-impact-scoreboard/SKILL.md +4 -1
  25. package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/SKILL.md +6 -1
  26. package/.agents/skills/05-security-and-compliance/security-dast-sentinel/SKILL.md +6 -1
  27. package/.agents/skills/05-security-and-compliance/skillspector-security-guard/SKILL.md +6 -1
  28. package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +6 -1
  29. package/.agents/skills/06-healing-and-resilience/agentless-qa-repair/SKILL.md +6 -1
  30. package/.agents/skills/06-healing-and-resilience/antigravity-test-sentinel/SKILL.md +6 -1
  31. package/.agents/skills/06-healing-and-resilience/failure-autopsy-and-healing/SKILL.md +7 -2
  32. package/.agents/skills/06-healing-and-resilience/flaky-test-sentinel-and-quarantine/SKILL.md +6 -1
  33. package/.agents/skills/06-healing-and-resilience/self-healing-locator/SKILL.md +6 -1
  34. package/.agents/skills/06-healing-and-resilience/systematic-debugging/SKILL.md +6 -1
  35. package/.agents/skills/06-healing-and-resilience/test-driven-development/SKILL.md +6 -1
  36. package/.agents/skills/06-healing-and-resilience/verification-before-completion/SKILL.md +6 -1
  37. package/.agents/skills/06-healing-and-resilience/visual-regression-sentinel/SKILL.md +6 -1
  38. package/.agents/skills/07-data-and-state/db-state-verifier-and-seeder/SKILL.md +6 -1
  39. package/.agents/skills/07-data-and-state/file-and-report-validator/SKILL.md +6 -1
  40. package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +6 -1
  41. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/SKILL.md +6 -1
  42. package/.agents/skills/08-code-quality/graphify-impact-analyzer/SKILL.md +6 -1
  43. package/.agents/skills/08-code-quality/lean-code-ladder/SKILL.md +6 -1
  44. package/.agents/skills/08-code-quality/repo-quality-audit/SKILL.md +4 -1
  45. package/.agents/skills/08-code-quality/senior-code-review/SKILL.md +4 -1
  46. package/.agents/skills/08-code-quality/surgical-coding-principles/SKILL.md +6 -1
  47. package/.agents/skills/08-code-quality/technical-debt-harvester/SKILL.md +4 -1
  48. package/.agents/skills/09-ci-and-devops/github-actions-templates/SKILL.md +6 -1
  49. package/.agents/skills/10-agent-orchestration/actor-qa-swarm/SKILL.md +6 -1
  50. package/.agents/skills/10-agent-orchestration/agent-orchestration-multi-agent-optimize/SKILL.md +6 -1
  51. package/.agents/skills/10-agent-orchestration/event-stream-qa-orchestrator/SKILL.md +6 -1
  52. package/.agents/skills/10-agent-orchestration/persistent-planning-files/SKILL.md +6 -1
  53. package/.agents/skills/10-agent-orchestration/qa-memory-os/SKILL.md +6 -1
  54. package/.agents/skills/11-ai-and-prompting/meta-prompt-crafter/SKILL.md +6 -1
  55. package/.agents/skills/11-ai-and-prompting/mipro-prompt-compiler/SKILL.md +6 -1
  56. package/.agents/skills/11-ai-and-prompting/qa-aci-interface/SKILL.md +6 -1
  57. package/.agents/skills/11-ai-and-prompting/token-and-context-optimizer/SKILL.md +6 -1
  58. package/AGENTS.md +7 -1
  59. package/LICENSE +5 -5
  60. package/NOTICE +1 -1
  61. package/README.en.md +4 -4
  62. package/README.md +4 -4
  63. package/agentskills.json +1 -1
  64. package/docs/ARCHITECTURE.en.md +2 -2
  65. package/docs/ARCHITECTURE.md +11 -2
  66. package/docs/CLI_REFERENCE.en.md +6 -4
  67. package/docs/CLI_REFERENCE.md +1 -1
  68. package/docs/CONTRIBUTING.en.md +1 -1
  69. package/docs/CONTRIBUTING.md +2 -2
  70. package/docs/TOOL_CATALOG.md +6 -2
  71. package/docs/research/agent_skill_training_analysis.md +1 -1
  72. package/package.json +1 -1
  73. package/plugin.json +1 -1
  74. package/skills_manifest.json +320 -55
  75. package/synapse.config.json +1 -1
  76. package/templates/ui/index.html +2 -2
  77. package/tools/TOOL_CATALOG.json +63 -3
  78. package/tools/__init__.py +1 -1
  79. package/tools/api_fuzzer.py +179 -118
  80. package/tools/author_integrity.py +121 -11
  81. package/tools/benchmark_swarm_context.py +119 -18
  82. package/tools/break_ui_generator.py +233 -0
  83. package/tools/browser_helpers.js +2 -2
  84. package/tools/check_version_sync.py +18 -50
  85. package/tools/cli.py +109 -18
  86. package/tools/core/bm25_retriever.py +218 -0
  87. package/tools/core/i18n.py +4 -4
  88. package/tools/core/provider_usage_adapter.py +317 -0
  89. package/tools/core/token_estimator.py +42 -14
  90. package/tools/count_tokens.py +5 -0
  91. package/tools/coverage_reporter.py +245 -0
  92. package/tools/dashboard_generator.py +6 -6
  93. package/tools/db_sandbox.py +146 -4
  94. package/tools/distill_skill.py +191 -0
  95. package/tools/git_pre_commit_guard.py +12 -0
  96. package/tools/humanize_linter.py +3 -0
  97. package/tools/mcp_docx_server.py +1 -1
  98. package/tools/mcp_excel_server.py +1 -1
  99. package/tools/mcp_server.py +75 -15
  100. package/tools/micro_mutator.py +84 -14
  101. package/tools/pentest_scope_guard.py +399 -56
  102. package/tools/perf/benchmark_perf_runner.py +42 -0
  103. package/tools/rules_router.py +401 -41
  104. package/tools/security_scanner.py +80 -0
  105. package/tools/senior_code_review.py +14 -0
  106. package/tools/skill_canonical_digest.py +244 -0
  107. package/tools/skill_profiles.py +77 -7
  108. package/tools/slide_deck_exporter.py +477 -0
  109. package/tools/sync_skills_manifest.py +166 -0
  110. package/tools/task_memory_manager.py +260 -0
  111. package/tools/ui_server.py +1 -1
  112. package/tools/update_sentinel.py +3 -3
  113. package/tools/validate_host_interop.py +485 -0
  114. package/tools/validate_skills_schema.py +282 -0
  115. package/tools/verify_all.py +572 -42
  116. package/tools/welcome_page.py +2 -2
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "$schema": "https://raw.githubusercontent.com/TeeVee98/Synapse-Hub/main/docs/schemas/synapse.config.schema.json",
3
- "version": "4.1.4",
3
+ "version": "4.2.0",
4
4
  "quality_gates": {
5
5
  "mutation_min_score": 80,
6
6
  "gates": {
@@ -671,7 +671,7 @@
671
671
 
672
672
  <!-- Footer -->
673
673
  <footer>
674
- <p>Synapse Hub &copy; 2026 <strong>Thế Vị (@TeeVee998)</strong> &mdash; Distributed under the <a href="https://github.com/TeeVee998/Synapse-Hub/blob/main/LICENSE" target="_blank">MIT License</a>.</p>
674
+ <p>Synapse Hub &copy; 2026 <strong>Thế Vị (@TeeVee98)</strong> &mdash; Distributed under the <a href="https://github.com/TeeVee98/Synapse-Hub/blob/main/LICENSE" target="_blank">MIT License</a>.</p>
675
675
  </footer>
676
676
 
677
677
  <script>
@@ -750,7 +750,7 @@
750
750
  "Target Repository: D:\\agent-skills",
751
751
  "Operational Mode : HUB\n",
752
752
  "[GATE 0] Verifying Author Attribution & MIT License Integrity...",
753
- "[PASS] Author Attribution & MIT License Provenance verified intact: Thế Vị (@TeeVee998)",
753
+ "[PASS] Author Attribution & MIT License Provenance verified intact: Thế Vị (@TeeVee98)",
754
754
  "\n[GATE 1] Scanning UTF-8 No BOM and Encoding Integrity across repository...",
755
755
  "[PASS] 100% UTF-8 No BOM & Clean Encoding verified across all source files.",
756
756
  "\n[GATE 2] Checking Path Portability (Zero absolute machine paths)...",
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "schema_version": "1.0.0",
3
- "updated_at": "2026-11-13T16:17:55.180336+00:00",
4
- "total_tools": 121,
5
- "stable_count": 121,
3
+ "updated_at": "2026-11-15T03:21:02.088778+00:00",
4
+ "total_tools": 125,
5
+ "stable_count": 125,
6
6
  "experimental_count": 0,
7
7
  "tools": [
8
8
  {
@@ -375,6 +375,21 @@
375
375
  ],
376
376
  "description": "Cross-Platform Token & Cost Auditor (Synapse-Hub)"
377
377
  },
378
+ {
379
+ "file": "tools/coverage_reporter.py",
380
+ "command": "python tools/coverage_reporter.py",
381
+ "category": "Auxiliary Utilities",
382
+ "owner_role": "orchestrator",
383
+ "status": "stable",
384
+ "risk_level": "read_only",
385
+ "inputs": [
386
+ "CLI options"
387
+ ],
388
+ "outputs": [
389
+ "Artifacts / Telemetry"
390
+ ],
391
+ "description": "tools/coverage_reporter.py — Standardized Coverage Metrics & Roadmap Evaluator"
392
+ },
378
393
  {
379
394
  "file": "tools/create_mock_docx.py",
380
395
  "command": "python tools/create_mock_docx.py",
@@ -1427,6 +1442,21 @@
1427
1442
  ],
1428
1443
  "description": "Zero-command automated project bootstrap tailoring AI agent rules to the target stack."
1429
1444
  },
1445
+ {
1446
+ "file": "tools/skill_canonical_digest.py",
1447
+ "command": "python tools/skill_canonical_digest.py",
1448
+ "category": "Auxiliary Utilities",
1449
+ "owner_role": "orchestrator",
1450
+ "status": "stable",
1451
+ "risk_level": "read_only",
1452
+ "inputs": [
1453
+ "CLI options"
1454
+ ],
1455
+ "outputs": [
1456
+ "Artifacts / Telemetry"
1457
+ ],
1458
+ "description": "tools/skill_canonical_digest.py — Single Source of Truth for Skill Canonical Digest & Lockfile Integrity"
1459
+ },
1430
1460
  {
1431
1461
  "file": "tools/skill_collision_guard.py",
1432
1462
  "command": "python tools/skill_collision_guard.py",
@@ -1579,6 +1609,21 @@
1579
1609
  ],
1580
1610
  "description": "tools/sync_agent_rules.py — Synchronizes AGENTS.md single-source rules to all AI bridges"
1581
1611
  },
1612
+ {
1613
+ "file": "tools/sync_skills_manifest.py",
1614
+ "command": "python tools/sync_skills_manifest.py",
1615
+ "category": "Auxiliary Utilities",
1616
+ "owner_role": "orchestrator",
1617
+ "status": "stable",
1618
+ "risk_level": "read_only",
1619
+ "inputs": [
1620
+ "CLI options"
1621
+ ],
1622
+ "outputs": [
1623
+ "Artifacts / Telemetry"
1624
+ ],
1625
+ "description": "tools/sync_skills_manifest.py — Synchronize Skill Policies & Frontmatter into Manifest"
1626
+ },
1582
1627
  {
1583
1628
  "file": "tools/telemetry_correlator.py",
1584
1629
  "command": "python tools/telemetry_correlator.py",
@@ -1821,6 +1866,21 @@
1821
1866
  ],
1822
1867
  "description": "Pre-check validator for Groovy scripts and POM keywords in enterprise test suites."
1823
1868
  },
1869
+ {
1870
+ "file": "tools/validate_skills_schema.py",
1871
+ "command": "python tools/validate_skills_schema.py",
1872
+ "category": "Auxiliary Utilities",
1873
+ "owner_role": "orchestrator",
1874
+ "status": "stable",
1875
+ "risk_level": "read_only",
1876
+ "inputs": [
1877
+ "CLI options"
1878
+ ],
1879
+ "outputs": [
1880
+ "Artifacts / Telemetry"
1881
+ ],
1882
+ "description": "tools/validate_skills_schema.py — Standalone Skill Schema & Policy Validator"
1883
+ },
1824
1884
  {
1825
1885
  "file": "tools/verify_all.py",
1826
1886
  "command": "python tools/verify_all.py",
package/tools/__init__.py CHANGED
@@ -17,7 +17,7 @@ Domain Packages:
17
17
  - tools.mcp: Model Context Protocol servers (core QA and Excel manipulation).
18
18
  """
19
19
 
20
- __version__ = "4.1.4"
20
+ __version__ = "4.2.0"
21
21
  __author__ = "Thế Vị (@TeeVee98)"
22
22
 
23
23
  # Expose domain packages
@@ -29,6 +29,13 @@ import urllib.parse
29
29
  import argparse
30
30
  from typing import Dict, Any, List, Optional
31
31
 
32
+ from pentest_scope_guard import (
33
+ PentestScopeGuard,
34
+ PentestRateLimiter,
35
+ PentestScopeError,
36
+ mask_secrets,
37
+ )
38
+
32
39
  # Enforce UTF-8 stdout encoding for Windows/macOS/Linux compatibility
33
40
  if hasattr(sys.stdout, 'reconfigure'):
34
41
  try:
@@ -73,6 +80,8 @@ ALARM_SEVERITY = {
73
80
  "SLA_TIMEOUT": "LOW",
74
81
  "AUTH_BYPASS": "CRITICAL",
75
82
  "CONNECTION_ERROR": "MEDIUM",
83
+ "DANGEROUS_REDIRECT_BLOCKED": "CRITICAL",
84
+ "SCOPE_BLOCKED": "CRITICAL",
76
85
  }
77
86
  SEVERITY_LEVELS = ["INFO", "LOW", "MEDIUM", "HIGH", "CRITICAL"]
78
87
 
@@ -103,7 +112,13 @@ class ApiFuzzer:
103
112
  timeout_sec: float = 10.0,
104
113
  sla_ms: float = 3000.0,
105
114
  verify_ssl: bool = True,
106
- insecure: bool = False
115
+ insecure: bool = False,
116
+ scope_guard: Optional[PentestScopeGuard] = None,
117
+ rate_limiter: Optional[PentestRateLimiter] = None,
118
+ max_requests: int = 500,
119
+ allow_internal: bool = False,
120
+ allow_loopback: bool = True,
121
+ consent: Any = False,
107
122
  ):
108
123
  self.base_url = base_url.rstrip("/")
109
124
  self.spec_path = spec_path_or_url
@@ -112,27 +127,15 @@ class ApiFuzzer:
112
127
  self.sla_ms = sla_ms
113
128
  self.insecure = insecure or (not verify_ssl)
114
129
  self.verify_ssl = not self.insecure
130
+ self.max_requests = max(1, int(max_requests))
131
+ self.consent = consent
115
132
 
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.")
133
+ # Wire unified scope guard and rate limiter (narrow loopback opt-in for local test harnesses)
134
+ self.scope_guard = scope_guard or PentestScopeGuard(
135
+ allow_internal=allow_internal,
136
+ allow_loopback=allow_loopback
137
+ )
138
+ self.rate_limiter = rate_limiter or self.scope_guard.rate_limiter
136
139
 
137
140
  # Prepare SSL context (support self-signed staging certificates via explicit --insecure flag)
138
141
  self.ssl_context = ssl.create_default_context()
@@ -141,90 +144,28 @@ class ApiFuzzer:
141
144
  self.ssl_context.check_hostname = False
142
145
  self.ssl_context.verify_mode = ssl.CERT_NONE
143
146
 
147
+ # Hardened transport opener with SafeRedirectHandler
148
+ self.opener = self.scope_guard.create_safe_opener(
149
+ timeout_sec=self.timeout_sec,
150
+ ssl_context=self.ssl_context
151
+ )
152
+
153
+ # Validate target base_url before proceeding (Fail-closed)
154
+ ok, reason = self.scope_guard.validate_target(self.base_url, actor="ApiFuzzer.__init__")
155
+ if not ok:
156
+ raise PermissionError(
157
+ f"[SAFETY FIREWALL - REJECTED] Target base URL '{self.base_url}' is not permitted by pentest scope guard: {reason}"
158
+ )
159
+
144
160
  @staticmethod
145
161
  def _is_safe_non_prod_host(host: str) -> bool:
146
162
  """
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'.
163
+ Deprecated: Replaced by PentestScopeGuard. Enforces strict allowlist validation
164
+ without loose subdomain heuristics.
149
165
  """
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
166
+ guard = PentestScopeGuard(allow_internal=True)
167
+ ok, _ = guard.validate_target(f"http://{host}")
168
+ return ok
228
169
 
229
170
  def load_spec(self) -> Dict[str, Any]:
230
171
  """Loads OpenAPI or Swagger specification from file or URL."""
@@ -256,10 +197,17 @@ class ApiFuzzer:
256
197
  }
257
198
 
258
199
  if self.spec_path.startswith(("http://", "https://")):
200
+ # Validate spec URL with scope guard before network dispatch
201
+ ok, reason = self.scope_guard.validate_target(self.spec_path, actor="ApiFuzzer.load_spec")
202
+ if not ok:
203
+ raise PermissionError(f"[PENTEST SCOPE GUARD] Disallowed OpenAPI spec URL '{self.spec_path}': {reason}")
259
204
  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)
205
+ try:
206
+ with self.opener.open(req, timeout=10.0) as resp:
207
+ raw = resp.read().decode("utf-8")
208
+ return json.loads(raw)
209
+ except PentestScopeError as pse:
210
+ raise PermissionError(f"[PENTEST SCOPE GUARD] Redirect blocked during load_spec: {pse}")
263
211
  else:
264
212
  if not os.path.exists(self.spec_path):
265
213
  raise FileNotFoundError(f"OpenAPI spec not found: {self.spec_path}")
@@ -432,7 +380,7 @@ class ApiFuzzer:
432
380
 
433
381
  return mutations
434
382
 
435
- def execute_request(self, mutation: Dict[str, Any], dry_run: bool = False) -> Dict[str, Any]:
383
+ def execute_request(self, mutation: Dict[str, Any], dry_run: bool = False, consent: Optional[Any] = None) -> Dict[str, Any]:
436
384
  """Dispatches HTTP mutation and evaluates the three-alarm Oracle."""
437
385
  url = f"{self.base_url}{mutation['path']}"
438
386
  method = mutation["method"]
@@ -445,7 +393,7 @@ class ApiFuzzer:
445
393
  return {
446
394
  "name": mutation["name"],
447
395
  "type": mutation["type"],
448
- "url": url,
396
+ "url": mask_secrets(url),
449
397
  "method": method,
450
398
  "status_code": 400 if mutation["type"] != "BASELINE" else 200,
451
399
  "duration_ms": 42.5,
@@ -455,6 +403,83 @@ class ApiFuzzer:
455
403
  "response_preview": '{"status": "handled_by_dry_run"}'
456
404
  }
457
405
 
406
+ # Consent verification: active live testing requires explicit consent before network dispatch
407
+ effective_consent = self.consent if consent is None else consent
408
+ if not self.scope_guard.verify_consent(effective_consent):
409
+ return {
410
+ "name": mutation.get("name", "unnamed"),
411
+ "type": mutation.get("type", "UNKNOWN"),
412
+ "url": mask_secrets(url),
413
+ "method": method,
414
+ "status_code": -5,
415
+ "duration_ms": 0.0,
416
+ "verdict": "FAIL",
417
+ "severity": "CRITICAL",
418
+ "alarms": ["CONSENT_REQUIRED: Active API request rejected. Explicit consent required (--confirm-pentest-scope, consent=True, or scoped consent dict)."],
419
+ "response_preview": "Active request blocked: missing consent."
420
+ }
421
+
422
+ # Scoped consent check: verify target, method, path if specified in consent dict
423
+ if isinstance(effective_consent, dict):
424
+ c_target = effective_consent.get("target") or effective_consent.get("base_url")
425
+ if c_target and not (url.startswith(c_target.rstrip("/")) or self.base_url == c_target.rstrip("/")):
426
+ return {
427
+ "name": mutation.get("name", "unnamed"),
428
+ "type": mutation.get("type", "UNKNOWN"),
429
+ "url": mask_secrets(url),
430
+ "method": method,
431
+ "status_code": -5,
432
+ "duration_ms": 0.0,
433
+ "verdict": "FAIL",
434
+ "severity": "CRITICAL",
435
+ "alarms": [f"CONSENT_MISMATCH: Scoped consent target '{c_target}' does not authorize target URL '{mask_secrets(url)}'."],
436
+ "response_preview": "Active request blocked: consent target mismatch."
437
+ }
438
+ c_method = effective_consent.get("method")
439
+ if c_method and c_method.upper() != method.upper():
440
+ return {
441
+ "name": mutation.get("name", "unnamed"),
442
+ "type": mutation.get("type", "UNKNOWN"),
443
+ "url": mask_secrets(url),
444
+ "method": method,
445
+ "status_code": -5,
446
+ "duration_ms": 0.0,
447
+ "verdict": "FAIL",
448
+ "severity": "CRITICAL",
449
+ "alarms": [f"CONSENT_MISMATCH: Scoped consent method '{c_method}' does not authorize mutation method '{method}'."],
450
+ "response_preview": "Active request blocked: consent method mismatch."
451
+ }
452
+ c_path = effective_consent.get("path")
453
+ if c_path and c_path != mutation.get("path"):
454
+ return {
455
+ "name": mutation.get("name", "unnamed"),
456
+ "type": mutation.get("type", "UNKNOWN"),
457
+ "url": mask_secrets(url),
458
+ "method": method,
459
+ "status_code": -5,
460
+ "duration_ms": 0.0,
461
+ "verdict": "FAIL",
462
+ "severity": "CRITICAL",
463
+ "alarms": [f"CONSENT_MISMATCH: Scoped consent path '{c_path}' does not authorize mutation path '{mutation.get('path')}'."],
464
+ "response_preview": "Active request blocked: consent path mismatch."
465
+ }
466
+
467
+ # Check target URL with PentestScopeGuard before network dispatch (Consent NEVER bypasses host scope guard)
468
+ ok, scope_reason = self.scope_guard.validate_target(url, actor="ApiFuzzer.execute_request")
469
+ if not ok:
470
+ return {
471
+ "name": mutation["name"],
472
+ "type": mutation["type"],
473
+ "url": mask_secrets(url),
474
+ "method": method,
475
+ "status_code": -3,
476
+ "duration_ms": 0.0,
477
+ "verdict": "FAIL",
478
+ "severity": "CRITICAL",
479
+ "alarms": [f"SCOPE_BLOCKED: Request target blocked by pentest scope guard: {scope_reason}"],
480
+ "response_preview": mask_secrets(scope_reason)
481
+ }
482
+
458
483
  req = urllib.request.Request(
459
484
  url=url,
460
485
  data=body_data,
@@ -466,11 +491,16 @@ class ApiFuzzer:
466
491
  status_code = 0
467
492
  response_body = ""
468
493
  duration_ms = 0.0
494
+ redirect_blocked = False
469
495
 
470
496
  try:
471
- with urllib.request.urlopen(req, context=self.ssl_context, timeout=self.timeout_sec) as resp: # nosec B310
497
+ with self.opener.open(req, timeout=self.timeout_sec) as resp:
472
498
  status_code = resp.getcode()
473
499
  response_body = resp.read().decode("utf-8", errors="replace")
500
+ except PentestScopeError as pse:
501
+ status_code = -4
502
+ response_body = str(pse)
503
+ redirect_blocked = True
474
504
  except urllib.error.HTTPError as he:
475
505
  status_code = he.code
476
506
  try:
@@ -491,6 +521,9 @@ class ApiFuzzer:
491
521
  # ----------------------------------------------------
492
522
  alarms = []
493
523
 
524
+ if redirect_blocked:
525
+ alarms.append(f"DANGEROUS_REDIRECT_BLOCKED: {response_body}")
526
+
494
527
  # Alarm 1: HTTP 500 / 502 / 503 Internal Server Error
495
528
  if status_code in (500, 502, 503):
496
529
  alarms.append(f"HTTP_{status_code}_SERVER_CRASH: Unhandled backend exception / server panic")
@@ -512,7 +545,7 @@ class ApiFuzzer:
512
545
 
513
546
  # Alarm 5: Target unreachable - an endpoint that could not be tested
514
547
  # must NEVER be reported as PASS (Truth Anchor discipline).
515
- if status_code < 0:
548
+ if status_code < 0 and not redirect_blocked:
516
549
  alarms.append("CONNECTION_ERROR: Target unreachable or transport failure - endpoint could not be verified")
517
550
 
518
551
  verdict = "FAIL" if alarms else "PASS"
@@ -526,18 +559,27 @@ class ApiFuzzer:
526
559
  return {
527
560
  "name": mutation["name"],
528
561
  "type": mutation["type"],
529
- "url": url,
562
+ "url": mask_secrets(url),
530
563
  "method": method,
531
564
  "status_code": status_code,
532
565
  "duration_ms": duration_ms,
533
566
  "verdict": verdict,
534
567
  "severity": severity,
535
568
  "alarms": alarms,
536
- "response_preview": response_body[:300]
569
+ "response_preview": mask_secrets(response_body[:300])
537
570
  }
538
571
 
539
- def run_fuzz_suite(self, dry_run: bool = False) -> Dict[str, Any]:
572
+ def run_fuzz_suite(self, dry_run: bool = False, consent: Any = False) -> Dict[str, Any]:
540
573
  """Runs the complete fuzzing suite against all extracted targets."""
574
+ # Consent validation: active live testing requires explicit consent
575
+ if not dry_run:
576
+ has_consent = self.scope_guard.verify_consent(consent)
577
+ if not has_consent:
578
+ raise PermissionError(
579
+ "Active API fuzzing requires explicit consent. Set PENTEST_CONSENT_ACKNOWLEDGED=1, "
580
+ "pass --confirm-pentest-scope, or set dry_run=True to preview safely."
581
+ )
582
+
541
583
  spec = self.load_spec()
542
584
  targets = self.extract_fuzz_targets(spec)
543
585
 
@@ -545,23 +587,36 @@ class ApiFuzzer:
545
587
  for t in targets:
546
588
  all_mutations.extend(self.generate_mutations(t))
547
589
 
590
+ total_generated = len(all_mutations)
591
+ volume_capped = False
592
+ if len(all_mutations) > self.max_requests:
593
+ all_mutations = all_mutations[:self.max_requests]
594
+ volume_capped = True
595
+
548
596
  results = []
549
597
  total_failures = 0
550
598
 
551
599
  print(f"\n{BOLD}{CYAN}======================================================================{RESET}")
552
600
  print(f"{BOLD}{CYAN} ENTERPRISE AUTONOMOUS API FUZZING & CHAOS BREAKER {RESET}")
553
601
  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'}")
602
+ print(f" Target Base URL : {mask_secrets(self.base_url)}")
603
+ print(f" Spec Source : {mask_secrets(self.spec_path or 'Default Archetype')}")
556
604
  print(f" Total Endpoints : {len(targets)}")
557
- print(f" Total Mutations : {len(all_mutations)}")
605
+ print(f" Total Mutations : {len(all_mutations)} (capped from {total_generated})" if volume_capped else f" Total Mutations : {len(all_mutations)}")
558
606
  print(f" SLA Threshold : {self.sla_ms} ms")
607
+ print(f" Rate Limit Max : {self.rate_limiter.max_req_per_sec} req/s")
559
608
  print(f" Mode : {'DRY-RUN (Air-Gapped / Deterministic)' if dry_run else 'LIVE STAGING ATTACK'}\n")
560
609
 
561
610
  for idx, m in enumerate(all_mutations, start=1):
562
- res = self.execute_request(m, dry_run=dry_run)
611
+ if not dry_run:
612
+ self.rate_limiter.acquire()
613
+
614
+ res = self.execute_request(m, dry_run=dry_run, consent=consent if not dry_run else None)
563
615
  results.append(res)
564
616
 
617
+ if not dry_run and res["status_code"] > 0:
618
+ self.rate_limiter.record_response(res["status_code"])
619
+
565
620
  status_str = f"{GREEN}PASS{RESET}" if res["verdict"] == "PASS" else f"{RED}ALARM{RESET}"
566
621
  sys.stdout.write(f" [{idx:03d}/{len(all_mutations):03d}] {status_str} | HTTP {res['status_code']} ({res['duration_ms']}ms) | {m['name']}\n")
567
622
  if res["alarms"]:
@@ -570,10 +625,13 @@ class ApiFuzzer:
570
625
  print(f" 👉 {RED}{BOLD}[DEFECT]{RESET} {alarm}")
571
626
 
572
627
  scorecard = {
573
- "base_url": self.base_url,
628
+ "base_url": mask_secrets(self.base_url),
574
629
  "timestamp": time.strftime("%Y-%m-%d %H:%M:%S"),
575
630
  "mode": "ACTIVE",
576
631
  "total_mutations": len(all_mutations),
632
+ "total_generated": total_generated,
633
+ "volume_capped": volume_capped,
634
+ "max_requests": self.max_requests,
577
635
  "passed": len(all_mutations) - total_failures,
578
636
  "failed": total_failures,
579
637
  "sla_ms": self.sla_ms,
@@ -727,6 +785,8 @@ def main():
727
785
  help="active = live fuzzing (default); passive = offline spec audit, zero traffic")
728
786
  parser.add_argument("--insecure", action="store_true", help="Explicitly bypass TLS certificate verification (for staging/self-signed certs)")
729
787
  parser.add_argument("--dry-run", action="store_true", help="Simulate mutation generation without live requests")
788
+ parser.add_argument("--max-requests", type=int, default=500, help="Max requests volume ceiling (default: 500)")
789
+ parser.add_argument("--confirm-pentest-scope", action="store_true", help="Explicit human consent acknowledgement for live fuzzing")
730
790
  parser.add_argument("--json", action="store_true", help="Output summary in JSON format")
731
791
 
732
792
  args = parser.parse_args()
@@ -740,7 +800,8 @@ def main():
740
800
  spec_path_or_url=args.spec,
741
801
  headers=headers,
742
802
  sla_ms=args.sla_ms,
743
- insecure=args.insecure
803
+ insecure=args.insecure,
804
+ max_requests=args.max_requests
744
805
  )
745
806
 
746
807
  if args.mode == "passive":
@@ -751,7 +812,7 @@ def main():
751
812
  blocking = int(severity_dict.get("HIGH", 0)) + int(severity_dict.get("CRITICAL", 0))
752
813
  return 1 if blocking > 0 else 0
753
814
 
754
- scorecard = fuzzer.run_fuzz_suite(dry_run=args.dry_run)
815
+ scorecard = fuzzer.run_fuzz_suite(dry_run=args.dry_run, consent=args.confirm_pentest_scope)
755
816
  if args.json:
756
817
  print(json.dumps(scorecard, indent=2))
757
818