View Gateway Audit Events

All audit events are recorded on the gateway for later viewing and troubleshooting. This topic describes the Gateway Audit Event window in detail.
gateway92
All audit events are recorded on the 
Layer7 API Gateway
 for later viewing and troubleshooting. This topic describes the Gateway Audit Event window in detail.
If you want to see logged messages for an 
individual 
Gateway node, see View Logs for the Gateway. 
Contents:
 
 
Gateway Audit Events Window
In the Policy Manager, the Gateway Audit Events window displays detailed audit messages for services, administrative, and internal system messages from the Gateway cluster. 
System audit events (those generated by the Gateway itself) are always available for viewing within the Gateway Audit Events window. Message auditing events may or may not appear, depending on the level set within the About Message Auditing.
The Gateway records audit events until the audit logs consume a predefined percentage of the hard disk space. Once this threshold is reached, all message processing ceases until the database utilization drops below the threshold. The threshold is defined in the��
audit.archiverShutdownThreshold 
cluster property, which by default is 90 percent.
The threshold does not apply to the Ping URI Test, as the pings do not use the message processing framework of the Gateway. If the Gateway and its database are reachable, the Ping URI Test always succeeds, even when all other message processing ceases.
The Gateway Audit Events window provides the following panels to let you search for the following:
  • The Audit Record Search Parameters panel lets you filter audit events that are based on various audit parameters.
  • The Entity Search Parameters panel lets you search the history of the selected entity.
  •  The Associated Logs Search Parameters lets you search based on the audit code.
These panels are collectively referred to as the "audit search panels".
The Gateway Audit Events window also lets you perform the following tasks:
  • Download audit events to an external file
  • Delete audit events more than 7 days old
  • Start the audit archiver
  • Save the audit events to review later.
The system timeout is disabled when the Gateway Audit Events window is open. For more information about the timeout, see Preferences.
 
 To open the Gateway Audit Events window, do one of the following
:
  • From the Main Menu, click [
    View
    ] > 
    Gateway Audit Events
     (on the browser client, from the 
    Monitor
     menu).
    The Gateway Audit Events window opens. Audit events from the previous session are shown by default.
  • In the Service Metrics window of the Dashboard, right-click anywhere in the moving chart and then select 
    Show Audit Events
     <
     
    time interval
     
    >.
    The Gateway Audit Events window opens loaded with the audit events from the time period selected.
 Gateway_Audit_Events.png 
Show/Hide Panels
The following panels in the Gateway Audit Events window can be hidden when not required:
  • Time Range panel plus all the audit search panels (all hidden/revealed at once)
  • Event details panel
Hide a panel when you do not need the controls in that section or if you want to increase screen space for the other panels.
 
To hide or show a panel, do any of the following
:
  • Click the appropriate arrow��image2014-10-14 16:4:48.png above the pane. It is useful to remember that the Time Range Panel hides by collapsing upward, while the Details Panel hides by collapsing downward.
  • Click [
    View
    ] > 
    Controls
     or [
    View
    ] > 
    Event Details
    .
  • Use the keyboard shortcuts [
    Alt + C
    ] (toggle Controls) or [
    Alt + E
    ] (toggle Event Details)
Source Panel
The Source panel is used to select the source of the audit records to display:
  •  
    Internal database
    : Select this to view audits that are sent to the internal Gateway database. You should select this option if you have not set up an external audit store.
  •  
    Via audit lookup policy
    : Select this to view audits that were sent to an external audit store. To use this option, ensure that an external audit store and its associate lookup policy has been correctly configured. For more information, see Manage the Audit Sink and Working with the Audit Lookup Policy.
To view or configure the lookup policy for the audit store, click [
Configure Audit Lookup Policy
] to load the lookup policy in the policy window.
When viewing audits from an audit lookup policy, the following actions are unavailable from the File menu: Download Audit Events, Delete Old Audit Events, and Start Archiver. For more information, see Gateway Audit Event Actions later in this topic.
Time Range Panel
The Time Range panel is not displayed when you view Gateway Dashboard.
The Time Range panel is used to narrow the audit events to a specified time period.
 
