Maintain Protection Using Scheduled Tasks

Scheduled tasks enable you to automatically perform specific Deep Security Manager tasks on a schedule. You can use the Deep Security API to perform all the scheduled task-related activities that you can do using the Deep Security Manager console, such as performing recommendation scans, checking for security updates, and synchronizing cloud accounts. See Schedule Deep Security to perform tasks in the Help Center 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 Deep Security via the API and SDK.

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

  • ScheduledTasksApi: Provides access to scheduled tasks on Deep Security Manager. 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 Create the Task for a list of classes.)

Create a scheduled task

Use the following general procedure to create a scheduled task (more detailed information follows):

  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 Deep Security Manager.

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
Python
discover_computer_task = api.ScheduledTask()
discover_computer_task.name = "Discover Computers - Daily"
discover_computer_task.type = "discover-computers"
discover_computer_task.run_now = False
JavaScript
const discoverComputersTask = new api.ScheduledTask();
discoverComputersTask.name = "Discover Computers - Daily";
discoverComputersTask.type = api.ScheduledTask.TypeEnum["discover-computers"];
discoverComputersTask.runNow = false;
Java
ScheduledTask discoverComputersTask = new ScheduledTask();
discoverComputersTask.setName("Discover Computers - Daily");
discoverComputersTask.setType(ScheduledTask.TypeEnum.DISCOVER_COMPUTERS);
discoverComputersTask.setRunNow(Boolean.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 Deep Security Manager, but are stored as part of a scheduled task. You cannot persist a ScheduleDetails object for later re-use 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:

Python
daily_schedule = api.ScheduleDetails()
daily_schedule.recurrence_type = "daily"
JavaScript
const dailySchedule = new api.ScheduleDetails();
dailySchedule.recurrenceType = api.ScheduleDetails.RecurrenceTypeEnum.daily;
Java
ScheduleDetails dailySchedule = new ScheduleDetails();
dailySchedule.setRecurrenceType(ScheduleDetails.RecurrenceTypeEnum.DAILY);

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

Python
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
JavaScript
const dailyScheduleParameters = new api.DailyScheduleParameters();
dailyScheduleParameters.frequencyType = api.DailyScheduleParameters.FrequencyTypeEnum.custom;
dailyScheduleParameters.customInterval = customInterval;
dailyScheduleParameters.startTime = startTime;
Java
DailyScheduleParameters dailyScheduleParameters = new DailyScheduleParameters();
dailyScheduleParameters.setFrequencyType(DailyScheduleParameters.FrequencyTypeEnum.CUSTOM);
dailyScheduleParameters.setCustomInterval(customInterval);
dailyScheduleParameters.setStartTime(startTime);

Finally, add the schedule parameters to the ScheduleDetails object:

Python
daily_schedule.daily_schedule_parameters = daily_schedule_parameters
JavaScript
dailySchedule.dailyScheduleParameters = dailyScheduleParameters;
Java
dailySchedule.setDailyScheduleParameters(dailyScheduleParameters);

Example: Daily schedule

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

Python

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
JavaScript

View source

// Create a ScheduleDetails object and set the recurrence type
const dailySchedule = new api.ScheduleDetails();
dailySchedule.recurrenceType = api.ScheduleDetails.RecurrenceTypeEnum.daily;= new api.DailyScheduleParameters();//Every day and only weekdays are other available frequency types
dailyScheduleParameters.frequencyType = api.DailyScheduleParameters.FrequencyTypeEnum.custom;
dailyScheduleParameters.customInterval = customInterval;
dailyScheduleParameters.startTime = startTime;dailySchedule.dailyScheduleParameters = dailyScheduleParameters;
Java

View source

// Create a ScheduleDetails object and set the recurrence type
ScheduleDetails dailySchedule = new ScheduleDetails();
dailySchedule.setRecurrenceType(ScheduleDetails.RecurrenceTypeEnum.DAILY);= new DailyScheduleParameters();intervals.types.
dailyScheduleParameters.setFrequencyType(DailyScheduleParameters.FrequencyTypeEnum.CUSTOM);
dailyScheduleParameters.setCustomInterval(customInterval);
dailyScheduleParameters.setStartTime(startTime);dailySchedule.setDailyScheduleParameters(dailyScheduleParameters);

Example: Monthly schedule

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

Python

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
JavaScript

View source

// Create a ScheduleDetails object and set the recurrence type
const quarterlySchedule = new api.ScheduleDetails();
quarterlySchedule.recurrenceType = api.ScheduleDetails.RecurrenceTypeEnum.monthly;= new api.MonthlyScheduleParameters();month.month, or a specific weekday of a specific week
monthlyScheduleParameters.frequencyType = api.MonthlyScheduleParameters.FrequencyTypeEnum["day-of-month"];
monthlyScheduleParameters.dayOfMonth = day;monthlyScheduleParameters.months = [
  api.MonthlyScheduleParameters.MonthsEnum.january,
  api.MonthlyScheduleParameters.MonthsEnum.april,
  api.MonthlyScheduleParameters.MonthsEnum.july,
  api.MonthlyScheduleParameters.MonthsEnum.october
];quarterlySchedule.monthlyScheduleParameters = monthlyScheduleParameters;
Java

View source

// Create a ScheduleDetails object and set the recurrence type
ScheduleDetails quarterlySchedule = new ScheduleDetails();
quarterlySchedule.setRecurrenceType(ScheduleDetails.RecurrenceTypeEnum.MONTHLY);= new MonthlyScheduleParameters();month.month, or a specific weekday of amonthlyScheduleParameters.setFrequencyType(MonthlyScheduleParameters.FrequencyTypeEnum.DAY_OF_MONTH);monthlyScheduleParameters.setDayOfMonth(day);monthlyScheduleParameters.addMonthsItem(MonthlyScheduleParameters.MonthsEnum.JANUARY);
monthlyScheduleParameters.addMonthsItem(MonthlyScheduleParameters.MonthsEnum.APRIL);
monthlyScheduleParameters.addMonthsItem(MonthlyScheduleParameters.MonthsEnum.JULY);
monthlyScheduleParameters.addMonthsItem(MonthlyScheduleParameters.MonthsEnum.OCTOBER);quarterlySchedule.setMonthlyScheduleParameters(monthlyScheduleParameters);

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:

Python
discover_computer_task = api.ScheduledTask()
discover_computer_task.type = "discover-computers"
JavaScript
const discoverComputersTask = new api.ScheduledTask();
discoverComputersTask.type = api.ScheduledTask.TypeEnum["discover-computers"];
Java
ScheduledTask discoverComputersTask = new ScheduledTask();
discoverComputersTask.setType(ScheduledTask.TypeEnum.DISCOVER_COMPUTERS);
Create the corresponding DiscoverComputerTaskParameters object and set the property values:

Python
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
JavaScript
const taskParameters = new api.DiscoverComputersTaskParameters();
taskParameters.discoveryType = api.DiscoverComputersTaskParameters.DiscoveryTypeEnum.range;
taskParameters.iprangeLow = "192.168.60.0";
taskParameters.iprangeHigh = "192.168.60.255";
taskParameters.scanDiscoveredComputers = true;
Java
DiscoverComputersTaskParameters taskParameters = new DiscoverComputersTaskParameters();
taskParameters.setDiscoveryType(DiscoverComputersTaskParameters.DiscoveryTypeEnum.RANGE);
taskParameters.setIprangeLow("192.168.1.1");
taskParameters.setIprangeHigh("192.168.1.100");
taskParameters.setScanDiscoveredComputers(Boolean.TRUE);
Then, add the DiscoverComputerTaskParameters object to the ScheduledTask object, and create the scheduled task on Deep Security Manager:

Python
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)
JavaScript
discoverComputersTask.discoverComputersTaskParameters = taskParameters;
const scheduledTasksApi = new api.ScheduledTasksApi();
scheduledTasksApi.createScheduledTask(discoverComputersTask, apiVersion);
Java
discoverComputersTask.setDiscoverComputersTaskParameters(taskParameters);
ScheduledTasksApi scheduledTasksApi = new ScheduledTasksApi();
discoverComputersTask = scheduledTasksApi.createScheduledTask(discoverComputersTask, apiVersion);

Example: Create a scheduled task

The following example creates a scheduled task that discovers computers.

Python

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
try:
    # Create the scheduled task on Deep Security Manager
    scheduled_tasks_api = api.ScheduledTasksApi(api.ApiClient(configuration))
    scheduled_task = scheduled_tasks_api.create_scheduled_task(discover_computer_task, api_version)
    return "The scheduled task ID is " + str(scheduled_task.id)
except api_exception as e:
    return "Exception: " + str(e)
JavaScript

View source

// Create the ScheduledTask object and set the name and type. Do not run now.
const discoverComputersTask = new api.ScheduledTask();
discoverComputersTask.name = "Discover Computers - Daily";
discoverComputersTask.type = api.ScheduledTask.TypeEnum["discover-computers"];
discoverComputersTask.runNow = false;// Set the start time to 03:00 DST
discoverComputersTask.scheduleDetails = module.exports.createDailyScheduleDetails(2, 1536030000000, api);object.addresses, and scans discovered computers for open ports
const taskParameters = new api.DiscoverComputersTaskParameters();
taskParameters.discoveryType = api.DiscoverComputersTaskParameters.DiscoveryTypeEnum.range;
taskParameters.iprangeLow = "192.168.60.0";
taskParameters.iprangeHigh = "192.168.60.255";
taskParameters.scanDiscoveredComputers = true;
discoverComputersTask.discoverComputersTaskParameters = taskParameters;= new api.ScheduledTasksApi();
scheduledTasksApi.createScheduledTask(discoverComputersTask, apiVersion);
Java

View source

