/portalAPI/ApprovalRequest/*

• Optional Body/Parameters
  
  • In header: "managedOrganizationId": <GUID> in format "00000000-0000-0000-0000-000000000000"
  • Field
    • message: This field determines what message/instructions will be displayed to the Cyber Hero Team in the "Ticket Details -> Comments" section of the Approval Request.
      • Expects: Any text input
  • Optional body

• Permissions Needed for User
  • Approve for Entire Organization
  • Approve for Group
  • Approve for Single Computer
  • Approve for Single Computer Application Only
  • View Approvals
  • Elevation Administrator (User)

ApprovalRequestGetCount

https://portalapi.INSTANCE.threatlocker.com/portalapi/ApprovalRequest/ApprovalRequestGetCount

• Method: GET
• Description: This API is used when initially clicking on the Response Center page in the ThreatLocker Portal to get the number of Approval Requests with a status of "Pending" for the organization. Note that this API will only get the count of Approval Requests with a status of "Pending" and return it as an Integer. To get the "Pending" Approval Request count from only 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
  • includeChildOrganizations: This field determines whether the "Pending" Approval Request count from child organizations, including grandchild organizations, will be included in the count of requests that is returned.
    • Expects: true or false
• Optional Body/Parameters
  • In header: "managedOrganizationId": <GUID> in format "00000000-0000-0000-0000-000000000000"
• Permissions Needed for User
  • Approve for Entire Organization
  • Approve for Group
  • Approve for Single Computer
  • Approve for Single Computer Application Only
  • View Approvals
  • Elevation Administrator (User)

ApprovalRequestPermitApplication

https://portalapi.INSTANCE.threatlocker.com/portalapi/ApprovalRequest/ApprovalRequestPermitApplication

• Method: POST
• Description: This API is used on the Response Center page in the ThreatLocker Portal when processing an Application Control Approval Request with either the Execute or Elevate action types. This API is used when clicking the Approve button in the Approval Request in the Portal. To process an Approval Request from a different organization than the currently logged in/managed organization, utilize the managedOrganizationId header as described below.

Note: Only the applicable fields need to be entered when applying a matching, existing, or new application. Example: If using an existing application, any fields related to a matching application and a new application can be removed, leaving and entering corresponding values into the useExistingApplication and exisitingApplication blocks/fields.

• Required Body/Parameters
  
  • Valid APIKey/Authorization Token in header
  • Fields
    • approvalRequest: The following fields are required to be entered for processing the request:
      • approvalRequestId: This field expects the approvalRequestId of the Approval Request that will be processed when this call is completed. To get the approvalRequestId, use the ApprovalRequestGetByParameters API endpoint listed above.
        • Expects: <GUID> in format "00000000-0000-0000-0000-000000000000"
      • comments: This field will populate any text entered into the Comments text box in the Ticket Details tab of the Approval Request in the ThreatLocker Portal and is optional to include altogether if no changes are desired. This can be used to provide additional context for why this Approval Request was permitted.
        • Note: If any text is in a request's Comments field before calling this API and different text or "" is provided, it will overwrite anything previously existing.
        • Expects: Any text input
      • json: This field can be imported/copied over from the API endpoint listed above (ApprovalRequestGetPermitApplicationById).
        • Expects: The complete, formatted JSON text
      • requestorEmailAddress: This field will populate any text entered into the Requestor Email Address text box in the Tickets Details tab of the Approval Request in the ThreatLocker Portal and is optional to include altogether if no changes are desired. This can be used to add or change the requestor's email address so that the requestor can be notified when their request is approved. 
        • Note: If any text is in a request's Requestor Email Address field before calling this API and different text or "" is provided, it will overwrite anything previously existing.
        • Expects: Any text input
      • ticketApprovalManager: This field will populate any text entered into the Approving Manager text box in the Tickets Details tab of the Approval Request in the ThreatLocker Portal and is optional to include altogether if no changes are desired. This can be used to add or change the approving manager related to the request itself for tracking/documentation purposes.

        • Note: If any text is in a request's Approving Manager field before calling this API and different text or "" is provided, it will overwrite anything previously existing.
        • Expects: Any text input
      • ticketId: This field will populate any text entered into the Ticket text box in the Tickets Details tab of the Approval Request in the ThreatLocker Portal and is optional to include altogether if no changes are desired. This can be used to add or change a ticket number related to the ThreatLocker Approval Request that is being processed.
        • Note: If any text is in a request's Ticket field before calling this API and different text or "" is provided, it will overwrite anything previously existing. 
        • Expects: Any text input
    • computerId: This field expects the computerId of the computer that requested access to the file/application.
      • Expects: <GUID> in format "00000000-0000-0000-0000-000000000000"
    • computerGroupId: This field expects the computerGroupId where the computer that requested access to the file/application exists.
      • Expects: <GUID> in format "00000000-0000-0000-0000-000000000000"
    • fileDetails: The following field is required to be entered for processing this request:
      • fullPath: This field expects the full path of the requested file. When you enter your file path, be sure to use \\ for the existing slashes in the path as shown in this example path: "c:\\program files (x86)\\microsoft\\edge\\application\\131.0.2903.99\\identity_helper.exe"
        • Expects: Text of the full filepath 
    • matchingApplications: Before utilizing the fields below, it is recommended to utilize the ApplicationGetMatchingList and ApplicationGetByParameters API (documentation link below). To find potential matching applications, use the file information from the request being processed and pass it into the ApplicationGetMatchingList API. To find existing applications that can be added to, use the ApplicationGetByParameters API. Ensure the corresponding OS Type and managedOrganizationId are used so accurate results for the intended target organization are shown. The following fields must be entered when processing the request when using either a matching, existing, or new application. However, only the fields related to how the request will be processed are required to be entered. For example, when using a matching application, only the fields useMatchingApplication and matchingApplication (plus all other sub-fields listed under matchingApplication) are necessary.

/portalAPI/Application/* | ThreatLocker Help Center

• • • • useMatchingApplication: This field specifies whether a matching application will be used or not when processing the Approval Request. To use a matching application, set this to true; Otherwise, set it to false.
        • Expects: true or false
      • matchingApplication: The following fields are used when applying a matching application (ensure the field useMatchingApplication is set to true) and are used to determine which application will be used when processing the request:
        • applicationName: This field specifies the policy name that will be applied to the new Allowlisting policy entry using the targeted matching application.
          • Expects: Any text input
        • applicationId: This field specifies the matching application that will be used when processing the request.
          • Expects: <GUID> in format "00000000-0000-0000-0000-000000000000"
        • organizationId: This field specifies the organization where the matching application that will be used when processing the request exists.
          • Expects: <GUID> in format "00000000-0000-0000-0000-000000000000"
        • osType: This field is used to specify the OS Type of the matching application. This field expects one of the following Integer values to be entered that correspond to the application being used:
          • Windows = 1
          • MAC = 2
          • Linux = 3
          • Windows XP = 5

• • • • useExistingApplication: This field determines whether an existing application will be used when processing the Approval Request. If you want to use an existing application, set this to true; otherwise, set it to false.
        • Expects: true or false
      • existingApplication: The following fields are used when applying an already existing application (ensure the field useExistingApplication is set to true) and are used to determine which application will be used when processing the request:
        • applicationName: This field specifies the policy name that will be applied to the new Allowlisting policy entry using the targeted existing application (when not using an existing policy).
          • Expects: Any text input
        • applicationId: This field specifies the existing application that will be used when processing the request.
          • Expects: <GUID> in format "00000000-0000-0000-0000-000000000000"
        • organizationId: This field specifies the organization where the existing application that will be used when processing the request exists.
          • Expects: <GUID> in format "00000000-0000-0000-0000-000000000000"
        • osType: This field is used to specify the OS Type of the existing application being used. This field expects one of the following Integer values to be entered that correspond to the application being used:
          • Windows = 1
          • MAC = 2
          • Linux = 3
          • Windows XP = 5
      • useNewApplication: This field determines whether a new application will be created when processing the request. If you want to create a new application, set this to true; otherwise, set it to false.
        • Expects: true or false
      • newApplicationName: This field is used when creating a new application. Ensure that the useNewApplication field is set to true. Any name can be entered and the applicationId will be automatically generated once this API is called.
        • Expects: Any text input
    • organizationId: This field expects the organizationId where the computer that requested access to the file/application exists.
      • Expects: <GUID> in format "00000000-0000-0000-0000-000000000000"
    • organizationIds: This field(s) expects the organizationId(s) of any parent organizations effectively "above" where the Approval Request originated from. For instance, if the request is from a child organization, one organizationId is expected. But if the request is from a grandchild organization, there will be two organizationIds expected.
      
      • Expects: <GUID> in format "00000000-0000-0000-0000-000000000000"
    • osType: This field is used to specify the OS Type of the requesting computer. This field expects one of the corresponding Integer values to be entered.
      • Windows = 1
      • MAC = 2
      • Linux = 3
      • Windows XP = 5
    • policyConditions: The following fields are used to apply policy conditions when processing the Approval Request. This is where application rules can be applied and where a Maintenance Mode can be used through the Approval Request. To determine if there is an existing policy associated with the desired application, utilize the PolicyGetForViewPoliciesByApplicationId API, as documented below.

PolicyGetForViewPoliciesByApplicationId

• • • • useExistingPolicy: This field determines whether an existing policy will be used or not when processing the Approval Request. If looking to use an existing policy, set this to true; Otherwise, set it to false. Note: If no existing policy is affecting the requesting computer and this field is set to true, one will not be created, and only the application definition will be updated.
        • Expects: true or false
      • manualOptions: This field is used to specify the conditions for the application definition rule(s) that will be created when adding to a new or existing application through the request. The following fields can be combined to create custom rules like the ones that can be created in the ThreatLocker Portal Approval Request window. The example shown in the body below will create a hash rule and a path + certificate rule in an application.

• • • • • fullPath: This field expects either the full or partial file path of the file from the Approval Request to be entered to create a custom rule using this and other fields. Be sure to use \\ instead of a single \ for the existing slashes in the path. Wildcards can be used in this field with the same conditions as in the ThreatLocker Portal, as shown in this example: 
          c:\\users\\*\\downloads\\steamsetup.exe.
          • Expects: Full file path or partial path with wildcards
        • processPath: This field expects either the full or partial process path of the process path from the Approval Request to be entered to create a custom rule using this and other fields. 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: 
          c:\\program files (x86)\\mozilla * service\\update\\updater.exe.
          • Expects: Full process path or partial process path with wildcards
        • cert: This field expects either the full or partial certificate path or the full SHA256 hash digest of the certificate from the Approval Request to be entered to create a custom rule using this and other fields. Wildcards should not be used in this field since this field checks for a certificate path that "contains" what is in the entered certificate. This effectively adds a wildcard already on either side of the certificate of what you enter.
          • Expects: Full certificate path or partial certificate path without wildcards OR full SHA256 hash digest of the certificate
        • hash: This field expects the full hash of the requested file from the Approval Request to be entered to create a rule using this field. This field is used when creating a rule based on either the ThreatLocker hash or the SHA256 hash. When creating a hash rule, only the hash should be used in the rule. No other fields should be applied with the hash rule when using this field. When permitting a hash value, it effectively permits the one file requested. A separate rule using a selection of the other fields covered in this section can be created to allow for future proofing related to the requested file, should the requested file be expected to change or update frequently. Wildcards should not be used with this field, only full hash values.
          • Expects: Full ThreatLocker hash or SHA256 hash 
        • createdBy: This field expects either the full or partial created by process path of the created by process path from the Approval Request to be entered to create a custom rule using this and other fields. 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: 
          c:\\program files (x86)\\microsoft\\edgeupdate\\*\\setup.exe.
          • Expects: Full created by process path or partial created by process path with wildcards

Note: It is not recommended to create a file rule using only one parameter (except for a hash-only rule). It is recommended that each parameter be paired with at least one additional parameter to improve the associated application definition’s security posture. For more information on creating secure custom rules in your organization, review this KB article and/or contact the Cyber Hero team for assistance.

Creating Custom Rules | ThreatLocker Help Center

• • • • ruleId: This field is used when looking to enable a Maintenance Mode when processing an Approval Request. This field expects one of the following Integer values to be entered
        • 0 = No Maintenance Mode activated, manual rules
        • 1 = Enable Installation Mode for one hour
        • 2 = Enable Learning Mode for one hour
        • 3 = Enable Monitor Mode for one hour
    • policyLevel: The following fields are only necessary when creating a new policy through the Approval Request. These fields indicate where a new policy will be created. Only one of the following fields should be set to true in order to create a policy at the desired level.
      • toEntireOrganization: This field will set the new policy at the entire organization level, specifically, it will create the new policy at the entire organization where the requesting computer exists.
        • Expects: true or false
      • toComputerGroup: This field will indicate that the new policy will be created at the computer group level, specifically at the computer group specified below in selectedComputerGroup.
      • selectedComputerGroup: The fields below determine the computer group that the new policy will apply to when creating a computer group policy. 
        • computerGroupId: This field expects the computerGroupId where the new policy will be created to be entered. Any computer group returned using the ComputerGroupGetForPermitApplication API endpoint can be used with this field. For accurate results, be sure to use the corresponding managedOrganizationId (the organization from which the request originated) as indicated in the documentation linked below.

           

          ComputerGroupGetForPermitApplication

           
          • Expects: <GUID> in format "00000000-0000-0000-0000-000000000000"
        • organizationId: This field expects the organizationId where the computer group that will have the new policy created at exists to be entered.
          • Expects: <GUID> in format "00000000-0000-0000-0000-000000000000"
        • osType: This field indicates the OS Type of the computer group where the new policy will be applied. This field should match the requesting computer's OS Type. This field expects one of the Integers below:
          • Windows = 1
          • MAC = 2
          • Linux = 3
          • Windows XP = 5
      • toComputer: This field will set the new policy at the computer level. Specifically, it will create the new policy on the individual computer where the Approval Request originated.

        • Expects: true or false
    • ringfenceActionId: This field determines whether Ringfencing will be enabled or not when creating a new policy through the Approval Request. This field expects the Integer value of either 0 or 1. The value of 0 will not enable Ringfencing. The value of 1 will enable Ringfencing with the new policy and will use the settings below in the ringfencingOptions/networkExclusions field to configure the policy.
      • Expects: Integer value 0 or 1
  • Required body:

• Optional Body/Parameters
  • In header: "managedOrganizationId": <GUID> in format "00000000-0000-0000-0000-000000000000"
  • Fields
    • elevationExpiration: This field determines what the expiration time frame of Elevation will be on a newly created policy. 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 policyExpirationDate field. This field expects an Integer and indicates the amount of time in hours from when this API is called that Elevation will be enabled on the policy. When this field is set to 0 and Elevation is set to be enabled, Elevation will never expire on the newly created policy.
      • Expects: Any Integer value
    • elevationStatus: This field determines whether Elevation will be applied when a new policy is created through the Approval Request. This field expects one of the corresponding Integer values to be entered.
      • Do not Elevate = 0
      • Elevate = 1
      • Silent Elevation = 2
    • networkExclusions: This field determines the exclusions that will be added in regard to Internet Ringfencing, specifically exclusions applied in the Exclusions tab of the Portal Approval Request window. 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
    • policyExpirationDate: This field determines if a new policy that will be created from the Approval Request 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"
    • ringfencingOptions: This field is used to specify the conditions when Ringfencing will be applied to a new policy that will be created. The following fields can be combined to add the desired amount of Ringfencing and initial exclusions, like what can be created in the ThreatLocker Portal Approval Request window.
      • restrictApplication: This field determines whether Application Ringfencing will apply to the policy or not. 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 or not. 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 or not. 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 or not. 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"
      • rfFilePolicy: This field determines the exclusions that will be added in regard to 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
      • rfRegistryPolicy: This field determines the exclusions that will be added in regard to 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
  • Optional body

• Permissions Needed for User
  • Approve for Entire Organization
  • Approve for Group
  • Approve for Single Computer
  • Approve for Single Computer Application Only