Umbrella Reporting API samples

Reporting

The Umbrella Reporting API provides visibility into your core network and security activities and Umbrella logs. You can find the Umbrella Reporting API endpoints under the reports scope in the Cloud Security API.

Use Cases and Best Practices

The Umbrella Reporting API enables you to programmatically access logs and reports, and build widgets or custom reports. The Reporting API does not support bulk data retrieval. If you need to export all of your data or large data collections, you can enable logging to Amazon Simple Storage Service (Amazon S3). For more information about Umbrella logs, see Manage Your Logs in the Umbrella User Guide.

Use Case Granularity/Type Recommendation Considerations
Compliance or Long term event retention Export and store all events Customer owned Amazon S3 bucket
SIEM: Event Correlation Export all events Cisco managed Amazon S3 bucket Umbrella retains data for 30 days.
Dashboard KPI/Widgets Activity Search and Aggregations Reporting API Use query parameters to filter requests.
Report Generation Aggregations Reporting API
SOAR Workflow: Trigger Activity Search Reporting API Use query parameters to filter requests.

Request Path Parameters

The Umbrella Reporting API endpoints require various path parameters.

Parameter Example Description
type dns Specifies the type of traffic. Valid values are: dns, proxy, firewall, ip, or intrusion. The type of traffic values vary by endpoint.
identityId 42 An identity ID.
threatTypeId Ransomware A string that represents a threat type.
threatNameId WannaCry A string that represents a threat name.

Request Query Parameters

You can customize and filter the Umbrella Reporting API requests with query parameters. Each Reporting API endpoint defines its required query parameters.

Note: Umbrella uses the timestamp of the events to sort the /activity, /activity/dns, /activity/proxy, /activity/firewall, and /activity/amp-retrospective collections. If multiple events occur in the same second, the order of the collection is not guaranteed to be consistent.

