Skip to main content

logoCorrectSize.png

Adaptive Insights LLC.

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
(YYYY-MM-DDTHH:MM:SS.sssZ) in UTC
of the event

2019-07-30 01:59:48.7781

action Y

The action that triggered the audit event:

  • 'CRE' Account creation
  • 'DIS' Account disabled
  • 'LOK' Account lockout
  • 'UOK' Account unlock
  • 'USC' Unsuccessful login
  • 'SUC' Successful login
  • 'ULO' User logout
  • 'PWC' User password change
  • 'TER' Session termination due to exceptions
  • 'EXP' Session expiration
  • 'CRD' Credential changes
  • 'AUT' Changes to authentication configuration
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) 

  • Was this article helpful?