/portalAPI/Application/*

This article will encompass all portalAPI calls that are related to /portalAPI/Application/* 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

ApplicationGetResearchDetailsById

https://portalapi.INSTANCE.threatlocker.com/portalapi/Application/ApplicationGetResearchDetailsById

• Method: GET
• Description: This API is used when clicking the Modules dropdown on the left side of the ThreatLocker Portal, clicking Application Control, viewing the Applications page, and selecting/clicking on an application that has available research data. This API will get any research data made available by the ThreatLocker Research Team based on the applicationId provided. For instance, for the Adobe Creative Cloud application, the following information/fields will be returned when utilizing this API:
  • productName: This field contains the full name of the product/application. For this example, "Adobe Creative Cloud" will be shown.
  • clientApplicationName: This field is the actual application name in your organization associated with the research details. Applications can vary slightly in name but still be linked to the same research details.
  • productDescription: This field is the description of the application as created by the ThreatLocker Research Team. For Adobe Creative Cloud, the productDescription reads, "A software suite that provides access to a collection of Adobe applications for various creative services including, web development, graphic design, photography, etc."
  • clientDescription: This field contains the description that you have added to the application definition that exists in your organization(s). Assuming the applicationId is for a custom application definition in your organization(s) relating to Adobe Creative Cloud, the clientDescription could read, "This is Adobe Creative Cloud and will contain everything related to Adobe." Note that you are not able to add your own descriptions to any ThreatLocker Built-In Applications, even when they are permitted in your organization(s), as Built-Ins are completely managed by ThreatLocker.
  • osType: This field identifies what operating system the application research details apply to. For this instance of Adobe Creative Cloud, the osType is 1, meaning this information applies to the Adobe Creative Cloud application for Windows computers. Listed below are the osTypes for reference.
    • Windows = 1
    • MAC = 2
    • Linux = 3
    • Windows XP = 5
  • remediationText: This field describes how to limit the potential harm the application can do in your organization(s). For Adobe Creative Cloud, the remediationText reads "Evaluate the need for this software. If it is required for business use, limit access to high-risk applications, files, and the ability to reach out to the internet."
  • potentialRiskStrategyText: This field describes the potential risk strategy/assessment of the application. For Adobe Creative Cloud, the potentialRiskStrategyText reads "Vulnerabilities can result to the compromise of intellectual property, unauthorized access to design projects, and potential manipulation of confidential design data."
  • concernRating: This field contains the concern/risk score of the application and can be used to determine whether some applications are too risky to run in your organization(s). For Adobe Creative Cloud, the concernRating is 3.
  • businessRating: This field contains the score for how relevant/useful the application is for business purposes. For Adobe Creative Cloud, the businessRating is 6.
  • reviewRating: This field contains the combined score calculation of the concern and business scores. This number is generated by taking the concern and business rating, weighting them on a scale, and then using an algorithm to generate the overall combined score. For Adobe Creative Cloud, the reviewRating is 4.
  • countriesWhereCodeCompiled: This field contains a list of the countries where the code is compiled. For Adobe Creative Cloud, the countriesWhereCodeCompiled contains "Romania", "India", and "United States".
  • categories: This field lists the categories the application applies to. For Adobe Creative Cloud, the categories are "Cloud Software" and "Design Software". Other categories include, but are not limited to, "Utility Software", Browser Extension", and "Discontinued Software".
  • accessLevels: This field lists the Ringfencing restrictions that can be/are applied to the application in your organization(s). The "displayName" field contains the type of Ringfencing and the "isProtected" field determines whether the Ringfencing is enabled or not (true or false) for that restriction.
• Required Body/Parameters
  • Valid APIKey/Authorization Token in header
  • applicationId: This is the Unique Identifier for the application you would like to review the research data for. Only one applicationId can be entered/reviewed at one time.
    • Expects a GUID in format: "00000000-0000-0000-0000-000000000000"
• Permissions Needed for User
  • Edit Application Control Applications
  • Approve for Entire Organization
  • Approve for Group
  • Approve for Single Computer
  • Approve for Single Computer Application Only
  • View Approvals

ApplicationGetForMaintenanceMode

https://portalapi.INSTANCE.threatlocker.com/portalapi/Application/ApplicationGetForMaintenanceMode

• Method: GET
• Description: This API is utilized on the Devices page when viewing an individual computer and navigating to the Maintenance tab on the computer sidebar in the ThreatLocker Portal. This API will get all the applications accessible when looking to enable a Maintenance Mode on an endpoint. When selecting to add into an application utilizing a Maintenance Mode, this API will pull the list of all applications available to learn or install into. If looking to view the applications for a different organization than the currently logged in/managed organization, utilize the managedOrganizationId header as described below. This API can be used to analyze the applications in your organization(s) that are available for use with a Maintenance Mode and for analyzing your applications as a whole.
  • NOTE: This will include all the applications the organization and/or currently authenticated user has access to. This will include access to any applicable parent applications and will show in the "label" field when run in the following format: "parentOrganizationName\\parentOrganizationApplicationName".
• Required Body/Parameters
  • Valid APIKey/Authorization Token in header
• Optional Body/Parameters
  
  • OSType: (Defaults to 1)
    • Windows = 1
    • MAC = 2
    • Linux = 3
    • Windows XP = 5
  • In header: "managedOrganizationId": <GUID> in format "00000000-0000-0000-0000-000000000000"

• Permissions Needed for User

  • Edit Computers

  • Edit Application Control Applications

ApplicationGetMatchingList

https://portalapi.INSTANCE.threatlocker.com/portalapi/Application/ApplicationGetMatchingList

• Method: POST
• Description: This API is used when clicking on an Application Control Approval Request in the Response Center of the ThreatLocker Portal to check for any applications that match the file being requested. This API will check based on the information provided in the body below for any matching applications. When looking for matching applications inside a child organization to potentially use in association with a request in a child organization, utilize the managedOrganizationId header as described below. Be sure the managedOrganizationId header aligns with the organizationId where the approval request came from for accurate results. If there is a matching application, then a policy can be created to permit or permit with a Ringfence through the Approval Request.

Note that any regex rules contained in your custom application definitions will not show as matching when completing this call. This is expected behavior and is intentional for enhanced processing.

ThreatLocker recommends inputting corresponding Fields for each call, keeping all the fields used related to the same file/potential matching application. Inputting fields from multiple application files, when all values may not align to the same unique application, may return multiple matching applications. For example, inputting the ThreatLocker hash value for the application "1pass", while simultaneously inputting the SHA256 hash value for the application "putty", the matching application details for both 1pass and putty will be returned. When looking for a potential match based on path and process rules for example, enter both the path and process from the same file in order to find potential matches.

** Before approving a built-in application from a request, ensure that the file being permitted through the request is in accordance with the application you believe the request originated from. There are cases where common DLL and other files will be requested that can be used across multiple applications, causing the file to match into multiple applications. When applying a built-in, the entire built-in application is being effectively permitted. **

• Required Body/Parameters
  • Valid APIKey/Authorization Token in header
  • Fields
    • hash: This field will check to see if any applications match based on the hash using the TheatLocker hashing algorithm. If there is an approval request associated with the file you're looking to investigate, the hash will be displayed in the request itself and can be copied into the body. The /portalapi/ApprovalRequest/ApprovalRequestGetByParameters endpoint can be used to get approval request details. If there was no request sent, an easy way to get the hash of the file is to navigate to the Unified Audit and utilize the search parameters to find the log of the file on the machine. The /portalapi/ActionLog/ActionLogGetByParametersV2 endpoint can be used to search through the Unified Audit logs.
      • Expects: A ThreatLocker hash
    • sha256: This field will check to see if any applications match based on the hash using the SHA256 hashing algorithm. If there is an approval request associated with the file you're looking to investigate, the hash will be displayed in the request itself and can be copied into this call. The /portalapi/ApprovalRequest/ApprovalRequestGetByParameters endpoint can be used to get approval request details. If there was no request sent, an easy way to get the hash of the file is to navigate to the Unified Audit and utilize the search parameters to find the log of the file on the machine. The /portalapi/ActionLog/ActionLogGetByParametersV2 endpoint can be used to search through the Unified Audit logs.
      • Expects: A SHA256 hash
    • path: This field will check to see if any applications match based on the file path. Do not use wildcards in this field as it will not work like wildcarding in custom rules. It is recommended to enter the entire file path of the file being executed/requested to get accurate results for any matching applications, but any text can be entered. Be sure to use \\ for the existing slashes in the path entered like in this example:
      • Original file path:
        •  "c:\program files (x86)\dropbox\update\dropboxupdate.exe"
      • Path adjusted to be entered into this field:
        • "c:\\program files (x86)\\dropbox\\update\\dropboxupdate.exe" 
    • processPath: This field will check to see if any applications match based on the process path. Do not use wildcards in this field as it will not work like wildcarding in custom rules. It is recommended to enter the entire process path to get accurate results for any matching applications, but any text can be entered. Be sure to use \\ for the existing slashes in the process path entered like in this example:
      
      • Original process path:
        • "c:\windows\system32\svchost.exe"
      • Process path adjusted to be entered into this field:
        • "c:\\windows\\system32\\svchost.exe"
    • certs: The following fields are used when searching for a matching application based on the certificate. Either just the sha and validCert, just the subject and validCert, or sha, subject, and validCert fields can be entered when searching using the certificate. This field can also check multiple certs in the same call as shown in the body below:
      • sha: This field expects the full SHA of the certificate to be entered. In order to get the SHA of the certificate, navigate to the Unified Audit and use the New Search (Beta). From there, search the file you are looking for, pull up the Unified Audit log, and click on "More Details". The SHA of the certificate will show under the Certificate field.
        • Expects: SHA of the certificate
      • subject: This field expects the text of either the full or partial certificate path to be entered as it appears in ThreatLocker. Where there is a " in the certificate path, enter a \ in front of each occurrence as shown in the example below:
        • Original cert path
          • "cn="dropbox, inc", o="dropbox, inc", l=san francisco, s=california, c=us"
        • Cert path adjusted to be entered into this field:
          • "cn=\"dropbox, inc\", o=\"dropbox, inc\", l=san francisco, s=california, c=us"
      • validCert: This field determines whether the cert that is entered is valid. If it is a valid certificate, set this to true, otherwise set it to false.
        • Expects: true or false

• • • createdBys: This field will check to see if any applications match based on the created by process path(s). This field can check multiple created by process paths in the same call as shown in the body below. Do not use wildcards in this field as it will not work like wildcarding in custom rules. It is recommended to enter the entire created by process path(s) to get accurate results for any matching applications, but any text can be entered. Be sure to use \\ for the existing slashes in the created by process path(s) entered like in this example:
      • Original created by process path:
        • "c:\users\username\appdata\local\temp\gum7a5e.tmp\dropboxupdate.exe"
      • Created by process path adjusted to be entered into this field:
        • "c:\\users\\username\\appdata\\local\\temp\\gum7a5e.tmp\\dropboxupdate.exe"
    • osType: This field determines the OSType of the application looking to view matches for. OSTypes to select from are listed below and this field expects the Integer associated with the OSType:
      • Windows = 1
      • MAC = 2
      • Linux = 3
      • Windows XP = 5
  • Required body

• 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