Parameter Example Description
from 1639146300000 A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time. For more information, see Timestamp and Relative Time Strings.
Required
to 1640010300000 A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time. For more information, see Timestamp and Relative Time Strings.
Required
offset 0 A number that represents an index into the collection.
limit 100 The maximum number of records to return from the collection.
Required
domains cisco.com A domain name or comma-delimited list of domain name.
urls https://google.com,facebook.com/help A URL or comma-delimited list of URL.
categories 148,151,66 A category ID or comma-delimited list of category ID.
policycategories 67,69 A category ID or comma-delimited list of category ID. Filter request by the categories that trigger a policy.
ip 10.10.10.10 An IP address.
order desc A string that describes how to order the results (for example: 'asc' or 'desc').
ports 7351,80 A port number or comma-delimited list of port number.
identityids 1,2,3 An identity ID or comma-delimited list of identity ID.
identitytypes network,roaming An identity type or comma-delimited list of identity type.
applicationid 1 An application ID.
verdict allowed,blocked,proxied A verdict string or comma-delimited list of verdict string.
ruleid 1 A firewall policy rule ID.
filename myfilename_* A string that identifies a filename. Filter request by the filename. Supports globbing or use of the wildcard character (*). The asterisk (*) matches zero or more occurrences of any character.
securityoverridden true A boolean value. If set to 'true', filter for requests that override security.
bundleid 1 A proxy bundle ID.
threats A threat name or comma-delimited list of threat name.
threattypes A threat type or comma-delimited list of threat type.
ampdisposition clean,malicious,unknown An AMP disposition string or a comma-delimited list of AMP disposition string.
isolatedstate isolated A string that describes the remote browser isolation (RBI) isolation type (for example: 'isolated' or 'not-isolated'.
isolatedFileAction downloaded-safe-pdf A string that describes the remote browser isolation (RBI) file action type (for example: 'viewed', 'downloaded-original-file', or 'downloaded-safe-pdf').
datalosspreventionstate blocked A string that describes the status of a destination (for example: 'blocked'). Filter data for requests that were blocked to protect data.
sha256 A SHA-256 hash.
antivirusthreats Trojan.Linux.Generic.144075 A threat name or comma-delimited list of threat name.
tenantcontrols true A boolean value. If set to 'true', filter data for requests that are part of a tenant control policy.
search somelabel A string that represents a search parameter. Filter data for requests in which the search string appears in the endpoint data.
application Games An application name.
filternoisydomains true A boolean value. If set to 'true', filter request on domains that generate high volume of insignificant traffic (noise).
httperrors certificateerror A string that represents a TLS or certificate error (for example: 'certificateerror' or 'tlserror'). Filter data for requests that resulted in a TLS or certificate error.
exists 'categories,destinationlistids' Specify a comma-separated list of attributes to filter the Activity Report. Valid values are: categories, policycategories, applicationid, nbarapplicationid, nbarapplicationtypeids, privateapplicationid, applicationgroupids, sha256, filename, threats, threattypes, antivirusthreats, destinationlistids, httperrors.

Request Data by Time Range

Many Umbrella Reporting API endpoints require that you set a time range to filter the data. You can define a time range with the to and from request query parameters. Additionally, some Umbrella Reporting API endpoints enable a timerange header.

Time Range Header

The timerange header describes how to group data within a twenty-four hour period. This header accepts the following strings:

Umbrella Reporting API resources that group data by hourly intervals do not enable the timerange header. These resources include:

Time Range Example

The Requests by Timerange resource accepts the timerange header as well as the to and from query parameters. For example, you can set the timerange header to minute, the to query parameter to now, and the from query parameter to -1days.

Timestamp and Relative Time Strings

The to and from query parameters accept a timestamp string defined in milliseconds from the Unix epoch. For example: 1619007756000 (converted from 2021-04-21:08:22:36 GMT-04:00).

You can also set other time range string values for these parameters.

Examples of to query parameter values:

Examples of from query parameter values:

Note: The time range set by the to and from query parameters cannot exceed 30 days.

HTTP Redirects and Request Authorization Header

Umbrella stores the reporting data in geolocated data warehouses.

Note: If an HTTP client request does not originate from the same continent as the location of the Umbrella data warehouse, the Umbrella server responds with 302 Found.

To automatically redirect HTTP requests and preserve the HTTP Authorization header, you can set additional flags or enable a redirect setting.

Get Top Categories By Type

GET https://api.umbrella.com/reports/v2/top-categories/{type}

Description

List the categories for the type of traffic which received the greatest number of requests. Order the number of requests in descending order.

Path Parameters

Query Parameters


Request Sample


curl -L --location-trusted --request GET --url 'https://api.umbrella.com/reports/v2/top-categories/{type}?from=<value>&to=<value>&limit=<value>' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (object)

data

category

Response Sample

Click to view the sample response (200, OK) 
{
    "data": [
        {
            "rank": 5,
            "category": {
                "id": 66,
                "label": "Malware",
                "type": "security",
                "integration": true
            },
            "count": 3827
        }
    ],
    "meta": {}
}

Get Top Identities (all)

GET https://api.umbrella.com/reports/v2/top-identities

Description

List the identities by the number of requests made, sorted in descending order.

Query Parameters


Request Sample


curl -L --location-trusted --request GET --url 'https://api.umbrella.com/reports/v2/top-identities?from=<value>&to=<value>&limit=<value>' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (object)

data

identity

type

counts

Response Sample

Click to view the sample response (200, OK) 
{
    "data": [
        {
            "requests": 3827,
            "bandwidth": 7051943359,
            "identity": {
                "id": 1,
                "label": "Catch Rate Testing System",
                "type": {
                    "id": 21,
                    "label": "Sites",
                    "type": "site"
                },
                "deleted": false
            },
            "counts": {
                "requests": 123,
                "allowedrequests": 60,
                "blockedrequests": 63
            },
            "rank": 3
        }
    ],
    "meta": {}
}