ledadmin/meshcentral-openclaw-bridge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial project documentation and status

Browse Source
This commit is contained in:
Clawdia
2026-08-30 14:46:23 -04:00
commit 765f372c72
50 changed files with 12916 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
research/INTEGRATION-RESEARCH.md
+140
View File
@@ -0,0 +1,140 @@
# MeshCentral Integration Research
**Project:** MeshCentral ↔ OpenClaw Bridge
**Research date:** 2026-08-24/25 (America/Toronto)
**Scope:** research only; no live MeshCentral or infrastructure changes were made.
## Executive summary
MeshCentral's most practical supported automation surface is the **official `meshctrl.js` command-line client**, shipped with the MeshCentral npm package. It connects to the server's `wss://.../control.ashx` WebSocket and uses the same control channel as the web application. The current upstream package metadata identifies MeshCentral **1.2.5**, released 2026-08-12, and requires Node.js >=20.
There is no evidence in the upstream repositories or the GitHub repository search performed on 2026-08-25 of a maintained, general-purpose MeshCentral MCP server. One search result, `spanishdexter/MeshOps`, is an automation-template project for `meshctrl.js`, but had 0 stars and an update timestamp of 2026-03-30; it should not be treated as a mature integration dependency. Recommendation: build a narrow bridge against a local adapter boundary, initially wrapping or reimplementing only the read-only subset of the official MeshCtrl protocol, with version-pinned compatibility tests. Do not expose MeshCentral's raw WebSocket protocol as an OpenClaw tool API.
**Overall confidence:** High for the existence and broad behavior of MeshCtrl; medium for protocol stability and exact authorization semantics because the control-channel messages are implementation details rather than a separately versioned public REST API; low for third-party MCP adapter availability.
## Official integration surfaces
### 1. MeshCtrl (`meshctrl.js`) — preferred starting point
The official documentation describes MeshCtrl as a Node.js command-line tool installed with MeshCentral. It may run on the server or remotely, logs in over WebSocket, and supports JSON output. Read-only commands relevant to the MVP include:
- `ServerInfo`, `ServerVersion`, `UserInfo`
- `ListDeviceGroups`, `ListDevices`, `DeviceInfo`
- `ListEvents` (careful: event data may contain sensitive information)
The current upstream source lists additional state-changing and high-risk operations, including `RunCommand`, shell/file transfer, device power, user/group management, and device deletion. The bridge must not pass these through merely because the client supports them.
Observed current source behavior:
- Default endpoint: `wss://localhost:443/control.ashx`; `--url` accepts `ws://` or `wss://` and appends `/control.ashx`.
- Password authentication is sent in an `x-meshauth` WebSocket header containing base64 username, password, and optionally a 2FA token.
- A login-key mode can generate a time-limited authentication cookie from an 80-byte hex key; upstream documentation warns that the login-token key can impersonate users and is highly sensitive.
- After connection, the client sends JSON actions such as `meshes`, `nodes`, `events`, `serverversion`, and `deviceinfo` and receives JSON responses.
- The client is updated with the server and is therefore a useful compatibility reference, but this is not equivalent to a stable, independently versioned API contract.
**Important security observation:** current upstream `meshctrl.js` source creates WebSocket options with `rejectUnauthorized: false` and a no-op certificate verifier (`onVerifyServer` returns `null`). This means blindly embedding or copying that client can permit a man-in-the-middle attack. The bridge must use a TLS implementation with certificate validation enabled, and should support an explicit private-CA trust bundle or certificate pinning appropriate to the homelab. This finding should be verified against the exact package version selected before implementation.
### 2. MeshCentral server-side JavaScript/module API
The main package exports/contains server internals (`meshcentral.js`, database, webserver, plugin and agent managers), but no separately documented, stable remote server API was found in the upstream documentation repository. Loading MeshCentral internals inside the bridge would couple the bridge to private objects, deployment paths, process/runtime state, and the server's upgrade lifecycle. It also risks granting access beyond the integration identity's intended authorization boundary.
**Recommendation:** do not load MeshCentral as an in-process library for the first implementation. Use a separate process and the authenticated control channel, or a small upstream-compatible adapter behind a typed interface. Revisit a server plugin only if a future requirement demands an event-driven or server-local capability and its lifecycle/security model is documented and tested.
### 3. Web UI/control protocol
MeshCtrl uses `control.ashx`, WebSocket JSON messages, and relay/tunnel endpoints for interactive shell/file operations. This is a useful protocol reference but is an internal application protocol. Message names, response shapes, auth cookies, and permissions may change between MeshCentral releases. A bridge should:
1. Pin and record the MeshCentral version.
2. Keep a protocol adapter isolated from OpenClaw schemas.
3. Validate response schemas and reject unexpected/ambiguous data.
4. Maintain mock fixtures and an integration test matrix for every upgrade.
5. Treat all endpoint/device text as untrusted data, not instructions.
## Authentication and session behavior
MeshCtrl supports two primary login styles:
1. **Username/password**, optionally with a TOTP/2FA token. The password is placed in a WebSocket header by the official client; avoid command-line arguments because process listings and shell history can expose them.
2. **Server login key**, used to create a login cookie for a specified user/domain. This is powerful impersonation material and should not be used for the bridge unless Rob explicitly chooses it and the key is scoped/protected as well as possible. A key file should never be committed, logged, or mounted broadly.
The WebSocket session is authenticated at connection time, then receives control actions and responses over the session. The bridge should use one dedicated account and explicitly check that target device/group identifiers are in its configured allowlist, even if MeshCentral also enforces permissions. Authorization should be treated as both server-side and bridge-side defense in depth.
Open questions about session details that require a controlled test against the actual deployment:
- Whether the selected MeshCentral account can perform each desired read-only action and which fields are returned.
- How sessions expire, how reconnects behave, and whether a reconnect can replay an action.
- Exact response/error messages and whether errors are distinguishable from empty results.
- Whether the deployment uses a non-default domain URL and/or reverse proxy path.
- Whether 2FA is required for the integration account and whether a non-interactive token/key method is acceptable.
## Version compatibility
Upstream package metadata observed 2026-08-25:
- MeshCentral version: `1.2.5`
- Published release: 2026-08-12
- Git commit: `b09b1d60328de8e2d2f7387561ed51c64011c82a`
- Node engine: `>=20.0.0`
- WebSocket dependency: `ws` 8.21.1
The release notes include changes to `meshctrl.js`, including allowing a user ID without a domain and adding server-version output. This reinforces that the bundled client and server are released together and that protocol behavior can change. The bridge should record the tested server version and client/source commit, use semver/commit compatibility checks, and fail closed or enter degraded read-only mode when an unknown version is detected.
## Existing adapters / MCP servers
A GitHub repository search for `MeshCentral MCP`, `MeshCentral API client`, and related terms found no clearly maintained general-purpose MCP server as of 2026-08-25. The notable related result was:
- [spanishdexter/MeshOps](https://github.com/spanishdexter/MeshOps) — workflow automation templates using MeshCentral's `meshctrl.js`; observed 0 stars and updated 2026-03-30. This may provide ideas, but is not sufficient evidence of maintained protocol support or security review.
No third-party adapter should be installed or granted credentials without reviewing source, release activity, dependency health, license, target scope, logging, and TLS behavior. A local OpenClaw MCP/tool wrapper owned by this project is preferable to adopting an unverified adapter, while retaining a replaceable MeshCentral adapter interface.
## Security implications and design requirements
MeshCentral is a remote-management control plane. Even read-only inventory can disclose hostnames, OS versions, IP addresses, uptime, user/session information, and event history. Diagnostics and command execution can become full remote code execution on an endpoint.
Required controls for the bridge:
- Dedicated least-privilege MeshCentral identity; never Rob's primary admin account.
- Bridge and MeshCentral restricted to the trusted management network; no public MCP endpoint.
- Validated TLS certificates; do not inherit upstream MeshCtrl's `rejectUnauthorized: false` behavior.
- Secrets in a protected runtime store/environment with restrictive permissions; never URLs, headers, passwords, login keys, or cookies in logs.
- Typed read-only operations first; no arbitrary shell text in the initial release.
- Explicit device and group allowlists; reject ambiguous names and require stable IDs where possible.
- Timeouts, response-size caps, concurrency/rate limits, reconnect backoff, and cancellation.
- Audit records containing authenticated principal, operation, target, request ID, timestamps, outcome, and truncation status—but not secrets or raw sensitive output by default.
- Treat device names, event text, command output, and logs as untrusted content to defend against prompt injection.
- Fail closed on uncertain auth, target resolution, server version, TLS, or partial execution.
- Separate read-only, diagnostic, reversible, disruptive, and destructive capabilities. Require immediate confirmation for every state-changing operation; keep destructive operations disabled.
## Recommended implementation path
1. Record Rob's actual MeshCentral version, domain/path, TLS CA, network placement, and a non-production test device.
2. Implement a `MeshCentralClient` interface with typed methods for server info, groups, device inventory, device metadata, and (only after review) events.
3. Add a MeshCtrl-compatible transport adapter with strict TLS validation and schema validation; keep it behind the interface.
4. Use mock WebSocket fixtures for auth success/failure, expired session, reconnect, malformed response, unknown version, oversized output, and permission denial.
5. Test against one selected non-production device only after explicit approval and after documenting credentials/secret storage.
6. Add diagnostics only as named allowlisted operations. Add actions only after a separate confirmation/audit design review.
## Open questions for Rob
1. What exact MeshCentral version and domain/path are deployed?
2. Is MeshCentral reachable only on the trusted LAN/VPN, or through public ingress/reverse proxy?
3. Which device group and one non-production test device may be allowlisted?
4. Should the bridge account be local MeshCentral credentials with 2FA, or is another supported identity provider in use?
5. Where may the bridge secret and audit logs be stored, and what retention is acceptable?
6. Does the MeshCentral TLS certificate chain validate from the proposed bridge host? If not, where is the private CA bundle managed?
7. Are event history and endpoint metadata allowed in OpenClaw responses, given possible personal/sensitive data?
8. Which initial diagnostics are genuinely needed, and what exact typed checks/limits should be permitted?
9. What is the required behavior on a MeshCentral upgrade: block unknown versions, or permit read-only operation after a compatibility check?
## Sources (accessed 2026-08-25)
1. MeshCentral source repository: https://github.com/Ylianst/MeshCentral
2. Current package metadata (version, Node requirement, dependencies): https://raw.githubusercontent.com/Ylianst/MeshCentral/master/package.json
3. Official MeshCtrl source (endpoint, auth headers, actions, TLS options): https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshctrl.js
4. Official MeshCtrl guide (WebSocket behavior, login methods, commands, login-key warning): https://docs.meshcentral.com/meshctrl/
5. Official MeshCentral security guidance (rate limiting, 2FA, TLS settings): https://docs.meshcentral.com/meshcentral/security/
6. Official secure-installation guidance (low-privilege account and manual updates): https://docs.meshcentral.com/install/security/secure/
7. Latest release API record observed during research (1.2.5, published 2026-08-12): https://api.github.com/repos/Ylianst/MeshCentral/releases/latest
8. Related third-party search result: https://github.com/spanishdexter/MeshOps
URLs and claims above are research references, not authorization to connect to or change live systems.