Skip to content

About

PowerShell wrapper for ConnectWise Control

Resources

Code of conduct

Contributing

Security policy

Stars

85 stars

Watchers

15 watching

Forks

Repository files navigation


logo
ConnectWiseControlAPI

A PowerShell wrapper for the ConnectWise ScreenConnect (formerly ConnectWise Control) web API

CI Codacy Badge Gallery Donate

List of Functions • Examples • Install • Contribute • Submit a Bug • Request a Feature

This module makes it easy to leverage PowerShell to automate tasks in ScreenConnect.

ConnectWise renamed Control back to ScreenConnect. The module keeps its name and its CWC command names, so scripts don't need renaming. Version 0.5.0 does change some behaviour: see Upgrading from 0.4.

The module can be easily installed from the PowerShellGallery

Install-Module 'ConnectWiseControlAPI'

If you are having issues accessing the PowerShell Gallery check out my repair script

Upgrading from 0.4

0.5.0 changes some behaviour. Check your scripts before you update:

  • Remove-CWCSession, Remove-CWCSessionNote, Remove-CWCHostFromSession and Remove-CWCToolboxItem ask for confirmation by default, and so does Send-CWCToolboxItem with -Elevated or -Silent. Unattended scripts must add -Confirm:$false. Without it, a session started with -NonInteractive fails at the prompt and does nothing; other unattended hosts may wait at the prompt or take its default answer (Yes).
  • Connect-CWC without -Force now switches to a different server, sign-in method or user. Before, it kept the old connection.
  • Get-CWCLastContact returns an error when it finds no connection event. Before, it returned the current time.
  • Get-CWCAuditLog covers the last 24 hours unless you pass -StartDate and -EndDate.
  • Get-CWCSession -Type Support and -Type Meeting without -Group read the All Sessions and All Meetings groups. Before, they read All Machines, which holds Access sessions.
  • A read or "set to value" update that gets HTTP 500 is retried 3 times (after 2, 4 and 8 seconds) before it fails. 0.4 failed at once. Commands, wakes, deletes and user creation are never retried.

The full list is in the changelog.

Requirements

  • Requires your ScreenConnect server to use https.

  • One of three authentication methods:

    • Credentials (Connect-CWC -Credentials): an account without MFA. Use a complex username and password. All functions except Find-CWCSession are available, limited by the account's permissions.

    • Credentials with MFA (Connect-CWC -Credentials plus -Mfa, -OneTimeCode or -TotpSecret): an account that requires MFA, signed in the way the web page does. Same functions as credentials. -Mfa asks for the code at the console (authenticator app, email or SMS). -TotpSecret computes the authenticator-app code for unattended scripts from the account's TOTP secret (ms:... or Base32); keep that secret in a secret store, and note that storing it next to the password makes MFA a single factor. The login expires on the server; run Connect-CWC again before each batch of work (a still-valid login is reused with one check call).

      Connect-CWC -Server 'screenconnect.example.com' -Credentials (Get-Credential) -Mfa
      
      # Unattended, with Microsoft.PowerShell.SecretManagement
      Connect-CWC -Server 'screenconnect.example.com' -Credentials (Get-Secret 'CWC-Login') -TotpSecret (Get-Secret 'CWC-TOTP')
    • API secret (Connect-CWC -ApiSecret): install the RESTful API Manager extension and set its RESTfulAuthenticationSecret setting to a long random value. Works when every account requires MFA. Available functions: Find-CWCSession, New-CWCSession, Get-CWCSessionDetail, Update-CWCSessionName, Invoke-CWCCommand (queues the command but does not return its output), Add-CWCSessionNote, Send-CWCSessionMessage, Send-CWCToolboxItem. The secret bypasses ScreenConnect's role permissions and acts on every session, so protect it like an administrator password. If the extension's RESTfulAllowedOrigin setting is set, pass a matching -Origin.

      $Secret = Read-Host -AsSecureString -Prompt 'RESTful API secret'
      Connect-CWC -Server 'screenconnect.example.com' -ApiSecret $Secret
      Find-CWCSession -Filter "Name LIKE 'DESKTOP-*'"

Tutorials & Resources

In-depth tutorials on christaylor.codes:

If you use this project please give it a star and follow so you can get updated when new features are released. This also lets me know what projects are getting used and what ones I should dedicate more time to. If you want to get more involved please see the contributing page. Projects need all kinds of help even if you don't know how to code.

Donating

If you cant take time to contribute maybe you would like to help another way.

It takes time to maintain this project. Does the time spent on this module help you do cool things? Is that time worth a beer or two?

Donations allow me to spend more time on this project and implement your feature requests.

About

PowerShell wrapper for ConnectWise Control

Resources

Code of conduct

Contributing

Security policy

Stars

85 stars

Watchers

15 watching

Forks

Releases

Packages

Contributors

Languages