Enterprise Threat Protector Reporting API Data

Enterprise Threat Protector report JSON data follows these overall conventions:

  • Total responses are arranged as an array of event count data.
  • Detail responses are arranged as an array of event detail data.
  • TimeSeries responses are arranged as an array of time series data.

The data schema tables below list membership requirements as follows:

Member is required to be present, regardless of whether the value is empty or null.
Member is optional, and may be omitted in some cases.

Filter

The filter JSON object allows you to specify values of certain data types to include or exclude from your report. You must provide this object as the filter parameter and not in the body of the request. For example, you can target historical config details for a specific domain, while excluding certain actions that are not relevant to the target report data.

Sample GET:

{
   "action":{
      "in":[
         "1"
      ]
   },
   "isAlert":{
      "in":[
         "true"
      ]
   },
   "asn":{
      "in":[
         "24940"
      ]
   },
   "site":{
      "in":[
         "-1"
      ]
   },
   "list":{
      "in":[
         "1"
      ]
   },
   "policy":{
      "in":[
         "164"
      ]
   },
   "category":{
      "in":[
         "1"
      ]
   },
   "domain":{
      "in":[
         "njit.edu."
      ]
   }
}

Filter Members

Member Type Description
action String JSON criteria object representing in and not-in clauses for action.
asn String JSON criteria object representing in and not-in clauses for autonomous serial number.
category String JSON criteria object representing in and not-in clauses for category.
country String JSON criteria object representing in and not-in clauses for country.
destinationIp String JSON criteria object representing in and not-in clauses for destination IP.
detectedBy String JSON criteria object representing in and not-in clauses for detected by.
detectionType String JSON criteria object representing in and not-in clauses for detection type.
domain String JSON criteria object representing in and not-in clauses for domain.
list String JSON criteria object representing in and not-in clauses for list.
policy String JSON criteria object representing in and not-in clauses for policy.
site String JSON criteria object representing in and not-in clauses for site. A site ID of -1 points to the roaming location.

Filter.* Members

Member Type Description
in Array An array of strings containing unique identifiers for any filter parameter to include in the report.
nin Array An array of strings containing unique identifiers for any filter parameter to exclude in the report.

Download the JSON schemas for this API.

Total

Encapsulates information about an aggregated list of events or traffic for the given time period.

Download schema: total.json

Sample GET:

{
    "id": "564",
    "name": "BOS-HQ-Corp",
    "total": 26
}

Total Members

Member Type Description
id String A unique identifier for the column object.
name String A descriptive name for the column identifier.
total Integer The total count of security events for the given time period.

Detail

Encapsulates information about the event details that contains a list of events which can be reported or analyzed.

Download schema: detail.json

Sample GET:

[
    {
        "id": "1",
        "configId": "640",
        "query": {
            "time": "2017-03-23T03:27:00Z",
            "clientIp": "208.114.124.44",
            "dnsIp": "23.216.52.23",
            "domain": "no-block.net.",
            "queryType": "A",
            "resolved": [
                {
                    "type": "A",
                    "response": "50.7.146.46",
                    "asn": "174"
                }
            ]
        },
        "event": {
            "detectionTime": "2017-03-23T03:27:34Z",
            "detectionType": "online",
            "siteId": "1401",
            "siteName": "MTN",
            "policyId": "1634",
            "policyName": "Got Honey?",
            "listId": "1",
            "listName": "Malware",
            "trigger": "domain",
            "categoryId": "1",
            "categoryName": "Malware",
            "confidenceId": "Known",
            "actionId": "344",
            "actionName": "Honeypot - BOSTON",
            "description": "Malware targeting Boston"
        }
    }
]

Detail Members

Member Type Description
event Detail.event Contains details about an event that occurred as a result of a DNS query.
id Integer A unique identifier for the column object.
query Detail.query The details about the requested DNS query.

Detail.event  

Contains details about an event that occurred as a result of a DNS query.

Member Type Description
actionName String A descriptive name for the action identifier.
categoryName String A descriptive name for the category identifier.
confidenceId String A unique identifier about the event confidence level.
description String A short description of the event.
detectionTime String Event detected time in ISO 8601 format.
detectionType Enumeration Event detected during online or while offline batch processing. Either ONLINE or OFFLINE.
listName String A descriptive name for the list identifier.
policyId String A unique identifier for the policy.
siteId String A unique identifier for the site.
trigger String Event triggered due to domain or IP policy settings.

Detail.query  

The details about the requested DNS query.

Member Type Description
clientIp String The requesting client’s IP address.
dnsIp String The DNS resolver IP address.
domain String The requested domain address.
queryType String The DNS query type.
resolved Detail.query.resolved[n] The details about the requested DNS query resolution.
time String Time of DNS request in ISO 8601 format.

Detail.query.resolved[n]  

The details about the requested DNS query resolution.

Member Type Description
asn String Autonomous system number used for resolution.
response String Resolved domain or IP address.
type String DNS resolution type. For example: A or CNAME

TimeSeries

Encapsulates information about time series that lists hourly events which can be reported or analyzed.

Download schema: time-series.json

Sample GET:

{
    "columns": [
        {
            "id": "TIMESTAMP",
            "name": "TIMESTAMP"
        },
        {
            "id": "1",
            "name": "Malware"
        },
        {
            "id": "3",
            "name": "C&C"
        },
        {
            "id": "2441",
            "name": "DeadStream"
        },
        {
            "id": "OTHERS",
            "name": "OTHERS"
        }
    ],
    "rows": [
        [
            "2017-03-22T10:00:00Z",
            0,
            3,
            0,
            0
        ],
        [
            "2017-03-22T12:00:00Z",
            2,
            0,
            0,
            0
        ],
        [
            "2017-03-22T14:00:00Z",
            15,
            0,
            0,
            0
        ]
    ]
}

