@teevee98/synapse-hub 4.2.0 → 4.2.2

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 (109) hide show
  1. package/.agents/skills/01-web-automation/auth-session-and-cookie-manager/SKILL.md +46 -2
  2. package/.agents/skills/01-web-automation/bats-testing-patterns/SKILL.md +49 -4
  3. package/.agents/skills/01-web-automation/clean-pom-crafter/SKILL.md +56 -66
  4. package/.agents/skills/01-web-automation/e2e-testing-patterns/SKILL.md +48 -3
  5. package/.agents/skills/01-web-automation/katalon-cli-runner/SKILL.md +56 -11
  6. package/.agents/skills/01-web-automation/lam-script-generator/SKILL.md +49 -7
  7. package/.agents/skills/01-web-automation/mobile-appium-som/SKILL.md +54 -11
  8. package/.agents/skills/01-web-automation/playwright-live-interaction/SKILL.md +48 -90
  9. package/.agents/skills/01-web-automation/playwright-webapp-testing/SKILL.md +53 -10
  10. package/.agents/skills/01-web-automation/web-agent-gym-benchmarking/SKILL.md +44 -3
  11. package/.agents/skills/02-test-design/architecture-decision-records/SKILL.md +49 -8
  12. package/.agents/skills/02-test-design/gherkin-to-suite/SKILL.md +49 -8
  13. package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +49 -7
  14. package/.agents/skills/02-test-design/review-spec/SKILL.md +46 -5
  15. package/.agents/skills/02-test-design/tot-exploratory-testing/SKILL.md +44 -3
  16. package/.agents/skills/03-api-and-contracts/api-network-mocking-interception/SKILL.md +50 -4
  17. package/.agents/skills/03-api-and-contracts/api-spec-to-e2e-matrix/SKILL.md +47 -6
  18. package/.agents/skills/03-api-and-contracts/consumer-driven-contract-testing/SKILL.md +79 -34
  19. package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/SKILL.md +47 -4
  20. package/.agents/skills/04-performance-and-load/lean-impact-scoreboard/SKILL.md +46 -5
  21. package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/SKILL.md +44 -2
  22. package/.agents/skills/05-security-and-compliance/security-dast-sentinel/SKILL.md +57 -13
  23. package/.agents/skills/05-security-and-compliance/skillspector-security-guard/SKILL.md +45 -4
  24. package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +48 -3
  25. package/.agents/skills/06-healing-and-resilience/agentless-qa-repair/SKILL.md +45 -4
  26. package/.agents/skills/06-healing-and-resilience/antigravity-test-sentinel/SKILL.md +47 -5
  27. package/.agents/skills/06-healing-and-resilience/failure-autopsy-and-healing/SKILL.md +48 -7
  28. package/.agents/skills/06-healing-and-resilience/flaky-test-sentinel-and-quarantine/SKILL.md +54 -23
  29. package/.agents/skills/06-healing-and-resilience/self-healing-locator/SKILL.md +46 -5
  30. package/.agents/skills/06-healing-and-resilience/systematic-debugging/SKILL.md +50 -9
  31. package/.agents/skills/06-healing-and-resilience/test-driven-development/SKILL.md +52 -11
  32. package/.agents/skills/06-healing-and-resilience/verification-before-completion/SKILL.md +52 -11
  33. package/.agents/skills/06-healing-and-resilience/visual-regression-sentinel/SKILL.md +47 -4
  34. package/.agents/skills/07-data-and-state/db-state-verifier-and-seeder/SKILL.md +50 -4
  35. package/.agents/skills/07-data-and-state/file-and-report-validator/SKILL.md +47 -3
  36. package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +52 -4
  37. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/SKILL.md +51 -10
  38. package/.agents/skills/08-code-quality/graphify-impact-analyzer/SKILL.md +78 -34
  39. package/.agents/skills/08-code-quality/graphify-impact-analyzer/examples/dependency_blast_radius.json +3 -4
  40. package/.agents/skills/08-code-quality/lean-code-ladder/SKILL.md +49 -9
  41. package/.agents/skills/08-code-quality/repo-quality-audit/SKILL.md +45 -5
  42. package/.agents/skills/08-code-quality/senior-code-review/SKILL.md +48 -6
  43. package/.agents/skills/08-code-quality/surgical-coding-principles/SKILL.md +49 -9
  44. package/.agents/skills/08-code-quality/technical-debt-harvester/SKILL.md +47 -4
  45. package/.agents/skills/09-ci-and-devops/github-actions-templates/SKILL.md +48 -16
  46. package/.agents/skills/09-ci-and-devops/github-actions-templates/examples/matrix_test_pipeline.yml +2 -1
  47. package/.agents/skills/10-agent-orchestration/actor-qa-swarm/SKILL.md +44 -3
  48. package/.agents/skills/10-agent-orchestration/agent-orchestration-multi-agent-optimize/SKILL.md +47 -6
  49. package/.agents/skills/10-agent-orchestration/event-stream-qa-orchestrator/SKILL.md +44 -3
  50. package/.agents/skills/10-agent-orchestration/persistent-planning-files/SKILL.md +52 -12
  51. package/.agents/skills/10-agent-orchestration/qa-memory-os/SKILL.md +45 -4
  52. package/.agents/skills/11-ai-and-prompting/meta-prompt-crafter/SKILL.md +51 -9
  53. package/.agents/skills/11-ai-and-prompting/mipro-prompt-compiler/SKILL.md +44 -3
  54. package/.agents/skills/11-ai-and-prompting/qa-aci-interface/SKILL.md +44 -3
  55. package/.agents/skills/11-ai-and-prompting/token-and-context-optimizer/SKILL.md +49 -8
  56. package/.cursor/rules/synapse-qa.mdc +20 -7
  57. package/.cursorrules +19 -5
  58. package/.windsurfrules +18 -3
  59. package/AGENTS.md +51 -65
  60. package/CLAUDE.md +38 -24
  61. package/README.en.md +2 -2
  62. package/README.md +2 -2
  63. package/agentskills.json +1 -1
  64. package/docs/ARCHITECTURE.en.md +1 -1
  65. package/docs/ARCHITECTURE.md +1 -1
  66. package/docs/CLIENT_SUPPORT_MATRIX.md +44 -0
  67. package/docs/SIDE_EFFECTING_TOOLS_INVENTORY.md +233 -0
  68. package/package.json +1 -1
  69. package/plugin.json +1 -1
  70. package/skills_manifest.json +1 -1
  71. package/synapse.config.json +1 -1
  72. package/templates/ai_bridges/CLAUDE.md +29 -26
  73. package/templates/ai_bridges/copilot-instructions.md +14 -5
  74. package/templates/ai_bridges/cursor_synapse_qa.mdc +16 -7
  75. package/templates/ai_bridges/windsurfrules +14 -3
  76. package/tools/TOOLS_RUNBOOK.md +1 -1
  77. package/tools/__init__.py +1 -1
  78. package/tools/api_fuzzer.py +295 -41
  79. package/tools/benchmark_swarm_context.py +11 -4
  80. package/tools/browser_helpers.js +2 -2
  81. package/tools/bump_version.py +2 -2
  82. package/tools/cli.py +4 -4
  83. package/tools/core/bm25_retriever.py +1 -1
  84. package/tools/core/i18n.py +1 -1
  85. package/tools/core/provider_usage_adapter.py +66 -0
  86. package/tools/core/token_estimator.py +39 -1
  87. package/tools/count_tokens.py +2 -2
  88. package/tools/dashboard_generator.py +8 -8
  89. package/tools/db_sandbox.py +182 -43
  90. package/tools/distill_log.py +1 -1
  91. package/tools/distill_skill.py +17 -2
  92. package/tools/git_pre_commit_guard.py +190 -1
  93. package/tools/hub_publisher.py +2 -12
  94. package/tools/mcp_docx_server.py +1 -1
  95. package/tools/mcp_excel_server.py +1 -1
  96. package/tools/mcp_server.py +33 -5
  97. package/tools/micro_mutator.py +30 -1
  98. package/tools/pentest_scope_guard.py +288 -15
  99. package/tools/project_state.py +29 -5
  100. package/tools/reversible_sandbox.py +58 -13
  101. package/tools/rules_router.py +80 -27
  102. package/tools/skill_canonical_digest.py +60 -2
  103. package/tools/sync_agent_rules.py +187 -61
  104. package/tools/task_memory_manager.py +16 -1
  105. package/tools/ui_server.py +3 -1
  106. package/tools/update_sentinel.py +3 -3
  107. package/tools/validate_skills_schema.py +349 -56
  108. package/tools/verify_all.py +98 -4
  109. package/tools/welcome_page.py +1 -1