Setting
 
 
Description
 
 
Last x hours y minutes
 
Select this option to specify the most recent number of hours and/or minutes. All audit events that are generated within this period are eligible to be displayed.
 
Auto-Refresh
 
Specify whether the Gateway Audit Events window should refresh automatically:
  • If auto-refresh is enabled, the list of audit events updates every 3 seconds. This is shown in the "Last Updated" indicator at the bottom left corner of the window.
  • If auto-refresh is disabled, the list updates only when you press [
    F5
    ] or click [
    View
    ] > 
    Refresh
    . Disabling auto-refresh is useful when you are attempting to troubleshoot.
 
From/To
 
Select this option to choose a time range to display audits. Specify the From and To dates either by typing or by clicking  image2014-10-14 16:7:52.png and using the calendar control. Optionally modify the time, if necessary.
 
Time zone
 
If searching based on a different time zone, select it from the drop-down list.
 The results are displayed in the time zone that is selected for the search. If a non-default time zone was used, the time zone is noted next to the time in the [
Details
] tab.
Audit Record Search Parameters
The Audit Record Search Parameters panel lets you refine the audit events to display.
 
Setting
 
 
Description
 
 
Level
 
From the drop-down list, select the severity of the events displayed:
  •  
    All
    : Display events of all severity levels. Use this setting to see the system messages that are generated by the Gateway.
  •  
    Info
    : Display events rated INFO, WARNING, or SEVERE.
  •  
    Warning
    : Display events rated WARNING or SEVERE.
  •  
    Severe
    : Display only SEVERE events.
 
Service
 
Display all events from the specified service. You can use wildcards here (for an example, see the Message field).
 
Message
 
Display all events with the specified message.
Use the wildcard '*' (asterisk) character to locate messages more easily. Examples:
  • exported*
     displays all messages that begin with the word 'exported'; no match is made if 'exported' appears in the middle of the message
  • *exported*
     displays all messages with the word 'exported', regardless of its position within the message.
The search text is not case sensitive.
 
Request ID
 
Displays only audit events with the specified request identifier.
You can use wildcards here (for an example, see the Message field).
 You can use the context variable 
${requestId}
 to access the request identifier.
 
Audit Type
 
From the drop-down list, select the type of audit events to be displayed. For more information about each audit type, see About Message Auditing.
 
Node
 
Display all events from the specified node.
 
User Name
 
Displays only audit events that are caused by the user with the specified user name. This is the user name that is used to log on to to the Gateway using the Policy Manager. You can use wildcards here (for an example, see the Message field).
Note that this may return multiple users if more than one person has the same name or if wildcards are used. For example, the user with the user name "john_smith" exists on more than one configured LDAP, or you search for "*Smith*".
The user name applies as follows for each type of audit:
  • Administrative audits: The administrative user who carried out the action.
  • Policy message audits: The last authenticated user, if any.
For more information about the audit types, see About Message Auditing.
 
User ID or User DN
 
Displays only audit events that are caused by the user with the specified User ID or User DN. A User ID is used for internal users who are defined in the Internal Identity Provider. A User DN is used users who are defined in an external LDAP. Unlike user names, entering a User ID or User DN uniquely identifies a user. You may use wildcards (see the Tip in the 
Message
 field).
 See "User Name" above for information about how a user is interpreted for each audit type.
Entity Search Parameters
The Entity Type Search Parameters panel lets you optionally search the history of a selected entity. You can see everything that has happened to that entity and you can see all audits belonging to that entity.
  •  
    Entity Type
    : Choose the type of entity to search from the drop-down list.
  •  
    Entity ID
    : Enter the ID of the entity to search on.
Associated Logs Search Parameter
The Associated Logs Search Parameter panel lets you search the contents of the [Associated Log] tab at the bottom of the viewer window.
  •  
    Audit Code
    : Enter the code of the audit detail to search for. For a list of all the codes, see Audit Detail Codes.
Message Operation Search Parameter
The Message Operation Search Parameter panel lets you search for audits based on a specific SOAP operation in the message.
  •  
    Operation
    : Enter the SOAP operation to search by.
