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

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

Create the schedule

The 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. Set the time zone on the ScheduledTask object.

Configure the task

Each of the following task parameter classes represents a type of scheduled task:

  • CheckForSecurityUpdatesTaskParameters
  • DiscoverComputersTaskParameters
  • GenerateReportTaskParameters
  • RunScriptTaskParameters
  • ScanForIntegrityChangesTaskParameters
  • ScanForMalwareTaskParameters
  • ScanForOpenPortsScanParameters
  • ScanForRecommendationsScanParameters
  • SendAlertSummaryScanParameters
  • SendPolicyTaskParameters
  • SynchronizeCloudAccountTaskParameters
  • SynchronizeDirectoryTaskParameters
  • SynchronizeVCenterTaskParameters
  • UpdateSuspiciousObjectsListTaskParameters
The Synchronize Users and Check for Software Updates tasks do not require configuration. For those tasks, do not create a task parameter class.

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.
  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.

Example: Create a daily schedule for a scheduled task

Python
Coming soon…
Javascript
/*
 * Creates a ScheduleDetails object for use with a scheduled task for daily execution
 * using a custom interval.
 * @param {Number} customInterval The interval for the runs. For example 2 to run every second day.
 * @param {Number} startTime	The epoch time in milliseconds when the scheduled task first runs.
 * @param {ApiClient} api The Deep Security API exports.
 * @returns A ScheduleDetails object.
 */
exports.createDailyScheduleDetails = function (customInterval, startTime, api) {

  // Create a ScheduleDetails object and set the recurrence type
  const dailySchedule = new api.ScheduleDetails();
  dailySchedule.recurrenceType = api.ScheduleDetails.RecurrenceTypeEnum.daily;

  // Specify when the task runs
  const dailyScheduleParameters = new api.DailyScheduleParameters();

  //Use a custom frequency type to run the task at daily intervals
  //Every day and only weekdays are other available frequency types
  dailyScheduleParameters.frequencyType = api.DailyScheduleParameters.FrequencyTypeEnum.custom;
  dailyScheduleParameters.customInterval = customInterval;
  dailyScheduleParameters.startTime = startTime;

  //Add the schedule parameters to the schedule details
  dailySchedule.dailyScheduleParameters = dailyScheduleParameters;

  return dailySchedule;
};
Java
/*
 * Creates a ScheduleDetails object for use with a scheduled task for daily execution
 * using a custom interval.
 * @param customInterval The interval for the runs. For example 2 to run every second day. 
 * @param startTime	The epoch time in milliseconds when the scheduled task first runs.
 * @return A ScheduleDetails object.
 */
public static ScheduleDetails createDailyScheduleDetails(int customInterval, Long startTime) {
	
	//Create a ScheduleDetails object and set the recurrence type
	ScheduleDetails dailySchedule = new ScheduleDetails();
	dailySchedule.setRecurrenceType(ScheduleDetails.RecurrenceTypeEnum.DAILY);
	
	//Specify when the task runs
	DailyScheduleParameters dailyScheduleParameters = new DailyScheduleParameters();
	
	//Use a custom frequency type to run the task at daily intervals.
	//Every day and only weekdays are other available frequency types.
	dailyScheduleParameters.setFrequencyType(DailyScheduleParameters.FrequencyTypeEnum.CUSTOM);
	dailyScheduleParameters.setCustomInterval(customInterval);
	dailyScheduleParameters.setStartTime(startTime);
	
	//Add the schedule parameters to the schedule details
	dailySchedule.setDailyScheduleParameters(dailyScheduleParameters);
	
	return dailySchedule;
}

Example: Create a monthly schedule for a scheduled task

Python
Coming soon…
Javascript
/*
 * Creates a ScheduleDetails object to use with a scheduled task for quarterly execution (every 3 months).
 * @param {Number} day The day of the month on which the scheduled task runs.
 * @param {ApiClient} api The Deep Security API exports.
 * @return A ScheduleDetails object.
 */
exports.createQuarterlyScheduleDetails = function (day, api) {

  // Create a ScheduleDetails object and set the recurrence type
  const quarterlySchedule = new api.ScheduleDetails();
  quarterlySchedule.recurrenceType = api.ScheduleDetails.RecurrenceTypeEnum.monthly;

  // Specify when the task runs
  const monthlyScheduleParameters = new 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
  monthlyScheduleParameters.frequencyType =
    api.MonthlyScheduleParameters.FrequencyTypeEnum["day-of-month"];
  monthlyScheduleParameters.dayOfMonth = day;

  // Set the months to be quarterly
  monthlyScheduleParameters.months =
    [api.MonthlyScheduleParameters.MonthsEnum.january,
    api.MonthlyScheduleParameters.MonthsEnum.april,
    api.MonthlyScheduleParameters.MonthsEnum.july,
    api.MonthlyScheduleParameters.MonthsEnum.october];

  // Add the schedule parameters to the schedule details
  quarterlySchedule.monthlyScheduleParameters = monthlyScheduleParameters;

  return quarterlySchedule;
};
Java
/*
 * Creates a ScheduleDetails object to use with a scheduled task for quarterly execution (every 3 months).
 * @param day The day of the month on which the scheduled task runs. 
 * @return A ScheduleDetails object.
 */
public static ScheduleDetails createQuarterlyScheduleDetails(int day) {

	//Create a ScheduleDetails object and set the recurrence type
	ScheduleDetails quarterlySchedule = new ScheduleDetails();
	quarterlySchedule.setRecurrenceType(ScheduleDetails.RecurrenceTypeEnum.MONTHLY);
	
	//Specify when the task runs
	MonthlyScheduleParameters monthlyScheduleParameters = new 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
	monthlyScheduleParameters.setFrequencyType(MonthlyScheduleParameters.FrequencyTypeEnum.DAY_OF_MONTH);
	
	//Set the day
	monthlyScheduleParameters.setDayOfMonth(day);
	
	//Set the months to be quarterly
	monthlyScheduleParameters.addMonthsItem(MonthlyScheduleParameters.MonthsEnum.JANUARY);
	monthlyScheduleParameters.addMonthsItem(MonthlyScheduleParameters.MonthsEnum.APRIL);
	monthlyScheduleParameters.addMonthsItem(MonthlyScheduleParameters.MonthsEnum.JULY);
	monthlyScheduleParameters.addMonthsItem(MonthlyScheduleParameters.MonthsEnum.OCTOBER);

	//Add the schedule parameters to the schedule details
	quarterlySchedule.setMonthlyScheduleParameters(monthlyScheduleParameters);
	
	return quarterlySchedule;
}

Example: Create a scheduled task that discovers computers

Python
Coming soon…
Javascript
/*
 * Creates a scheduled task that runs daily to discover new computers on the network.
 * The task does not run now.
 * @param {ApiClient} api The Deep Security API exports.
 * @param {String} apiVersion The API version to use.
 * @returns {Promise} A promise object that resolves to the ID of the ScheuledTask.
 */
exports.createDiscoverComputersScheduledTask = function (api, apiVersion) {
  return new Promise((resolve, reject) => {

    // 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;

    // Call the createDailyScheduleDetails method to obtain a daily ScheduleDetails object
    // Set the start time to 03:00 DST
    discoverComputersTask.scheduleDetails =
      module.exports.createDailyScheduleDetails(2, 1536030000000, api);

    // Create a DiscoverComputersTaskParameters object.
    // The scan applies to a range of IP 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;

    // Create the scheduled task on Deep Security Manager
    const scheduledTasksApi = new api.ScheduledTasksApi();
    scheduledTasksApi.createScheduledTask(discoverComputersTask, apiVersion)
      .then(scheduledTask => {
        resolve(scheduledTask.ID);
      })
      .catch(error => {
        reject(error);
      });
  });
};
Java
/*
 * Creates a scheduled task that runs daily to discover new computers on the network.
 * The task does not run now.
 */
public static void createDiscoverComputersScheduledTask() {
	//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(false);
	
	//Call the createDailyScheduleDetails method to obtain a daily ScheduleDetails object.
	//Set the start time to 03:00 DST.
	ScheduleDetails scheduleDetails= ScheduledTasksExamples.createDailyScheduleDetails(2, 1536030000000L);
	discoverComputersTask.setScheduleDetails(scheduleDetails);
	
	//Create a DiscoverComputersTaskParameters object.
	//The scan applies to a range of IP addresses, and scans discovered computers for open ports.
	DiscoverComputersTaskParameters taskParameters = new DiscoverComputersTaskParameters();
	taskParameters.setDiscoveryType(DiscoverComputersTaskParameters.DiscoveryTypeEnum.RANGE);
	taskParameters.setIprangeLow("192.168.1.1");
	taskParameters.setIprangeHigh("192.168.1.100");
	taskParameters.setScanDiscoveredComputers(true);
	discoverComputersTask.setDiscoverComputersTaskParameters(taskParameters);
	
	//Create the scheduled task on Deep Security Manager.
	ScheduledTasksApi scheduledTasksApi = new ScheduledTasksApi();
	try {
		scheduledTasksApi.createScheduledTask(discoverComputersTask, "v1");
	} catch (ApiException e) {
		System.out.println(e.getMessage());
		e.printStackTrace();
	}
	
}

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.

Example: Create, run, and delete a scheduled task that checks for security updates

Python
Coming soon…
Javascript
/*
 * Creates a scheduled task that checks for security updates.
 * The scheduled task runs immediately after it is created, and is
 * deleted thereafter.
 * @param {ApiClient} api The Deep Security API exports.
 * @param {String} apiVersion The API version to use.
 * @returns {Promise} A promise object that resolves to the ID of the ScheuledTask.
 */
