@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.
- package/.agents/rules/git-push-protocol.md +2 -2
- package/.agents/skills/01-web-automation/auth-session-and-cookie-manager/SKILL.md +52 -3
- package/.agents/skills/01-web-automation/bats-testing-patterns/SKILL.md +55 -5
- package/.agents/skills/01-web-automation/clean-pom-crafter/SKILL.md +62 -67
- package/.agents/skills/01-web-automation/e2e-testing-patterns/SKILL.md +54 -4
- package/.agents/skills/01-web-automation/katalon-cli-runner/SKILL.md +62 -12
- package/.agents/skills/01-web-automation/lam-script-generator/SKILL.md +55 -8
- package/.agents/skills/01-web-automation/mobile-appium-som/SKILL.md +60 -12
- package/.agents/skills/01-web-automation/mobile-appium-som/examples/BaseScreen.java +2 -2
- package/.agents/skills/01-web-automation/mobile-appium-som/examples/LoginScreen.java +2 -2
- package/.agents/skills/01-web-automation/mobile-appium-som/examples/TC_MobileLogin.java +2 -2
- package/.agents/skills/01-web-automation/playwright-live-interaction/SKILL.md +54 -91
- package/.agents/skills/01-web-automation/playwright-webapp-testing/SKILL.md +59 -11
- package/.agents/skills/01-web-automation/web-agent-gym-benchmarking/SKILL.md +50 -4
- package/.agents/skills/02-test-design/architecture-decision-records/SKILL.md +55 -9
- package/.agents/skills/02-test-design/gherkin-to-suite/SKILL.md +55 -9
- package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +55 -8
- package/.agents/skills/02-test-design/review-spec/SKILL.md +50 -6
- package/.agents/skills/02-test-design/tot-exploratory-testing/SKILL.md +50 -4
- package/.agents/skills/03-api-and-contracts/api-network-mocking-interception/SKILL.md +56 -5
- package/.agents/skills/03-api-and-contracts/api-spec-to-e2e-matrix/SKILL.md +53 -7
- package/.agents/skills/03-api-and-contracts/consumer-driven-contract-testing/SKILL.md +86 -36
- package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/SKILL.md +54 -6
- package/.agents/skills/04-performance-and-load/lean-impact-scoreboard/SKILL.md +50 -6
- package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/SKILL.md +50 -3
- package/.agents/skills/05-security-and-compliance/security-dast-sentinel/SKILL.md +63 -14
- package/.agents/skills/05-security-and-compliance/skillspector-security-guard/SKILL.md +51 -5
- package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +54 -4
- package/.agents/skills/06-healing-and-resilience/agentless-qa-repair/SKILL.md +51 -5
- package/.agents/skills/06-healing-and-resilience/antigravity-test-sentinel/SKILL.md +53 -6
- package/.agents/skills/06-healing-and-resilience/failure-autopsy-and-healing/SKILL.md +54 -8
- package/.agents/skills/06-healing-and-resilience/flaky-test-sentinel-and-quarantine/SKILL.md +60 -24
- package/.agents/skills/06-healing-and-resilience/self-healing-locator/SKILL.md +52 -6
- package/.agents/skills/06-healing-and-resilience/systematic-debugging/SKILL.md +56 -10
- package/.agents/skills/06-healing-and-resilience/test-driven-development/SKILL.md +58 -12
- package/.agents/skills/06-healing-and-resilience/verification-before-completion/SKILL.md +58 -12
- package/.agents/skills/06-healing-and-resilience/visual-regression-sentinel/SKILL.md +53 -5
- package/.agents/skills/07-data-and-state/db-state-verifier-and-seeder/SKILL.md +56 -5
- package/.agents/skills/07-data-and-state/file-and-report-validator/SKILL.md +53 -4
- package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +58 -5
- package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/SKILL.md +57 -11
- package/.agents/skills/08-code-quality/graphify-impact-analyzer/SKILL.md +83 -34
- package/.agents/skills/08-code-quality/graphify-impact-analyzer/examples/dependency_blast_radius.json +3 -4
- package/.agents/skills/08-code-quality/lean-code-ladder/SKILL.md +55 -10
- package/.agents/skills/08-code-quality/repo-quality-audit/SKILL.md +49 -6
- package/.agents/skills/08-code-quality/senior-code-review/SKILL.md +52 -7
- package/.agents/skills/08-code-quality/surgical-coding-principles/SKILL.md +55 -10
- package/.agents/skills/08-code-quality/technical-debt-harvester/SKILL.md +51 -5
- package/.agents/skills/09-ci-and-devops/github-actions-templates/SKILL.md +54 -17
- package/.agents/skills/09-ci-and-devops/github-actions-templates/examples/matrix_test_pipeline.yml +2 -1
- package/.agents/skills/10-agent-orchestration/actor-qa-swarm/SKILL.md +50 -4
- package/.agents/skills/10-agent-orchestration/agent-orchestration-multi-agent-optimize/SKILL.md +53 -7
- package/.agents/skills/10-agent-orchestration/event-stream-qa-orchestrator/SKILL.md +50 -4
- package/.agents/skills/10-agent-orchestration/persistent-planning-files/SKILL.md +58 -13
- package/.agents/skills/10-agent-orchestration/qa-memory-os/SKILL.md +51 -5
- package/.agents/skills/11-ai-and-prompting/meta-prompt-crafter/SKILL.md +57 -10
- package/.agents/skills/11-ai-and-prompting/mipro-prompt-compiler/SKILL.md +50 -4
- package/.agents/skills/11-ai-and-prompting/qa-aci-interface/SKILL.md +50 -4
- package/.agents/skills/11-ai-and-prompting/token-and-context-optimizer/SKILL.md +55 -9
- package/.cursor/rules/synapse-qa.mdc +20 -7
- package/.cursorrules +19 -5
- package/.windsurfrules +18 -3
- package/AGENTS.md +51 -59
- package/CLAUDE.md +38 -24
- package/LICENSE +5 -5
- package/NOTICE +1 -1
- package/README.en.md +4 -4
- package/README.md +4 -4
- package/agentskills.json +1 -1
- package/docs/ARCHITECTURE.en.md +2 -2
- package/docs/ARCHITECTURE.md +11 -2
- package/docs/CLIENT_SUPPORT_MATRIX.md +44 -0
- package/docs/CLI_REFERENCE.en.md +6 -4
- package/docs/CLI_REFERENCE.md +1 -1
- package/docs/CONTRIBUTING.en.md +1 -1
- package/docs/CONTRIBUTING.md +2 -2
- package/docs/SIDE_EFFECTING_TOOLS_INVENTORY.md +233 -0
- package/docs/TOOL_CATALOG.md +6 -2
- package/docs/research/agent_skill_training_analysis.md +1 -1
- package/package.json +1 -1
- package/plugin.json +1 -1
- package/skills_manifest.json +320 -55
- package/synapse.config.json +1 -1
- package/templates/ai_bridges/CLAUDE.md +29 -26
- package/templates/ai_bridges/copilot-instructions.md +14 -5
- package/templates/ai_bridges/cursor_synapse_qa.mdc +16 -7
- package/templates/ai_bridges/windsurfrules +14 -3
- package/templates/ui/index.html +2 -2
- package/tools/TOOLS_RUNBOOK.md +1 -1
- package/tools/TOOL_CATALOG.json +63 -3
- package/tools/__init__.py +1 -1
- package/tools/api_fuzzer.py +447 -132
- package/tools/author_integrity.py +121 -11
- package/tools/benchmark_swarm_context.py +130 -22
- package/tools/break_ui_generator.py +233 -0
- package/tools/browser_helpers.js +2 -2
- package/tools/check_version_sync.py +18 -50
- package/tools/cli.py +110 -19
- package/tools/core/bm25_retriever.py +218 -0
- package/tools/core/i18n.py +5 -5
- package/tools/core/provider_usage_adapter.py +383 -0
- package/tools/core/token_estimator.py +81 -15
- package/tools/count_tokens.py +7 -2
- package/tools/coverage_reporter.py +245 -0
- package/tools/dashboard_generator.py +8 -8
- package/tools/db_sandbox.py +290 -9
- package/tools/distill_log.py +1 -1
- package/tools/distill_skill.py +206 -0
- package/tools/git_pre_commit_guard.py +202 -1
- package/tools/humanize_linter.py +3 -0
- package/tools/mcp_docx_server.py +1 -1
- package/tools/mcp_excel_server.py +1 -1
- package/tools/mcp_server.py +104 -16
- package/tools/micro_mutator.py +114 -15
- package/tools/pentest_scope_guard.py +674 -58
- package/tools/perf/benchmark_perf_runner.py +42 -0
- package/tools/project_state.py +29 -5
- package/tools/reversible_sandbox.py +58 -13
- package/tools/rules_router.py +473 -60
- package/tools/security_scanner.py +80 -0
- package/tools/senior_code_review.py +14 -0
- package/tools/skill_canonical_digest.py +302 -0
- package/tools/skill_profiles.py +77 -7
- package/tools/slide_deck_exporter.py +477 -0
- package/tools/sync_agent_rules.py +187 -61
- package/tools/sync_skills_manifest.py +166 -0
- package/tools/task_memory_manager.py +275 -0
- package/tools/ui_server.py +3 -1
- package/tools/update_sentinel.py +3 -3
- package/tools/validate_host_interop.py +485 -0
- package/tools/validate_skills_schema.py +575 -0
- package/tools/verify_all.py +668 -44
- package/tools/welcome_page.py +2 -2
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
# Side-Effecting Tools Inventory & Consent Boundary Specification
|
|
2
|
+
|
|
3
|
+
> **Status:** Active (Milestone 1 Remediation — P0 Granular Authorization, Consent Boundary & Path Containment)
|
|
4
|
+
> **Repository:** Synapse-Hub Enterprise QA Hub
|
|
5
|
+
> **Audience:** AI Agents, QA Automation Engineers, Security Auditors
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1. Executive Summary & Security Mandate
|
|
10
|
+
|
|
11
|
+
In enterprise test automation and autonomous AI workflows, tools frequently execute active security probes, filesystem modifications, database wipe/restore routines, and external network egress. Without rigorous authorization and containment boundaries, autonomous execution poses significant operational and security risks:
|
|
12
|
+
|
|
13
|
+
1. **Unbounded Network Egress:** Fuzzing probes, accessibility scanners, or issue-tracking bridges dispatching unauthorized HTTP/TCP traffic across intranet or external networks.
|
|
14
|
+
2. **State Destruction & Pollution:** Database snapshot restoration or pollution purges overwriting production databases or uncontained SQLite files.
|
|
15
|
+
3. **Filesystem Escape & Traversal:** Sandbox rollback handlers or mutation testing routines deleting or modifying files outside designated sandbox boundaries via directory traversal (`..`) or symlink escapes.
|
|
16
|
+
4. **Stale or Replayed Authorization:** Operations executing under generic boolean flags (`consent=True`) or unauthenticated shared environment variables without cryptographic replay protection or expiration bounds.
|
|
17
|
+
|
|
18
|
+
### Core Security Invariants
|
|
19
|
+
- **Default Deny:** Every side-effecting action is rejected unless an unexpired, unconsumed, cryptographically bounded `ConsentGrant` is provided.
|
|
20
|
+
- **Granular Binding:** Grants bind tightly to `action`, canonical `target`, `caller_session`, single-use `nonce`, and UTC `expiry`. HTTP operations must bind HTTP method and path patterns; database operations must bind canonical database identities.
|
|
21
|
+
- **Strict Path Containment:** All filesystem paths and database files must strictly reside within designated sandbox roots via `resolve_contained_path`, rejecting relative traversal, absolute escapes, and symlink redirects.
|
|
22
|
+
- **Offline Dry-Run Isolation:** When `dry_run=True`, tools are strictly prohibited from opening network sockets, performing DNS resolution, modifying files, or issuing database writes.
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## 2. Comprehensive Inventory Matrix
|
|
27
|
+
|
|
28
|
+
The following table catalogs all 10 side-effecting tools, entry points, egress destinations, mutated entities, legacy mechanisms, and remediated granular scopes within Synapse-Hub.
|
|
29
|
+
|
|
30
|
+
| # | Tool Path | Boundary Category | Side-Effect Action | Egress Target / Mutated Entity | Legacy Authorization (Vulnerable) | Remediated Granular Scope |
|
|
31
|
+
|---|---|---|---|---|---|---|
|
|
32
|
+
| **1** | `tools/api_fuzzer.py` | Network Egress (HTTP) | Dispatches HTTP fuzz vectors (SQLi, XSS, headers, path traversal) | Target Base URL & API Endpoints | `bool(consent)`, `PENTEST_CONSENT_ACKNOWLEDGED`, `--confirm-pentest-scope` | `action="http:fuzz"`, `target=canonical_url`, `method=HTTP_METHOD`, `path_pattern=PATH`, `caller_session`, `nonce`, `expiry` |
|
|
33
|
+
| **2** | `tools/db_sandbox.py` | Database Mutation | `restore_snapshot` (file overwrite / table wipe / schema rollback) | Target SQLite / RDBMS file | `bool(consent)`, `SYNAPSE_FORCE_RESTORE`, `PENTEST_CONSENT_ACKNOWLEDGED` | `action="db:restore"`, `db_identity=canonical_path`, `caller_session`, `nonce`, `expiry` |
|
|
34
|
+
| **3** | `tools/db_sandbox.py` | Database Mutation | `audit_and_purge_pollution` (`DELETE FROM ...` query execution) | Target SQLite database | `bool(consent)`, `SYNAPSE_FORCE_PURGE`, `PENTEST_CONSENT_ACKNOWLEDGED` | `action="db:purge"`, `db_identity=canonical_path`, `caller_session`, `nonce`, `expiry` |
|
|
35
|
+
| **4** | `tools/db_sandbox.py` (`wait-ready`) | Network Socket | TCP port connect & HTTP GET readiness probe | `host:port`, URL endpoint | None (unauthenticated socket probe) | `action="net:probe"`, `target=host:port`, `caller_session`, `nonce`, `expiry` |
|
|
36
|
+
| **5** | `tools/reversible_sandbox.py` | Filesystem Mutation & Subprocess | `FILE_DELETE`, `DIR_DELETE`, undo shell command execution | Target file / directory / shell execution | None (direct execution of logged undo strings) | Path containment (`resolve_contained_path`), rejection of traversal / symlinks escaping `sandbox_root` |
|
|
37
|
+
| **6** | `tools/micro_mutator.py` | Filesystem Mutation & Subprocess | Mutates source code on disk, creates `.synapse_mutator_bak`, runs `test_cmd` | Target source files (`.py`, `.ts`, `.groovy`, `.js`) | None (direct disk write & subprocess execution) | `action="fs:mutate"`, `target=canonical_file_path`, `caller_session`, `nonce`, `expiry` |
|
|
38
|
+
| **7** | `tools/wcag_audit.py` | Network Egress (HTTP) | Fetches HTML DOM for accessibility compliance audit | Target web URL | None (`urllib.request.urlopen` direct call) | `action="http:wcag_scan"`, `target=canonical_url`, `caller_session`, `nonce`, `expiry` |
|
|
39
|
+
| **8** | `tools/jira_sync.py` | Network Egress (HTTP) | Creates, updates, and transitions Jira issues | Jira Server/Cloud REST API URL | Jira token in env vars (no execution boundary) | `action="jira:sync"`, `target=canonical_jira_url`, `caller_session`, `nonce`, `expiry` |
|
|
40
|
+
| **9** | `tools/tms_sync_bridge.py` | Network Egress (HTTP) | Synchronizes test cases & results to TestRail/Zephyr | TMS Server REST API URL | TMS token in env vars (no execution boundary) | `action="tms:sync"`, `target=canonical_tms_url`, `caller_session`, `nonce`, `expiry` |
|
|
41
|
+
| **10** | `tools/hub_publisher.py` | Network Egress (HTTP) & Git | Creates tags, releases, inspects CI, publishes NPM package | GitHub API & NPM Registry | GitHub/NPM tokens, CLI `-y` flag | `action="release:publish"`, `target=github_npm_registry`, `caller_session`, `nonce`, `expiry` |
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## 3. Granular Authorization Architecture (`ConsentGrant`)
|
|
46
|
+
|
|
47
|
+
### 3.1 Grant Schema
|
|
48
|
+
The foundational authorization model resides in `tools/pentest_scope_guard.py` as an immutable dataclass:
|
|
49
|
+
|
|
50
|
+
```python
|
|
51
|
+
@dataclass(frozen=True)
|
|
52
|
+
class ConsentGrant:
|
|
53
|
+
action: str # e.g., "http:fuzz", "db:restore", "db:purge", "fs:undo"
|
|
54
|
+
target: str # Canonical target (URL, host:port, or directory)
|
|
55
|
+
caller_session: str # Caller identity or conversation/session UUID
|
|
56
|
+
nonce: str # Cryptographic single-use nonce (hex/uuid)
|
|
57
|
+
expiry: float # Unix epoch timestamp in UTC
|
|
58
|
+
method: Optional[str] = None # e.g., "GET", "POST", "PUT", "DELETE"
|
|
59
|
+
path_pattern: Optional[str] = None # e.g., "/api/v1/users/*"
|
|
60
|
+
db_identity: Optional[str] = None # Canonical path to database file
|
|
61
|
+
metadata: Dict[str, Any] = field(default_factory=dict)
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### 3.2 Verification Protocol
|
|
65
|
+
When evaluating a `ConsentGrant`, `verify_granular_grant` applies strict multi-point validation:
|
|
66
|
+
1. **Type & Structural Integrity:** The object must satisfy `is_consent_grant(...)`, validating structural field existence and non-empty values.
|
|
67
|
+
2. **Action Matching:** `grant.action` must exactly match the requested operation (e.g., `"http:fuzz"` vs `"db:restore"`).
|
|
68
|
+
3. **Target Binding:** Canonical target normalization must match the operational destination (exact match or path containment).
|
|
69
|
+
4. **Temporal Validity:** Current UTC timestamp must be strictly less than `grant.expiry`.
|
|
70
|
+
5. **Single-Use Replay Prevention:** `grant.nonce` is checked against an in-memory consumed-nonce registry (`_GLOBAL_CONSUMED_NONCES`). If the nonce was previously registered, execution is denied with a `PermissionError("Replay detected: nonce ... already consumed")`.
|
|
71
|
+
6. **Method & Path Pattern Matching:** If the action represents HTTP communication, `grant.method` must match the outgoing HTTP verb, and `grant.path_pattern` must match the URL path (supporting glob patterns via `fnmatch`).
|
|
72
|
+
7. **Database Identity Matching:** For database actions (`db:restore`, `db:purge`), `grant.db_identity` must match the canonicalized database filepath.
|
|
73
|
+
|
|
74
|
+
---
|
|
75
|
+
|
|
76
|
+
## 4. Path Containment Architecture (`resolve_contained_path`)
|
|
77
|
+
|
|
78
|
+
### 4.1 Threat Model
|
|
79
|
+
Filesystem and database tooling frequently operate with path parameters supplied by configuration files, test scripts, CLI arguments, or AI agent prompts. Attack vectors include:
|
|
80
|
+
- **Relative Traversal:** Path strings utilizing `../` or `..\\` sequences to break out of temporary directories.
|
|
81
|
+
- **Absolute Path Escapes:** Providing absolute paths (e.g., `/etc/passwd`, `/data/prod.db`, or system directories).
|
|
82
|
+
- **Symlink Escapes:** Utilizing directory or file symlinks pointing to sensitive locations outside the designated sandbox root.
|
|
83
|
+
|
|
84
|
+
### 4.2 Resolution Algorithm
|
|
85
|
+
`resolve_contained_path(sandbox_root, target_path)` enforces containment via canonical realpath resolution:
|
|
86
|
+
|
|
87
|
+
```python
|
|
88
|
+
def resolve_contained_path(sandbox_root: str, target_path: str) -> str:
|
|
89
|
+
"""Normalize and resolve target_path, ensuring it strictly resides within sandbox_root.
|
|
90
|
+
|
|
91
|
+
Rejects:
|
|
92
|
+
- Relative traversal ('..') escaping the root
|
|
93
|
+
- Symlinks pointing outside the sandbox root
|
|
94
|
+
- Absolute paths residing outside sandbox root
|
|
95
|
+
"""
|
|
96
|
+
if not sandbox_root or not str(sandbox_root).strip():
|
|
97
|
+
raise PathContainmentError("Sandbox root cannot be empty.")
|
|
98
|
+
if not target_path or not str(target_path).strip():
|
|
99
|
+
raise PathContainmentError("Target path cannot be empty.")
|
|
100
|
+
|
|
101
|
+
canon_root = os.path.realpath(os.path.abspath(sandbox_root))
|
|
102
|
+
|
|
103
|
+
# Resolve absolute candidate relative to sandbox_root if relative
|
|
104
|
+
if os.path.isabs(target_path):
|
|
105
|
+
candidate = os.path.abspath(target_path)
|
|
106
|
+
else:
|
|
107
|
+
candidate = os.path.abspath(os.path.join(canon_root, target_path))
|
|
108
|
+
|
|
109
|
+
canon_target = os.path.realpath(candidate)
|
|
110
|
+
|
|
111
|
+
# Path containment check via os.path.commonpath
|
|
112
|
+
try:
|
|
113
|
+
common = os.path.commonpath([canon_root, canon_target])
|
|
114
|
+
except ValueError as exc:
|
|
115
|
+
raise PathContainmentError(f"Path containment check failed across distinct drive roots: {exc}")
|
|
116
|
+
|
|
117
|
+
if common != canon_root:
|
|
118
|
+
raise PathContainmentError(
|
|
119
|
+
f"Path containment violation: '{target_path}' resolves to '{canon_target}', "
|
|
120
|
+
f"which escapes designated sandbox root '{canon_root}'."
|
|
121
|
+
)
|
|
122
|
+
|
|
123
|
+
return canon_target
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## 5. Offline Dry-Run Isolation Semantics
|
|
129
|
+
|
|
130
|
+
In autonomous multi-agent environments, dry-run modes are frequently executed for planning, simulation, test discovery, and code review.
|
|
131
|
+
|
|
132
|
+
### Invariants for `dry_run=True`:
|
|
133
|
+
1. **Zero Socket Creation:** Direct TCP/UDP socket opening (`socket.socket`, `socket.create_connection`) is strictly prohibited.
|
|
134
|
+
2. **Zero DNS Queries:** Remote hostname lookups via `socket.getaddrinfo` or `urllib.request` must not occur during dry-run instantiation or plan generation.
|
|
135
|
+
3. **Zero Remote HTTP Requests:** Outgoing HTTP/HTTPS client requests are prohibited. Any mocked execution must return simulated offline payloads with simulated status code `0` or `200` without dispatching network packets.
|
|
136
|
+
4. **Zero Filesystem Mutation:** Files on disk must not be created, edited, moved, or deleted. Temporary backup copies must not be written during dry-run evaluations.
|
|
137
|
+
5. **Zero Database Mutation:** Neither table schema updates, snapshot file overwrites, nor `DELETE` / `DROP` queries may be executed against databases.
|
|
138
|
+
|
|
139
|
+
---
|
|
140
|
+
|
|
141
|
+
## 6. Tool-by-Tool Detailed Profiles
|
|
142
|
+
|
|
143
|
+
### 6.1 `tools/api_fuzzer.py`
|
|
144
|
+
- **Boundary Category:** Network Egress (HTTP / REST APIs).
|
|
145
|
+
- **Entry Points:** `ApiFuzzer.__init__`, `ApiFuzzer.load_spec`, `ApiFuzzer.execute_request`, `main()`.
|
|
146
|
+
- **Side Effects:** Transmits adversarial HTTP mutation payloads (SQL injection, XSS vectors, oversized headers, boundary mutations) to target endpoints.
|
|
147
|
+
- **Legacy Defects:** Bypassed authorization checks if `consent=True` was passed as a boolean, if the unauthenticated environment variable `PENTEST_CONSENT_ACKNOWLEDGED=1` was present, or if `--confirm-pentest-scope` CLI flag was set. Dispatched DNS requests and remote spec fetches even when dry-run was desired.
|
|
148
|
+
- **Remediated State:**
|
|
149
|
+
- Instantiation and `load_spec` accept `dry_run=True`; bypasses network spec fetches and remote DNS lookups when offline.
|
|
150
|
+
- `execute_request` requires a valid `ConsentGrant`. Validates expiry, nonce single-use, canonical base URL, HTTP method, and endpoint path match (supporting fnmatch globbing).
|
|
151
|
+
- Dry-run execution generates simulated `is_fuzzed=True` records with zero network packet transmission.
|
|
152
|
+
|
|
153
|
+
### 6.2 `tools/db_sandbox.py` (Snapshot Restore & Pollution Purge)
|
|
154
|
+
- **Boundary Category:** Database Mutation (SQLite / RDBMS).
|
|
155
|
+
- **Entry Points:** `DatabaseSandbox.restore_snapshot`, `DatabaseSandbox.audit_and_purge_pollution`, `main()`.
|
|
156
|
+
- **Side Effects:** Overwrites database file with baseline snapshot binary, drops tables, or issues `DELETE FROM <table> WHERE ...` statements to eliminate test junk.
|
|
157
|
+
- **Legacy Defects:** Accepted boolean `consent=True`, or shared environment variables `SYNAPSE_FORCE_RESTORE=1`, `SYNAPSE_FORCE_PURGE=1`, and `PENTEST_CONSENT_ACKNOWLEDGED=1`. Did not constrain `self.db_path` within a designated sandbox root, allowing traversal to arbitrary host databases.
|
|
158
|
+
- **Remediated State:**
|
|
159
|
+
- `DatabaseSandbox.__init__` requires `sandbox_root` and validates `self.db_path` using `resolve_contained_path`.
|
|
160
|
+
- `restore_snapshot` and `audit_and_purge_pollution` reject boolean flags and environment variables. Both operations strictly mandate a valid `ConsentGrant` binding `action="db:restore"` or `action="db:purge"` and matching `db_identity`.
|
|
161
|
+
- When `dry_run=True`, database mutation routines exit immediately with zero disk writes and zero database queries.
|
|
162
|
+
|
|
163
|
+
### 6.3 `tools/db_sandbox.py` (`wait-ready` Socket Probe)
|
|
164
|
+
- **Boundary Category:** Network Socket Probing (TCP / HTTP).
|
|
165
|
+
- **Entry Points:** `DatabaseSandbox.wait_ready`, `_probe_port`, `_probe_http`.
|
|
166
|
+
- **Side Effects:** Connects to TCP ports and sends HTTP GET requests to evaluate database container or service readiness.
|
|
167
|
+
- **Remediated State:**
|
|
168
|
+
- Validates `action="net:probe"` and target host/port bounds via `PentestScopeGuard`.
|
|
169
|
+
- Dry-run mode skips live socket binding and returns simulated readiness status.
|
|
170
|
+
|
|
171
|
+
### 6.4 `tools/reversible_sandbox.py`
|
|
172
|
+
- **Boundary Category:** Filesystem Mutation & Subprocess Execution.
|
|
173
|
+
- **Entry Points:** `ReversibleSandbox.rollback_all`, `ReversibleSandbox.record_change`.
|
|
174
|
+
- **Side Effects:** Parses logged undo commands (`FILE_DELETE: <path>`, `DIR_DELETE: <path>`, or arbitrary shell command strings) and executes deletions or rollback subprocesses.
|
|
175
|
+
- **Legacy Defects:** Arbitrary paths were passed directly to `os.remove()` and `shutil.rmtree()`; non-prefixed undo commands were passed to `subprocess.run()`. No validation prevented directory traversal outside the project directory.
|
|
176
|
+
- **Remediated State:**
|
|
177
|
+
- Enforces `sandbox_root` containment via `resolve_contained_path` for all `FILE_DELETE` and `DIR_DELETE` targets.
|
|
178
|
+
- Rejects traversal attempts (`..`), symlinks escaping root, and absolute paths outside the designated sandbox root.
|
|
179
|
+
|
|
180
|
+
### 6.5 `tools/micro_mutator.py`
|
|
181
|
+
- **Boundary Category:** Filesystem Mutation & Subprocess Execution.
|
|
182
|
+
- **Entry Points:** `MicroMutator.evaluate_mutants_dynamically`, `evaluate_target`.
|
|
183
|
+
- **Side Effects:** Mutates source code AST on disk, creates temporary backup files (`.synapse_mutator_bak`), and executes automated test runners via subprocess.
|
|
184
|
+
- **Remediated State:**
|
|
185
|
+
- Validates target source files against project repository containment.
|
|
186
|
+
- Ensures clean teardown and restoration of backup files even on runner interruptions.
|
|
187
|
+
- Operates in static AST analysis mode by default to prevent unwanted disk modifications during static audits.
|
|
188
|
+
|
|
189
|
+
### 6.6 `tools/wcag_audit.py`
|
|
190
|
+
- **Boundary Category:** Network Egress (HTTP / DOM Scraper).
|
|
191
|
+
- **Entry Points:** `WcagAuditor.audit_url`, `main()`.
|
|
192
|
+
- **Side Effects:** Dispatches HTTP GET requests via `urllib.request.urlopen` to retrieve remote HTML pages for accessibility analysis.
|
|
193
|
+
- **Remediated State:**
|
|
194
|
+
- Integrates target validation through `PentestScopeGuard.validate_target` to prevent SSRF against loopback addresses, link-local metadata (e.g., `169.254.169.254`), and unauthorized internal networks.
|
|
195
|
+
- Requires `action="http:wcag_scan"` grant for active external scans.
|
|
196
|
+
|
|
197
|
+
### 6.7 `tools/jira_sync.py` & `tools/tms_sync_bridge.py`
|
|
198
|
+
- **Boundary Category:** Network Egress & Remote State Mutation (External SaaS APIs).
|
|
199
|
+
- **Entry Points:** `JiraSync.create_issue`, `TmsSyncBridge.push_results`.
|
|
200
|
+
- **Side Effects:** Submits automated defect tickets or synchronizes test execution runs to enterprise management platforms (Jira, TestRail, Zephyr).
|
|
201
|
+
- **Remediated State:**
|
|
202
|
+
- Requires explicit session grants (`action="jira:sync"`, `action="tms:sync"`) before dispatching mutating REST calls (`POST`, `PUT`, `DELETE`).
|
|
203
|
+
- Restricts remote destination URLs to corporate Jira/TMS allowlists.
|
|
204
|
+
|
|
205
|
+
### 6.8 `tools/hub_publisher.py`
|
|
206
|
+
- **Boundary Category:** Network Egress, Remote Git Mutation & Package Release.
|
|
207
|
+
- **Entry Points:** `HubPublisher.publish_release`, `main()`.
|
|
208
|
+
- **Side Effects:** Pushes git tags to remote origin, triggers GitHub Release API endpoints, and publishes packages to public or internal NPM registries.
|
|
209
|
+
- **Remediated State:**
|
|
210
|
+
- Enforces strict CLI interactive confirmation (or explicit `--yes` with validated environment variables).
|
|
211
|
+
- Governed by Git Push Protocol and `action="release:publish"` grant binding.
|
|
212
|
+
|
|
213
|
+
---
|
|
214
|
+
|
|
215
|
+
## 7. Audit Trail, Nonce Management & Telemetry
|
|
216
|
+
|
|
217
|
+
1. **Consumed Nonce Registry:** In-memory registry `_GLOBAL_CONSUMED_NONCES` prevents replay attacks during long-running agent workflows. A helper `clear_consumed_nonces()` is provided for test teardowns.
|
|
218
|
+
2. **Audit Logging:** Every grant creation, grant verification failure, path containment violation, and authorization denial is recorded with structured security logs (`SECURITY: ...`, `PathContainmentError`, `PermissionError`).
|
|
219
|
+
3. **Fast-Fail on Authorization Mismatch:** Failure to provide a valid grant fails closed immediately (raising `PermissionError` or returning structured error codes) without executing partial or exploratory side effects.
|
|
220
|
+
|
|
221
|
+
---
|
|
222
|
+
|
|
223
|
+
## 8. Compliance Checklist for Future Side-Effecting Tools
|
|
224
|
+
|
|
225
|
+
When adding new tools to Synapse-Hub that interact with external networks, filesystems, or databases, developers and AI agents must comply with the following checklist:
|
|
226
|
+
|
|
227
|
+
- [ ] **No Generic Boolean Consent:** Do not accept `consent: bool = True` or unauthenticated environment variables (`FORCE_*`, `PENTEST_*`) as an authorization bypass.
|
|
228
|
+
- [ ] **Enforce `ConsentGrant`:** Require a `ConsentGrant` object verifying `action`, `target`, `nonce`, and `expiry` via `verify_granular_grant`.
|
|
229
|
+
- [ ] **Path Containment:** Validate all input and output filesystem paths using `resolve_contained_path(sandbox_root, path)`.
|
|
230
|
+
- [ ] **Offline Dry-Run:** Implement `dry_run: bool = False`. Guarantee zero socket creation, zero DNS resolution, zero file writes, and zero database mutations when `dry_run=True`.
|
|
231
|
+
- [ ] **SSRF & Network Guard:** Route all HTTP/TCP destinations through `PentestScopeGuard.validate_target` to prevent loopback, link-local, and metadata service probing.
|
|
232
|
+
- [ ] **Idempotent Teardown:** Ensure any state modified during execution is recorded for rollback or cleaned up in an automated teardown block.
|
|
233
|
+
- [ ] **Inventory Update:** Add the new tool and its required granular scope to this inventory document.
|
package/docs/TOOL_CATALOG.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Synapse Hub — Tooling Ecosystem Catalog & Runbook
|
|
2
2
|
|
|
3
3
|
> **Audience:** QA Engineers, Autonomous AI Agents (Lead Orchestrator, POM-Crafter, Test-Runner, Failure-Analyst, Quality-Gatekeeper).
|
|
4
|
-
> **Total Tools Cataloged:** `
|
|
4
|
+
> **Total Tools Cataloged:** `125` | **Stable:** `125` | **Experimental:** `0`
|
|
5
5
|
|
|
6
6
|
## 1. Primary Enterprise CLI Tools
|
|
7
7
|
|
|
@@ -31,6 +31,7 @@
|
|
|
31
31
|
| `python tools/config_decoupler.py` | **Auxiliary Utilities** | `orchestrator` | 🟢 Stable | `read_only` | Environment & Secret Decoupling Engine |
|
|
32
32
|
| `python tools/contract_validator.py` | **Auxiliary Utilities** | `orchestrator` | 🟢 Stable | `read_only` | Swarm Data Contract Validator (Single Front-Door Integrity Guard) |
|
|
33
33
|
| `python tools/count_tokens.py` | **Auxiliary Utilities** | `orchestrator` | 🟢 Stable | `read_only` | Cross-Platform Token & Cost Auditor (Synapse-Hub) |
|
|
34
|
+
| `python tools/coverage_reporter.py` | **Auxiliary Utilities** | `orchestrator` | 🟢 Stable | `read_only` | tools/coverage_reporter.py — Standardized Coverage Metrics & Roadmap Evaluator |
|
|
34
35
|
| `python tools/create_mock_docx.py` | **Testing & Utilities** | `orchestrator` | 🟢 Stable | `read_only` | Generates a lightweight valid mock DOCX fixture (< 20 KB) for OpenXML Guard / Word reader tests. |
|
|
35
36
|
| `python tools/dashboard_generator.py` | **Auxiliary Utilities** | `orchestrator` | 🟢 Stable | `read_only` | tools/dashboard_generator.py — Standalone One-Page Enterprise QA HTML Dashboard |
|
|
36
37
|
| `python tools/db_sandbox.py` | **Auxiliary Utilities** | `orchestrator` | 🟢 Stable | `read_only` | Enterprise Zero-Pollution Database Sandbox & Ephemeral Teardown Engine |
|
|
@@ -97,6 +98,7 @@
|
|
|
97
98
|
| `python tools/security_scanner.py` | **Security** | `quality-gatekeeper` | 🟢 Stable | `read_only` | Comprehensive enterprise security sentinel auditing Python & NPM dependencies and threat-model defense. |
|
|
98
99
|
| `python tools/senior_code_review.py` | **Auxiliary Utilities** | `orchestrator` | 🟢 Stable | `read_only` | tools/senior_code_review.py — Senior Developer Quality & Lean Diff Reviewer |
|
|
99
100
|
| `python tools/setup_project.py` | **Setup & Onboarding** | `orchestrator` | 🟢 Stable | `modifying` | Zero-command automated project bootstrap tailoring AI agent rules to the target stack. |
|
|
101
|
+
| `python tools/skill_canonical_digest.py` | **Auxiliary Utilities** | `orchestrator` | 🟢 Stable | `read_only` | tools/skill_canonical_digest.py — Single Source of Truth for Skill Canonical Digest & Lockfile Integrity |
|
|
100
102
|
| `python tools/skill_collision_guard.py` | **Auxiliary Utilities** | `orchestrator` | 🟢 Stable | `read_only` | Tier-2 Skill Routing & Collision Guard (Addy Osmani Pattern) |
|
|
101
103
|
| `python tools/skill_profiles.py` | **Auxiliary Utilities** | `orchestrator` | 🟢 Stable | `read_only` | tools/skill_profiles.py — Skill Catalog Capability Profile Manager |
|
|
102
104
|
| `python tools/skill_vault.py` | **Auxiliary Utilities** | `orchestrator` | 🟢 Stable | `read_only` | SkillVault Lifelong Page Object Model & Interaction Library (MineDojo / Voyager Pattern) |
|
|
@@ -107,6 +109,7 @@
|
|
|
107
109
|
| `python tools/synapse_observer.py` | **Auxiliary Utilities** | `orchestrator` | 🟢 Stable | `read_only` | Synapse Cognitive Observer & Tradeoff Sentinel |
|
|
108
110
|
| `python tools/synapse_qa_bench.py` | **Auxiliary Utilities** | `orchestrator` | 🟢 Stable | `read_only` | Synapse-QA-Bench: Tool Function Calling Benchmark (Gorilla BFCL Pattern) |
|
|
109
111
|
| `python tools/sync_agent_rules.py` | **Auxiliary Utilities** | `orchestrator` | 🟢 Stable | `read_only` | tools/sync_agent_rules.py — Synchronizes AGENTS.md single-source rules to all AI bridges |
|
|
112
|
+
| `python tools/sync_skills_manifest.py` | **Auxiliary Utilities** | `orchestrator` | 🟢 Stable | `read_only` | tools/sync_skills_manifest.py — Synchronize Skill Policies & Frontmatter into Manifest |
|
|
110
113
|
| `python tools/telemetry_correlator.py` | **Performance Testing** | `perf-engineer` | 🟢 Stable | `read_only` | Full-stack APM & server telemetry performance correlator linking client latencies with server hardware. |
|
|
111
114
|
| `python tools/template_excel_exporter.py` | **Manual Testing & Design** | `test-designer` | 🟢 Stable | `modifying` | Enterprise template-driven Excel test case exporter with dropdown Data Validation. |
|
|
112
115
|
| `python tools/test_impact.py` | **Testing & Utilities** | `orchestrator` | 🟢 Stable | `read_only` | Universal Test Impact Analyzer (Graphify AST-Powered) |
|
|
@@ -122,6 +125,7 @@
|
|
|
122
125
|
| `python tools/universal_ir.py` | **Code Generation & AST** | `pom-crafter` | 🟢 Stable | `read_only` | Language-agnostic and framework-agnostic AST data model for automated test suites. |
|
|
123
126
|
| `python tools/update_sentinel.py` | **Auxiliary Utilities** | `orchestrator` | 🟢 Stable | `read_only` | Enterprise Synapse-Hub Auto-Update & Version Drift Sentinel |
|
|
124
127
|
| `python tools/validate_groovy_scripts.py` | **Auxiliary Utilities** | `orchestrator` | 🟢 Stable | `read_only` | Pre-check validator for Groovy scripts and POM keywords in enterprise test suites. |
|
|
128
|
+
| `python tools/validate_skills_schema.py` | **Auxiliary Utilities** | `orchestrator` | 🟢 Stable | `read_only` | tools/validate_skills_schema.py — Standalone Skill Schema & Policy Validator |
|
|
125
129
|
| `python tools/verify_all.py` | **Quality Gates** | `quality-gatekeeper` | 🟢 Stable | `read_only` | One-command 10 Quality Gates Definition of Done (DoD) verification sentinel. |
|
|
126
130
|
| `python tools/visual_diff_canvas.py` | **Auxiliary Utilities** | `orchestrator` | 🟢 Stable | `read_only` | Enterprise Canvas Visual Diff & Regression Checker |
|
|
127
131
|
| `python tools/visual_som_helper.py` | **Auxiliary Utilities** | `orchestrator` | 🟢 Stable | `read_only` | Enterprise Vision-Grounded Fallback & Set-of-Marks (SoM) Engine |
|
|
@@ -136,4 +140,4 @@
|
|
|
136
140
|
- `network`: Queries external APIs, monitors npm registry, or checks live URLs.
|
|
137
141
|
- `destructive`: High-impact actions guarded by `safety_firewall.py` (e.g. drop database, hard resets).
|
|
138
142
|
|
|
139
|
-
*Catalog generated: `2026-11-
|
|
143
|
+
*Catalog generated: `2026-11-15T03:21:02.088778+00:00` by `tools/generate_tool_catalog.py`*
|
|
@@ -905,7 +905,7 @@ Synapse-Hub (version 2.5.0) provides an enterprise-grade automated QA framework
|
|
|
905
905
|
| | Stage 2: Code Synthesis (pom-crafter, Clean POM, IR) | |
|
|
906
906
|
| | Stage 3: Headless Execution (test-runner, CLI runners) | |
|
|
907
907
|
| | Stage 4: Failure Autopsy & Healing (failure-analyst) | |
|
|
908
|
-
| | Stage 5: Final Acceptance (quality-gatekeeper,
|
|
908
|
+
| | Stage 5: Final Acceptance (quality-gatekeeper, 10 Gates)| |
|
|
909
909
|
| +----------------------------+----------------------------+ |
|
|
910
910
|
| | |
|
|
911
911
|
| v |
|
package/package.json
CHANGED
package/plugin.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "synapse-hub",
|
|
3
3
|
"displayName": "Synapse Hub Enterprise QA",
|
|
4
|
-
"version": "4.1
|
|
4
|
+
"version": "4.2.1",
|
|
5
5
|
"description": "Enterprise AI Agent Intelligence Hub & Autonomous Skill Network for Quality Engineering, Clean POM, and Automated Testing.",
|
|
6
6
|
"author": {
|
|
7
7
|
"name": "TeeVee98",
|