Validate Signatures
The 
Validate Signatures
 check box allows you to verify the signatures of the audits that are displayed in the Audit Events Panel.
When you select 
Validate Signatures
, validation begins immediately. The validation may require a moment to complete, depending on how many audit events were found and how many of those contain signatures. The status bar displays: "Signature validation is on" and the Audit Events Panel displays "Signature validation is on [
In Progress
]" to indicate that verification is in progress. "[
In Progress
]" is cleared when all audit records in the search result have been validated. While verification is in progress, you can manually clear this check box to suspend signature validation and reselect it to resume.
When signature validation is on, the "Sig" column of the Audit Events Panel displays the appropriate icon as each audit is verified. For a description of each icon, see the "Sig" column.
The Validate Signatures check box is available only when there is a connection to the Gateway. Validating signatures may impact Gateway performance if audit records for the time period contain large request or response messages or large audit details.
The Validate Signature check box is automatically cleared when you perform a new search. It is also cleared when the Gateway Audit Events window is opened. This ensures that validation occurs only when you explicitly select the check box.
Audit Events Panel
The audit events panel displays the events for the given time period or filter criteria once [
Search
] is clicked. To help you analyze the events, you can click a column heading to re-sort the list based on that column.
To clear all search text fields and reset all the drop-down lists to their default settings, click [
Clear Search Criteria
].
To cancel a search in progress, click [
Cancel
].  
When a search filter is in effect, the following message displays above the Audit Events Panel to indicate that only a subset of records is being shown: "Caution! Constraint may exclude some events." Audit events are displayed only if you have Read permission for "<Any Cluster Node Information>". Some predefined roles (such as "Manage X Service") include this permission. Custom roles may also include this permission.
 
Column Name
 
 
Description
 
 
Sig
 
Indicates the signature status of the audit record:
  • Red
    : Audit record is signed, but the signature cannot be verified. This may indicate tampering of the audit record. This may also indicate that the default SSL key that is used to sign the audit record is an ECC key. The Gateway does not support ECC keys.
  • Yellow
    : Audit signing is enabled, but the audit record is not signed.
  • Green (check mark)
    : Audit record is signed and the signature is valid.
  • Green (down arrow)
    : Audit record is signed, but the signature was not validated because the message exceeds 2.5MB in size.
  • No symbol
    : Audit signing is disabled and the audit record is not signed.
Audit signing is controlled by the audit.signing cluster property.
 
AuditRecord
 
Displays the internal audit record number. This number is useful when an audit record refers to another audit record by ID and you want to find that other audit record.
Node
 
Displays the Gateway node that the event applies to.
Time
 
Displays the time that the event took place in the Gateway. This time is displayed in the time zone that is selected for the search (if not searching by date then the time is displayed in the default time zone). Note that if a non-default time zone is selected, this is not displayed in the event listing but is displayed in the [
Details
] tab.
Severity
 
Displays the severity rating for the event, as assigned by the Gateway.
  • FINE
    FINER
    FINEST
    : Internal system messages from the Gateway.
  • INFO
    : Reasonably significant informational messages.
  • WARNING
    : Indicates a potential problem.
  • SEVERE
    : Indicates a serious failure that requires immediate attention.
 It is possible to override the severity of the Gateway audit messages, to help you exclude certain material from appearing in the audits. For more information, see Override the Audit Level later in this topic.
Note that the events that are displayed depend on the Time Range and Audit Record Search Parameters.
Service
 
The service that generated the event, if any.
 
Message
 
The actual event message.
Event Details Panel
Select an audit event to see detailed information about the event.
Tab
 
Description
 
Details
 
Displays detailed information about the audit event.
Associated Logs
 
