API - Admin Audit Logs

The admin audit log includes events that occurred in your FortiMail Browser Security tenant. You can use the FortiMail Browser Security Admin Audit Logs API to access the admin audit log. The FortiMail Browser Security Admin Audit Logs API lets you monitor what's happening in your FortiMail Browser Security console tenant. The Admin Audit Logs API can be used by "security information and event management" (SIEM) tools to provide analysis of how your FortiMail Browser Security console tenant is being accessed. You can also use the Admin Audit Logs API to write your own applications that will show how members of your organization are using the FortiMail Browser Security console.

FortiMail Browser Security maintains events in the admin audit log for 365 days.

This topic includes the following sections:

What the Admin Audit Logs API can do

The Admin Audit Logs API lets you monitor the audit events that occur in the FortiMail Browser Security console. This lets you:

  • ensure continued compliance

  • safeguard against inappropriate system access

  • audit suspicious behavior within your tenant

The Admin Audit Logs API gives FortiMail Browser Security console administrators the ability to query administrative actions in the tenant. With this API, you can:

  • automatically feed FortiMail Browser Security console access data into an SIEM or another auditing tool

  • proactively monitor for potential security issues or malicious access attempts

  • write custom apps to gain insight into how your organization uses the FortiMail Browser Security console

The Admin Audit Logs API provides insight into audit events that have actually occurred in the FortiMail Browser Security console of a tenant, and is therefore read only. There are no write methods for Admin Audit Log events.

The FortiMail Browser Security console does not perform any kind of automated intrusion detection. The Admin Audit Logs API will return the data, but cannot automatically determine or indicate whether an action was appropriate.

Who is the Admin Audit Logs API for

The Admin Audit Logs API is meant for anyone interested in programmatically monitoring audit events in a FortiMail Browser Security console tenant. This may include:

  • providers of SIEM solutions looking to integrate with the FortiMail Browser Security console

  • FortiMail Browser Security console administrators looking for insight into how their team is accessing the FortiMail Browser Security console

  • security professionals interested in actively monitoring their FortiMail Browser Security console activity for potential security issues

Using the FortiMail Browser Security API to fetch Admin Audit Logs

You use PowerShell scripts to run the FortiMail Browser Security API calls to fetch admin audit logs. For details on how to write PowerShell scripts that authenticate with the FortiMail Browser Security console, see API [FortiMail Browser Security only].

The FortiMail Browser Security API includes the following "admin audit log" calls:

  • GET /api/admin-audit-log-entries

    This call may include the following parameters:

    • since: Limits the response to device event entries that were generated since a specified timestamp.

    • limit: Limits the number of results that can be included in the response.

    • pageToken: A token that is used to retrieve the next page of partial results.

  • GET /api/admin-audit-log-entries/{auditlogId}

Retrieving full logs using pagination - pages of partial logs

Admin audit logs can be extremely long. The FortiMail Browser Security API therefore lets you implement pagination - you can return logs that are composed of multiple pages of partial logs, that together can combine to produce the full admin audit logs. Each of these pages of partial logs is shorter and more manageable. This is achieved using a page token-based approach. For details on how to implement pagination, see API - Implementing Pagination.

Examples

Example 1: The full log

To fetch an admin audit log, use the GET ​/admin-audit-log-entries API call. For example:

inherit 
(Invoke-RestMethod -Method Get -Uri "https://console.hysolate.com/api/admin-audit-log-entries" -Headers $Headers).items

  • The entries in the returned log are sorted in chronological order - the first entry is the oldest.

Example 2: Time/date limit

The full admin audit log may be very long. You can query the admin audit log, and use the since parameter to return only those events that occurred [on or] after a specified timestamp. To add the query, add a question mark [?] to the right-end of the -Uri parameter, then add the parameter name "since", add an equal sign [=], and then specify the required date/time. For example:

inherit 
(Invoke-RestMethod -Method Get -Uri "https://console.hysolate.com/api/admin-audit-log-entries?since=2021-01-07T11:33:39.557Z" -Headers $Headers).items

  • The returned events are inclusive of the specified date/time.

Example 3:

You can fetch the details of a specific event in the admin audit log - based on the ID of the event. For example:

inherit 
Invoke-RestMethod -Method Get -Uri "https://console.hysolate.com/api/admin-audit-log-entries/60082ff597fe4891e255ec30" -Headers $Headers

Example 4: Multiple consecutive pages, each page with a quantity limit

The full audit log may be very long. You can query the log multiple times, and use the limit and pageToken parameters together, to return only a limited number of events in each consecutive query.

This approach may be useful when the output from the admin audit log API is sent to security information and event management (SIEM) tools.

The following example returns multiple pages of events. Each page can include a maximum of 100 events.

inherit 
# load $pageToken from a persistent state storage, or set to $null if missing
$pageToken = $null
 
do {
  $url = "https://console.hysolate.com/api/admin-audit-log-entries?limit=100"
  if ($null -ne $pageToken) {
    $url += "&pageToken=$pageToken"
  }
 
  $response = Invoke-RestMethod -Method Get -Uri $url -Headers $Headers
  $items = $response.items
 
  # Handle/Forward event items here
 
  $pageToken = $response.nextPageToken
​
} while ($items.Length -ne 0)
​
# store $pageToken to a persistent state storage, unless it is $null

See also: