/portalAPI/SystemAudit/*

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

SystemAuditGetByParameters

https://portalapi.INSTANCE.threatlocker.com/portalapi/SystemAudit/SystemAuditGetByParameters

• Method: POST
• Description: This API is used when navigating to the Manage icon and selecting the Users -> System Audit page from the popout menus in the ThreatLocker Portal. This API returns all the System Audit logs for the organization. To view logs in a different organization than the currently logged-in/managed organization, use the managedOrganizationId header as described below. 
• Required Body/Parameters
  • Valid APIKey/Authorization Token in header
  • Fields
    
    • endDate: This field specifies the end date and time for the System Audit search. This expects a date and 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 are the minutes, and SS are the seconds. The T must be included to designate the time and should not be changed or removed.

      • Expects end date and time in format: "YYYY-MM-DDTHH:MM:SSZ"
    • pageNumber and pageSize: These fields determine how many System Audit logs will be returned as if the response were on the System Audit page. However, these fields do not follow the same conventions for pageNumber and pageSize as the Portal does (the Portal uses 25, 100, 200, or 500 for pageSize). Any valid integer can be entered, and it will return in the selected formatting. It is recommended to keep the pageSize to 5000 or below to avoid potential timeouts. For instance, if there are 5 logs to be returned but “pageNumber”: 1 and “pageSize”: 2, 2 entries will be returned per page, and the first two logs will be shown.

      • Expects: An Integer value
    • startDate: This field specifies the start date and time for the System Audit search. This expects a date and 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 are the minutes, and SS are the seconds. The T must be included to designate the time and should not be changed or removed.

      • Expects start date and time in format: "YYYY-MM-DDTHH:MM:SSZ"

• Optional Body/Parameters
  
  • In header: "managedOrganizationId": <GUID> in format "00000000-0000-0000-0000-000000000000"
  • Fields
    
    • actions: This field allows you to search based on specific action types completed within the System Audit. When this field is omitted, all logs with any action type will be returned based on the other fields used. This field expects the text from one or multiple of the options below to be entered exactly as they appear.

      • Create
      • Delete
      • Logon
      • Modify
      • Read
    • afterKeys: This field allows searching for large amounts of data/allows searching the System Audit logs when the pageNumber becomes greater than 10. This field needs to be used when the pageNumber exceeds 10 and should be refreshed to include all new values every 10 pages. To get the values for this field, this API must be called with a pageNumber of 10 or less. Then, get the afterKeyLookup values returned in the Pagination string in the response header and add them in addition to any other values already in this field. Formatting is shown in the Optional body section below.

      • Expects: Set of Integer values
    • details: This field allows you to search based on the text in the System Audit. When this field is omitted, all logs with any text will be returned based on the other fields used. Only partial logs can be searched using this field. For instance, if the log in the System Audit reads "Audit - View Page - Viewed page", the text "Audit", "View Page", and "Viewed page" could be searched separately, but the entire log of "Audit - View Page - Viewed page" could not be searched at once. When you enter the details of the message you want to search for, do not include any wildcards (*) in what you enter. Wildcards will be automatically accounted for based on your input.

      • Expects: Text of part of the System Audit log
    • effectiveAction: This field allows you to search for actions based on the effective action recorded in the System Audit. When this field is omitted, all logs with any effective action will be returned based on the other fields used. This field expects the text from one of the options below to be entered exactly as they appear.

      • Denied
      • Permitted
    • emailAddress: This field allows you to narrow your search to a specific user/users by entering a full or partial username from the ThreatLocker administrator account(s), including API user accounts. When this field is omitted, all logs from all users will be returned based on the other fields used. When you enter your username, do not include any wildcards (*) in what you enter. Wildcards will be automatically accounted for based on your input.

      • Expects: Text of either the entire username or part of the username
    • iPAddress: This field allows you to narrow your search to a specific IP address you enter. This field searches based on the IP address of the ThreatLocker administrator account that completed said action at that time. When this field is omitted, all logs from all IP addresses will be returned based on the other fields used. When you enter your IP address, do not include any wildcards (*) in what you enter. Wildcards will be automatically accounted for based on your input.

      • Expects: Text of either the entire IP address or part of the IP address
    • objectId: This field allows you to search based on actions recorded relating to a specific ThreatLocker asset ID. When this field is omitted, all logs from all ThreatLocker objects/actions are returned based on the other fields used. This ID can be any ID associated with a ThreatLocker asset, including but not limited to organizationId, applicationId, policyId, and computerId.

      • Expects: <GUID> in format "00000000-0000-0000-0000-000000000000"
    • viewChildOrganizations: This field determines whether System Audit logs from all child organizations will be returned. When this field is omitted or set to false, only logs from the currently managed organization will be returned; Typically, this will be the parent organization. When set to true, all logs from all child organizations, including grandchild organizations, will be returned based on the other fields used.

      • Expects: true or false

• Permissions Needed for User
  
  • View System Audit

SystemAuditGetForHealthCenter

https://portalapi.INSTANCE.threatlocker.com/portalapi/SystemAudit/SystemAuditGetForHealthCenter

• Method: POST
• Description: This API is utilized on the Health Center page in the ThreatLocker Portal under the Login Attempts section to display the list of Login Attempts, either successful or denied, for the currently managed organization. If looking to view the logins from a different organization than the currently logged in/managed organization through API, utilize the managedOrganizationId header as described below. Various fields are described below that can be changed to search like you can on the Health Center page itself in the Portal.
• Required Body/Parameters
  • Valid APIKey/Authorization Token in header
  • Fields
    • days: This field will determine how many days back this API will search for login attempts as per the other fields entered. This will take into account the current day automatically; it will be how many days back from the current day. In the ThreatLocker Portal, this is limited to a maximum of 30 days and has other options to show 7 and 14 days back from the current day. However, when using this endpoint through API, any integer value can be entered.
      • Expects: An Integer value
    • isLoggedIn: This field will determine whether the successful or denied login attempts will be displayed. True will display successful logins and denied will display unsuccessful logins.
      • Expects: true or false
    • pageSize and pageNumber: This field determines how many login logs from the System Audit will be returned as if the response was on the Health Center page. However, this field does not follow the same conventions of the pageNumber and pageSize values as the Portal does (pageSize in the Portal is 25). Any valid integer can be entered and it will return in the selected formatting. For instance, if there are 5 logs to be returned but “pageNumber” : 1 and “pageSize” : 2, 2 entries will be returned per page and the first two logs will be shown.
      • Expects: An Integer value
  • Required body:

{

"days": <Integer>,

"isLoggedIn": <Boolean>,

"pageSize": <Integer>,

"pageNumber": <Integer>

}

• Optional Body/Parameters
  
  • In header: "managedOrganizationId": <GUID> in format "00000000-0000-0000-0000-000000000000"
  • Fields
    • searchText: This field will help to search the results based on one of the below fields that are returned when calling this endpoint. Use one of the fields below as a basis for what you enter into the search. For instance, if looking to narrow your search to a specific username, enter the username in the searchText field, ensuring that only one specific username is entered, and their login attempts will be displayed based on the other fields. When you enter the text you want to search for, do not include any wildcards (*) in what you enter. Wildcards will be accounted for automatically depending on your input:
      • Username
      • ipAddress
      • Country
      • Region
      • City
  • Optional body:

• Permissions Needed for User
  • View Health Center