110 lines
5.3 KiB
Markdown
110 lines
5.3 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`).
|
|
|
|
## Future: GuruRMM integration (Raw idea)
|
|
|
|
Tie this into GuruRMM (parallels the multi-vendor security thought, Feature 6):
|
|
when a device is flagged for ScreenConnect in the RMM, GuruRMM looks up the
|
|
device's client/site/tags and calls `build-installer` to produce a parameterized
|
|
installer, then pushes it via the agent - so the device installs the correct SC
|
|
client and self-places into the right Company/Site/Tag automatically. `set-
|
|
properties` keeps the SC tags in sync when the RMM record changes. Capture/advance
|
|
via RMM_THOUGHTS -> /shape-spec (needs Mike's go).
|
|
|
|
## Reference
|
|
|
|
Verified method/param spec, auth, installer params, and the GetSessions gap:
|
|
`references/api-reference.md`.
|