/portalAPI/Policy/*

This article will encompass all portalAPI calls that are related to /portalAPI/Policy/* endpoints

 

Be sure to input the instance your organization exists on for each call. This is indicated with the "INSTANCE" text in each endpoint. Linked here is a KB to find your instance:

Locating Your Organization's Instance | ThreatLocker Help Center

PolicyGetForViewPoliciesByApplicationId

https://portalapi.INSTANCE.threatlocker.com/portalapi/Policy/PolicyGetForViewPoliciesByApplicationId

• Method: GET
• Description: This API is used when selecting the Modules drop-down menu on the left side of the ThreatLocker® Portal, selecting Application Control, viewing the Applications page, and selecting the policy icon in the Policies column next to the corresponding application to view the policies attached to the application. This API can be utilized to identify if/how many policies are applied to a specific application and how those policies are applied in the organization (either permitted, permitted with or without a Ringfence™, permitted with or without Elevation, or denied). If looking to narrow/expand the policy search for applications and/or policies in a different organization than the currently logged in/managed organization, utilize the managedOrganizationId header as described below. 
• Required Body/Parameters
  • Valid APIKey/Authorization Token in header
  • applicationId: This field determines which application's policies will be returned. To get a list of applicationIds for the applications currently permitted (with or without Ringfencing and/or Elevation), explicitly denied, and/or existing with no policies in your organization, use the ApplicationGetByParameters endpoint, as documented in this article: /portalAPI/Application/* | ThreatLocker Help Center

• • • Expects: <GUID> in format "00000000-0000-0000-0000-000000000000"
  • pageNumber and pageSize: These fields determine how many policies will be returned as if the response was on the Applications page. However, these fields do not follow the same conventions of the pageNumber and pageSize values as the Portal does (pageSize in the Portal is 25, 50, or 100). Any valid integer can be entered, and it will return in the selected formatting. For instance, if there are 5 policies to be returned but “pageNumber”: 1 and “pageSize”: 2, 2 entries will be returned per page, and the first two policies will be shown.
    • Expects: An Integer value
• Optional Body/Parameters
  
  • In header: "managedOrganizationId": <GUID> in format "00000000-0000-0000-0000-000000000000"
  • includeDenies: This field determines whether explicit deny policies will be included when returning the policies associated with the selected application. When set to true, the deny policies will be included/shown. When set to false, or if this field is omitted completely, the deny policies will not be included/shown; Only policies that are set to permit or permit with a Ringfence™, with and without Elevation, will be included/shown.
    • Expects: true or false
• Permissions Needed for User
  • Edit Application Control Policies

PolicyInsert

https://portalapi.INSTANCE.threatlocker.com/portalapi/Policy/PolicyInsert

• Method: POST
• Description: This API is used when navigating through the Application Control pages of the ThreatLocker Portal, locating and selecting the "New Policy" button, entering new policy details, and selecting "Create." This API is responsible for creating new Application Control policies in your organization. To create a new policy in a different organization than the currently logged in/managed organization, use the managedOrganizationId header as described below.

Ensure that the managedOrganizationId aligns with where the policy will be created as per what is entered into the computerGroupId field outlined below.

 

Once you have called this API to create your new policy, be sure to deploy policies in the organization where the policy was created (or for all organizations if a global policy was created) either through the Portal using the Deploy Policies button or through API, documentation linked below.

/portalAPI/DeployPolicyQueue/* | ThreatLocker Help Center

• Required Body/Parameters
  • Valid APIKey/Authorization Token in header
  • Fields

Note: These are the only fields required; however, without the isEnabled field set to true, the new policy will be created as inactive. Also, without the logAction field set to true, the new policy will not log to the Unified Audit when it is matched.

• • • applicationIdList: This field is where applications are applied to the policy that will be created. One or multiple applications can be entered. For each application, enter the applicationId in the format below. The required body section formats adding two applications to a new policy.
      • Expects a GUID in format: "00000000-0000-0000-0000-000000000000"
    • computerGroupId: This field determines where the Application Control policy will be applied. This field corresponds to the "Applies To" section of the "Create Application Policy" sidebar in the Portal. Any valid organizationId, computerGroupId, or computerId can be entered. For instance, if looking to apply the policy at the entire organization level, enter the organizationId into this field.
      • Expects a GUID in format: "00000000-0000-0000-0000-000000000000"
    • name: This field determines the name that will be applied to the new policy. Any name can be entered, and the policyId will be automatically generated.
      • Expects: Any text input
    • osType: This field determines the OS Type of the policy that will be created. OSTypes to select from are listed below. This field expects the Integer associated with the OSType:
      • Windows = 1
      • MAC = 2
      • Linux = 3
      • Windows XP = 5
    • policyActionId: This field determines the policy action of the new policy that will be created. This field expects the Integer associated with the policy action to be entered:
      • Permit = 1
      • Deny = 2
      • Permit with Ringfence = 6

• Optional Body/Parameters
  • In header: "managedOrganizationId": <GUID> in format "00000000-0000-0000-0000-000000000000"
  • Fields
    
    • allDevices: This field determines if the policy that will be created will apply to all interfaces or a selected interface. When this field is set to false, the deviceType field must be used so that only one specific interface will affect the new policy. When this field is omitted, the deviceType field should not be used/included, and the new policy will apply to all interfaces. When this field is set to true, the new policy will apply to all interfaces, and anything entered into the deviceType field will be ignored.
      • Expects: true or false
    • allUserGroups: This field determines if the policy that will be created will apply to all users and groups or selected users and groups. When this field is set to false, the userGroups field must be used so that only selected users and groups will affect the new policy. Otherwise, this field will default to true. When this field is omitted or set to true, the new policy will apply to all users and groups.
      • Expects: true or false
    • allowRequest: This field can only be used when policyActionId is set to 2 and determines if the new policy will allow the user the option to request access to the denied file from the ThreatLocker Tray prompt. If this field is set to false or omitted entirely, the user will not be able to request access. If this field is set to true, the user will be able to request access and send an Approval Request.
      • Expects: true or false

Note: ThreatLocker does not recommend using the applicationSelection field below unless you are creating a default deny policy. Improper use of this field could cause all applications to be permitted. A warning is displayed before creating a new policy associated with all applications, and to create a policy with this setting, the name must contain either "Permit All" or begin with "Default - "

• • • applicationSelection: This field determines whether the new policy will apply to selected applications or all applications. When this field is omitted or set to 0, the applications in the applicationIdList field will be added to the policy. Only when this field is explicitly set to 1 will the policy be created selecting all applications.
      • Expects: Integer value 0 or 1
    • comments: This field will populate any text entered into the File Path text box in the Ticket Details tab of the policy in the ThreatLocker Portal. This field is typically used to indicate any file paths that may have been referenced during the creation of the new policy, but can be used as you see fit.
      • Expects: Any text input
    • description: This field determines the description of the policy that will be created. If nothing is entered (null or "") or this field is omitted entirely, no description will be added to the new policy.
      • Expects: Any text input
    • deviceType: This field determines what interface the new policy will apply to when allDevices is set to false. If allDevices is set to true, anything input into this field will be ignored since the policy will apply to all devices. This field expects one of the following options to be entered exactly as they appear below:
      • USB
      • DVD
      • UNC
      • SCSI
      • SATA
      • IDE
    • elevationEndDate: This field is used when Elevation will be enabled and you want elevation to expire after a set time. When this field is used and Elevation expires before the new permit policy does, two policies are created in the ThreatLocker Portal. One policy will be created with Elevation enabled, with the expiration specified in this field. The other policy will be created with no Elevation to continue permitting the application once Elevation expires on the other policy. This field only affects the expiration of Elevation and does not affect the expiration of the policy as a whole. The overall policy expiration configuration is completed with the policyScheduleStatus and endDate fields. When this field is omitted or null, Elevation will never expire on the newly created policy. This expects a time entered in UTC in format "YYYY-MM-DDTHH:MM:SSZ", where YYYY is the year, the first MM is the month, DD is the day, HH are the hours, the second MM is the minutes, and SS are the seconds. The T must be included to designate the time and should not be changed or removed.
      • Expects expiration date and time in format: "YYYY-MM-DDTHH:MM:SSZ"
    • elevationStatus: This field determines whether Elevation to run as a local administrator will be applied to the new policy. This field expects one of the corresponding Integer values to be entered.
      • Do not Elevate = 0
      • Elevate (Notify User) = 1
      • Elevate (Do Not Notify User) = 2
      • Force the program to run as a standard user (Does not apply for administrators) = 3
    • endDate: This field is used when policyScheduleStatus is set to 1 and determines when a new policy will expire. This expects a time entered in UTC in format "YYYY-MM-DDTHH:MM:SSZ", where YYYY is the year, the first MM is the month, DD is the day, HH are the hours, the second MM is the minutes, and SS are the seconds. The T must be included to designate the time and should not be changed or removed.
      • Expects expiration date and time in format: "YYYY-MM-DDTHH:MM:SSZ"
    • isEnabled: This field determines if the policy will be enabled when the new policy is created. If this field is set to false or omitted entirely, the policy will not be enabled. If this field is set to true, the policy will be enabled.
      • Expects: true or false
    • killRunningProcesses: This field can only be used when policyActionId is set to 2 and determines if the new policy will kill any running processes when the policy is matched. When enabled, once a file matches the new Policy, the process that the file originated from will be terminated. If this field is set to false or omitted entirely, kill running processes will not be enabled. If this field is set to true, kill running processes will be enabled.
      • Expects: true or false
    • logAction: This field determines if the policy that will be created will log when matched in the Unified Audit. If this field is set to false or omitted entirely, the policy will not log in the Unified Audit. If this field is set to true, the policy will log in the Unified Audit.
      • Expects: true or false
    • monitorMode: This field determines the status that will be applied to the new policy. When this field is omitted, it will default to 0. When this field is set to 0, the policy will be set to "Inherit Status From Computer", meaning the behavior of the policy will depend on the Maintenance Mode of the computer. When this field is set to 1, the policy will be set to "Secured Mode", meaning no matter the Maintenance Mode of the computer, the policy will behave as indicated by the policy action (Permit with Ringfence, or Deny). When this field is set to 2, the policy will be set to "Monitor Only Mode", meaning no matter the Maintenance Mode of the computer, the policy itself will act as if the computer is in the Monitor Only Maintenance Mode. Setting this field to 2 is particularly useful when setting up Ringfencing for the first time, as it will monitor the Ringfencing traffic coming through the policy, but not block anything.
      • Expect: Integer value 0, 1, or 2
    • networkExclusions: This field determines the exclusions that will be added regarding Internet Ringfencing. One, multiple, or no exclusions can be added. As demonstrated in the "Optional body" section, each exclusion requires each of the fields listed below:
      • tagPrefixTypeId: This field specifies what type of exclusion will be added, either a domain, IPv4, or IPv6. This field expects one of the following Integer values to be entered, corresponding to the type of exclusion desired.
        • Domain = 1
        • IPv4 = 2
        • IPv6 = 3
      • value: This field determines the domain, IPv4, or IPv6 value that is applied to the Ringfencing policy.
        • Expects: Either an IPv4 or IPv6 address (in correct CIDR notation) or a valid domain
    • notifyOnRequest: This field can only be used when policyActionId is set to 2, must be used in combination with the requestEmailAddressesList field, and determines if the new policy will notify the listed ThreatLocker administrator(s) (in the requestEmailAddressesList field) through email/SMS of an Approval Request generated after the policy was matched. If this field is set to false or omitted entirely, no administrators will be notified. If this field is set to true, the administrators listed will be notified.
      • Expects: true or false
    • orderBefore: This field determines where the new policy will be placed. When this field is omitted or set to false, the policy will be added to the bottom of the policy order where it is applied. When this field is true, the policy will be added to the top of the policy order where it is applied.
      • Expects: true or false
    • parentProcessIdList: This field is where applications are specified that are allowed to launch the application(s) tied to the new policy. One or multiple applications can be entered. The optional body section formats adding/maintaining two applications to the new policy. When using this field, ensure that the field parentRestrictionEnabled is used and set to true. For each application, enter the applicationId in the format below. Ensure that the applications specified in this field utilize the same osType as the policy.

      • Expects a GUID in format: "00000000-0000-0000-0000-000000000000"
    • parentRestrictionEnabled: This field determines whether the new policy will restrict the application(s) that are permitted to launch the selected application(s) in the policy. When this field is set to false or omitted, the parentProcessIdList field must not be used so that all applications can launch the application(s) tied to the policy. When this field is set to true, the parentProcessIdList field must be used so that only a selected application(s) can launch the application(s) tied to the policy.
      • Expects: true or false
    • policyScheduleStatus: This field determines whether a policy expiration or policy schedule will be applied to the new policy. When this field is set to 0 or omitted, no policy expiration or schedule will be applied. When this field is set to 1, the endDate field must be used to specify an expiration date. When this field is set to 2, the policySchedules field must be used to specify the days, duration in hours and minutes, and the start time of the new policy.
      • Expects: Integer value 0, 1, or 2
    • policySchedules: This field determines the schedule of the new policy. This field expects policyScheduleStatus to have a value of 2. The following fields are used for each defined policy schedule.
      • dayOfTheWeek: This field determines the day of the week when the policy will be enabled. This field expects an Integer between 0 and 6, 0 being Sunday and 6 being Saturday.
      • durationHours: This field determines the number of hours that the policy will be enabled. This field expects any valid Integer value, anything less than 24.
      • durationMinutes: This field determines the number of minutes that the policy will be enabled. This field expects any valid Integer value, anything less than 60.
      • startTime: This field expects the start time to be entered in a 24-hour format "YYYY-MM-DDTHH:MM:SSZ", where YYYY is the year, the first MM is the month, DD is the day, HH are the hours, the second MM are the minutes, and SS are the seconds. The T must be included to designate the time and should not be changed or removed.
    • requestEmailAddressesList: This field is used in association with the notifyOnRequest field and is used to specify the email address(es) of the ThreatLocker administrator(s) who will be notified when a request is sent in relation to the new policy. One or multiple email addresses can be entered as shown in the "Optional body" section below.
      • Expects: Any valid email address(es)
    • requestor: This field will populate any text entered into the Requestor text box in the Tickets Details tab of the policy in the ThreatLocker Portal. This is typically used to indicate who requested the new policy to be implemented, but can be used as you see fit.
      • Expects: Any text input 
    • ringfencingOptions: This field is used to specify the conditions under which Ringfencing will be applied to a new policy that will be created. In order to apply Ringfencing, the policyActionId must be set to 6. The following fields can be combined to add the desired amount of Ringfencing and initial exclusions.
      • restrictApplication: This field determines whether Application Ringfencing will apply to the policy. If this Ringfencing is desired, set this field to true; Otherwise, set this field to false.
        • Expects: true or false
      • restrictApplicationSpawning: This field determines what type of Application Ringfencing will apply to the policy. Set this field to true to specify that all application interaction will be blocked except for the ones listed below in the field rfAssociatedApplicationPolicy. Otherwise, set this field to false to specify that all application interactions will be allowed besides the ones listed below in the field rfAssociatedApplicationPolicy.
        • Expects: true or false
      • restrictFileAccess: This field determines whether File Ringfencing will apply to the policy. When File Ringfencing is applied, any monitored file path in Storage Control and any path exclusions set up in the field rfFilePolicy with the action of 'Deny' will have their file interaction blocked. If this Ringfencing is desired, set this field to true; Otherwise, set this field to false.
        • Expects: true or false
      • restrictNetworkAccess: This field determines whether Internet Ringfencing will apply to the policy. Any internet/network interaction not specifically listed within the exclusions in the field networkExclusions will have the interaction blocked. If this Ringfencing is desired, set this field to true; Otherwise, set this field to false.
        • Expects: true or false
      • restrictRegistryAccess: This field determines whether Registry Ringfencing will apply to the policy. Any registry interaction not specifically listed within the exclusions in the field rfRegistryPolicy will have the interaction blocked. If this Ringfencing is desired, set this field to true; Otherwise, set this field to false.

        • Expects: true or false
      • rfAssociatedApplicationPolicy: This field determines the applications/exclusions that will either be blocked from interacting or allowed to interact, depending on the restrictApplicationSpawning field. One, multiple, or no exclusions can be added. As demonstrated in the "Optional body" section, each application/exclusion requires each of the fields listed below:
        • applicationId: This field specifies the application that will be affected by the Ringfencing.
          • Expects: <GUID> in format "00000000-0000-0000-0000-000000000000"
        • osType: This field determines the OS Type of the application that will be Ringfenced. OSTypes to select from are listed below. This field expects the Integer associated with the OSType:
          • Windows = 1
          • MAC = 2
          • Linux = 3
          • Windows XP = 5
      • rfFilePolicy: This field determines the exclusions that will be added regarding File Ringfencing. One, multiple, or no exclusions can be added. As demonstrated in the "Optional body" section, each exclusion requires each of the fields listed below:
        • action: This field determines the action that will be taken on the specified path below. This field expects the Integer value of either 1 or 2. The value of 1 will permit the file interaction with the file path. The value of 2 will deny/block the file interaction with the file path.
          • Expects: Integer value 1 or 2
        • path: This field determines the file path that will be affected by the Ringfencing action taken. Be sure to use \\ instead of a single \ for the existing slashes in the path. Wildcards can be used in this field in the same way as in the ThreatLocker Portal, as shown in this example: c:\\users\\*\\documents\\*
          • Expects: Full file path or partial path with wildcards
        • permission: This field determines whether the action of permit or deny will affect read, write, or both read and write actions taken on the specified file path. This field expects an Integer value of either 1 or 2. If the action is set to permit, Integer value 1 specifies that read actions will be permitted, and Integer value 2 specifies that read and write actions will be permitted. If the action is set to deny, Integer value 1 specifies that write actions will be denied, and Integer value 2 specifies that read and write actions will be denied.
          • Expects: Integer value 1 or 2
      • rfNetworkPolicy: This field determines the Tags that will be added regarding Internet Ringfencing. One, multiple, or no Tags can be added. If no tags are added in association with this policy, this field should be removed from the body. As demonstrated in the "Optional body" section, each tag requires each of the fields listed below:
        • action: This field determines the action that will be taken on the specified Tag. This field expects an Integer value of either 1 or 2. The value of 1 will permit the Tag interaction with the application. The value of 2 will deny/block the Tag interaction with the application.
          • Expects: Integer value 1 or 2
        • port: This field determines the port number that the Tag will be applied to. Only one port can be entered per Tag; A range cannot be specified.
          • Expects: An Integer value
        • server: This field specifies the tagId/specific Tag that this exclusion will apply to. This field expects the text "tag:" to be entered, followed by the tagId of the Tag being applied to the policy, as shown below.
          • Expects: "tag:00000000-0000-0000-0000-000000000000"
      • rfRegistryPolicy: This field determines the exclusions that will be added regarding Registry Ringfencing. One, multiple, or no exclusions can be added. As demonstrated in the "Optional body" section, each exclusion requires each of the fields listed below:
        • action: This field determines the action that will be taken on the specified path below. This field expects an Integer value of either 1 or 2. The value of 1 will permit the Registry interaction with the path. The value of 2 will deny/block the Registry interaction with the path.
          • Expects: Integer value 1 or 2
        • path: This field determines the Registry path that will be affected by the Ringfencing action taken. Be sure to use \\ instead of a single \ for the existing slashes in the path. Wildcards can be used in this field like they can in the ThreatLocker Portal, as shown in this example: \\registry\\user\\software\\threatlocker\\*
          • Expects: Full file path or partial path with wildcards
    • ticketInfo: This field will populate any text entered into the Ticket text box in the Ticket Details tab of the policy in the ThreatLocker Portal. This field is typically used to indicate any ticket number that may have been referenced during the creation of the new policy, but can be used as you see fit.
      • Expects: Any text input
    • userGroups: This field determines what users or groups the new policy will apply to when allUserGroups is set to false. If allUserGroups is set to true, anything input into this field will be ignored since the policy will apply to all users and groups. One or multiple users/groups can be entered. This field expects any username or group to be entered in the corresponding format, typically this format will be: HOSTNAME\USERNAME or DOMAIN\USERNAME. For each user/group, enter the text and value field. The required body section formats adding two users/groups to a new policy.
      • text: expects any text input
      • value: expects any text input

• Permissions Needed for User
  • Edit Application Control Policies

PolicyUpdateById

https://portalapi.INSTANCE.threatlocker.com/portalapi/Policy/PolicyUpdateById

• Method: PUT
• Description: This API is used when navigating to the Application Control page, selecting the Policies tab, selecting a policy you wish to make changes to, making your changes, and selecting "Save," where this API is called. This API is responsible for updating Application Control policies in your organization. To edit a policy in a different organization than the currently logged-in/managed organization, use the managedOrganizationId header as described below.

Be sure to review the Optional Body/Parameters section. Review the current policy configuration of the policy you are making changes to. Many fields listed are not required to be entered/included in the call to this API. If some fields are not included, you may unintentionally make changes to your policy.

 

Ensure that the managedOrganizationId aligns with where the policy will be updated as per what is entered into the computerGroupId field outlined below.

 

Once you have called this API to edit your policy, be sure to deploy policies in the organization where the policy exists (or for all organizations if a global policy was edited) either through the Portal using the Deploy Policies button or through API, documentation linked below.

/portalAPI/DeployPolicyQueue/* | ThreatLocker Help Center

• Required Body/Parameters
  • Valid APIKey/Authorization Token in header
  • Fields
    
    • applicationIdList: This field is where applications are applied to the policy. One or multiple applications can be entered. The required body section formats adding/maintaining two applications to the policy. To keep the same application(s) applied to the policy, enter the same applicationId(s) as those already applied. For each application, enter the applicationId in the format below. Ensure that the applications tied to the policy utilize the same osType as the policy.
      • Expects a GUID in format: "00000000-0000-0000-0000-000000000000"
    • computerGroupId: This field determines where the Application Control policy will be applied. This field corresponds to the "Applies To" section of the "Edit Application Policy" sidebar in the Portal. Any valid organizationId, computerGroupId, or computerId can be entered. For instance, if looking to apply the policy at the entire organization level, enter the organizationId into this field. To keep the policy at the same level, enter the same computerGroupId that has already been applied to the policy.
      • Expects a GUID in format: "00000000-0000-0000-0000-000000000000"
    • name: This field determines the name that will be applied to the policy. Any name can be entered. If you do not wish to change the policy's name, enter the existing name.
      • Expects: Any text input
    • osType: The same OS Type as what currently applies to the policy is expected. It cannot be updated since the policy has already been created. This field expects the Integer associated with the OSType:
      • Windows = 1
      • MAC = 2
      • Linux = 3
      • Windows XP = 5
    • policyActionId: This field determines the policy action of the policy. If you do not wish to change the policy action, enter the same Integer value associated with the action currently applied to the policy. This field expects the Integer associated with the policy action to be entered:
      • Permit = 1
      • Deny = 2
      • Permit with Ringfence = 6
    • policyId: This field determines which policy will be updated. The same policyId as what currently applies to the policy is expected. It cannot be updated since the policy has already been created.
      • Expects: <GUID> in format "00000000-0000-0000-0000-000000000000"

• Optional Body/Parameters
• • In header: "managedOrganizationId": <GUID> in format "00000000-0000-0000-0000-000000000000" 
  • Fields
    
    • allDevices: This field determines if the policy will apply to all interfaces or a selected interface. When this field is set to false, the deviceType field must be used so that only one specific interface will affect the policy. Otherwise, this field will default to true. When this field is omitted, the deviceType field should not be used/included, and the policy will apply to all interfaces. When this field is set to true, the policy will apply to all interfaces, and anything entered into the deviceType field will be ignored.
      • Expects: true or false
    • allUserGroups: This field determines if the policy will apply to either all or selected users and groups. When this field is set to false, the userGroups field must be used so that only selected users and groups will affect the policy. Otherwise, this field will default to true. When this field is omitted, the userGroups field should not be used/included, and the policy will apply to all users and groups. When this field is set to true, the policy will apply to all users and groups, and anything entered into the userGroups field will be ignored.
      • Expects: true or false
    • allowRequest: This field can only be used when policyActionId is set to 2 and determines if the policy will allow the user the option to request access to the denied file from the ThreatLocker Tray prompt. If this field is set to false or omitted entirely, the user will not be able to request access. If this field is set to true, the user will be able to request access and send an Approval Request. If this field is omitted when calling this API and allowRequest is set to true, allowRequest will default to false, and the policy will not allow the user to request access.
      • Expects: true or false

Note: ThreatLocker does not recommend using the applicationSelection field below unless you are creating a default deny policy. Improper use of this field could cause all applications to be permitted. A warning is displayed before changing policies to use all applications, and to change a policy to use this setting, the name must contain either "Permit All" or begin with "Default - "

• • • applicationSelection: This field determines whether the policy will apply to selected applications or all applications. When this field is omitted or set to 0, the applications in the applicationIdList field will be added to the policy. Only when this field is explicitly set to 1 will the policy be set to select all applications.
      • Expects: Integer value 0 or 1
    • comments: This field will populate any text entered into the File Path text box in the Ticket Details tab of the policy in the ThreatLocker Portal. This field is typically used to indicate any file paths that may have been referenced in association with the policy, but can be used as you see fit. If nothing is entered (null or "") or this field is omitted entirely, no comments will be attached to the policy; If comments are already attached, they will be removed. If comments are already attached to the policy, any text entered into this field will overwrite what is currently attached. If you wish to keep the comments already attached to the policy, enter the same text that is already attached.
      • Expects: Any text input
    • description: This field determines the description of the policy. If nothing is entered (null or "") or this field is omitted entirely, no description will be attached to the policy; If a description is already attached, it will be removed. If a description is already attached to the policy, any text entered into this field will overwrite what is currently attached. If you wish to keep the description already attached to the policy, enter the same description that is already attached.
      • Expects: Any text input
    • deviceType: This field determines what interface the policy will apply to when allDevices is set to false. If allDevices is set to true, anything input into this field will be ignored since the policy will apply to all devices. If you wish to keep the same device type attached to the policy, enter the same device type into this field and ensure that the field allDevices is used and set to false. This field expects one of the following options to be entered exactly as they appear below:
      • USB
      • DVD
      • UNC
      • SCSI
      • SATA
      • IDE
    • elevationStatus: This field determines whether Elevation to run as a local administrator will be applied to the policy. This field expects one of the corresponding Integer values to be entered. A separate Elevation expiration and overall policy expiration cannot be configured, like when creating the policy using the elevationEndDate field through API. To change or add an Elevation expiration once the policy has been created, set the policyScheduleStatus field to 1 and set the endDate field to when the policy should expire. If there is already Elevation applied and you do not wish to make changes, enter the same Integer value. Otherwise, Elevation will be changed/removed.
      • Do not Elevate = 0
      • Elevate (Notify User) = 1
      • Elevate (Do Not Notify User) = 2
      • Force the program to run as a standard user (Does not apply for administrators) = 3
    • endDate: This field is used when policyScheduleStatus is set to 1 and determines when the policy will expire. This expects a time entered in UTC in format "YYYY-MM-DDTHH:MM:SSZ", where YYYY is the year, the first MM is the month, DD is the day, HH are the hours, the second MM is the minutes, and SS are the seconds. The T must be included to designate the time and should not be changed or removed. If there is already a date and time specified in this field and you do not wish to make changes, enter the same date and time. Otherwise, your policy expiration will be changed/removed.
      • Expects expiration date and time in format: "YYYY-MM-DDTHH:MM:SSZ"
    • isEnabled: This field determines if the policy is enabled. If this field is set to false or omitted entirely, the policy will not be enabled. If this field is set to true, the policy will be enabled. If this field is omitted when calling this API and isEnabled is set to true, isEnabled will default to false, and the policy will be disabled.
      • Expects: true or false
    • killRunningProcesses: This field can only be used when policyActionId is set to 2 and determines if the policy will kill any running processes when the policy is matched. When enabled, once a file matches the policy, the process that the file originated from will be terminated. If this field is set to false or omitted entirely, kill running processes will not be enabled. If this field is set to true, kill running processes will be enabled. If this field is omitted when calling this API and killRunningProcesses is set to true, killRunningProcesses will default to false, and the policy will not kill running processes as described above. 
      • Expects: true or false
    • logAction: This field determines if the policy will log when matched in the Unified Audit. If this field is set to false or omitted entirely, the policy will not log in the Unified Audit. If this field is set to true, the policy will log in the Unified Audit. If this field is omitted when calling this API and logAction is set to true, logAction will default to false, and the policy will not log in the Unified Audit.
      • Expects: true or false
    • monitorMode: This field determines the status that will be applied to the policy. When this field is omitted, it will default to 0. When this field is set to 0, the policy will be set to "Inherit Status From Computer", meaning the behavior of the policy will depend on the Maintenance Mode of the computer. When this field is set to 1, the policy will be set to "Secured Mode", meaning no matter the Maintenance Mode of the computer, the policy will act as if the computer is in Secured Mode and will take the policy action indicated (Permit with Ringfence or Deny). When this field is set to 2, the policy will be set to "Monitor Only Mode", meaning no matter the Maintenance Mode of the computer, the policy itself will act as if the computer is in the Monitor Only Maintenance Mode. Setting this field to 2 is particularly useful when setting up Ringfencing for the first time, as it will monitor the Ringfencing traffic coming through the policy, but not block anything. If there is already a status applied (Secured or Monitor) to the policy and you do not wish to make changes, enter the same Integer value. Otherwise, the status will be changed/removed.
      • Expect: Integer value 0, 1, or 2
    • networkExclusions: This field determines the exclusions that will be added regarding Internet Ringfencing. One, multiple, or no exclusions can be added. If you want to make no changes, the same exclusions need to be added with all their fields. Otherwise, the exclusion(s) may be changed/removed. As demonstrated in the "Optional body" section, each exclusion requires each of the fields listed below:
      • tagPrefixTypeId: This field specifies what type of exclusion will be added, either a domain, IPv4, or IPv6. This field expects one of the following Integer values to be entered, corresponding to the type of exclusion desired.
        • Domain = 1
        • IPv4 = 2
        • IPv6 = 3
      • value: This field determines the domain, IPv4, or IPv6 value that is applied to the Ringfencing policy.
        • Expects: Either an IPv4 or IPv6 address (in correct CIDR notation) or a valid domain
    • notifyOnRequest:  This field can only be used when policyActionId is set to 2, must be used in combination with the requestEmailAddressesList field, and determines if the policy will notify the listed ThreatLocker administrator(s) (in the requestEmailAddressesList field) through email/SMS of an Approval Request generated after the policy was matched. If this field is set to false or omitted entirely, no administrators will be notified. If this field is set to true, the administrators listed will be notified. If this field is omitted when calling this API and notifyOnRequest is set to true, notifyOnRequest will default to false, and the policy will not notify the administrators.
      • Expects: true or false
    • orderBy: This field determines in what order the policy can be matched in the currently assigned hierarchy. For instance, if the policy exists at the entire organization level with an orderBy Integer value of -10, all policies at the global, global group, and any policies with a higher orderBy value at the entire organization level will be processed first. When this field is omitted, it will default to the Integer value 0 and overwrite any existing orderBy value. If you wish to keep your policy where it is currently placed, enter the same orderBy value that already applies to the policy.
      • Expects: Any Integer value (positive or negative)
    • parentProcessIdList: This field is where applications are specified that are allowed to launch the application(s) tied to the policy. One or multiple applications can be entered. The optional body section formats adding/maintaining two applications to the policy. To keep the same application(s) applied, enter the same applicationId(s) as those already applied and ensure that the field parentRestrictionEnabled is used and set to true. For each application, enter the applicationId in the format below. Ensure that the applications specified in this field utilize the same osType as the policy.

      • Expects a GUID in format: "00000000-0000-0000-0000-000000000000"
    • parentRestrictionEnabled: This field determines whether the policy will restrict the application(s) that are permitted to launch the selected application(s) in the policy. When this field is set to false or omitted, the parentProcessIdList field must not be used so that all applications can launch the application(s) tied to the policy. When this field is set to true, the parentProcessIdList field must be used so that only a selected application(s) can launch the application(s) tied to the policy.
      • Expects: true or false
    • policyScheduleStatus: This field determines whether a policy expiration or policy schedule will be applied to the policy. When this field is set to 0 or omitted, no policy expiration or schedule will be applied. If a policy expiration or policy schedule has already been applied, ensure that this field is not omitted and the corresponding Integer is entered into this field. Otherwise, your policy expiration/schedule may be changed/removed. When this field is set to 1, the endDate field must be used to specify an expiration date. When this field is set to 2, the policySchedules field must be used to specify the days, duration in hours and minutes, and the start time of the policy. To remove a policy schedule/expiration, this field can be omitted, or the Integer value 0 can be used.
      • Expects: Integer value 0, 1, or 2
    • policySchedules: This field is used when policyScheduleStatus is set to 2 and determines the schedule that will be applied to the policy. If policy schedules are already specified in this field and you do not wish to make changes, enter the current policy schedules. Otherwise, your policy schedule will be changed/removed. The following fields are used for each defined policy schedule.
      • dayOfTheWeek: This field determines the day of the week when the policy will be enabled. This field expects an Integer between 0 and 6, 0 being Sunday and 6 being Saturday.
      • durationHours: This field determines the number of hours that the policy will be enabled. This field expects any valid Integer value, anything less than 24.
      • durationMinutes: This field determines the number of minutes that the policy will be enabled. This field expects any valid Integer value, anything less than 60.
      • startTime: This field expects the start time to be entered in a 24-hour format "YYYY-MM-DDTHH:MM:SSZ", where YYYY is the year, the first MM is the month, DD is the day, HH are the hours, the second MM are the minutes, and SS are the seconds. The T must be included to designate the time and should not be changed or removed.
    • requestEmailAddressesList: This field is used in association with the notifyOnRequest field to specify the email address(es) of the ThreatLocker administrator(s) who will be notified when a request is sent in relation to the policy. One or multiple email addresses can be entered as shown in the "Optional body" section below. If nothing is entered (null or "") or this field is omitted entirely, no email addresses will be attached to the policy; If email addresses are already attached, they will be removed. If you wish to keep the email addresses that are already attached to the policy, enter the same emails.
      • Expects: Any valid email address(es)
    • requestor: This field will populate any text entered into the Requestor text box in the Tickets Details tab of the policy in the ThreatLocker Portal. This is typically used to indicate who requested the policy changes to be implemented, but can be used as you see fit. If nothing is entered (null or "") or this field is omitted entirely, no requestor will be attached to the policy; If requestor is already attached, it will be removed. If requestor is already attached to the policy, any text entered into this field will overwrite what is currently attached. If you wish to keep the requestor already attached to the policy, enter the same text that is already attached.
      • Expects: Any text input
    • ringfencingOptions: This field is used to specify the conditions under which Ringfencing will be applied to the policy. In order to apply Ringfencing, the policyActionId must be set to 6. The following fields can be combined to add the desired amount of Ringfencing and initial exclusions.

Note: For all the fields below involving Ringfencing, if you want to make no changes, the same selections and restrictions need to be added in their respective fields. Otherwise, either exclusion(s) or component(s) of Ringfencing may be changed/removed.

• • • • restrictApplication: This field determines whether Application Ringfencing will apply to the policy. If this Ringfencing is desired, set this field to true; Otherwise, set this field to false.
        • Expects: true or false
      • restrictApplicationSpawning: This field determines what type of Application Ringfencing will apply to the policy. Set this field to true to specify that all application interaction will be blocked except for the ones listed below in the field rfAssociatedApplicationPolicy. Otherwise, set this field to false to specify that all application interactions will be allowed besides the ones listed below in the field rfAssociatedApplicationPolicy.
        • Expects: true or false
      • restrictFileAccess: This field determines whether File Ringfencing will apply to the policy. When File Ringfencing is applied, any monitored file path in Storage Control and any path exclusions set up in the field rfFilePolicy with the action of 'Deny' will have their file interaction blocked. If this Ringfencing is desired, set this field to true; Otherwise, set this field to false.
        • Expects: true or false
      • restrictNetworkAccess: This field determines whether Internet Ringfencing will apply to the policy. Any internet/network interaction not specifically listed within the exclusions in the field networkExclusions will have the interaction blocked. If this Ringfencing is desired, set this field to true; Otherwise, set this field to false.
        • Expects: true or false
      • restrictRegistryAccess: This field determines whether Registry Ringfencing will apply to the policy. Any registry interaction not specifically listed within the exclusions in the field rfRegistryPolicy will have the interaction blocked. If this Ringfencing is desired, set this field to true; Otherwise, set this field to false.

        • Expects: true or false
      • rfAssociatedApplicationPolicy: This field determines the applications/exclusions that will either be blocked from interacting or allowed to interact, depending on the restrictApplicationSpawning field. One, multiple, or no exclusions can be added. As demonstrated in the "Optional body" section, each application/exclusion requires each of the fields listed below:
        • applicationId: This field specifies the application that will be affected by the Ringfencing.
          • Expects: <GUID> in format "00000000-0000-0000-0000-000000000000"
        • osType: This field determines the OS Type of the application that will be Ringfenced. OSTypes to select from are listed below. This field expects the Integer associated with the OSType:
          • Windows = 1
          • MAC = 2
          • Linux = 3
          • Windows XP = 5
      • rfFilePolicy: This field determines the exclusions that will be added regarding File Ringfencing. One, multiple, or no exclusions can be added. As demonstrated in the "Optional body" section, each exclusion requires each of the fields listed below:
        • action: This field determines the action that will be taken on the specified path below. This field expects the Integer value of either 1 or 2. The value of 1 will permit the file interaction with the file path. The value of 2 will deny/block the file interaction with the file path.
          • Expects: Integer value 1 or 2
        • path: This field determines the file path that will be affected by the Ringfencing action taken. Be sure to use \\ instead of a single \ for the existing slashes in the path. Wildcards can be used in this field in the same way as in the ThreatLocker Portal, as shown in this example: c:\\users\\*\\documents\\*
          • Expects: Full file path or partial path with wildcards
        • permission: This field determines whether the action of permit or deny will affect read, write, or both read and write actions taken on the specified file path. This field expects an Integer value of either 1 or 2. If the action is set to permit, Integer value 1 specifies that read actions will be permitted, and Integer value 2 specifies that read and write actions will be permitted. If the action is set to deny, Integer value 1 specifies that write actions will be denied, and Integer value 2 specifies that read and write actions will be denied.
          • Expects: Integer value 1 or 2
      • rfNetworkPolicy: This field determines the Tags that will be added regarding Internet Ringfencing. One, multiple, or no Tags can be added. If no tags are added in association with this policy, this field should be removed from the body. As demonstrated in the "Optional body" section, each tag requires each of the fields listed below:
        • action: This field determines the action that will be taken on the specified Tag. This field expects an Integer value of either 1 or 2. The value of 1 will permit the Tag interaction with the application. The value of 2 will deny/block the Tag interaction with the application.
          • Expects: Integer value 1 or 2
        • port: This field determines the port number that the Tag will be applied to. Only one port can be entered per Tag; A range cannot be specified.
          • Expects: An Integer value
        • server: This field specifies the tagId/specific Tag that this exclusion will apply to. This field expects the text "tag:" to be entered, followed by the tagId of the Tag being applied to the policy, as shown below.
          • Expects: "tag:00000000-0000-0000-0000-000000000000"
      • rfRegistryPolicy: This field determines the exclusions that will be added regarding Registry Ringfencing. One, multiple, or no exclusions can be added. As demonstrated in the "Optional body" section, each exclusion requires each of the fields listed below:
        • action: This field determines the action that will be taken on the specified path below. This field expects an Integer value of either 1 or 2. The value of 1 will permit the Registry interaction with the path. The value of 2 will deny/block the Registry interaction with the path.
          • Expects: Integer value 1 or 2
        • path: This field determines the Registry path that will be affected by the Ringfencing action taken. Be sure to use \\ instead of a single \ for the existing slashes in the path. Wildcards can be used in this field like they can in the ThreatLocker Portal, as shown in this example: \\registry\\user\\software\\threatlocker\\*
          • Expects: Full file path or partial path with wildcards
    • ticketInfo: This field will populate any text entered into the Ticket text box in the Ticket Details tab of the policy in the ThreatLocker Portal. This field is typically used to indicate any ticket number that may have been referenced in relation to the policy, but can be used as you see fit. If nothing is entered (null or "") or this field is omitted entirely, no ticketInfo will be attached to the policy; If ticketInfo is already attached, it will be removed. If ticketInfo is already attached to the policy, any text entered into this field will overwrite what is currently attached. If you wish to keep the ticketInfo already attached to the policy, enter the same text that is already attached.
      • Expects: Any text input
    • userGroups: This field determines what users or groups the policy will apply to when allUserGroups is set to false. If allUserGroups is set to true, anything input into this field will be ignored since the policy will apply to all users and groups. One or multiple users/groups can be entered. When selected users and groups are already applied to the policy before calling this API, they must be entered again into this field. Otherwise, they will be removed/overwritten based on what is entered. Also, ensure that the field allUserGroups is included and set to false. This field expects any username or group to be entered in the corresponding format, typically this format will be: HOSTNAME\USERNAME or DOMAIN\USERNAME. For each user/group, enter the text and value field. The required body section formats adding/keeping two users/groups applied to the policy.
      • text: expects any text input
      • value: expects any text input

• Permissions Needed for User
• • Edit Application Control Policies

PolicyUpdateForDeleteByIds

https://portalapi.INSTANCE.threatlocker.com/portalapi/Policy/PolicyUpdateForDeleteByIds

• Method: PUT
• Description: This API is used in multiple locations throughout the ThreatLocker Portal to delete one or multiple Application Control policies. This API is responsible for deleting Application Control policies in your organization.

Once you have called this API to delete your policy or policies, be sure to deploy policies in the organization where the policy exists (or for all organizations if a global policy was deleted) either through the Portal using the Deploy Policies button or through API, documentation linked below.

/portalAPI/DeployPolicyQueue/* | ThreatLocker Help Center

 

For accurate System Audit logging of the deletion of the policy, please review the Optional Body/Parameters section below.

• Required Body/Parameters
  • Valid APIKey/Authorization Token in header
  • Fields

Note: Each of the following fields needs to be entered for each policy you want to delete, as shown in the Required body section.

• • • organizationId: This field expects the organizationId of the organization where the policy that will be deleted exists.
      • Expects: <GUID> in format "00000000-0000-0000-0000-000000000000"
    • policyId: This field expects the policyId of the policy that will be deleted.
      • Expects: <GUID> in format "00000000-0000-0000-0000-000000000000"

• Optional Body/Parameters
  
  • Fields
    • name: This field determines the name that will be logged in the System Audit. This field should match the name of the policy that will be deleted.
      • Expects: Text of the policy's name

• Permissions Needed for User
  • Edit Application Control Policies