Support for Chrome OS remote device commands

Update documentation

src/GamCommands.txt

@@ -67,7 +67,9 @@ If an item contains spaces, it should be surrounded by ".
 	gpresentation|
 	gscript|
 	gsite|
-	gsheet|gspreadsheet
+	gsheet|gspreadsheet|
+	gshortcut|
+	g3pshortcut
 <ProductID> ::=
 	Google-Apps|
 	Google-Chrome-Device-Management|
@@ -91,14 +93,19 @@ If an item contains spaces, it should be surrounded by ".
 	gams|postini|gsuitegams|gsuitepostini|gsuitemessagesecurity|Google-Apps-For-Postini|
 	gal|gsl|lite|gsuitelite|Google-Apps-Lite|
 	gau|gsb|unlimited|gsuitebusiness|Google-Apps-Unlimited|
-	gae|gse|enterprise|gsuiteenterprise|1010020020|
+	wsentplus|workspaceenterpriseplus|gae|gse|enterprise|gsuiteenterprise|1010020020|
+	wsbizplus|workspacebusinessplus|1010020025|
+	wsentstan|workspaceenterprisestandard|'1010020026|
+	wsbizstart|workspacebusinessstarter|1010020027|
+	wsbizstan|workspacebusinessstandard|1010020028|
 	gsefe|e4e|gsuiteenterpriseeducation|1010310002|
 	gsefes|e4es|gsuiteenterpriseeducationstudent|1010310003|
 	gsbau|businessarchived|gsuitebusinessarchived|
 	gseau|enterprisearchived|gsuiteenterprisearchived|
 	chrome|cdm|googlechromedevicemanagement|Google-Chrome-Device-Management|
 	coordinate|googlecoordinate|Google-Coordinate|
-	d4e|driveenterprise|drive4enterprise|
+	wsess|workspaceesentials|gsuiteessentials|essentials|d4e|driveenterprise|drive4enterprise|1010060001|
+	wsentess|workspaceenterpriseessentials|1010060003|
 	drive20gb|20gb|googledrivestorage20gb|Google-Drive-storage-20GB|
 	drive50gb|50gb|googledrivestorage50gb|Google-Drive-storage-50GB|
 	drive200gb|200gb|googledrivestorage200gb|Google-Drive-storage-200GB|
@@ -308,6 +315,7 @@ If an item contains spaces, it should be surrounded by ".
 	appdatacontents|
 	cancomment|
 	canreadrevisions|
+	contentrestrictions|
 	copyable|
 	copyrequireswriterpermission|
 	createddate|createdtime|
@@ -681,16 +689,22 @@ Specify a collection of Users by directly specifying them or by specifiying item
 	(localfile <FileName>)|
 	(convert)|(ocr)|(ocrlanguage <Language>)|
 	(restricted|restrict)|(starred|star)|(trashed|trash)|(viewed|view)|
+	(contentrestrictions readonly false)|
+	(contentrestrictions readonly true [reason <String>])|
 	copyrequireswriterpermission|
 	(lastviewedbyme <Time>)|(modifieddate|modifiedtime <Time>)|(description <String>)|(mimetype <MimeType>)|
-	(parentid <DriveFolderID>)|(parentname <DriveFolderName>)|(anyownerparentname <DriveFolderName>)|writerscantshare
+	(parentid <DriveFolderID>)|(parentname <DriveFolderName>)|(anyownerparentname <DriveFolderName>)|writerscantshare|
+	(shortcut <DriveFileID>)
 <DriveFileUpdateAttributes> ::=
 	(localfile <FileName>)|
 	(convert)|(ocr)|(ocrlanguage <Language>)|
 	(restricted|restrict <Boolean>)|(starred|star <Boolean>)|(trashed|trash <Boolean>)|(viewed|view <Boolean>)|
+	(contentrestrictions readonly false)|
+	(contentrestrictions readonly true [reason <String>])|
 	(copyrequireswriterpermission <Boolean>)|
 	(lastviewedbyme <Time>)|(modifieddate <Time>)|(description <String>)|(mimetype <MimeType>)|
-	(parentid <DriveFolderID>)|(parentname <DriveFolderName>)|(anyownerparentname <DriveFolderName>)|writerscantshare
+	(parentid <DriveFolderID>)|(parentname <DriveFolderName>)|(anyownerparentname <DriveFolderName>)|writerscantshare|
+	(shortcut <DriveFileID>)
 <GroupSettingsAttribute> ::=
 	(allowexternalmembers <Boolean>)|
 	(allowwebposting <Boolean>)|
@@ -1491,4 +1505,3 @@ gam <UserTypeEntity> show vacation [format]
 
 gam <UserTypeEntity> signout
 gam <UserTypeEntity> turnoff2sv
-

src/gam-install.sh

@@ -28,7 +28,7 @@ upgrade_only=false
 gamversion="latest"
 adminuser=""
 regularuser=""
-gam_glibc_vers="2.27 2.23"
+gam_glibc_vers="2.31 2.27 2.23"
 gam_macos_vers="10.15.6 10.14.6 10.13.6"
 
 while getopts "hd:a:o:b:lp:u:r:v:" OPTION

src/gam/__init__.py

@@ -3197,10 +3197,21 @@ def printDriveFileList(users):
                                                 'kind', 'etag', 'selfLink'
                                         ]:
                                             continue
-                                        x_attrib = f'{attrib}.{j}.{list_attrib}'
-                                        if x_attrib not in titles:
-                                            titles.append(x_attrib)
-                                        a_file[x_attrib] = l_attrib[list_attrib]
+                                        if not isinstance(l_attrib[list_attrib], dict):
+                                            x_attrib = f'{attrib}.{j}.{list_attrib}'
+                                            if x_attrib not in titles:
+                                                titles.append(x_attrib)
+                                            a_file[x_attrib] = l_attrib[list_attrib]
+                                        else:
+                                            for sl_attrib in l_attrib[list_attrib]:
+                                                if sl_attrib in [
+                                                        'kind', 'etag', 'selfLink'
+                                                ]:
+                                                    continue
+                                                x_attrib = f'{attrib}.{j}.{list_attrib}.{sl_attrib}'
+                                                if x_attrib not in titles:
+                                                    titles.append(x_attrib)
+                                                a_file[x_attrib] = l_attrib[list_attrib][sl_attrib]
                     elif isinstance(f_file[attrib], (str, int, bool)):
                         if attrib not in titles:
                             titles.append(attrib)
@@ -3538,7 +3549,11 @@ def getDriveFileAttribute(i, body, parameters, myarg, update=False):
                 sys.argv[i+2], f'gam <users> {operation} drivefile')
             i += 3
             if len(sys.argv) > i and sys.argv[i].lower() == 'reason':
-                body['contentRestrictions'][0]['reason'] = sys.argv[i+1]
+                if body['contentRestrictions'][0]['readOnly']:
+                    body['contentRestrictions'][0]['reason'] = sys.argv[i+1]
+                else:
+                    controlflow.invalid_argument_exit(
+                        'reason', 'contentrestrictions readonly false')
                 i += 2
         else:
             controlflow.invalid_argument_exit(
@@ -11391,6 +11406,14 @@ def ProcessGAMCommand(args):
                 elif command == 'block':
                     gapi_cloudidentity_devices.block_user()
             sys.exit(0)
+        elif command in ['issuecommand', 'getcommand']:
+            target = sys.argv[2].lower().replace('_', '')
+            if target == 'cros':
+                if command == 'issuecommand':
+                    gapi_directory_cros.issue_command()
+                elif command == 'getcommand':
+                    gapi_directory_cros.get_command()
+            sys.exit(0)
         users = getUsersToModify()
         command = sys.argv[3].lower()
         if command == 'print' and len(sys.argv) == 4:

src/gam/gapi/directory/cros.py

@@ -1,4 +1,7 @@
 import datetime
+import time
+
+import googleapiclient
 
 from gam.var import *
 import gam
@@ -7,10 +10,94 @@ from gam import display
 from gam import fileutils
 from gam import gapi
 from gam.gapi import directory as gapi_directory
+from gam.gapi import errors as gapi_errors
 from gam.gapi.directory import orgunits as gapi_directory_orgunits
 from gam import utils
 
 
+def issue_command():
+    cd = gapi_directory.build()
+    i, devices = getCrOSDeviceEntity(3, cd)
+    body = {}
+    final_states = ['EXPIRED', 'CANCELLED', 'EXECUTED_BY_CLIENT']
+    valid_commands = gapi.get_enum_values_minus_unspecified(
+            cd._rootDesc['schemas']
+            ['DirectoryChromeosdevicesIssueCommandRequest']
+            ['properties']['commandType']['enum'])
+    command_map = {}
+    for valid_command in valid_commands:
+        v = valid_command.lower().replace('_', '')
+        command_map[v] = valid_command
+    times_to_check_status = 1
+    doit = False
+    while i < len(sys.argv):
+        myarg = sys.argv[i].lower().replace('_', '')
+        if myarg == 'command':
+             command = sys.argv[i+1].lower().replace('_', '')
+             if command not in command_map:
+                 controlflow.system_error_exit(2, f'expected command of ' \
+                     f'{", ".join(valid_commands)} got {command}')
+             body['commandType'] = command_map[command]
+             i += 2
+             if command == 'setvolume':
+                 body['payload'] = {'volume': int(sys.argv[i])}
+                 i += 1
+        elif myarg == 'timestocheckstatus':
+            times_to_check_status = int(sys.argv[i+1])
+            i += 2
+        elif myarg == 'doit':
+            doit = True
+            i += 1
+        else:
+            controlflow.invalid_argument_exit(sys.argv[i], 'gam issuecommand cros')
+    if body['commandType'] == 'WIPE_USERS' and not doit:
+        controlflow.system_error_exit(2, 'wipe_users command requires admin ' \
+            'acknowledge user data will be destroyed with the ' \
+            'doit argument')
+    if body['commandType'] == 'REMOTE_POWERWASH' and not doit:
+        controlflow.system_error_exit(2, 'remote_powerwash command requires ' \
+            'admin acknowledge user data will be destroyed, device will need' \
+            ' to be reconnected to WiFi and re-enrolled with the doit argument')
+    for device_id in devices:
+        try:
+            result = gapi.call(cd.customer().devices().chromeos(), 'issueCommand',
+                  customerId=GC_Values[GC_CUSTOMER_ID], deviceId=device_id,
+                  throw_reasons=[gapi_errors.ErrorReason.FOUR_O_O],
+                  body=body)
+        except googleapiclient.errors.HttpError:
+            controlflow.system_error_exit(4, '400 response from Google. This ' \
+              'usually indicates the devices was not in a state where it will' \
+              ' accept the command. For example, reboot and take_a_screenshot' \
+              ' require the device to be in auto-start kiosk app mode.')
+        display.print_json(result)
+        command_id = result.get('commandId')
+        for i in range(0, times_to_check_status):
+            time.sleep(2)
+            result = gapi.call(cd.customer().devices().chromeos().commands(), 'get',
+              customerId=GC_Values[GC_CUSTOMER_ID], deviceId=device_id,
+              commandId=command_id)
+            display.print_json(result)
+            state = result.get('state')
+            if state in final_states:
+                break
+
+def get_command():
+    cd = gapi_directory.build()
+    i, devices = getCrOSDeviceEntity(3, cd)
+    command_id = None
+    while i < len(sys.argv):
+        myarg = sys.argv[i].lower().replace('_', '')
+        if myarg == 'commandid':
+            command_id = sys.argv[i+1]
+            i += 2
+        else:
+            controlflow.invalid_argument_exit(sys.argv[i], 'gam getcommand cros')
+    for device_id in devices:
+        result = gapi.call(cd.customer().devices().chromeos().commands(), 'get',
+                  customerId=GC_Values[GC_CUSTOMER_ID], deviceId=device_id,
+                  commandId=command_id)
+        display.print_json(result)
+
 def doUpdateCros():
     cd = gapi_directory.build()
     i, devices = getCrOSDeviceEntity(3, cd)

src/gam/var.py

@@ -8,7 +8,7 @@ import platform
 import re
 
 GAM_AUTHOR = 'Jay Lee <jay0lee@gmail.com>'
-GAM_VERSION = '5.23'
+GAM_VERSION = '5.24'
 GAM_LICENSE = 'Apache License 2.0 (http://www.apache.org/licenses/LICENSE-2.0)'
 
 GAM_URL = 'https://git.io/gam'
@@ -114,10 +114,44 @@ SKUS = {
         'aliases': ['gau', 'gsb', 'unlimited', 'gsuitebusiness'],
         'displayName': 'G Suite Business'
     },
+    '1010020027': {
+         'product': 'Google-Apps',
+         'aliases': ['wsbizstart', 'workspacebusinessstarter'],
+         'displayName': 'Workspace Business Starter'
+    },
+    '1010020028': {
+         'product': 'Google-Apps',
+         'aliases': ['wsbizstan', 'workspacebusinessstandard'],
+         'displayName': 'Workspace Business Standard'
+    },
+    '1010020025': {
+         'product': 'Google-Apps',
+         'aliases': ['wsbizplus', 'workspacebusinessplus'],
+         'displayName': 'Workspace Business Plus'
+    },
+    '1010060001': {
+        'product': 'Google-Apps',
+        'aliases': [
+            'gsuiteessentials', 'essentials', 'd4e', 'driveenterprise',
+            'drive4enterprise', 'wsess', 'workspaceesentials'
+        ],
+        'displayName': 'Google Workspace Essentials'
+    },
+    '1010060003': {
+         'product': 'Google-Apps',
+         'aliases': ['wsentess', 'workspaceenterpriseessentials'],
+         'displayName': 'Workspace Enterprise Essentials'
+    },
+    '1010020026': {
+         'product': 'Google-Apps',
+         'aliases': ['wsentstan', 'workspaceenterprisestandard'],
+         'displayName': 'Workspace Enterprise Standard'
+    },
     '1010020020': {
         'product': 'Google-Apps',
-        'aliases': ['gae', 'gse', 'enterprise', 'gsuiteenterprise'],
-        'displayName': 'Google Workspace Enterprise Plus (fka G Suite Enterprise)'
+        'aliases': ['gae', 'gse', 'enterprise', 'gsuiteenterprise',
+                    'wsentplus', 'workspaceenterpriseplus'],
+        'displayName': 'Workspace Enterprise Plus'
     },
     '1010340002': {
         'product': '101034',
@@ -129,14 +163,6 @@ SKUS = {
         'aliases': ['gseau', 'enterprisearchived', 'gsuiteenterprisearchived'],
         'displayName': 'Google Workspace Enterprise Plus Archived'
     },
-    '1010060001': {
-        'product': '101006',
-        'aliases': [
-            'gsuiteessentials', 'essentials', 'd4e', 'driveenterprise',
-            'drive4enterprise'
-        ],
-        'displayName': 'Google Workspace Essentials'
-    },
     'Google-Drive-storage-20GB': {
         'product': 'Google-Drive-storage',
         'aliases': ['drive20gb', '20gb', 'googledrivestorage20gb'],
@@ -192,11 +218,6 @@ SKUS = {
         'aliases': ['vfe', 'googlevaultformeremployee'],
         'displayName': 'Google Vault Former Employee'
     },
-    'Google-Coordinate': {
-        'product': 'Google-Coordinate',
-        'aliases': ['coordinate', 'googlecoordinate'],
-        'displayName': 'Google Coordinate'
-    },
     'Google-Chrome-Device-Management': {
         'product': 'Google-Chrome-Device-Management',
         'aliases': ['chrome', 'cdm', 'googlechromedevicemanagement'],
@@ -380,6 +401,7 @@ DRIVEFILE_FIELDS_CHOICES_MAP = {
     'appdatacontents': 'appDataContents',
     'cancomment': 'canComment',
     'canreadrevisions': 'canReadRevisions',
+    'contentrestrictions': 'contentRestrictions',
     'copyable': 'copyable',
     'copyrequireswriterpermission': 'copyRequiresWriterPermission',
     'createddate': 'createdDate',
@@ -499,6 +521,7 @@ MIMETYPE_GA_SCRIPT = f'{APPLICATION_VND_GOOGLE_APPS}script'
 MIMETYPE_GA_SITES = f'{APPLICATION_VND_GOOGLE_APPS}sites'
 MIMETYPE_GA_SPREADSHEET = f'{APPLICATION_VND_GOOGLE_APPS}spreadsheet'
 MIMETYPE_GA_SHORTCUT = f'{APPLICATION_VND_GOOGLE_APPS}shortcut'
+MIMETYPE_GA_3P_SHORTCUT = f'{APPLICATION_VND_GOOGLE_APPS}drive-sdk'
 
 MIMETYPE_CHOICES_MAP = {
     'gdoc': MIMETYPE_GA_DOCUMENT,
@@ -510,6 +533,8 @@ MIMETYPE_CHOICES_MAP = {
     'gfusion': MIMETYPE_GA_FUSIONTABLE,
     'gpresentation': MIMETYPE_GA_PRESENTATION,
     'gscript': MIMETYPE_GA_SCRIPT,
+    'gshortcut': MIMETYPE_GA_SHORTCUT,
+    'g3pshortcut': MIMETYPE_GA_3P_SHORTCUT,
     'gsite': MIMETYPE_GA_SITES,
     'gsheet': MIMETYPE_GA_SPREADSHEET,
     'gspreadsheet': MIMETYPE_GA_SPREADSHEET,