How to: Use API calls to access the BIG-IP Next Central Manager audit logs¶

Summary¶

As a central management system, the BIG-IP Next Central Manager tracks the operations performed on the system. This tracking makes it possible for you to know which users accessed the system, when the system was accessed, and which operations were executed. The system feature that provides this tracking capability is called the audit log.

Audit log entries are written to persistent storage, so they survive system failures and restarts. To access these audit logs, you use an API call to the BIG-IP Next Central Manager.

The BIG-IP Next Central Manager also aggregates application log entries. These log entries are generated by the various microservices that make up the application. For information on how to access these logs refer to Access the BIG-IP Next Central Manager application logs.

The following procedures provide example API calls using the curl HTTP client. To submit your own API calls, use any HTTP client (for example, Postman), and ensure that you observe the syntax outlined in the example API calls.

Prerequisites¶

You need to know the management IP address used to access the BIG-IP Next Central Manager for which you want to view log entries.
You need to know the admin user name and password configured for the BIG-IP Next Central Manager on which you want to examine log entries.

Audit log events¶

The following is a list of events that trigger an audit log entry. You can retrieve these events using the correct, REST API call.

Login to the BIG-IP Next Central Manager
Logout of the BIG-IP Next Central Manager
Any REST request that creates, modifies, or deletes data: (including POST, PUT, and DELETE requests).
Any request that fails due to authentication or authorization problems. That is, the request resulted in either an unauthorized (401) or forbidden (403) response code.

Most Audit log entries include the identity of the user who performed the request. An exception to this can occur if a request fails because the user identity was not provided.

Procedures¶

Access the BIG-IP Next Central Manager audit logs
Audit log properties and descriptions

Access the BIG-IP Next Central Manager audit logs¶

Use the following procedure to access the audit logs for BIG-IP Next Central Manager. To retrieve the audit logs, you use a REST API call. All API calls to the BIG-IP Next Central Manager must be authenticated using an access token (or bearer token). To get an access token, you need the IP address of the BIG-IP Next Central Manager as well as the admin login credentials. Use the syntax shown in the following example:

Send a Post to the /api/login endpoint.

POST https://<big-ip_next_cm_mgmt_ip>/api/login

For the API body, use the following, substituting the username and password for the BIG-IP Next Central Manager you are accessing.

{

"username": "admin",

"password": "admin"

}

Response:

{
 "access_token": "+42Cvb6we9wsgqDtJLZHMHZ2lAk9LYR5/w+rMvTkPvm5KVJbe9Pvzg0Tdg+F7Vis4CRNAxsPStHP9cSn7lRONWPB+IA4HGJuJWAHtXyWfwvTeMakA36CqhlZKACfgukLEvj0u5IBzNFAL3vdniPDmvJIL9HpGkNyCIVrKGE7rrmAdiyOP6x01WjTILSlM2m26/cfheF04U8q8uzygMUXBLdAkNkVziBkTTwzMnQkTmAqTxhrSsaktS9FYbfeuul3mA602IiaWlT8noewxZ5bu3pehI18Ckyh3IXX7GpfcmCmgmWUA5r9Zif2URn5Lp57kfnWK4kzw/LVvX5dZ6VD2YN+MSTuYAAd1lflFLFmGlWK/LEA/4MaMGU2+LWBo7vyvv+ur7837pKNjwKtQ9uZBNDfaAsrz2eXAa+AXp92dxrTspTY4I8gZnUTGc7k36iDxJW5t9/Ja3Qyold8y/F/t4vzIZvPSK5u/ivkcfbfvC0JUPP2+f5OpCmVng4FC6fqOF8p+zo9",
 "refresh_token": "+42Cvb6we9wsgqDtJLZHMHZ2lAk9LYR5/w+rMvTkPvm5KVJbe9Pvzg0Tdg+F7Vis4CRNAxsPStHP9cSn7lRONWPB+IA4HGJuJWAHtXyWfwvTeMakA36CplRaKDKfgvkLEvj0u5IBzNFAL3vdniPDmvJIL9HqGkNyCIVrKGE7rrmAdiyOP6x01WjTILSlM2m26/cfheF04U8q8uzygcUXBLdAkNkVziBkTTwzMnQkTmN0WCV3SMSntndFW7aCrsdZ1A602ImNc1T8iK2gxZ1hu35Kg7BsHmWl3pP57G9IZUKmgmWUA5r9Zif2URn5Lp57kfnWK4kzw/LVvX5dZ6VD2YN+MSTuYAAd1lflFLFmGlWK/LEA/4MaMGU2+LWBo7vyreeb0oEx1pCzggmoCNjuHaaWCw1J+FCPLrvrJZNfQUO7+Nb5+9NFclIxBIz1x6rS7biJxdrjeHgIgx9UlZlcz8qpF+nbE79K0ijXPorNlAMuBPyM5ti7buodAxh2BcJYNuf+IVhI"
}