// Create the ScheduledTask object and set the name and type. Do not run now.
ScheduledTask discoverComputersTask = new ScheduledTask();
discoverComputersTask.setName("Discover Computers - Daily");
discoverComputersTask.setType(ScheduledTask.TypeEnum.DISCOVER_COMPUTERS);
discoverComputersTask.setRunNow(Boolean.FALSE);// object.11:00 DST.
Long startTime = Long.valueOf(1553007600000L);
ScheduleDetails scheduleDetails = ScheduledTasksExamples.createDailyScheduleDetails(Integer.valueOf(2), startTime);
discoverComputersTask.setScheduleDetails(scheduleDetails);object.addresses, and scans discovered computersports.
DiscoverComputersTaskParameters taskParameters = new DiscoverComputersTaskParameters();
taskParameters.setDiscoveryType(DiscoverComputersTaskParameters.DiscoveryTypeEnum.RANGE);
taskParameters.setIprangeLow("192.168.1.1");
taskParameters.setIprangeHigh("192.168.1.100");
taskParameters.setScanDiscoveredComputers(Boolean.TRUE);
discoverComputersTask.setDiscoverComputersTaskParameters(taskParameters);Manager.
ScheduledTasksApi scheduledTasksApi = new ScheduledTasksApi();
discoverComputersTask = scheduledTasksApi.createScheduledTask(discoverComputersTask, apiVersion);

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 Deep 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 Deep Security Manager.
  3. Use the ScheduledTasksApi object to delete the scheduled task on Deep Security Manager.

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

Python

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
try:
    # Create the scheduled task on Deep Security Manager
    scheduled_tasks_api = api.ScheduledTasksApi(api.ApiClient(configuration))
    scheduled_task = scheduled_tasks_api.create_scheduled_task(check_for_security_updates, api_version)
JavaScript

View source

// Set the name and task type
const checkForSecurityUpdates = new api.ScheduledTask();
checkForSecurityUpdates.name = "Check For Security Updates";
checkForSecurityUpdates.type = api.ScheduledTask.TypeEnum["check-for-security-updates"];checkForSecurityUpdates.runNow = true;once-only recurrence
const scheduleDetails = new api.ScheduleDetails();
scheduleDetails.recurrenceType = api.ScheduleDetails.RecurrenceTypeEnum.none;1 so that the task is deleted after running
scheduleDetails.recurrenceCount = 1;
const scheduleParameters = new api.OnceOnlyScheduleParameters();scheduleParameters.startTime = 0;
scheduleDetails.onceOnlyScheduleParameters = scheduleParameters;
checkForSecurityUpdates.scheduleDetails = scheduleDetails;= new api.ComputerFilter();
computerFilter.type = api.ComputerFilter.TypeEnum["all-computers"];= new api.CheckForSecurityUpdatesTaskParameters();
taskParameters.computerFilter = computerFilter;
checkForSecurityUpdates.checkForSecurityUpdatesTaskParameters = taskParameters;= new api.ScheduledTasksApi();
scheduledTasksApi
  .createScheduledTask(checkForSecurityUpdates, apiVersion)
Java

View source

// Set the name and task type
ScheduledTask checkForSecurityUpdates = new ScheduledTask();
checkForSecurityUpdates.setName("Check For Security Updates");
checkForSecurityUpdates.setType(ScheduledTask.TypeEnum.CHECK_FOR_SECURITY_UPDATES);checkForSecurityUpdates.setRunNow(Boolean.TRUE);once-only recurrence
ScheduleDetails scheduleDetails = new ScheduleDetails();
scheduleDetails.setRecurrenceType(ScheduleDetails.RecurrenceTypeEnum.NONE);1 so that the task is deleted after running
scheduleDetails.setRecurrenceCount(Integer.valueOf(1));
OnceOnlyScheduleParameters scheduleParameters = new OnceOnlyScheduleParameters();scheduleParameters.setStartTime(Long.valueOf(0L));
scheduleDetails.setOnceOnlyScheduleParameters(scheduleParameters);
checkForSecurityUpdates.setScheduleDetails(scheduleDetails);= new ComputerFilter();
computerFilter.setType(ComputerFilter.TypeEnum.ALL_COMPUTERS);= new CheckForSecurityUpdatesTaskParameters();
taskParameters.setComputerFilter(computerFilter);
checkForSecurityUpdates.setCheckForSecurityUpdatesTaskParameters(taskParameters);= new ScheduledTasksApi();
checkForSecurityUpdates = scheduledTasksApi.createScheduledTask(checkForSecurityUpdates, apiVersion);

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 Deep Security Manager and runs every 2 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.

Python

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 Deep Security Manager
scheduled_tasks_api = api.ScheduledTasksApi(api.ApiClient(configuration))
scheduled_tasks_api.modify_scheduled_task(scheduled_task_id, scheduled_task, api_version)
JavaScript

View source

// Create the ScheduledTask object and set to run now
const scheduledTask = new api.ScheduledTask();
scheduledTask.runNow = true;= new api.ScheduledTasksApi();
scheduledTasksApi.modifyScheduledTask(scheduledTaskID, api, apiVersion)
Java

View source

// Create the ScheduledTask object set to run now
ScheduledTask scheduledTask = new ScheduledTask();
scheduledTask.runNow(Boolean.TRUE);= new ScheduledTasksApi();
scheduledTasksApi.modifyScheduledTask(scheduledTaskID, scheduledTask, apiVersion);

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