win32-taskscheduler 0.2.0 → 2.0.4

data/lib/win32/taskscheduler/constants.rb

@@ -0,0 +1,266 @@
+require_relative "sid"
+
+module Win32
+  class TaskScheduler
+    module TaskSchedulerConstants
+      SERVICE_ACCOUNT_USERS = SID::SERVICE_ACCOUNT_USERS
+
+      BUILT_IN_GROUPS = SID::BUILT_IN_GROUPS
+
+      SYSTEM_USERS = SERVICE_ACCOUNT_USERS + BUILT_IN_GROUPS
+
+      # Triggers
+
+      # Trigger is set to run the task a single time
+      TASK_TIME_TRIGGER_ONCE = 1
+
+      # Trigger is set to run the task on a daily interval
+      TASK_TIME_TRIGGER_DAILY = 2
+
+      # Trigger is set to run the task on specific days of a specific week & month
+      TASK_TIME_TRIGGER_WEEKLY = 3
+
+      # Trigger is set to run the task on specific day(s) of the month
+      TASK_TIME_TRIGGER_MONTHLYDATE = 4
+
+      # Trigger is set to run the task on specific day(s) of the month
+      TASK_TIME_TRIGGER_MONTHLYDOW = 5
+
+      # Trigger is set to run the task if the system remains idle for the amount
+      # of time specified by the idle wait time of the task
+      TASK_EVENT_TRIGGER_ON_IDLE = 6
+
+      TASK_TRIGGER_REGISTRATION = 7
+
+      # Trigger is set to run the task at system startup
+      TASK_EVENT_TRIGGER_AT_SYSTEMSTART = 8
+
+      # Trigger is set to run the task when a user logs on
+      TASK_EVENT_TRIGGER_AT_LOGON = 9
+
+      TASK_TRIGGER_SESSION_STATE_CHANGE = 11
+
+      # Daily Tasks
+
+      # The task will run on Sunday
+      TASK_SUNDAY = 0x1
+
+      # The task will run on Monday
+      TASK_MONDAY = 0x2
+
+      # The task will run on Tuesday
+      TASK_TUESDAY = 0x4
+
+      # The task will run on Wednesday
+      TASK_WEDNESDAY = 0x8
+
+      # The task will run on Thursday
+      TASK_THURSDAY = 0x10
+
+      # The task will run on Friday
+      TASK_FRIDAY = 0x20
+
+      # The task will run on Saturday
+      TASK_SATURDAY = 0x40
+
+      # Weekly tasks
+
+      # The task will run between the 1st and 7th day of the month
+      TASK_FIRST_WEEK = 0x01
+
+      # The task will run between the 8th and 14th day of the month
+      TASK_SECOND_WEEK = 0x02
+
+      # The task will run between the 15th and 21st day of the month
+      TASK_THIRD_WEEK = 0x04
+
+      # The task will run between the 22nd and 28th day of the month
+      TASK_FOURTH_WEEK = 0x08
+
+      # The task will run the last seven days of the month
+      TASK_LAST_WEEK = 0x10
+
+      # Monthly tasks
+
+      # The task will run in January
+      TASK_JANUARY = 0x1
+
+      # The task will run in February
+      TASK_FEBRUARY = 0x2
+
+      # The task will run in March
+      TASK_MARCH = 0x4
+
+      # The task will run in April
+      TASK_APRIL = 0x8
+
+      # The task will run in May
+      TASK_MAY = 0x10
+
+      # The task will run in June
+      TASK_JUNE = 0x20
+
+      # The task will run in July
+      TASK_JULY = 0x40
+
+      # The task will run in August
+      TASK_AUGUST = 0x80
+
+      # The task will run in September
+      TASK_SEPTEMBER = 0x100
+
+      # The task will run in October
+      TASK_OCTOBER = 0x200
+
+      # The task will run in November
+      TASK_NOVEMBER = 0x400
+
+      # The task will run in December
+      TASK_DECEMBER = 0x800
+
+      # Flags
+
+      # Used when converting AT service jobs into work items
+      TASK_FLAG_INTERACTIVE = 0x1
+
+      # The work item will be deleted when there are no more scheduled run times
+      TASK_FLAG_DELETE_WHEN_DONE = 0x2
+
+      # The work item is disabled. Useful for temporarily disabling a task
+      TASK_FLAG_DISABLED = 0x4
+
+      # The work item begins only if the computer is not in use at the scheduled
+      # start time
+      TASK_FLAG_START_ONLY_IF_IDLE = 0x10
+
+      # The work item terminates if the computer makes an idle to non-idle
+      # transition while the work item is running
+      TASK_FLAG_KILL_ON_IDLE_END = 0x20
+
+      # The work item does not start if the computer is running on battery power
+      TASK_FLAG_DONT_START_IF_ON_BATTERIES = 0x40
+
+      # The work item ends, and the associated application quits, if the computer
+      # switches to battery power
+      TASK_FLAG_KILL_IF_GOING_ON_BATTERIES = 0x80
+
+      # The work item starts only if the computer is in a docking station
+      TASK_FLAG_RUN_ONLY_IF_DOCKED = 0x100
+
+      # The work item created will be hidden
+      TASK_FLAG_HIDDEN = 0x200
+
+      # The work item runs only if there is a valid internet connection
+      TASK_FLAG_RUN_IF_CONNECTED_TO_INTERNET = 0x400
+
+      # The work item starts again if the computer makes a non-idle to idle
+      # transition
+      TASK_FLAG_RESTART_ON_IDLE_RESUME = 0x800
+
+      # The work item causes the system to be resumed, or awakened, if the
+      # system is running on batter power
+      TASK_FLAG_SYSTEM_REQUIRED = 0x1000
+
+      # The work item runs only if a specified account is logged on interactively
+      TASK_FLAG_RUN_ONLY_IF_LOGGED_ON = 0x2000
+
+      # Triggers
+
+      # The task will stop at some point in time
+      TASK_TRIGGER_FLAG_HAS_END_DATE = 0x1
+
+      # The task can be stopped at the end of the repetition period
+      TASK_TRIGGER_FLAG_KILL_AT_DURATION_END = 0x2
+
+      # The task trigger is disabled
+      TASK_TRIGGER_FLAG_DISABLED = 0x4
+
+      # Run Level Types
+      # Tasks will be run with the least privileges
+      TASK_RUNLEVEL_LUA      = 0
+      # Tasks will be run with the highest privileges
+      TASK_RUNLEVEL_HIGHEST  = 1
+
+      # Logon Types
+      # Used for non-NT credentials
+      TASK_LOGON_NONE                           = 0
+      # Use a password for logging on the user
+      TASK_LOGON_PASSWORD                       = 1
+      # The service will log the user on using Service For User
+      TASK_LOGON_S4U                            = 2
+      # 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
+      # When 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
+
+      TASK_MAX_RUN_TIMES = 1440
+      TASKS_TO_RETRIEVE  = 5
+
+      # Task creation
+
+      TASK_VALIDATE_ONLY = 0x1
+      TASK_CREATE = 0x2
+      TASK_UPDATE = 0x4
+      TASK_CREATE_OR_UPDATE = 0x6
+      TASK_DISABLE = 0x8
+      TASK_DONT_ADD_PRINCIPAL_ACE = 0x10
+      TASK_IGNORE_REGISTRATION_TRIGGERS = 0x20
+
+      # Priority classes
+
+      REALTIME_PRIORITY_CLASS     = 0
+      HIGH_PRIORITY_CLASS         = 1
+      ABOVE_NORMAL_PRIORITY_CLASS = 2 # Or 3
+      NORMAL_PRIORITY_CLASS       = 4 # Or 5, 6
+      BELOW_NORMAL_PRIORITY_CLASS = 7 # Or 8
+      IDLE_PRIORITY_CLASS         = 9 # Or 10
+
+      CLSCTX_INPROC_SERVER = 0x1
+      CLSID_CTask = [0x148BD520, 0xA2AB, 0x11CE, 0xB1, 0x1F, 0x00, 0xAA, 0x00, 0x53, 0x05, 0x03].pack("LSSC8")
+      CLSID_CTaskScheduler = [0x148BD52A, 0xA2AB, 0x11CE, 0xB1, 0x1F, 0x00, 0xAA, 0x00, 0x53, 0x05, 0x03].pack("LSSC8")
+      IID_ITaskScheduler = [0x148BD527, 0xA2AB, 0x11CE, 0xB1, 0x1F, 0x00, 0xAA, 0x00, 0x53, 0x05, 0x03].pack("LSSC8")
+      IID_ITask = [0x148BD524, 0xA2AB, 0x11CE, 0xB1, 0x1F, 0x00, 0xAA, 0x00, 0x53, 0x05, 0x03].pack("LSSC8")
+      IID_IPersistFile = [0x0000010b, 0x0000, 0x0000, 0xC0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x46].pack("LSSC8")
+
+      # Days of month
+
+      TASK_FIRST = 0x01
+      TASK_SECOND = 0x02
+      TASK_THIRD = 0x04
+      TASK_FOURTH = 0x08
+      TASK_FIFTH = 0x10
+      TASK_SIXTH = 0x20
+      TASK_SEVENTH = 0x40
+      TASK_EIGHTH = 0x80
+      TASK_NINETH = 0x100
+      TASK_TENTH = 0x200
+      TASK_ELEVENTH = 0x400
+      TASK_TWELFTH = 0x800
+      TASK_THIRTEENTH = 0x1000
+      TASK_FOURTEENTH = 0x2000
+      TASK_FIFTEENTH = 0x4000
+      TASK_SIXTEENTH = 0x8000
+      TASK_SEVENTEENTH = 0x10000
+      TASK_EIGHTEENTH = 0x20000
+      TASK_NINETEENTH = 0x40000
+      TASK_TWENTIETH = 0x80000
+      TASK_TWENTY_FIRST = 0x100000
+      TASK_TWENTY_SECOND = 0x200000
+      TASK_TWENTY_THIRD = 0x400000
+      TASK_TWENTY_FOURTH = 0x800000
+      TASK_TWENTY_FIFTH = 0x1000000
+      TASK_TWENTY_SIXTH = 0x2000000
+      TASK_TWENTY_SEVENTH = 0x4000000
+      TASK_TWENTY_EIGHTH = 0x8000000
+      TASK_TWENTY_NINTH = 0x10000000
+      TASK_THIRTYETH = 0x20000000
+      TASK_THIRTY_FIRST = 0x40000000
+      TASK_LAST = 0x80000000
+    end
+  end
+end

data/lib/win32/taskscheduler/helper.rb

@@ -0,0 +1,51 @@
+require "ffi"
+
+module Win32
+  class TaskScheduler
+    module Helper
+      extend FFI::Library
+
+      FORMAT_MESSAGE_IGNORE_INSERTS = 0x00000200
+      FORMAT_MESSAGE_FROM_SYSTEM    = 0x00001000
+      FORMAT_MESSAGE_MAX_WIDTH_MASK = 0x000000FF
+
+      ffi_lib :kernel32, :advapi32
+
+      attach_function :FormatMessage, :FormatMessageA,
+                      %i{ulong pointer ulong ulong pointer ulong pointer}, :ulong
+
+      attach_function :ConvertStringSidToSidW, %i{pointer pointer}, :bool
+      attach_function :LookupAccountSidW, %i{pointer pointer pointer pointer pointer pointer pointer}, :bool
+      attach_function :LocalFree, [:pointer], :pointer
+
+      def win_error(function, err = FFI.errno)
+        err_msg = ""
+        flags = FORMAT_MESSAGE_IGNORE_INSERTS |
+          FORMAT_MESSAGE_FROM_SYSTEM |
+          FORMAT_MESSAGE_MAX_WIDTH_MASK
+
+        # 0x0409 == MAKELANGID(LANG_ENGLISH, SUBLANG_ENGLISH_US)
+        # We use English for errors because Ruby uses English for errors.
+
+        FFI::MemoryPointer.new(:char, 1024) do |buf|
+          len = FormatMessage(flags, nil, err, 0x0409, buf, buf.size, nil)
+          err_msg = function + ": " + buf.read_string(len).strip
+        end
+
+        err_msg
+      end
+
+      def ole_error(function, err)
+        regex = /OLE error code:(.*?)\sin/
+        match = regex.match(err.to_s)
+
+        if match
+          error = match.captures.first.hex
+          win_error(function, error)
+        else
+          "#{function}: #{err}"
+        end
+      end
+    end
+  end
+end

data/lib/win32/taskscheduler/sid.rb

@@ -0,0 +1,132 @@
+require_relative "helper"
+
+module FFI
+  class Pointer
+    def read_wstring(num_wchars = nil)
+      if num_wchars.nil?
+        # Find the length of the string
+        length = 0
+        last_char = nil
+        while last_char != "\000\000"
+          length += 1
+          last_char = get_bytes(0, length * 2)[-2..-1]
+        end
+
+        num_wchars = length
+      end
+
+      wide_to_utf8(get_bytes(0, num_wchars * 2))
+    end
+
+    def wide_to_utf8(wstring)
+      # ensure it is actually UTF-16LE
+      # Ruby likes to mark binary data as ASCII-8BIT
+      wstring = wstring.force_encoding("UTF-16LE")
+
+      # encode it all as UTF-8 and remove trailing CRLF and NULL characters
+      wstring.encode("UTF-8").strip
+    end
+  end
+end
+
+module Win32
+  class TaskScheduler
+    module SID
+      extend Win32::TaskScheduler::Helper
+      ERROR_INSUFFICIENT_BUFFER = 122
+
+      def self.LocalSystem
+        from_string_sid("S-1-5-18")
+      end
+
+      def self.NtLocal
+        from_string_sid("S-1-5-19")
+      end
+
+      def self.NtNetwork
+        from_string_sid("S-1-5-20")
+      end
+
+      def self.BuiltinAdministrators
+        from_string_sid("S-1-5-32-544")
+      end
+
+      def self.BuiltinUsers
+        from_string_sid("S-1-5-32-545")
+      end
+
+      def self.Guests
+        from_string_sid("S-1-5-32-546")
+      end
+
+      # Converts a string-format security identifier (SID) into a valid, functional SID
+      # and returns a hash with account_name and account_simple_name
+      # @see https://docs.microsoft.com/en-us/windows/desktop/api/sddl/nf-sddl-convertstringsidtosidw
+      #
+      def self.from_string_sid(string_sid)
+        result = FFI::MemoryPointer.new :pointer
+        unless ConvertStringSidToSidW(utf8_to_wide(string_sid), result)
+          raise FFI::LastError.error
+        end
+        result_pointer = result.read_pointer
+        domain, name, use = account(result_pointer)
+        LocalFree(result_pointer)
+        account_names(domain, name, use)
+      end
+
+      def self.utf8_to_wide(ustring)
+        # ensure it is actually UTF-8
+        # Ruby likes to mark binary data as ASCII-8BIT
+        ustring = (ustring + "").force_encoding("UTF-8")
+
+        # ensure we have the double-null termination Windows Wide likes
+        ustring += "\000\000" if ustring.empty? || ustring[-1].chr != "\000"
+
+        # encode it all as UTF-16LE AKA Windows Wide Character AKA Windows Unicode
+        ustring.encode("UTF-16LE")
+      end
+
+      # Accepts a security identifier (SID) as input.
+      # It retrieves the name of the account for this SID and the name of the
+      # first domain on which this SID is found
+      # @see https://docs.microsoft.com/en-us/windows/desktop/api/winbase/nf-winbase-lookupaccountsidw
+      #
+      def self.account(sid)
+        sid = sid.pointer if sid.respond_to?(:pointer)
+        name_size = FFI::Buffer.new(:long).write_long(0)
+        referenced_domain_name_size = FFI::Buffer.new(:long).write_long(0)
+
+        if LookupAccountSidW(nil, sid, nil, name_size, nil, referenced_domain_name_size, nil)
+          raise "Expected ERROR_INSUFFICIENT_BUFFER from LookupAccountSid, and got no error!"
+        elsif FFI::LastError.error != ERROR_INSUFFICIENT_BUFFER
+          raise FFI::LastError.error
+        end
+
+        name = FFI::MemoryPointer.new :char, (name_size.read_long * 2)
+        referenced_domain_name = FFI::MemoryPointer.new :char, (referenced_domain_name_size.read_long * 2)
+        use = FFI::Buffer.new(:long).write_long(0)
+        unless LookupAccountSidW(nil, sid, name, name_size, referenced_domain_name, referenced_domain_name_size, use)
+          raise FFI::LastError.error
+        end
+        [referenced_domain_name.read_wstring(referenced_domain_name_size.read_long), name.read_wstring(name_size.read_long), use.read_long]
+      end
+
+      # Formats domain, name and returns a hash with
+      # account_name and account_simple_name
+      #
+      def self.account_names(domain, name, _use)
+        account_name = !domain.to_s.empty? ? "#{domain}\\#{name}" : name
+        account_simple_name = name
+        { account_name: account_name, account_simple_name: account_simple_name }
+      end
+
+      SERVICE_ACCOUNT_USERS = [self.LocalSystem, self.NtLocal, self.NtNetwork].map do |user|
+        [user[:account_simple_name].upcase, user[:account_name].upcase]
+      end.flatten.freeze
+
+      BUILT_IN_GROUPS = [self.BuiltinAdministrators, self.BuiltinUsers, self.Guests].map do |user|
+        [user[:account_simple_name].upcase, user[:account_name].upcase]
+      end.flatten.freeze
+    end
+  end
+end