Displays any associated logs for the event, if applicable. All audit codes from "The table below lists all the audit messages that are used by the Gateway when reporting audit events. These messages are organized into the following high-level groupings.
  • The Code column shows the associated cluster property. It is also help if you want to reduce the runtime audit level so that the code no longer appears here (see Override the Audit Level).
  • The Detail column displays a button if there are further details about the event that are too large to display in a tooltip. Clicking this button displays comprehensive log information in a new window. If the details are protected by an Audit Message Filter policy and your role permits it, click [
    Invoke Audit Viewer Policy
    ] to invoke the Audit Viewer policy for the audit detail.
  • Messages may convert non-identifiable characters into a string literal of their Unicode value. For example, if "null" is being expressed in a message, it is displayed as "\u0000", which is the Unicode representation for null.
Request 
 
Displays the request message that is received by the Gateway after any required message processing (for example, WS-Security). Selecting 
Reformat Request XML
 reformats the message for improved readability if XML.
If the details are protected by an Audit Message Filter policy and your role permits it, clicking [
Invoke Audit Viewer Policy
] invokes the Audit Viewer policy for the audit detail.
 You can see the request message only if the Save request option is enabled in the Audit Messages in Policy Assertion.
 
Response 
 
Displays the response message. Select 
Reformat Response XML
 to reformat the message for improved readability if XML.
If the details are protected by an Audit Message Filter policy and your role permits it, clicking [
Invoke Audit Viewer Policy
] invokes the Audit Viewer policy for the audit detail.
 You can see the response message only if the Save response option is enabled in the Audit Messages in Policy Assertion.
 
Total
 
 
(bottom of window)
 
Displays the total number of records that are returned for a search. If there are many records, the Gateway Audit Events window displays "(truncated)" next to the total number.  
If auto-fresh is enabled, the "(truncated)" label disappears when new records arrive, even though the display is still truncated.
Last Updated
 
(bottom of window)
 
Displays when the log was last updated. When the Gateway Audit Events window is opened from the Service Metrics window of the Dashboard, the time range from the selected bar is displayed here instead.
Audit Viewer Policy
Information in the [
Associated Logs
], [
Request
], or [
Response
] tabs may be protected by the Audit Message Filter policy, if one was used to encrypt them. Click [
Invoke Audit Viewer Policy
] to invoke the Audit Viewer policy for the audit record or detail. The output of the Audit Viewer policy is displayed in place of the original text. For more information about the Audit Message Filter and Audit Viewer policies, see Internal Use Policies.
Only users with the role "Invoke Audit Viewer Policy" can invoke this policy via the audit viewer. For all other roles, the [
Invoke Audit Viewer Policy
] button is unavailable. For more information about security roles, see Private Key Properties.
Gateway Audit Event Actions
While the Gateway Audit Events window is primarily for display, you can perform the following actions:
Download Audit Events
The Download Audit Events option is not available when the Gateway Audit Events window is opened from the Service Metrics window of the Gateway Dashboard. In the browser client version of the Policy Manager, downloading is possible only when the Java applet is running in the trusted mode.
 
To download audit events in the database to an external file
:
  1. From the Gateway Audit Events window, select [
    File
    ] > 
    Download Audit Events
    .
    The Download Audit Events window appears.
  2. Specify the Time Range for audit events to be downloaded: All:
    • Download all audit events in the database.
    •  
      From/To
      : Download only those events that fall within the time range. You can either type the time values or click to select the date from the calendar control. You can also change the time zone if necessary.
  3. Specify the Published Services to be included:
    •  
      All
      : Include all services. This option includes all the system events that are automatically generated.
    •  
      Selected
      : Select one or more services to include (hold down the [Ctrl] key to select multiple services).
  4. Do one of the following to specify the destination file:
    • Type the full path and name of the file.
    • Click [
      Browse
      ] and then navigate to the target location, then enter a file name.
    The system adds the ".zip" extension to the file name for you.  
  5. Click [
    Download
    ]. The audit events are saved to the specified zip file.
  6. Click [
    Close
    ] when done.
    The audit events are saved as a colon-delimited text file within a zip file. The file is accompanied by a digitally signed XML file containing checksum and metadata information about the exported audit records. The XML file is signed using the Gateway's SSL certificate.
Delete Audit Events
 The Delete Old Audit Events option is not available when the Gateway Audit Events window is opened from the Service Metrics window of the Gateway Dashboard.
