Umbrella Reporting v1 API: DNS Requests, Top Destinations

Request Samples

Find Most Recent DNS Requests

For all identities in an organization, find the latest DNS requests for a certain destination. A destination is a domain or an IP address, specified without any protocol or delimiters. For instance, www.cisco.com is valid, but https://cisco.com is not valid, nor is cisco.com/index.html.

Request Query Parameters

Field Type Description
limit integer The number of records to return in the collection. The default value is 100. The maxiumum number of records to return in a query is 500.
offset integer A number that represents an index in the collection. The default value is 0.

Request

GET /organizations/{organizationId}/destinations/{destination}/activity

The following query returns the first ten results for the destination:

curl -i GET 'https://reports.api.umbrella.com/v1/organizations/{organizationId}/destinations/{destination}/activity?limit=10' \
-H 'Authorization: Basic %YourEncodedKeySecret%' \
-H 'Content-Type: application/json'

Response

Sample response (200, OK):

{
    [
        {
            "originId": 81185341,
            "internalIp": "192.0.2.0",
            "externalIp": "192.0.2.0",
            "originLabel": "YVR test",
            "categories": [
                "Software/Technology",
                "Business Services"
            ],
            "originType": "Networks",
            "actionTaken": "ALLOWED",
            "datetime": "2017-12-05T21:45:14.897Z",
            "destination": "destination.organization.example"
        }
    ]
}

Response Fields

Field Type Description
originId integer The numerical identifier for the identity making the request.
internalIp string The internal IP address of the identity making the request (if available).
externalIp string The external IP address of the identity making the request.
originLabel string The human readable name for the identity. The originLabel matches the origin label in the dashboard.
categories array The list of categories that apply to the requested destination.
originType string The identity type (for example: network, roaming computer, or AD user).
actionTaken string The type of action for this destination. Possible values: Blocked or Allowed.
datetime string The time at which the event occurred, in UTC.
destination string The destination to which this request was made.

List Top Destination Identities

For an organization, list the top 10 identities that have made a DNS request to the destination. A destination can be a domain or an IP address and should not include a protocol or delimiters. For instance, www.cisco.com is valid, but https://cisco.com is not valid, nor is cisco.com/index.html.

Request

GET /organizations/{organizationId}/destinations/{destination}/identities

curl -i GET "https://reports.api.umbrella.com/v1/organizations/{organizationId}/destinations/{destination}/identities" \
-H 'Authorization: Basic %YourEncodedKeySecret%' \
-H 'Content-Type: application/json'

Response

Sample response (200, OK):

{
    "identities": [
        {
            "rank": 1,
            "originLabel": "The Corporate Network",
            "originType": "network",
            "originId": 87414500,
            "numberOfRequests": 2
        }
    ]
}

Response Fields

Field Type Description
rank integer The order of this identity in the list of top 10 identities that query the destination.
originLabel string The human readable name for the identity. The originLabel matches the origin label in the dashboard.
originType string The type of the identity. The originType matches the type of the identity in the dashboard. For example: Network, Roaming Computer, or Site are common types.
originId integer The numerical identifier for the individual identity.
numberOfRequests integer The number of DNS requests made to the destination.

List Security Activity

The Security Activity endpoint provides details about blocked security activity events for an organization. This endpoint returns data for the previous 24 hours. The Security Activity endpoint can return a maximum of 500 results in a single query.

Request Query Parameters

Field Type Description
limit integer The number of results to return in the collection. The maximum number of records is 500. If not specified, the default limit is 100.
start integer A Unix (epoch) timestamp specified in seconds. This timestamp represents the start of the time window. Filter for data that appears after this time.
stop integer A Unix (epoch) timestamp specified in seconds. This timestamp represents the end of the time window. Filter for data that appears before this time.
stopTimestamp integer A Unix (epoch) timestamp specified in seconds. This timestamp represents the time of a recorded event in the previous response. Use stopTimestamp to paginate the records in the collection.

Request

GET /organizations/{organizationId}/security-activity

curl -i GET "https://reports.api.umbrella.com/v1/organizations/{organizationId}/security-activity?limit=2&start=1512432000&stop=1512518400"  \
-H 'Authorization: Basic %YourEncodedKeySecret%' \
-H 'Content-Type: application/json'

Response

Sample response (200, OK):

{
  "requests": [
    {
      "originId": 105489403,
      "internalIp": "192.168.64.5",
      "externalIp": "59.102.103.63",
      "destination": "some-bad-website.com",
      "originLabel": "IDENTITY-NAME-GOES-HERE",
      "categories": [
        "Malware"
      ],
      "originType": "Roaming Computers",
      "actionTaken": "BLOCKED",
      "datetime": "2017-11-15T06:34:27.841Z"
    }
   ]
}

Response Fields

Field Type Description
originId integer The numerical identifier for the identity making the request.
internalIp string The internal IP address of the identity making the request (if available).
externalIp string The external IP address of the identity making the request.
originLabel string The human readable name for the identity. The originLabel matches the origin label in the dashboard.
categories array The list of categories that apply to the requested destination.
originType string The identity type (for example: network, roaming computer, or AD user).
actionTaken string The type of action for this destination. Possible values: Blocked or Allowed.
datetime string The time at which the event occurred, in UTC.
destination string The destination to which the request was made.