Using the bearer token (or access token), submit a command similar to the following to the BIG-IP Next Central Manager BIG-IP Next Central Manager:

   curl -sk -H "Authorization: Bearer <bearer token>" https://<BIG-IP Next Central Manager IP address>/api/system/v1/logs/audit

Where <bearer token> is the random string you retrieved in the first step, and <BIG-IP Next Central Manager IP address> is the management IP address of the BIG-IP Next Central Manager you are trying to view audit logs for.

The BIG-IP Next Central Manager responds by sending the audit log entries for the BIG-IP Next Central Manager targeted in your command. Each response will contain as many fields as appropriate for that particular audit log entry.

Note: If you use an HTTP client (like Postman) to submit your audit log command, each audit log entry will be nicely parsed and formatted similar to what is shown below.

{
 "action": "user login",
 "duration_ms": 157,
 "endpoint": "login",
 "feature": "gateway",
 "http_method": "GET",
 "level": "info",
 "msg": "",
 "result_code": 200,
 "source_addr": "10.10.10.10",
 "timestamp": "2021-12-08T18:07:48.839858Z",
 "url": "/login",
 "user": "admin",
 "user_id": "7aef5f9c-5af1-4ec8-a58f-6d597309ada4"
}

Otherwise, the response displays as a long chunk of content on your screen. If there are hundreds of audit events and the BIG-IP Next Central Manager returns all of the audit log entries in one response, you might find it very challenging to read the response. To avoid this issue, consider limiting the number of responses. For more information, refer to Limit the number of audit log responses (below).

To understand the meaning of the audit log responses, refer to Audit log properties and descriptions.

Limit the number of audit log responses¶

You might find it useful to use a switch that limits the number of audit logs that the BIG-IP Next Central Manager returns in response to your command. Without this limit, BIG-IP Next Central Manager displays the last 1000 audit log entries (or all of the entries if there are less than a 1000).

If you have a BIG-IP Next Central Manager that’s been live for a while, you probably only want to see a small subset of these entries. To use this limit, just add ?limit=<number of entries> to your command.

For example, to limit the response in the previous example to the last 10 audit log entries, you would append ?limit=10 to the command, like this:

   curl -sk -H "Authorization: Bearer <bearer token>" https://<BIG-IP Next Central Manager IP address>/api/v1/logs/audit?limit=10

In response to this command, the BIG-IP Next Central Manager returns only the last 10 audit log entries.

Audit log properties and descriptions¶

Properties that can trigger audit log entries for BIG-IP Next Central Manager are described in the following table.

Property Name	Description	Example Values
`action`	A brief label describing the high-level contextual action being performed.	"login" (the API is a REST GET request, but the actual action is login)
`duration_ms`	The number of milliseconds it took to complete the operation that triggered the event.
`feature`	The target feature that handled the request.	"system-feature"
`http_method`	The HTTP verb used in the request.	"POST"
`result_code`	HTTP result code	404
`request`	The body of the request.	"{"username": "John Doe","password" : "******"}"
`source_address`	The IP address of the client (for example, the user's laptop) that initiated the request.	"10.10.10.1"
`timestamp`	The time stamp (in UTC format) when the event was logged.	"2021-08-11T22:26:11.9907972Z" (if we don't set the Gateway's time zone) "2021-08-11T15:26:11.9907972-0700" (if we set Gateway's time zone)
`user`	The username of the user who initiated the request.	"admin" or the user's UUID string.
`user_id`	The UUID is always present, except for login failures or unauthenticated requests.

Previous Next