@@ -35,6 +35,9 @@ import urllib.error
35
35
  import http.client
36
36
  import ssl
37
37
  import uuid
38
+ import secrets
39
+ import fnmatch
40
+ from dataclasses import dataclass
38
41
  from datetime import datetime, timezone
39
42
  from typing import List, Tuple, Optional, Set, Any, Dict
40
43
 
@@ -115,6 +118,264 @@ class PentestScopeError(RuntimeError):
115
118
  pass
116
119
 
117
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
+
118
379
  class PentestRateLimiter:
119
380
  """Enforces max requests/second, concurrency cap, and 5xx/429 circuit breaking."""
120
381
 
@@ -318,6 +579,7 @@ class PentestScopeGuard:
318
579
  self.audit_log_path = audit_log_path or DEFAULT_AUDIT_LOG
319
580
  self.rate_limiter = rate_limiter or PentestRateLimiter()
320
581
  self._pinned_ips: Dict[str, str] = {}
582
+ self.consumed_nonces: Set[str] = set()
321
583
 
322
584
  hosts = set()
323
585
  if allowed_hosts is not None:
@@ -563,23 +825,34 @@ class PentestScopeGuard:
563
825
  return False, reason
564
826
  return True, f"Redirect to '{redirect_url}' is within authorized scope."
