/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
  • Required body

• 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 mode 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, 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
    • policyScheduleStatus: This field determines whether a policy expiration or policy schedule will be applied with the new policy. When this field is set to 1, use the endDate field to specify an expiration date. When this field is set to 2, use the policySchedules field 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
  • Optional body

• Permissions Needed for User
  • Edit Application Control Policies