SIEM Integration

Configure a user role in Settings → Roles that will be able to manage API bearer tokens - there are 3 permissions associated with the viewing, creation, and deletion of tokens:

API Token Management

In order to export system logs, a token must be created that also has it’s own permission assigned. This token specifically will need to be associated to a “Role” with one permission only:

External APIs:

A great role to use as an example can be seen below - it should have a descriptive role name highlighting that it is meant for API Bearer Tokens, and it should have only one permission (Export Logs):

Provided that the user is now in a role that is capable of managing API Bearer Tokens (at least has the permission to View API Tokens), the user can now access the page to manage tokens by navigating to Settings → Security → API Bearer Tokens:

The screenshot above is the view for a user that has full permissions (Create API Tokens, Delete API Tokens, View API Tokens). There is a “Create Token” button in the top right to open the dialog for creating a new token (this button being present is dependent on the permission - Create API Tokens). There is also a small red trash icon on the far right column of the “Delete Me” example token (this icon being present is dependent on the permission - Delete API Tokens).

To create a new token the user will click “Create Token” and the dialog below will open. The user MUST at least define a unique “Token Name” and a “Role” for the token (make sure you use an API Bearer Token specific role, like mentioned in Step 3). The user can also give the token a “Description”, which is recommended for keeping track of a token’s use case.

Once the token is created (after configuring the token and clicking “Create Token”), there will be another view that appears with the new created token.

VERY IMPORTANT: This new view will be the only time the token is available, it should be stored securely for use before closing this dialog. Once the dialog is closed, you cannot recover the unique token again. If the token string is lost or not stored securely, the user would have to delete this token and start over to create another token. There are two options for copying the token with a single click that are outlined in the image below:

Now that everything is configured, and the token itself has been stored securely for use, it can be used to export system logs. The external API url that will be used with this token is https://app.govworx.net/api/v1/external/logs. The authorization will be Bearer {insert token here}. The default return for this API is going to be an array of system log entries from the last 24 hours with a limit of 1,000 entries. At the end of the array will be a pagination object for letting the external system know if there are more records than what was returned. If there are more than 1,000 entries, then timestamp-based pagination will suggest the next date to query from to get the next “batch” (explained more in detail below). Below are the parameters used to further filter log records as desired:

Query Parameters:

Default response body JSON:

NOTE: "data" will contain an array of logs, where each object inside of it is a separate log entry, each with it’s own unique "id" number.

Timestamp-Based Pagination Example:

Default pagination JSON:

Say the user queried from a time period that had exactly 21 records. As expected (because there is no defined limit parameter), all 21 records are returned. Also, the “truncated” value is false because we were able to return all of the records under the default parameters.

Now, after adding a query parameter limit of 20 (?limit=20), the value for “truncated” is true because we have 21 records and our limit of 20 “cut off” one record. The result of the truncated field being true has created a value for suggestedNextFrom . This is the timestamp we need to add as a from parameter to get that next “batch” of records.

Now if the query is changed with from being the "suggestedNextFrom" (still with the limit of 20), it will return that last record. Also the value for truncated has gone back to false and there is no suggestedNextFrom, meaning that all records have been retrieved.

Going back to the permissions for the user that were discussed earlier, if the user has delete permissions, then they can delete tokens in the UI. Tokens that are deleted then become deprecated and can no longer be used to access system logs externally. The steps below show the process of deleting bearer tokens: