Files

Howard Enos 87688b65da sync: auto-sync from HOWARD-HOME at 2026-06-21 20:36:14

Author: Howard Enos
Machine: HOWARD-HOME
Timestamp: 2026-06-21 20:36:14

2026-06-21 20:36:41 -07:00

5.3 KiB

Raw Blame History

name, description

name	description
screenconnect	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.

name

description

screenconnect

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

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:

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.
Push that installer via /rmm (download + msiexec /i ... /qn as SYSTEM).
The SC agent connects -> a session named <name> appears with CP1/CP2/CP3 set.
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.

5.3 KiB Raw Blame History