It is recommended that you purge old audit records periodically to free up hard disk space and to prevent performance issues. By default, the Policy Manager purges all non-SEVERE audit records older than seven days. Audit events marked “SEVERE” are never removed, regardless of age. 
Tip:
 You can adjust the minimum age for purging with the 
audit.purgeMinimumAge
 cluster property.
 
To delete audit events:
 
  1. From the Gateway Audit Events window, select 
    [File] > Delete Old Audit Events
    .
  2. Click [
    Delete Events
    ] when prompted to confirm.
    Deletion occurs in the background, so that you can keep working. An audit event is created immediately and refreshes itself after every 10,000 events are deleted. This lets you monitor the progress of the deletion.
    If the deletion is interrupted before it is complete (for example, a system failure occurs), the audit event shows the number of events that are purged up to that point. When the system restarts, run Delete Old Audit Events again to finish the purge.  
Start Archiver
 The Start Archiver option is not available when the Gateway Audit Events window is opened from the Service Metrics window of the Gateway Dashboard.
Start Archiver manually starts the audit archiver if it is not already running,using the settings from Configure FTP Audit Archiver. The status of the archive is displayed on the Audit Events window.
This manual archive does not affect the scheduled archive task. For example, the default as specified by the 
audit.archiverTimerPeriod
 cluster property is to archive every 10 minutes. This occurs regardless of how many manual archive requests were made.
Save Displayed Events
 In the browser client version of the Policy Manager, saving displayed events is possible only when the Java applet is running in the trusted mode.
Ensure that the events you wish to save a currently visible. Data that is filtered out is not saved.
 
To save the currently displayed audit events:
 
  1. From the Gateway Audit Events window, select [
    File
    ] > 
    Save as
    .
  2. Specify a file name and location or accept the defaults that are shown.
    Accepting the suggested file name makes it easier to sort and organize your saved events. Be sure to preserve the ".ssga" file extension
  3. Click [
    Save
    ].
     Saved audit events do not include the time zone. This means that when the events are viewed, they are displayed in the default time zone.
 
To view the saved events:
 
  • See "Saved Events" below.
Saved Events
You can view saved events even when not connected to the Gateway.
 
To view saved audit events:
 
  1. From the Policy Manager Main Menu, click [
    View
    ] > 
    Saved Events
     (on the browser client, from the Monitor menu).
  2. Navigate to the appropriate ".ssga" file.
  3. Click [
    Open
    ].
    The saved audit events are displayed. You can view and filter the saved events in the same manner as live events.  
 The saved data uses the node names that were in effect at the time of saving. This may differ from node names currently in use.
Override the Audit Level
It is possible to change the severity of audit messages at run time to suit your needs. For example, you are finding that the auditing system is flagging material that you do not wish to appear in the audit logs. To solve this, identify the messages to suppress and then reassign them to a lower severity level to prevent them from being logged.
The following cluster properties are used to override audit levels:
  • audit.setDetailLevel.SEVERE
     
  • audit.setDetailLevel.WARNING
     
  • audit.setDetailLevel.INFO
     
  • audit.setDetailLevel.CONFIG
     
  • audit.setDetailLevel.FINE
     
  • audit.setDetailLevel.FINER
     
  • audit.setDetailLevel.FINEST
     
  • audit.auditDetailExcludeList
     
Add the number of the audit detail code to the appropriate property to reassign the code to that level. Separate multiple codes with spaces. If a code appears in more than one property, the higher audit level takes precedence.
 
  • Overriding an audit level only changes the severity at run time. It does not change the level of the audit when displayed in the Gateway Audit Events window.
  • The 
    audit.setDetailLevel.* 
    cluster properties are hidden and not selected from the drop-down list in Manage Cluster-Wide Properties. To use them, manually type the name in the Key field of the dialog.
  • Overriding an audit level only does not determine whether a messaged is logged or not. For more information, see Policy Message Audits.
  • Codes entered into the property 
    audit.auditDetailExcludeList
     are excluded from auditing.