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.

Schemas

Total

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

Sample GET:

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

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.

Sample GET:

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

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. Possible enum values: OFFLINE, ONLINE.
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.

Sample GET:

{
    "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
        ]
    ],
    "columns": [
        {
            "id": "TIMESTAMP",
            "name": "TIMESTAMP"
        },
        {
            "id": "1",
            "name": "Malware"
        },
        {
            "id": "3",
            "name": "C&C"
        },
        {
            "id": "2441",
            "name": "DeadStream"
        },
        {
            "id": "OTHERS",
            "name": "OTHERS"
        }
    ]
}

TimeSeries Members  

Member Type Description
columns TimeSeries.columns[n] 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

TimeSeries.columns[n]  

Each column object contains a unique identifier and name.

Member Type Description
id String A unique identifier for the column object.
name String Describes the column contents of the column.

Information

Provides registration details for a domain.

Sample GET:

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

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. Possible enum values: DOMAIN, 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. Possible enum values: Known, Suspected.
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.
contestId String A unique identifier for the contest.
contestReason String A description of the reason for the contest.
contestedOn String The time of contest in ISO 8601 format.

Changes

Provides a list of IOC changes.

Sample GET:

[
    {
        "date": "2017-03-07T00:00:00Z",
        "state": "ADDED",
        "recordType": "DOMAIN",
        "description": "First tracked"
    },
    {
        "key": "CONFIDENCE",
        "listName": "Malware",
        "recordType": "DOMAIN",
        "listId": "1",
        "state": "CHANGED",
        "oldValue": "Unknown",
        "date": "2017-03-07T00:00:00Z",
        "newValue": "Suspected",
        "description": "Severity upgraded from Unknown to Suspected 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. Possible enum values: DOMAIN, IP.
state Enumeration The state of the change made. Possible enum values: ADDED, CHANGED, DELETED, REMOVED.

Last modified: 8/18/2017