Maintain protection using scheduled tasks

Scheduled tasks enable you to automatically perform specific Workload Security tasks on a schedule. You can use the Workload Security API to perform all the scheduled task-related activities that you can do using the Workload Security console, such as performing recommendation scans, checking for security updates, and synchronizing cloud accounts. See Schedule Workload Security to perform tasks for more information about the available types of scheduled tasks.

After you create a scheduled task you can run it at any time. You can also run them immediately upon creation and then immediately delete them. In this way, scheduled tasks provide access to several powerful and convenient tools for automating Workload Security via the API and SDK.

Related classes

You use the following SDK classes when working with scheduled tasks:

• ScheduledTasksApi: Provides access to scheduled tasks on Workload Security. You can create, describe, modify, delete, search, and list scheduled tasks
• ScheduledTask: Represents the scheduled task
• ScheduleDetails: Defines the schedule for running the scheduled task
• Task parameter classes: Define the task that the scheduled task performs. See Configure the task for a list of classes.

Create a scheduled task

Use the following general procedure to create a scheduled task:

1. Create a ScheduledTask object and configure the general properties.
2. Create a ScheduleDetails object to define the schedule on which the task runs, and add it to the ScheduledTask object.
3. Create a task parameter class to define the task to perform, and add it to the ScheduledTask object. A different task parameter class is available for each type of task. Note that the Synchronize Users and Check for Software Updates tasks do not require a task parameter class.
4. Use a ScheduledTasksApi object to create the scheduled task on Workload Security.

Configure general properties

When you create a ScheduledTask object, use it to define the general properties:

• Name
• The type of task that it schedules
• Whether the task is enabled
• Whether the task runs after it is created

discover_computer_task = api.ScheduledTask()
discover_computer_task.name = "Discover Computers - Daily"
discover_computer_task.type = "discover-computers"
discover_computer_task.run_now = False

After you set the general properties, configure the schedule and the task and add them to the ScheduledTask object.

Create the schedule

The following properties of a ScheduleDetails object controls when a task runs:

• The recurrence type - either monthly, weekly, daily, hourly, or none (to run once).
• The recurrence of runs for daily, weekly, and monthly schedules. Daily and weekly recurrences are expressed as an interval such as every second day. For monthly recurrence, you specify specific months.
• The number of times the task runs (recurrence count). The task is automatically deleted after the task runs the specified number of times. This is useful when you want to run a scheduled task only once.
• The start time, for daily, weekly, and monthly recurrence types, determines the time of day that the task runs, specified in milliseconds (Epoch time). When the recurrence is expressed in intervals for daily and weekly schedules, the days or weeks on which subsequent runs occur are calculated from the start time. For example, when the recurrence is every second day, a start time that falls on a Monday means that the next day the task runs is Wednesday.
• The time zone to use to interpret the start time.

Note that ScheduleDetails objects are not persisted as a separate entity on Workload Security, but are stored as part of a scheduled task. You cannot persist a ScheduleDetails object for later reuse with other scheduled tasks.

Use the following general procedure to create the schedule:

1. Create a ScheduleDetails object and set the recurrence type.
2. Create a ScheduleParameters object that corresponds with the recurrence type, configure the recurrence of runs and the start time, and add it to the ScheduledTask object. The available ScheduleParameters objects are DailyScheduleParameters, HourlyScheduleParameters, MonthlyScheduleParameters, and OnceOnlyScheduleParameters.
3. Optionally, set the time zone on the ScheduledTask object.

For example, create a ScheduleDetails object for a daily schedule:

daily_schedule = api.ScheduleDetails()
daily_schedule.recurrence_type = "daily"

The DailyScheduleParameters class corresponds with a daily schedule. This example configures the schedule using a custom interval:

daily_schedule_parameters = api.DailyScheduleParameters()

daily_schedule_parameters.frequency_type = "custom"
daily_schedule_parameters.custom_interval = custom_interval
daily_schedule_parameters.start_time = start_time

Finally, add the schedule parameters to the ScheduleDetails object:

daily_schedule.daily_schedule_parameters = daily_schedule_parameters

Example: Daily schedule

The following example creates a daily schedule for use with a scheduled task:

View source

