exportSecurityAudit
Supported in API v20 +
Category |
Data retrieval |
Description |
Returns a report of all security events in a specified time range, filterable by event type. Security events include unsuccessful login attempts, password changes, account lockout, account creation, and other security related information. If no time range is requested, all events from the last 24 hours return. Security events recorded by the audit log are based on NIST 800-53. Adaptive Insights only keeps 30 days of audit trail data. |
Permissions Required To Invoke |
Administrator |
Parameters Required On Request |
Credentials |
This method's request contains a credentials tag to identify and authorize the calling user, and an include tag identifying the actor and time range to retrieve security events for. Once verified, the method returns an XML document describing all security events in the specified time range, filterable by event type.
Request Format
<?xml version='1.0' encoding='UTF-8'?> <call method="exportSecurityAudit" callerName="a string that identifies your client application"> <credentials login="sampleuser@company.com" password="my_pwd"/> <include actor="stevec@greenco.com" dateTimeFrom="2019-07-30 00:00:00" dateTimeTo="2019-07-30 11:59:59"/> </call>
credentials element |
|||
Tag Name |
credentials |
||
Description |
All API calls must contain a single credentials element to identify the user invoking the API. The API call is then performed as this user (any audit trail or history of actions in the system will show that this user performed the action), and therefore the user must have the required permissions to perform the action in order for the API call to succeed. |
||
Attributes of the Element |
|||
Attribute Name |
Required? |
Value |
Example |
login |
Y |
The login name of the user invoking the API method. This user must have a role containing the permissions required for the method being invoked. |
sampleuser@company.com |
password |
Y |
The password of the user invoking the API method. |
my_password |
Contents of the Element |
|||
none |
include element |
|||
Tag Name |
include |
||
Description |
|
||
Attributes of the Element |
|||
Attribute Name |
Required? |
Value |
Example |
actor |
N |
The username whose security events you want to retrieve. Returns events for all users when actor is not included. |
stevec@greenco.com |
dateTimeFrom |
N |
The start of the time range in ISO-8601 compatible format (YYYY-MM-DDTHH:MM:SS) in UTC for the security events you want to retrieve. |
2019-07-30 00:00:00 |
dateTimeTo |
N |
The end of the time range in ISO-8601 compatible format (YYYY-MM-DDTHH:MM:SS) in UTC for the security events you want to retrieve. |
2019-07-30 11:59:59 |
Contents of the Element |
|||
none |
Response Format
<?xml version='1.0' encoding='UTF-8'?> <response success="true"> <output> <audit> <event timestamp="2019-07-30 01:59:48.7781" action="SUC" actor="475245454E434F000000000001000004" version="20" interface="" object="User - 475245454E434F000000000001000004" outcome="0" context="" /> <event timestamp="2019-07-30 01:59:48.9822" action="SUC" actor="475245454E434F000000000001000004" version="20" interface="" object="User - 475245454E434F000000000001000004" outcome="0" context="" /> <event timestamp="2019-07-30 02:01:29.115" action="SUC" actor="475245454E434F000000000001000004" version="20" interface="" object="User - 475245454E434F000000000001000004" outcome="0" context="" /> <event timestamp="2019-07-30 02:02:03.0594" action="SUC" actor="475245454E434F000000000001000004" version="20" interface="" object="User - 475245454E434F000000000001000004" outcome="0" context="" /> <event timestamp="2019-07-30 02:06:35.8937" action="SUC" actor="475245454E434F000000000001000004" version="20" interface="" object="User - 475245454E434F000000000001000004" outcome="0" context="" /> <event timestamp="2019-07-30 02:06:36.0589" action="SUC" actor="475245454E434F000000000001000004" version="20" interface="" object="User - 475245454E434F000000000001000004" outcome="0" context="" /> <event timestamp="2019-07-30 02:06:36.1219" action="SUC" actor="475245454E434F000000000001000004" version="20" interface="" object="User - 475245454E434F000000000001000004" outcome="0" context="" /> <event timestamp="2019-07-30 02:06:59.8724" action="SUC" actor="475245454E434F000000000001000004" version="20" interface="" object="User - 475245454E434F000000000001000004" outcome="0" context="" /> <event timestamp="2019-07-30 02:07:36.5505" action="SUC" actor="475245454E434F000000000001000004" version="20" interface="" object="User - 475245454E434F000000000001000004" outcome="0" context="" /> <event timestamp="2019-07-30 02:07:37.8862" action="SUC" actor="475245454E434F000000000001000004" version="20" interface="" object="User - 475245454E434F000000000001000004" outcome="0" context="" /> <event timestamp="2019-07-30 02:08:06.7037" action="SUC" actor="475245454E434F000000000001000004" version="20" interface="" object="User - 475245454E434F000000000001000004" outcome="0" context="" /> <event timestamp="2019-07-30 02:08:10.4557" action="SUC" actor="475245454E434F000000000001000004" version="20" interface="" object="User - 475245454E434F000000000001000004" outcome="0" context="" /> <event timestamp="2019-07-30 02:08:14.8878" action="SUC" actor="475245454E434F000000000001000004" version="20" interface="" object="User - 475245454E434F000000000001000004" outcome="0" context="" /> </audit> </output> </response>
response element |
|||
Tag Name |
response |
||
Attributes of the Element |
|||
Attribute Name |
Required? |
Value |
Example |
success |
Y |
Either true or false, indicating whether the API call was successful or not. Even successful calls may contain warning messages in their response. |
true |
obsolete |
N |
If present on the response tag and set to true, this attribute indicates that the version of the method or API which is being invoked has become obsolete and is officially deprecated by Adaptive Insights. While it continues to function at this time, it may cease functioning in a short while. Typically, this attribute is not present. |
false |
Contents of the Element |
|||
A single optional messages element, and exactly one required output element. |
output element |
|
Tag Name |
output |
Attributes of the Element |
|
(none) |
|
Contents of the Element |
|
A single audit element. This output wrapper is standard on all API responses and encloses the valid output of any successful API call. |
audit element |
|||
Tag Name |
audit |
||
Description | A collection of security events. | ||
Attributes of the Element |
|||
(none) |
|
|
|
Contents of the Element |
|||
One or more event elements. |
event element |
|||
Tag Name |
event |
||
Description | A security event. | ||
Attributes of the Element |
|||
Attribute Name |
Required? |
Value |
Example |
timestamp |
Y |
The timestamp in ISO-8601 compatible format |
2019-07-30 01:59:48.7781 |
action | Y |
The action that triggered the audit event:
|
SUC |
actor | Y | ID of the actor (service, user, system user) that initiated the operation triggering the event (NULL if no particular user can be assigned). | 475245454E434F000000000001000004 |
version | Y | The version of the software used to perform the action. | 21 |
interface | N | The interface (API, UI, or URI) triggering the audit event. | API |
object | N | The system object triggering the audit event. | User - 475245454E434F000000000001000004 |
outcome | Y | The success or failure of the action. 0 indicates success, 1 indicates failure. | 0 |
context | N | System specific information about the audit event. | |
Contents of the Element |
|||
(none) |