Howard Enos
3de8b7fde3
Replace the thin "Future: GuruRMM integration" stub with a "Why this skill exists" section: ScreenConnect surfaces as a per-partner Integrations Center / addons-page entry, positioned as the bring-your-own alternative to GuruConnect (a partner already paying for ScreenConnect uses their licensed instance as the remote-access backend). Points at the mapped plan: SPEC-024, RMM_THOUGHTS Feature 7 + Refinement 7a, the Integrations Center roadmap item. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
134 lines
6.9 KiB
Markdown
134 lines
6.9 KiB
Markdown
---
|
|
name: screenconnect
|
|
description: >-
|
|
Manage the ACG ConnectWise ScreenConnect (Control) instance via the RESTful API
|
|
Manager extension: list/inspect sessions, build PARAMETERIZED access installers
|
|
(self-tag a device into the right Company/Site/Tag), run backstage commands,
|
|
message guests, and update custom properties. Read-only by default; state-
|
|
changing ops are gated behind --confirm. Pairs with /rmm to push the installer.
|
|
Triggers: screenconnect, connectwise control, sc session, remote access agent,
|
|
build screenconnect installer, run command on a screenconnect session, tag a
|
|
device in screenconnect, deploy screenconnect via rmm.
|
|
---
|
|
|
|
# ScreenConnect (ConnectWise Control) Skill
|
|
|
|
Standalone CLI for the ACG ScreenConnect cloud instance
|
|
(`https://computerguru.screenconnect.com`) via the **RESTful API Manager**
|
|
extension. Read-only by default; writes gated behind `--confirm`.
|
|
|
|
## Running the CLI
|
|
|
|
```bash
|
|
SC="bash $CLAUDETOOLS_ROOT/.claude/scripts/py.sh C:/claudetools/.claude/skills/screenconnect/scripts/sc.py"
|
|
$SC status # auth check + instance info
|
|
$SC sessions --name "<hostname>" # find sessions by Name
|
|
$SC session <sessionID> # full session detail
|
|
$SC build-installer --platform msi --name HOST --company "X" --site "Y" --tag "Z"
|
|
$SC send-command --session <id> --command "..." --confirm
|
|
$SC set-properties --session <id> --props-json '["Company","Site","Tag"]' --confirm
|
|
$SC raw --method GetSessionsByName --body '{"sessionName":""}'
|
|
```
|
|
|
|
Transport auto-selects httpx, else stdlib urllib (no hard dependency).
|
|
|
|
## Credentials & auth (VERIFIED)
|
|
|
|
API secret is NEVER hardcoded - loaded from the SOPS vault
|
|
`msp-tools/screenconnect.sops.yaml` field `credentials.api_secret` (or the
|
|
`SCREENCONNECT_API_SECRET` env override). Auth is two headers:
|
|
|
|
```
|
|
CTRLAuthHeader: <raw api_secret> (NO "Basic" prefix - Basic auth 401s)
|
|
Origin: https://computerguru.screenconnect.com
|
|
```
|
|
|
|
Endpoints: `POST <base>/App_Extensions/2d558935-686a-4bd0-9991-07539f5fe749/Service.ashx/<Method>`.
|
|
Reads take a JSON object; the write methods take a **positional array**.
|
|
Custom properties on this instance: **CP1=Company, CP2=Site, CP3=Tag** (up to CP8).
|
|
|
|
## The deploy workflow (RMM push -> self-tag -> control)
|
|
|
|
This is the headline use case - set a device for SC and have it land correctly:
|
|
|
|
1. `build-installer` with the device's Company/Site/Tag (+ name) -> a parameterized
|
|
access-installer URL (`?e=Access&y=Guest&t=<name>&c=<Company>&c=<Site>&c=<Tag>`).
|
|
The cloud serves a pre-keyed installer; the `c=` params self-tag the agent.
|
|
2. Push that installer via `/rmm` (download + `msiexec /i ... /qn` as SYSTEM).
|
|
3. The SC agent connects -> a session named `<name>` appears with CP1/CP2/CP3 set.
|
|
4. `sessions --name <name>` -> get the sessionID -> control it (`send-command`, etc.).
|
|
|
|
VERIFIED end-to-end on RMM-TEST-MACHINE 2026-06-22 (installed, self-tagged
|
|
Company/Site/Tag, ran a command, re-tagged via set-properties).
|
|
|
|
## Method surface (probed live 2026-06-22)
|
|
|
|
**Available (CLI-exposed):**
|
|
- Reads: `GetSessionsByName` (matches the Name field; "" -> blank-name sessions),
|
|
`GetSessionDetailsBySessionID`, `GetSessionBySessionID`.
|
|
- Writes (gated): `SendCommandToSession` `[sessionID, command]`,
|
|
`SendMessageToSession` `[sessionID, message]`,
|
|
`UpdateSessionCustomProperties` `[sessionID, [cp1,cp2,cp3,...]]`,
|
|
`CreateSession` (array; not the primary path - the installer creates access sessions).
|
|
|
|
**MISSING on this extension version (NOT a deploy/control blocker):**
|
|
- `GetSessions` / `GetAllSessions` / `GetSessionGroups` (full-fleet inventory) ->
|
|
"web method does not exist". Listing ALL agents needs Mike to update the RESTful
|
|
API Manager extension to expose a list-all method. Until then, find sessions by
|
|
Name (the installer sets the Name = machine name, so by-name lookup works).
|
|
|
|
## Safety gating
|
|
|
|
`send-command`, `send-message`, `set-properties` refuse to run without `--confirm`
|
|
(print what they WOULD do, exit 3). `raw` also refuses state-changing method names
|
|
(sendcommand/updatesession/create/delete/end/transfer/install/...) without
|
|
`--confirm`. NEVER run `send-command` against a production client session casually -
|
|
it executes on the guest. Test against a known test machine.
|
|
|
|
## Error logging
|
|
|
|
On a GENUINE functional error (auth failure, unexpected API response, transport
|
|
failure) the CLI logs it to `errorlog.md` via `log-skill-error.sh` before
|
|
surfacing it. It does NOT log expected/handled conditions - a missing extension
|
|
method ("web method does not exist"), a rate-limit (429), the `raw` probe path, or
|
|
selftest runs (`SC_SUPPRESS_ERRORLOG=1`) are skipped (see `_should_log_error`).
|
|
|
|
## Why this skill exists: the GuruRMM addon integration (the end goal)
|
|
|
|
This skill is the **verified connector prototype** for a GuruRMM addon, not a
|
|
one-off CLI. The end goal is to surface ScreenConnect as a first-class, per-partner
|
|
entry on the GuruRMM **Integrations Center / App Center** ("addons page"), so a
|
|
partner can wire in their OWN paid ScreenConnect instance and the RMM drives it.
|
|
|
|
**Positioning - ScreenConnect is the bring-your-own alternative to GuruConnect.**
|
|
GuruRMM's native remote-access product is **GuruConnect** (consumed via its
|
|
integration contract - see `guru-rmm/docs/GURU_CONNECT_INTEGRATION.md`). A partner
|
|
who is **already paying for ScreenConnect and does NOT want GuruConnect** enables
|
|
the ScreenConnect addon instead and uses their existing licensed instance for
|
|
remote access. Same RMM surface (the "remote control" device action, embedded/
|
|
launched session), different provider behind it - selectable per partner on the
|
|
addons page. It is an alternative remote-access backend, not an addition GuruConnect
|
|
depends on.
|
|
|
|
**What this skill proves / ports into the server:** the parameterized access
|
|
installer build (`build-installer` -> a pre-keyed URL whose repeated `c=` params
|
|
self-tag the device into the right Company/Site/Tag with no SC-console step), the
|
|
silent RMM push, and post-install control (`send-command`, `send-message`,
|
|
`set-properties` to keep SC custom properties in sync as the RMM record changes).
|
|
`sc_client.build_installer_url` + the control methods are what move server-side.
|
|
|
|
**Where the plan is mapped (all GuruRMM-side, needs Mike's go - status Raw):**
|
|
- `docs/specs/SPEC-024-screenconnect-auto-deploy.md` - the auto-deploy mechanics
|
|
(per-partner instance config, `c0..c7` slot mapping, scope toggles, dispatch).
|
|
- `docs/RMM_THOUGHTS.md` **Feature 7** - parameterized deploy + control from the RMM.
|
|
- `docs/RMM_THOUGHTS.md` **Refinement 7a** (Mike) - ScreenConnect as a per-partner
|
|
App Center entry; generalizes to a "Remote Access" category (SC/TeamViewer/AnyDesk).
|
|
- `docs/FEATURE_ROADMAP.md` **Integrations Center** - the unified addons UI surface.
|
|
|
|
Advance via RMM_THOUGHTS -> `/shape-spec`. Do NOT build until Mike gives the go.
|
|
|
|
## Reference
|
|
|
|
Verified method/param spec, auth, installer params, and the GetSessions gap:
|
|
`references/api-reference.md`.
|