TimeSeries Members

Member Type Description
columns Array Each column object contains a unique identifier and name.
rows Array Array of arrays corresponding to table rows and columns. Within each row, the first value represents the ISO 8601 timestamp, and subsequent values represent numeric data for each column

Information

Provides registration details for a domain.

Download schema: ioc-information.json

Sample GET:

{
    "record": "00005ik.rcomhost.com.",
    "recordType": "DOMAIN",
    "description": "Locky Ransomware distribution site",
    "registrarName": "NETWORK SOLUTIONS, LLC.",
    "registrantName": "LLC, networksolutions",
    "registrantOrganization": "Network Solutions LLC",
    "registrantCity": "HERNDON",
    "registrantState": "VA",
    "registrantEmails": [
        "Domains@web.com"
    ],
    "nameServerNames": [
        "NS45.WORLDNIC.COM",
        "NS46.WORLDNIC.COM"
    ],
    "registrantAddress": "HERNDON",
    "registrantCountry": "UNITED STATES",
    "whoisServer": "whois.networksolutions.com",
    "createdDate": "2012-01-25T00:00:00Z",
    "lastModifiedDate": "2014-02-26T00:00:00Z"
}

Information Members

Member Type Description
category Information.category[n] Lists category information for a domain or IP.
contestInformations Information.contestInformations[n] Contains information and details on contest actions for a domain.
createDate String The registration date of the domain in ISO 8601 format.
description String A description of the record.
expiryDate String The expiration date of the domain registration in ISO 8601 format.
lastModifiedDate String The last modified date of the domain in ISO 8601 format.
nameServerIPs Array A list of name server IP addresses for a domain.
nameServerNames Array A list of name servers for a domain.
record String The name of the record.
recordType Enumeration Specifies the type of record. Either DOMAIN or IP.
registrantAddress String The address of the domain registrant.
registrantCountry String The country of the domain registrant.
registrantEmails Array A list of email addresses associated with the domain registrant.
registrantName String The name of the domain registrant.
registrarName String The name of the domain registrar.

Information.category[n]  

Lists category information for a domain or IP.

Member Type Description
categoryId String A unique identifier for the category.
categoryName String The name of the category.
confidenceId Enumeration The confidence level of the list entry. Either SUSPECTED or KNOWN.
listId String A unique identifier for the list.

Information.contestInformations[n]  

Contains information and details on contest actions for a domain.

Member Type Description
actionTaken String A description of the actions taken to resolve the contest.
contestedOn String The time of contest in ISO 8601 format.
contestId String A unique identifier for the contest.
contestReason String A description of the reason for the contest.

Changes

Provides a list of IOC changes.

Download schema: changes.json

Sample GET:

[
    {
        "recordType": "DOMAIN",
        "date": "2017-03-07T00:00:00Z",
        "state": "ADDED",
        "description": "First tracked"
    },
    {
        "recordType": "DOMAIN",
        "date": "2017-03-07T00:00:00Z",
        "state": "CHANGED",
        "description": "Severity upgraded from Unknown to Suspected Malware",
        "key": "CONFIDENCE",
        "oldValue": "Unknown",
        "newValue": "Suspected",
        "listId": "1",
        "listName": "Malware"
    }
]

Changes Members

Member Type Description
date String The date of the change in ISO 8601 format.
description String A description of the change made.
key String The name of the key that changed.
listId String A unique identifier for the list the domain is assigned to.
listName String The name of the list that the domain is assigned to.
newValue String The new value of the key.
oldValue String The previous value of the key.
recordType Enumeration Specifies the type of record. Either DOMAIN or IP.
state Enumeration The state of the change made. Possible values are ADDED, CHANGED, REMOVED, and DELETED.

ReportSchedule

Contains configuration to schedule reoccuring reports on a daily or weekly basis.

Download schema: report-schedule.json

Sample GET:

{
    "scheduleId": 100,
    "recurrence": "WEEKLY",
    "dayOfWeek": "MONDAY",
    "userTimeZone": "+05:30",
    "filters": {
        "isAlert": {
            "in": [
                "true"
            ]
        }
    },
    "status": "ENABLED",
    "reportTemplate": "THREAT_EVENTS_BY_LOCATION_AND_DOMAIN",
    "emails": [
        "user1@akamai.com",
        "user2@akamai.com"
    ],
    "createdBy": "user1",
    "creationDate": "2017-06-22T11:12:55Z",
    "modifiedBy": "user2",
    "modifiedDate": "2017-06-28T11:12:55Z"
}

ReportSchedule Members

Member Type Description
createdBy String Identifies the user who initially created the report schedule configuration.
createdDate String ISO–8601 timestamp string indicating when the report schedule configuration was initially created.
dayOfWeek Enumeration, Null Specifies the day of the week the report generates, either MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, or SUNDAY. Only used when recurrence is set to WEEKLY, otherwise null.
emails Array Specifies the email addresses to send generated reports.
filters Object, Null Specifies filters to apply while generating the report. See the Filter object type.
modifiedBy String Identifies the last user who modified the report schedule configuration.
modifiedDate String ISO–8601 timestamp string indicating when the report schedule configuration was last modified.
recurrence Enumeration Specifies the frequency of the report schedule, either DAILY, or WEEKLY.
reportTemplate Enumeration Specifies the report template (representational-structure). Set to THREAT_EVENTS_BY_LOCATION_AND_DOMAIN.
scheduleId Integer A unique identifier for the report schedule configuration.
status Enumeration Specifies the status of the report schedule configuration, either ENABLED or DISABLED.
userTimeZone String Specifies a user-timezone-offset for generating the report. For example, -05:00

Last modified: 4/18/2018