# Create a ScheduleDetails object and set the recurrence type
daily_schedule = api.ScheduleDetails()
daily_schedule.recurrence_type = "daily"

# Specify when the task runs
daily_schedule_parameters = api.DailyScheduleParameters()

# Use a custom frequency type to run the task at daily intervals.
# Every day and only weekdays are other available frequency types.
daily_schedule_parameters.frequency_type = "custom"
daily_schedule_parameters.custom_interval = custom_interval
daily_schedule_parameters.start_time = start_time

# Add the schedule parameters to the schedule details
daily_schedule.daily_schedule_parameters = daily_schedule_parameters

Example: Monthly schedule

The following example creates a monthly schedule for use with a scheduled task:

View source

# Create a ScheduleDetails object and set the recurrence type
quarterly_schedule = api.ScheduleDetails()
quarterly_schedule.recurrence_type = "monthly"

# Specify when the task runs
monthly_schedule_parameters = api.MonthlyScheduleParameters()

# Set the schedule to run on a specific day of the month.
# Other options are the last day of the month, or a specific weekday of a specific week
monthly_schedule_parameters.frequency_type = "day-of-month"

# Set the day
monthly_schedule_parameters.day_of_month = day

# Set the months to be quarterly
monthly_schedule_parameters.months = ["january", "april", "july", "october"]

# Add the schedule parameters to the schedule details
quarterly_schedule.monthly_schedule_parameters = monthly_schedule_parameters

Configure the task

Each of the following task parameter classes corresponds with a type of scheduled task. You use these classes to configure the task:

• CheckForSecurityUpdatesTaskParameters
• DiscoverComputersTaskParameters
• GenerateReportTaskParameters
• RunScriptTaskParameters
• ScanForIntegrityChangesTaskParameters
• ScanForMalwareTaskParameters
• ScanForOpenPortsScanParameters
• ScanForRecommendationsScanParameters
• SendAlertSummaryScanParameters
• SendPolicyTaskParameters
• SynchronizeCloudAccountTaskParameters
• SynchronizeDirectoryTaskParameters
• SynchronizeVCenterTaskParameters
• UpdateSuspiciousObjectsListTaskParameters

The permissions that have been granted to your API key determine which task parameter classes are available. For example, when the primary tenant restricts tenants from using scripts, the RunScriptTaskParameters class is not available to tenants.

Use the following general procedure to create and configure the task object:

1. Create a task parameters object from the class that corresponds with the type of scheduled task that you are creating.

   The Synchronize Users and Check for Software Updates tasks do not require configuration. For those tasks, do not create a task parameter class.

2. Configure the task parameters object to define how the task behaves:

   • Each class defines different properties that you need to configure.
   • Several task parameter classes require a ComputerFilter object to identify the computers to act on.
   • Depending on the type of task parameters object, you might need to add a Recipients, TagFilter, or TimeRange object.

For example, create a ScheduledTask object and set the task type so that it discovers computers:

discover_computer_task = api.ScheduledTask()
discover_computer_task.type = "discover-computers"

Create the corresponding DiscoverComputerTaskParameters object and set the property values:

task_parameters = api.DiscoverComputersTaskParameters()
task_parameters.discovery_type = "range"
task_parameters.iprange_low = "192.168.60.0"
task_parameters.iprange_high = "192.168.60.255"
task_parameters.scan_discovered_computers = True

Then, add the DiscoverComputerTaskParameters object to the ScheduledTask object, and create the scheduled task on Workload Security:

discover_computer_task.discover_computers_task_parameters = task_parameters

scheduled_tasks_api = api.ScheduledTasksApi(api.ApiClient(configuration))
scheduled_task = scheduled_tasks_api.create_scheduled_task(discover_computer_task, api_version)

Example: Create a scheduled task

The following example creates a scheduled task that discovers computers:

View source

# Create the ScheduledTask object and set the name and type. Do not run now.
discover_computer_task = api.ScheduledTask()
discover_computer_task.name = "Discover Computers - Daily"
discover_computer_task.type = "discover-computers"
discover_computer_task.run_now = False

# Call the createDailyScheduleDetails method to obtain a daily ScheduleDetails object.
# Set the start time to 03:00 DST.
discover_computer_task.schedule_details = create_daily_schedule_details(api, api_exception, 2, 1536030000000);