565
827
 
566
- def verify_consent(self, consent_flag: Any = False, impact_summary: str = "") -> bool:
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:
567
837
  """
568
- Verifies that human consent has been explicitly granted for active testing.
569
- Accepts:
570
- - Explicit consent parameter (consent_flag=True or scoped dict)
571
- - Environment variable PENTEST_CONSENT_ACKNOWLEDGED=1 (or 'true', 'yes')
572
- - CLI flag --confirm-pentest-scope
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).
573
842
  """
574
- if isinstance(consent_flag, dict):
575
- return bool(consent_flag.get("confirmed", True) and consent_flag)
576
- if bool(consent_flag):
577
- return True
578
- env_consent = os.environ.get("PENTEST_CONSENT_ACKNOWLEDGED", "").strip().lower()
579
- if env_consent in ("1", "true", "yes"):
580
- return True
581
- if "--confirm-pentest-scope" in sys.argv:
582
- return True
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
+ )
583
856
  return False
584
857
 
585
858
  def create_safe_opener(
@@ -36,6 +36,7 @@ def init_state(target_dir, goal="Initial Autonomous Setup"):
36
36
  if os.path.exists(state_file):
37
37
  return state_file
38
38
 
39
+ os.makedirs(os.path.dirname(os.path.abspath(state_file)), exist_ok=True)
39
40
  project_name = os.path.basename(os.path.abspath(target_dir))
40
41
  timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
41
42
 
@@ -166,9 +167,32 @@ def read_state(target_dir):
166
167
 
167
168
  if __name__ == "__main__":
168
169
  if len(sys.argv) > 1 and sys.argv[1] in ("-h", "--help"):
169
- print("Usage: python3 tools/project_state.py [target_dir]")
170
- print("Initializes or verifies the rolling-window PROJECT_STATE.md anchor in target directory.")
170
+ print("Usage: python3 tools/project_state.py [status|init|update] [target_dir]")
171
+ print("Initializes, verifies, or inspects the rolling-window PROJECT_STATE.md anchor.")
171
172
  sys.exit(0)
172
- target = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
173
- sf = init_state(target)
174
- print(f"Project state anchor initialized at: {sf}")
173
+
174
+ arg1 = sys.argv[1] if len(sys.argv) > 1 else "status"
175
+
176
+ if arg1 == "status":
177
+ target = sys.argv[2] if len(sys.argv) > 2 else os.getcwd()
178
+ state = read_state(target)
179
+ if state is None:
180
+ init_state(target)
181
+ state = read_state(target)
182
+ print(state)
183
+ sys.exit(0)
184
+ elif arg1 == "init":
185
+ target = sys.argv[2] if len(sys.argv) > 2 else os.getcwd()
186
+ sf = init_state(target)
187
+ print(f"Project state anchor initialized at: {sf}")
188
+ sys.exit(0)
189
+ elif arg1 == "update":
190
+ target = sys.argv[2] if len(sys.argv) > 2 else os.getcwd()
191
+ sf = update_state(target)
192
+ print(f"Project state anchor updated at: {sf}")
193
+ sys.exit(0)
194
+ else:
195
+ # Default: treat argument as target_dir
196
+ target = arg1
197
+ sf = init_state(target)
198
+ print(f"Project state anchor initialized at: {sf}")
@@ -33,10 +33,16 @@ import atexit
33
33
  import signal
34
34
  import weakref
35
35
  import threading
36
+ import tempfile
36
37
  import subprocess
37
38
  from dataclasses import dataclass, field
38
39
  from typing import List, Optional, Dict, Any
39
40
 
41
+ from pentest_scope_guard import (
42
+ resolve_contained_path,
43
+ PathContainmentError,
44
+ )
45
+
40
46
  # Enforce UTF-8 stdout encoding for Windows console compatibility
41
47
  if hasattr(sys.stdout, 'reconfigure'):
42
48
  try:
@@ -84,10 +90,16 @@ class ReversibleAction:
84
90
  class ExecutionSandbox:
85
91
  """Manages an undo stack of stateful mutations with WAL persistence for guaranteed cleanup."""
86
92
 
87
- def __init__(self, auto_rollback_on_exit: bool = True, wal_path: Optional[str] = None):
93
+ def __init__(
94
+ self,
95
+ auto_rollback_on_exit: bool = True,
96
+ wal_path: Optional[str] = None,
97
+ sandbox_root: Optional[str] = None
98
+ ):
88
99
  self.undo_stack: List[ReversibleAction] = []
89
100
  self.failed_actions: List[ReversibleAction] = []
90
101
  self.auto_rollback_on_exit = auto_rollback_on_exit
102
+ self.sandbox_root = os.path.realpath(os.path.abspath(sandbox_root)) if sandbox_root else None
91
103
  self.wal_path = wal_path if wal_path is not None else _resolve_wal_path()
92
104
  if self.wal_path:
93
105
  try:
@@ -97,6 +109,31 @@ class ExecutionSandbox:
97
109
  self.wal_path = None
98
110
  _ACTIVE_SANDBOXES.add(self)
99
111
 
112
+ def _validate_contained_path(self, target_path: str) -> str:
113
+ """Ensures file or directory path is strictly contained within sandbox roots."""
114
+ if self.sandbox_root:
115
+ return resolve_contained_path(self.sandbox_root, target_path)
116
+
117
+ allowed_roots = [
118
+ os.path.realpath(os.path.abspath(os.getcwd())),
119
+ os.path.realpath(os.path.abspath(QA_HUB_ROOT)),
120
+ os.path.realpath(os.path.abspath(tempfile.gettempdir())),
121
+ ]
122
+
123
+ contained = None
124
+ last_err = None
125
+ for root in allowed_roots:
126
+ try:
127
+ contained = resolve_contained_path(root, target_path)
128
+ break
129
+ except PathContainmentError as pce:
130
+ last_err = pce
131
+ continue
132
+
133
+ if contained is None:
134
+ raise last_err or PathContainmentError(f"Path '{target_path}' escapes sandbox root containment.")
135
+ return contained
136
+
100
137
  def _append_wal(self, action: ReversibleAction):
101
138
  """Persists a pending undo action to disk before side-effects complete."""
102
139
  if not self.wal_path:
@@ -233,21 +270,29 @@ class ExecutionSandbox:
233
270
 
234
271
  if cmd.startswith("FILE_DELETE:"):
235
272
  fpath = cmd.split(":", 1)[1].strip()
236
- if os.path.exists(fpath):
237
- try:
238
- os.remove(fpath)
239
- except OSError as e:
240
- success = False
241
- err_msg = str(e)
273
+ try:
274
+ contained_fpath = self._validate_contained_path(fpath)
275
+ if os.path.exists(contained_fpath):
276
+ os.remove(contained_fpath)
277
+ except PathContainmentError as pce:
278
+ success = False
279
+ err_msg = str(pce)
280
+ except OSError as e:
281
+ success = False
282
+ err_msg = str(e)
242
283
  elif cmd.startswith("DIR_DELETE:"):
243
284
  dpath = cmd.split(":", 1)[1].strip()
244
- if os.path.isdir(dpath):
245
- try:
285
+ try:
286
+ contained_dpath = self._validate_contained_path(dpath)
287
+ if os.path.isdir(contained_dpath):
246
288
  import shutil
247
- shutil.rmtree(dpath, ignore_errors=True)
248
- except Exception as e:
249
- success = False
250
- err_msg = str(e)
289
+ shutil.rmtree(contained_dpath, ignore_errors=True)
290
+ except PathContainmentError as pce:
291
+ success = False
292
+ err_msg = str(pce)
293
+ except Exception as e:
294
+ success = False
295
+ err_msg = str(e)
251
296
  elif cmd in ("NOOP", ":"):
252
297
  success = True
253
298
  elif cmd: