-
Notifications
You must be signed in to change notification settings - Fork 33
/
task.rb
589 lines (476 loc) · 20.9 KB
/
task.rb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
# frozen_string_literal: true
# This class is used to manage tasks using the Task Scheduler V2 API
#
# https://docs.microsoft.com/en-gb/windows/win32/taskschd/task-scheduler-2-0-interfaces
#
require_relative './error'
require_relative './trigger'
# disabling some false positives on the FFI definitions
# rubocop:disable Naming/ClassAndModuleCamelCase,Lint/Void
# module PuppetX
module PuppetX; end
# module PuppetX::PuppetLabs
module PuppetX::PuppetLabs; end
module PuppetX::PuppetLabs::ScheduledTask
# Installs and manages Windows Scheduled Tasks.
class Task
# The name of the root folder for tasks
ROOT_FOLDER = '\\'
# https://docs.microsoft.com/en-us/windows/win32/api/taskschd/ne-taskschd-task_enum_flags
class TASK_ENUM_FLAGS
# Enumerates all tasks, including tasks that are hidden.
TASK_ENUM_HIDDEN = 0x1
end
# https://docs.microsoft.com/en-us/windows/win32/api/taskschd/ne-taskschd-task_action_type
class TASK_ACTION_TYPE
# This action performs a command-line operation. For example, the action can run a script, launch
# an executable, or, if the name of a document is provided, find its associated application and
# launch the application with the document.
TASK_ACTION_EXEC = 0
# This action fires a handler. This action can only be used if the task Compatibility property is
# set to TASK_COMPATIBILITY_V2.
TASK_ACTION_COM_HANDLER = 5
# This action sends email message. This action can only be used if the task Compatibility property
# is set to TASK_COMPATIBILITY_V2.
TASK_ACTION_SEND_EMAIL = 6
# This action shows a message box. This action can only be used if the task Compatibility property
# is set to TASK_COMPATIBILITY_V2.
TASK_ACTION_SHOW_MESSAGE = 7
end
# https://docs.microsoft.com/en-us/windows/win32/api/taskschd/ne-taskschd-task_compatibility
# Win7/2008 R2 = 3
# Win8/Server 2012 R2 or Server 2016 = 4
# Windows 10 = 5 / 6
class TASK_COMPATIBILITY
# The task is compatible with the AT command.
TASK_COMPATIBILITY_AT = 0
# The task is compatible with Task Scheduler 1.0.
TASK_COMPATIBILITY_V1 = 1
# The task is compatible with Task Scheduler 2.0.
TASK_COMPATIBILITY_V2 = 2
# The task is compatible with Task Scheduler 2.1.
TASK_COMPATIBILITY_V2_1 = 3
# The task is compatible with Task Scheduler 2.2.
TASK_COMPATIBILITY_V2_2 = 4
# The task is compatible with Task Scheduler 2.3.
TASK_COMPATIBILITY_V2_3 = 5
# The task is compatible with Task Scheduler 2.4.
TASK_COMPATIBILITY_V2_4 = 6
end
# https://docs.microsoft.com/en-us/windows/win32/api/taskschd/ne-taskschd-task_creation
class TASK_CREATION
# The Task Scheduler service checks the syntax of the XML that describes the task but does
# not register the task. This constant cannot be combined with the TASK_CREATE,
# TASK_UPDATE, or TASK_CREATE_OR_UPDATE values.
TASK_VALIDATE_ONLY = 0x1
# The Task Scheduler service registers the task as a new task.
TASK_CREATE = 0x2
# The Task Scheduler service registers the task as an updated version of an existing task.
# When a task with a registration trigger is updated, the task will execute after the update occurs.
TASK_UPDATE = 0x4
# ( TASK_CREATE | TASK_UPDATE )
TASK_CREATE_OR_UPDATE = 0x6
# The Task Scheduler service registers the disabled task. A disabled task cannot run until it is enabled.
# For more information, see Enabled Property of ITaskSettings and Enabled Property of IRegisteredTask.
TASK_DISABLE = 0x8
# The Task Scheduler service is prevented from adding the allow access-control entry (ACE) for the context principal.
# When the ITaskFolder::RegisterTaskDefinition or ITaskFolder::RegisterTask functions are called with
# this flag to update a task, the Task Scheduler service does not add the ACE for the new context principal
# and does not remove the ACE from the old context principal.
TASK_DONT_ADD_PRINCIPAL_ACE = 0x10
# The Task Scheduler service creates the task, but ignores the registration triggers in the task.
# By ignoring the registration triggers, the task will not execute when it is registered unless a
# time-based trigger causes it to execute on registration.
TASK_IGNORE_REGISTRATION_TRIGGERS = 0x20
end
# https://docs.microsoft.com/en-us/windows/win32/api/taskschd/ne-taskschd-task_logon_type
class TASK_LOGON_TYPE
# The logon method is not specified. Used for non-NT credentials.
TASK_LOGON_NONE = 0
# Use a password for logging on the user. The password must be supplied at registration time.
TASK_LOGON_PASSWORD = 1
# The service will log the user on using Service For User (S4U), and the task will run in a non-interactive desktop.
# When an S4U logon is used, no password is stored by the system and there is no access to either the network or to encrypted files.
TASK_LOGON_S4U = 2
# User must already be logged on. The task will be run only in an existing interactive session.
TASK_LOGON_INTERACTIVE_TOKEN = 3
# Group activation. The groupId field specifies the group.
TASK_LOGON_GROUP = 4
# Indicates that a Local System, Local Service, or Network Service account is being used as a security context to run the task.
TASK_LOGON_SERVICE_ACCOUNT = 5
# Not in use; currently identical to TASK_LOGON_PASSWORD.
TASK_LOGON_INTERACTIVE_TOKEN_OR_PASSWORD = 6
end
# https://docs.microsoft.com/en-us/windows/win32/api/taskschd/ne-taskschd-task_run_flags
class TASK_RUN_FLAGS
# The task is run with all flags ignored.
TASK_RUN_NO_FLAGS = 0
# The task is run as the user who is calling the Run method.
TASK_RUN_AS_SELF = 0x1
# The task is run regardless of constraints such as "do not run on batteries" or "run only if idle".
TASK_RUN_IGNORE_CONSTRAINTS = 0x2
# The task is run using a terminal server session identifier.
TASK_RUN_USE_SESSION_ID = 0x4
# The task is run using a security identifier.
TASK_RUN_USER_SID = 0x8
end
# https://docs.microsoft.com/en-us/windows/win32/api/taskschd/ne-taskschd-task_runlevel_type
class TASK_RUNLEVEL_TYPE
# Tasks will be run with the least privileges.
TASK_RUNLEVEL_LUA = 0
# Tasks will be run with the highest privileges.
TASK_RUNLEVEL_HIGHEST = 1
end
# https://docs.microsoft.com/en-us/windows/win32/api/taskschd/ne-taskschd-task_processtokensid_type
class TASK_PROCESSTOKENSID_TYPE
# No changes will be made to the process token groups list.
TASK_PROCESSTOKENSID_NONE = 0
# A task SID that is derived from the task name will be added to the process token groups list,
# and the token default discretionary access control list (DACL) will be modified to allow only
# the task SID and local system full control and the account SID read control.
TASK_PROCESSTOKENSID_UNRESTRICTED = 1
# A Task Scheduler will apply default settings to the task process.
TASK_PROCESSTOKENSID_DEFAULT = 2
end
# https://docs.microsoft.com/en-us/windows/win32/api/taskschd/ne-taskschd-task_state
class TASK_STATE
# The state of the task is unknown.
TASK_STATE_UNKNOWN = 0
# The task is registered but is disabled and no instances of the task are queued or running. The task cannot be run until it is enabled.
TASK_STATE_DISABLED = 1
# Instances of the task are queued.
TASK_STATE_QUEUED = 2
# The task is ready to be executed, but no instances are queued or running.
TASK_STATE_READY = 3
# One or more instances of the task is running.
TASK_STATE_RUNNING = 4
end
# https://docs.microsoft.com/en-us/windows/win32/api/taskschd/ne-taskschd-task_instances_policy
class TASK_INSTANCES_POLICY
# Starts new instance while an existing instance is running.
TASK_INSTANCES_PARALLEL = 0
# Starts a new instance of the task after all other instances of the task are complete.
TASK_INSTANCES_QUEUE = 1
# Does not start a new instance if an existing instance of the task is running.
TASK_INSTANCES_IGNORE_NEW = 2
# Stops an existing instance of the task before it starts a new instance.
TASK_INSTANCES_STOP_EXISTING = 3
end
# Returns a new TaskScheduler object.
# An existing task named task_name will be returned if one exists,
# otherwise a new task is created by that name (but not yet saved to the system).
#
def initialize(task_name, compatibility_level = nil)
raise TypeError unless task_name.is_a?(String)
@full_task_path = ROOT_FOLDER + task_name
# definition populated when task exists, otherwise new
@task, @definition = self.class.task(@full_task_path)
task_userid = @definition.Principal.UserId || ''
self.compatibility = TASK_COMPATIBILITY::TASK_COMPATIBILITY_V1 if compatibility_level == :v1_compatibility
set_account_information(task_userid, nil)
end
# API v1 Compatibility list
V1_COMPATIBILITY = [
TASK_COMPATIBILITY::TASK_COMPATIBILITY_AT,
TASK_COMPATIBILITY::TASK_COMPATIBILITY_V1,
].freeze
# API v2 Compatibility list
V2_COMPATIBILITY = [
TASK_COMPATIBILITY::TASK_COMPATIBILITY_V2_4,
TASK_COMPATIBILITY::TASK_COMPATIBILITY_V2_3,
TASK_COMPATIBILITY::TASK_COMPATIBILITY_V2_2,
TASK_COMPATIBILITY::TASK_COMPATIBILITY_V2_1,
TASK_COMPATIBILITY::TASK_COMPATIBILITY_V2,
TASK_COMPATIBILITY::TASK_COMPATIBILITY_AT,
TASK_COMPATIBILITY::TASK_COMPATIBILITY_V1,
].freeze
# Returns an array of scheduled task names.
#
def self.tasks(compatibility = V2_COMPATIBILITY)
enum_task_names(ROOT_FOLDER,
include_child_folders: true,
include_compatibility: compatibility).map do |item|
item.partition('\\')[2]
end
end
# Reserved for furure use
RESERVED_FOR_FUTURE_USE = 0
# Returns an array of scheduled task names.
# By default EVERYTHING is enumerated
# option hash
# include_child_folders: recurses into child folders for tasks. Default true
# include_compatibility: Only include tasks which have any of the specified compatibility levels. Default empty array (everything is permitted)
#
def self.enum_task_names(folder_path = ROOT_FOLDER, enum_options = {})
raise TypeError unless folder_path.is_a?(String)
options = {
include_child_folders: true,
include_compatibility: []
}.merge(enum_options)
array = []
task_folder = task_service.GetFolder(folder_path)
filter_compatibility = !options[:include_compatibility].empty?
task_folder.GetTasks(TASK_ENUM_FLAGS::TASK_ENUM_HIDDEN).each do |task|
next if filter_compatibility && !options[:include_compatibility].include?(task.Definition.Settings.Compatibility)
array << task.Path
end
return array unless options[:include_child_folders]
task_folder.GetFolders(RESERVED_FOR_FUTURE_USE).each do |child_folder|
array += enum_task_names(child_folder.Path, options)
end
array
end
# Returns whether or not the scheduled task exists.
def self.exists?(task_path)
raise TypeError unless task_path.is_a?(String)
begin
task_folder = task_service.GetFolder(folder_path_from_task_path(task_path))
# https://msdn.microsoft.com/en-us/library/windows/desktop/aa381363(v=vs.85).aspx
_task = task_folder.GetTask(task_name_from_task_path(task_path))
rescue StandardError
return false
end
true
end
# Delete the specified task name.
#
def self.delete(task_name)
task_path = ROOT_FOLDER + task_name
task_folder = task_service.GetFolder(folder_path_from_task_path(task_path))
task_folder.DeleteTask(task_name_from_task_path(task_path), 0)
end
# Creates or Updates an existing task with the supplied task definition
# Tasks must be saved before they can be activated.
#
# The .job file itself is typically stored in the C:\WINDOWS\Tasks folder.
def save
task_path = @task ? @task.Path : @full_task_path
self.class.create_folder(self.class.folder_path_from_task_path(task_path))
task_folder = self.class.task_service.GetFolder(self.class.folder_path_from_task_path(task_path))
task_user = nil
task_password = nil
case @definition.Principal.LogonType
when TASK_LOGON_TYPE::TASK_LOGON_PASSWORD,
TASK_LOGON_TYPE::TASK_LOGON_INTERACTIVE_TOKEN_OR_PASSWORD
task_user = @definition.Principal.UserId
task_password = @task_password
end
saved = task_folder.RegisterTaskDefinition(
self.class.task_name_from_task_path(task_path),
@definition,
TASK_CREATION::TASK_CREATE_OR_UPDATE,
task_user, task_password, @definition.Principal.LogonType
)
@task ||= saved
end
# Sets the +user+ and +password+ for the given task. If the user and
# password are set properly then true is returned.
#
# In some cases the job may be created, but the account information was
# bad. In this case the task is created but a warning is generated and
# false is returned.
#
# Note that if intending to use SYSTEM, specify an empty user and nil password
#
# This must be done prior to the 1st save() call for the task to be
# properly registered and visible through the MMC snap-in / schtasks.exe
#
def set_account_information(user, password)
@task_password = password
@definition.Principal.RunLevel = TASK_RUNLEVEL_TYPE::TASK_RUNLEVEL_HIGHEST
if user.nil? || user == ''
# Setup for the local system account
@definition.Principal.UserId = 'SYSTEM'
@definition.Principal.LogonType = TASK_LOGON_TYPE::TASK_LOGON_SERVICE_ACCOUNT
else
@definition.Principal.UserId = user
@definition.Principal.LogonType = if @task_password || user[-1] == '$'
TASK_LOGON_TYPE::TASK_LOGON_PASSWORD
else
TASK_LOGON_TYPE::TASK_LOGON_INTERACTIVE_TOKEN
end
end
true
end
# Returns the user associated with the task or nil if no user has yet
# been associated with the task.
#
def account_information
principal = @definition.Principal
principal&.UserId
end
# Returns the name of the application associated with the task.
#
def application_name
action = default_action(create_if_missing: false)
action&.Path
end
# Sets the application name associated with the task.
#
def application_name=(app)
action = default_action(create_if_missing: true)
action.Path = app
app
end
# Returns the command line parameters for the task.
#
def parameters
action = default_action(create_if_missing: false)
action&.Arguments
end
# Sets the parameters for the task. These parameters are passed as command
# line arguments to the application the task will run. To clear the command
# line parameters set it to an empty string.
#
def parameters=(param)
action = default_action(create_if_missing: true)
action.Arguments = param
param
end
# Returns the working directory for the task.
#
def working_directory
action = default_action(create_if_missing: false)
action&.WorkingDirectory
end
# Sets the working directory for the task.
#
def working_directory=(dir)
action = default_action(create_if_missing: false)
action.WorkingDirectory = dir
dir
end
# Gets task compatibility
def compatibility
@definition.Settings.Compatibility
end
# Sets task compatibility
def compatibility=(value)
# https://msdn.microsoft.com/en-us/library/windows/desktop/aa381846(v=vs.85).aspx
@definition.Settings.Compatibility = value
end
# Gets task description
def description
@definition.RegistrationInfo.Description
end
# Sets task description
def description=(value)
@definition.RegistrationInfo.Description = value
end
# Returns a set of trigger hashes with their indexes, for supported trigger
# types. Returns nil for each unknown trigger types in the collection.
#
def triggers
Array.new(@definition.Triggers.count) { |i| trigger(i) }
end
# Deletes the trigger at the specified index.
#
def delete_trigger(index)
# The older V1 API uses a starting index of zero, wherease the V2 API uses one.
# Need to increment by one to maintain the same behavior
index += 1
@definition.Triggers.Remove(index)
index
end
# Deletes all triggers
def clear_triggers
@definition.Triggers.Clear()
end
# Appends a new trigger for the currently active task.
#
def append_trigger(manifest_hash)
Trigger::V2.append_trigger(@definition, manifest_hash)
end
# Checks if task is enabled
def enabled
@definition.Settings.Enabled
end
# Sets the enabled value
def enabled=(value)
@definition.Settings.Enabled = value
end
# :stopdoc:
def self.task_service
return @service unless @service.nil?
@service = WIN32OLE.new('Schedule.Service')
@service.connect
@service
end
# Get task name from task path
def self.task_name_from_task_path(task_path)
task_path.rpartition('\\')[2]
end
# Get task path folder
def self.folder_path_from_task_path(task_path)
path = task_path.rpartition('\\')[0]
path.empty? ? ROOT_FOLDER : path
end
# create_folder returns "S_OK" if created or an HRESULT error code.
# It will create the full path specified, not just a the last child.
def self.create_folder(path)
task_service.GetFolder(path)
rescue WIN32OLERuntimeError => e
raise Puppet::Error.new(_('GetFolder failed with: %{error}') % { error: e }, e) unless Error.com_error_type?(e, Error::ERROR_FILE_NOT_FOUND)
task_service.GetFolder(ROOT_FOLDER).CreateFolder(path)
end
# Gets the task with a specified task path
def self.task(task_path)
raise TypeError unless task_path.is_a?(String)
service = task_service
begin
task_folder = service.GetFolder(folder_path_from_task_path(task_path))
# https://msdn.microsoft.com/en-us/library/windows/desktop/aa381363(v=vs.85).aspx
task = task_folder.GetTask(task_name_from_task_path(task_path))
return task, task.Definition
rescue WIN32OLERuntimeError => e
raise Puppet::Error.new(_('GetTask failed with: %{error}') % { error: e }, e) unless Error.com_error_type?(e, Error::ERROR_FILE_NOT_FOUND)
end
[nil, service.NewTask(0)]
end
# Find the first TASK_ACTION_EXEC action
def default_action(options = {})
action = nil
([email protected]).each do |i|
index_action = action_at(i)
action = index_action if index_action.Type == TASK_ACTION_TYPE::TASK_ACTION_EXEC
break if action
end
action = @definition.Actions.Create(TASK_ACTION_TYPE::TASK_ACTION_EXEC) if action.nil? && options.fetch(:create_if_missing, false)
action
end
# Gets the action item with the specified index
def action_at(index)
@definition.Actions.Item(index)
rescue WIN32OLERuntimeError => e
raise unless Error.com_error_type?(e, Error::E_INVALIDARG)
nil
end
# Returns a Win32OLE Trigger Object for the trigger at the given index for the
# supplied definition.
#
# Returns nil if the index does not exist
#
# Note - This is a 1 based array (not zero)
#
def trigger_at(index)
@definition.Triggers.Item(index)
rescue WIN32OLERuntimeError => e
raise unless Error.com_error_type?(e, Error::E_INVALIDARG)
nil
end
# Returns a hash that describes the trigger at the given index for the
# current task.
#
def trigger(index)
# The older V1 API uses a starting index of zero, wherease the V2 API uses one.
# Need to increment by one to maintain the same behavior
trigger_object = trigger_at(index + 1)
if trigger_object.nil? || Trigger::V2::TYPE_MANIFEST_MAP[trigger_object.Type].nil?
# nil trigger definitions are unsupported ITrigger types
nil
else
Trigger::V2.to_manifest_hash(trigger_object).merge!('index' => index)
end
end
end
end