# Create a DiscoverComputersTaskParameters object.
# The scan applies to a range of IP addresses, and scans discovered computers for open ports.
task_parameters = api.DiscoverComputersTaskParameters()
task_parameters.discovery_type = "range"
task_parameters.iprange_low = "192.168.60.0"
task_parameters.iprange_high = "192.168.60.255"
task_parameters.scan_discovered_computers = True
discover_computer_task.discover_computers_task_parameters = task_parameters

# Create the scheduled task on Workload Security
scheduled_tasks_api = api.ScheduledTasksApi(api.ApiClient(configuration))
scheduled_task = scheduled_tasks_api.create_scheduled_task(discover_computer_task, api_version)

return scheduled_task.id

Also see the Create a Scheduled Task operation in the API Reference.

Create, run, and delete a scheduled task

Create a scheduled task that runs immediately when it is created, and then delete the scheduled task. Use scheduled tasks in this way to conveniently access many Workload Security capabilities via the API.

When the recurrence count of the ScheduleDetails object is set to 1, the scheduled task is automatically deleted after it runs.

Use the following general procedure to create, run, and delete a scheduled task:

1. Create and configure a ScheduledTask object:

   • Set the scheduled task to run now.
   • Set the task to run once to ensure subsequent runs do not occur.
   • Create and configure the task details as required.

2. Create a ScheduledTasksApi object and use it to create the scheduled task on Workload Security.

3. Use the ScheduledTasksApi object to delete the scheduled task on Workload Security.

The following example creates, runs, and deletes a scheduled task that checks for security updates:

View source

# Set the name and task type
check_for_security_updates = api.ScheduledTask()
check_for_security_updates.name = "Check For Security Updates"
check_for_security_updates.type = "check-for-security-updates"

# Run when the scheduled task is created
check_for_security_updates.run_now = True

# Use a once-only recurrence
schedule_details = api.ScheduleDetails()
schedule_details.recurrence_type = 'none'

# Set the recurrence count to 1 so that the task is deleted after running
schedule_details.recurrence_count = 1
schedule_parameters = api.OnceOnlyScheduleParameters()

# The start time is not important because it is deleted after running
schedule_parameters.start_time = 0
schedule_details.once_only_schedule_parameters = schedule_parameters
check_for_security_updates.schedule_details = schedule_details

# Scan all computers
computer_filter = api.ComputerFilter()
computer_filter.type = "all-computers"

# Create the task parameters object and add the computer filter
task_parameters = api.CheckForSecurityUpdatesTaskParameters()
task_parameters.computer_filter = computer_filter

check_for_security_updates.check_for_security_updates_task_parameters = task_parameters

# Create the scheduled task on Workload Security
scheduled_tasks_api = api.ScheduledTasksApi(api.ApiClient(configuration))
scheduled_task = scheduled_tasks_api.create_scheduled_task(check_for_security_updates, api_version)

return scheduled_task.id

Also see the Create a Scheduled Task operation in the API Reference.

Run an existing scheduled task

You can run an existing scheduled task at any time. For example, a scheduled task that scans the network for computers has been created on Workload Security and runs every two days. However, you need to perform the scan now, so you immediately run the scheduled task.

Use the following general procedure to run a scheduled task:

1. Create a ScheduledTask object and set the runNow property to true. Do not set any other properties.
2. Obtain the ID of the existing scheduled task to run.
3. Create a ScheduledTasksApi object and use it to modify the existing scheduled task according to the ScheduledTask object that you created.

When you set runNow to true, the scheduled task is configured to run at the current time of day for the configured interval. You might want to reset the start time to the original value after you run the scheduled task.

The following example runs the discover computers scheduled task:

View source

# Create the ScheduledTask object and set to run now
scheduled_task = api.ScheduledTask()
scheduled_task.run_now = True

# Modify the scheduled task on Workload Security
scheduled_tasks_api = api.ScheduledTasksApi(api.ApiClient(configuration))
scheduled_tasks_api.modify_scheduled_task(scheduled_task_id, scheduled_task, api_version)

Also see the Modify a Scheduled Task operation in the API Reference.