Introduction
Our Log Extraction API enables customers to programmatically retrieve audit log data from their organization.
Use
To invoke the API, a set of commands is posted to an Authentic8 API host via https.
The Authentic8 API server is: extapi.authentic8.com
JSON structures should be POSTed to: https://extapi.authentic8.com/api/
The POST Content-Type should be application/json.
The commands are in the form of a JSON array of objects; each object should have a “command” item; the rest are arguments to the command:
[
{ “command”: <command>, “arg1”: <value>, “arg2”: <value> },
[...]
{ “command”: <command>, “arg1”: <value>, “arg2”: <value> }
]
The return is a JSON array of responses, one per command. The responses will be returned in the order that the commands were sent. All commands will accept a “command_id” argument; if present, this id will be present in the response for that command.
Auth Token
An Authentication Token is a security credential required for programmatic access to Authentic8 API. Auth tokens are issued by Authentic8's Support team by request, and can be assigned to an existing Admin or Service account. The scope of the API operation will be restricted to the assigned user account's level of permission, along with the intended log extraction role of the API auth token. This helps prevent inadvertent org changes with a Log Extraction API token, such as, user deletion or similar.
Org names
Org names within the Authentic8 system are not required to be unique -- however, they are required to be unique within a single parent org structure. In most cases, this will not be an issue; a simple org name is acceptable as long as it is not ambiguous relative to the Admin specified in the auth token. If there is ambiguity, an org path may be specified.
Org paths are slash-separated org names (slashes may be escaped by backslash if there is a slash in an org name). Org paths do not need to be complete; each element only needs to disambiguate the next element, so elements may be skipped.
Log Extraction
Commands
setauth
arguments: data
Sets the authorization token to be used in subsequent API commands. An authorization token must be present and must be the first command in the JSON array of commands sent to the API (see the Examples section for a sample).
extractlog
arguments: start_seq end_seq org type limit
Extracts log data of type for the referenced org.
start_seq and optional end_seq can be used to retrieve subsets of the log data. start_seq of 0 and no end_seq will return all available log data.
A max value of 1,000 log items will be returned per request. In the response, there is a boolean, is_more, and a number, next_seq, which will let you page through the results when there are more than can be returned in a single request. If you prefer fewer log lines per request, you can set the limit argument to the request to a number.
The Authentic8 API allows extraction of the following log types:
Type | Description |
|
|
|
|
|
Note: ONLY logged if using log encryption |
|
|
|
|
|
Note: ONLY logged if using log encryption |
|
|
|
Note: When encryption is enabled, discrimination between different log types is not possible during extraction, since logs are encrypted with the customer’s public key. The customer will be able to identify log types in the decrypted data. |
|
|
|
|
|
Note: Also tracks Google.com searches when Enter/Return key submitted on the search form |
|
|
|
|
The results will include the next_seq and is_more fields to help identify the last logs retrieved. If is_more is false, that means there are no more logs that fit the criteria at the moment of the request. More may appear at any moment.
If extracting ENC log type, the results will include the customer assigned key_name to help identify the public key that was used to encrypt the logs.
Examples
A sample of commands with responses.
[
{"command": "setauth", "data": "<AuthToken>"},
{"command": "extractlog", "start_seq": 0, "org": "<OrgName>", "type": "ENC"}
]
Results
{
"next_seq": 3233683,
"logs": [
{
"key_name": "SILOTest",
"enc": "AegpLEeh9mseUW8Gc7eop03cZ/9kLiHtvSHClOUop4DR/PRMIGXmiFATlI7/O2pK1ZxT69KLoxNzpvvgXCgYSEENRZKoVLJknGGVSbMK/NhjKFOXxdxMrLNFijJTsJ2qICt/2EkSRLxbFjXiSAEGBLmFqqq3gt3Je4flo9mpRViNxWHmYY8L4KPbHKYbp8AJeCcjWlldvnRTlXh/biKbBu9Cn85TbyUak+MVmPofKHjYAj0KivPd2DsISGSV0RRw2gY5ymIDLoNaS4wchMQUmwxo3duHF+r+L0GXo4fkgRrR360c4TQ7qA2HykQT",
"type": "ENC",
"create_ts": 1407538630.06108,
"seq_id": 3233682
}
],
"is_more": false
}
Note that the fields that get returned are different, depending on the type of logs getting pulled:
[
{"command": "setauth", "data": "<AuthToken>"},
{"command": "extractlog", "start_seq": 0, "org": "<OrgName>", "type": "URL"}
]
returns:
{
"next_seq": 3204202,
"logs": [
{
"domain": "www.java.com",
"user_id": "466...3d4",
"response_headers": "Server: Sun-Java-System-Web-Server/7.0\r\nContent-Type: text/html;charset=UTF-8\r\nContent-Encoding: gzip\r\nVary: accept-encoding\r\nContent-Length: 2516\r\nDate: Tue, 01 Jul 2014 20:19:33 GMT\r\nConnection: keep-alive\r\n",
"seq_id": 3204201,
"response_code": 200,
"org_id": "509...0c0",
"session_id": "399...aa9",
"headers": "Host: www.java.com\r\nUser-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:29.0) Gecko/20100101 Firefox/29.0 Authentic8/1.0\r\nAccept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8\r\nAccept-Language: en-US,en;q=0.5\r\nAccept-Encoding: gzip, deflate\r\nDNT: 1\r\nConnection: keep-alive\r\n",
"create_ts": 1404245973.396193,
"response_size": 2516,
"path": "/en/download/installed.jsp",
"scheme": "http",
"type": "URL"
}, ...
],
"is_more": true
}
Additional Notes
Please contact Support if you have any additional questions and/or require further information.