exports.checkForSecurityUpdatesUsingScheduledTask = function (api, apiVersion) {
  return new Promise((resolve, reject) => {
    // 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"];

    // Run when the scheduled task is created
    checkForSecurityUpdates.runNow = true;

    // Use a once-only recurrence
    const scheduleDetails = new api.ScheduleDetails();
    scheduleDetails.recurrenceType = api.ScheduleDetails.RecurrenceTypeEnum.none;

    // Set the recurrence count to 1 so that the task is deleted after running
    scheduleDetails.recurrenceCount = 1;
    const scheduleParameters = new api.OnceOnlyScheduleParameters();

    // The start time is not important because it is deleted after running
    scheduleParameters.startTime = 0;
    scheduleDetails.onceOnlyScheduleParameters = scheduleParameters;
    checkForSecurityUpdates.scheduleDetails = scheduleDetails;

    // Scan all computers
    const computerFilter = new api.ComputerFilter();
    computerFilter.type = api.ComputerFilter.TypeEnum["all-computers"];

    // Create the task parameters object and add the computer filter
    const taskParameters = new api.CheckForSecurityUpdatesTaskParameters();
    taskParameters.computerFilter = computerFilter;

    checkForSecurityUpdates.checkForSecurityUpdatesTaskParameters = taskParameters;

    // Create the scheduled task on Deep Security Manager
    const scheduledTasksApi = new api.ScheduledTasksApi();
    scheduledTasksApi.createScheduledTask(checkForSecurityUpdates, apiVersion)
      .then(scheduledTask => {
        resolve(scheduledTask.ID);
      })
      .catch(error => {
        reject(error);
      });
  });
};
Java
/*
 * Creates a scheduled task that checks for security updates.
 * The scheduled task runs immediately after it is created, and is
 * deleted thereafter.
 */
public static void checkForSecurityUpdatesUsingScheduledTask() {
	//Set the name and task type
	ScheduledTask checkForSecurityUpdates = new ScheduledTask();
	checkForSecurityUpdates.setName("Check For Security Updates");
	checkForSecurityUpdates.setType(ScheduledTask.TypeEnum.CHECK_FOR_SECURITY_UPDATES);
	
	//Run when the scheduled task is created
	checkForSecurityUpdates.setRunNow(true);
	
	//Use a once-only recurrence
	ScheduleDetails scheduleDetails = new ScheduleDetails();
	scheduleDetails.setRecurrenceType(ScheduleDetails.RecurrenceTypeEnum.NONE);
	
	//Set the recurrence count to 1 so that the task is deleted after running
	scheduleDetails.setRecurrenceCount(1);
	OnceOnlyScheduleParameters scheduleParameters = new OnceOnlyScheduleParameters();
	
	//The start time is not important because it is deleted after running
	scheduleParameters.setStartTime(0L);
	scheduleDetails.setOnceOnlyScheduleParameters(scheduleParameters);
	checkForSecurityUpdates.setScheduleDetails(scheduleDetails);
	
	//Scan all computers
	ComputerFilter computerFilter = new ComputerFilter();
	computerFilter.setType(ComputerFilter.TypeEnum.ALL_COMPUTERS);
	
	//Create the task parameters object and add the computer filter
	CheckForSecurityUpdatesTaskParameters taskParameters = new CheckForSecurityUpdatesTaskParameters();
	taskParameters.setComputerFilter(computerFilter);
	
	checkForSecurityUpdates.setCheckForSecurityUpdatesTaskParameters(taskParameters);
	
	ScheduledTasksApi scheduledTasksApi = new ScheduledTasksApi();
	try {
		//Create the scheduled task
		checkForSecurityUpdates = scheduledTasksApi.createScheduledTask(checkForSecurityUpdates, "v1");
	} catch (ApiException e) {
		System.out.println(e.getMessage());
		e.printStackTrace();
	}
}

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.

Example: Run the discover computers scheduled task

Python
Coming soon…
Javascript
/*
 * Runs a scheduled task.
 * @param scheduledTaskID The ID of the scheduled task.
 * @param {ApiClient} api The Deep Security API exports.
 * @param {String} apiVersion The API version to use.
 * @returns {Promise} A promise object that resolves to the ScheduledTask object.
 */
exports.runScheduledTask = function (scheduledTaskID, api, apiVersion) {
  return new Promise((resolve, reject) => {

    // Create the ScheduledTask object and set to run now
    const scheduledTask = new api.ScheduledTask();
    scheduledTask.runNow = true;

    // Modify the scheduled task on Deep Security Manager
    const scheduledTasksApi = new api.ScheduledTasksApi();
    scheduledTasksApi.modifyScheduledTask(scheduledTaskID, api, apiVersion)
      .then(modifiedScheduledTask => {
        resolve(modifiedScheduledTask);
      })
      .catch(error => {
        reject(error);
      });
  });
};
Java
/*
 * Runs a scheduled task.
 * @param scheduledTaskID The ID of the scheduled task.
 */
public static void runScheduledTask(Integer scheduledTaskID) {
	//Create the ScheduledTask object set to run now
	ScheduledTask scheduledTask = new ScheduledTask();
	scheduledTask.runNow(true);
	
	//Modify the scheduled task on Deep Security Manager
	ScheduledTasksApi scheduledTasksApi = new ScheduledTasksApi();
	try {
		scheduledTasksApi.modifyScheduledTask(scheduledTaskID, scheduledTask, "v1");
	} catch (ApiException e) {
		System.out.println(e.getMessage());
		e.printStackTrace();
	}
}