Cloud Security Gov

Reporting

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

Use Cases and Best Practices

The 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 for Government SIG 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 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 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 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 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:

  • minute
  • hour (default value)
  • day

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

  • Bandwidth by Hour
  • Requests by Hour
  • Requests by Hour and Category

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:

  • now
  • -1days

Examples of from query parameter values:

  • -2days
  • -10minutes
  • -2weeks
Note: The time range set by the to and from query parameters cannot exceed 30 days.

HTTP Redirects and Request Authorization Header

Umbrella stores your reporting data in data warehouses located in the Continental United States.

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

  • curl: You must pass the -L or --location, and --location-trusted flags to redirect the curl HTTP request and retain the Authorization header.

    shell
    Copycurl -i --location --location-trusted \
--request GET --url 'https://api.umbrellagov.com/reports/v2/activity?from=-7days&to=now&limit=10' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

  • Postman: Within the Postman environment, navigate to an API and choose a GET method. Navigate to Settings. Enable Follow Authorization header to preserve the Authorization header for redirect requests.

Get Activities (All)

GET https://api.umbrellagov.com/reports/v2/activity

Description

List all activities (dns/proxy/firewall/intrusion) within the timeframe. Note: The IP activity report is not available.

Access Scope: Reports > Aggregations > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • ports

    (Optional, string) A port number or comma-delimited list of port numbers.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • ruleid

    (Optional, number) The firewall policy rule ID.

  • filename

    (Optional, string) A string that identifies a filename. Filter the request by the filename. Supports globbing or use of the wildcard character (''). The asterisk () matches zero or more occurrences of any character.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • isolatedstate

    (Optional, string) A string that describes the remote browser isolation (RBI) isolation type.

  • isolatedFileAction

    (Optional, string) A string that describes the remote browser isolation (RBI) file action type.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • httperrors

    (Optional, string) Filter data for requests that resulted in a TLS error or a certificate error.

  • exists

    (Optional, string) Specify an attribute or comma-separated list of attributes to filter the data. Valid values are: categories, policycategories, applicationid, nbarapplicationid, nbarapplicationtypeids, privateapplicationid, applicationgroupids, sha256, filename, threats, threattypes, antivirusthreats, destinationlistids, and httperrors.

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

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

Response Schema (object)

  • data

    (Required, array (anyOf))

    • anyOf-1
      • externalip

        (Required, string) The external IP for the entry.

      • internalip

        (Required, string) The internal IP for the entry.

      • policycategories

        (Required, array (object)) The list of the policy categories.

        • id

          (Optional, number) The ID of the category.

        • label

          (Optional, string) The descriptive label for the category.

        • type

          (Optional, string) The type of the category.

        • integration

          (Optional, boolean) Specifies whether the category is an integration.

        • deprecated

          (Optional, boolean) Specifies whether the category is a legacy category.

      • categories

        (Required, array (object)) The list of categories.

        • id

          (Optional, number) The ID of the category.

        • label

          (Optional, string) The descriptive label for the category.

        • type

          (Optional, string) The type of the category.

        • integration

          (Optional, boolean) Specifies whether the category is an integration.

        • deprecated

          (Optional, boolean) Specifies whether the category is a legacy category.

      • verdict

        (Required, string) The verdict for the entry.

      • domain

        (Required, string) The domain name for the entry.

      • timestamp

        (Required, number) The timestamp represented in milliseconds.

      • identities

        (Required, array (object)) The list of identities for the entry.

        • id

          (Required, number) The ID of the identity.

        • label

          (Required, string) The descriptive label for the identity.

        • type

          (Required, object) The information about the identity including the type.

          • id

            (Optional, number) The ID of the origin type for the identity.

          • label

            (Optional, string) The label of the origin type for the identity.

          • type

            (Optional, string) The name of the origin type for the identity.

        • deleted

          (Required, boolean) Indicates whether the identity was deleted.

      • allapplications

        (Required, array (object)) The list of all applications for the entry.

        • id

          (Optional, number) The ID of the application.

        • label

          (Optional, string) The descriptive label for the application.

        • type

          (Optional, string) The type of the application: NBAR or AVC.

        • category

          (Optional, object) The category of the application.

          • id

            (Optional, number) The ID of the application category.

          • label

            (Optional, string) The label of the application category.

      • threats

        (Required, array (object)) The list of threats for the entry.

        • label

          (Optional, string) The descriptive label for the threat name.

        • type

          (Optional, string) The type of the threat.

      • type

        (Required, string) The type of the request. A DNS request always has the type dns.

      • querytype

        (Required, string) The type of DNS request that was made. For more information, see Common DNS Request Types.

      • date

        (Required, string) The date from the timestamp based on the timezone parameter.

      • time

        (Required, string) The time in 24-hour format based on the timezone parameter.

      • returncode

        (Required, number) The DNS return code for this request. For more information, see Common DNS return codes for any DNS service (and Umbrella).

      • allowedapplications

        (Required, array (object)) The list of allowed applications.

        • id

          (Optional, number) The ID of the application.

        • label

          (Optional, string) The descriptive label for the application.

        • type

          (Optional, string) The type of the application: NBAR or AVC.

        • category

          (Optional, object) The category of the application.

          • id

            (Optional, number) The ID of the application category.

          • label

            (Optional, string) The label of the application category.

      • blockedapplications

        (Required, array (object)) The list of blocked applications.

        • id

          (Optional, number) The ID of the application.

        • label

          (Optional, string) The descriptive label for the application.

        • type

          (Optional, string) The type of the application: NBAR or AVC.

        • category

          (Optional, object) The category of the application.

          • id

            (Optional, number) The ID of the application category.

          • label

            (Optional, string) The label of the application category.

    • anyOf-2
      • date

        (Required, string) The date from the timestamp based on the timezone parameter.

      • destinationip

        (Required, string) The destination IP for the entry.

      • sourceip

        (Required, string) The source IP for the entry.

      • sourceport

        (Required, number) The source port for the entry.

      • destinationport

        (Required, number) The destination port for entry.

      • categories

        (Optional, array (object)) The list of categories.

        • id

          (Optional, number) The ID of the category.

        • label

          (Optional, string) The descriptive label for the category.

        • type

          (Optional, string) The type of the category.

        • integration

          (Optional, boolean) Specifies whether the category is an integration.

        • deprecated

          (Optional, boolean) Specifies whether the category is a legacy category.

      • verdict

        (Required, string) The verdict for the entry.

      • time

        (Required, string) The time in 24-hour format based on the timezone parameter.

      • timestamp

        (Required, number) The timestamp represented in milliseconds.

      • identities

        (Required, array (object)) The list of identities for the entry.

        • id

          (Required, number) The ID of the identity.

        • label

          (Required, string) The descriptive label for the identity.

        • type

          (Required, object) The information about the identity including the type.

          • id

            (Optional, number) The ID of the origin type for the identity.

          • label

            (Optional, string) The label of the origin type for the identity.

          • type

            (Optional, string) The name of the origin type for the identity.

        • deleted

          (Required, boolean) Indicates whether the identity was deleted.

      • protocol

        (Required, object) The properties of the protocol.

        • id

          (Required, number) The ID of protocol.

        • label

          (Required, string) The name of the protocol.

      • rule

        (Required, object) The properties of the firewall rule.

        • id

          (Required, number) The ID of the rule.

        • label

          (Required, string) The name of the rule.

        • privateapplicationgroup

          (Optional, object) The private application group.

          • id

            (Optional, number) The ID of application group.

          • label

            (Optional, string) The name of the application group.

      • type

        (Required, string) The type of the request. A firewall request always has type firewall.

      • allapplications

        (Required, array (object)) A list of firewall applications

        • id

          (Optional, number) The ID of the application or protocol.

        • label

          (Optional, string) The descriptive label for the application or protocol.

        • app

          (Optional, string) The information about the app type.

      • applicationprotocols

        (Required, array (object)) A list of firewall application protocols.

        • id

          (Optional, number) The ID of the application or protocol.

        • label

          (Optional, string) The descriptive label for the application or protocol.

        • app

          (Optional, string) The information about the app type.

      • direction

        (Required, string) The direction of the packet. It is destined either towards the internet or to the customer's network.

      • packetsize

        (Required, number) The size of the packet that was received.

    • anyOf-3
      • classification

        (Required, string) The category of attack detected by a rule that is part of a more general type of attack class, such as trojan-activity, attempted-user, and unknown.

      • date

        (Required, string) The date from the timestamp based on the timezone parameter.

      • destinationip

        (Required, string) The destination IP for the entry.

      • destinationport

        (Required, number) The destination port for entry.

      • identities

        (Required, array (object)) The list of identities for the entry.

        • id

          (Required, number) The ID of the identity.

        • label

          (Required, string) The descriptive label for the identity.

        • type

          (Required, object) The information about the identity including the type.

          • id

            (Optional, number) The ID of the origin type for the identity.

          • label

            (Optional, string) The label of the origin type for the identity.

          • type

            (Optional, string) The name of the origin type for the identity.

        • deleted

          (Required, boolean) Indicates whether the identity was deleted.

      • protocol

        (Required, object) The properties of the protocol.

        • id

          (Required, number) The ID of protocol.

        • label

          (Required, string) The name of the protocol.

      • sessionid

        (Required, number) The unique identifier of a session, which is used to group the correlated events between various services.

      • severity

        (Required, string) The severity level of the rule.

      • signature

        (Required, object) The properties of the signature.

        • generatorid

          (Required, number) The unique ID that is assigned to the part of the IPS, which generated the event.

        • id

          (Required, number) The ID that is used to uniquely identify signatures.

        • label

          (Required, string) A descriptive label for the the signature.

        • cves

          (Required, array (string)) The list of common vulnerabilites and exposures (CVEs).

      • signaturelist

        (Required, object) The properties of the signature list.

        • id

          (Required, number) The unique ID assigned to a default or custom signature list.

      • sourceip

        (Required, string) The source IP for the entry.

      • sourceport

        (Required, number) The source port for the entry.

      • time

        (Required, string) The time in 24-hour format based on the timezone parameter.

      • timestamp

        (Required, number) The timestamp represented in milliseconds.

      • type

        (Required, string) The type of the request. An intrusion request always has type intrusion.

      • verdict

        (Required, string) The verdict for the entry.

    • anyOf-4
      • externalip

        (Required, string) The external IP for the entry.

      • internalip

        (Required, string) The internal IP for the entry.

      • policycategories

        (Required, array (object)) The list of policy categories.

        • id

          (Optional, number) The ID of the category.

        • label

          (Optional, string) The descriptive label for the category.

        • type

          (Optional, string) The type of the category.

        • integration

          (Optional, boolean) Specifies whether the category is an integration.

        • deprecated

          (Optional, boolean) Specifies whether the category is a legacy category.

      • categories

        (Required, array (object)) The list of categories.

        • id

          (Optional, number) The ID of the category.

        • label

          (Optional, string) The descriptive label for the category.

        • type

          (Optional, string) The type of the category.

        • integration

          (Optional, boolean) Specifies whether the category is an integration.

        • deprecated

          (Optional, boolean) Specifies whether the category is a legacy category.

      • verdict

        (Required, string) The verdict for the entry.

      • timestamp

        (Required, number) The timestamp represented in milliseconds.

      • identities

        (Required, array (object)) The list of identities for the entry.

        • id

          (Required, number) The ID of the identity.

        • label

          (Required, string) The descriptive label for the identity.

        • type

          (Required, object) The information about the identity including the type.

          • id

            (Optional, number) The ID of the origin type for the identity.

          • label

            (Optional, string) The label of the origin type for the identity.

          • type

            (Optional, string) The name of the origin type for the identity.

        • deleted

          (Required, boolean) Indicates whether the identity was deleted.

      • allapplications

        (Required, array (object)) The list of applications for the entry.

        • id

          (Optional, number) The ID of the application.

        • label

          (Optional, string) The descriptive label for the application.

        • type

          (Optional, string) The type of the application: NBAR or AVC.

        • category

          (Optional, object) The category of the application.

          • id

            (Optional, number) The ID of the application category.

          • label

            (Optional, string) The label of the application category.

      • allowedapplications

        (Required, array (object)) The list of allowed applications for the entry.

        • id

          (Optional, number) The ID of the application.

        • label

          (Optional, string) The descriptive label for the application.

        • type

          (Optional, string) The type of the application: NBAR or AVC.

        • category

          (Optional, object) The category of the application.

          • id

            (Optional, number) The ID of the application category.

          • label

            (Optional, string) The label of the application category.

      • blockedapplications

        (Required, array (object)) The list of blocked applications for the entry.

        • id

          (Optional, number) The ID of the application.

        • label

          (Optional, string) The descriptive label for the application.

        • type

          (Optional, string) The type of the application: NBAR or AVC.

        • category

          (Optional, object) The category of the application.

          • id

            (Optional, number) The ID of the application category.

          • label

            (Optional, string) The label of the application category.

      • responsefilename

        (Required, string) The response filename for the entry.

      • blockedfiletype

        (Required, string) The blocked file type for the entry.

      • bundleid

        (Required, number) The ID of the bundle type.

      • amp

        (Required, object) The properties of the AMP disposition and score for the malware.

        • score

          (Required, number) The AMP score.

        • disposition

          (Required, string) The AMP disposition.

        • malware

          (Required, string) The AMP malware.

      • type

        (Required, string) The type of the request. A proxy request is always of type 'proxy'.

      • tenantcontrols

        (Required, boolean) Specifies whether the request is part of a tenant control policy.

      • port

        (Required, number) The port used to make the request.

      • antivirusthreats

        (Required, object) The information about the antivirus threats.

        • puas

          (Required, array (object)) The list of potentially unwanted applications.

        • viruses

          (Required, array (string)) The list of viruses.

        • others

          (Required, array (object)) The list of other antivirus threats.

      • policy

        (Required, object) The properties of the rules in the policy.

        • timebasedrule

          (Required, boolean) Specify whether the policy triggered a time-of-day rule.

        • destinationlistids

          (Required, array (number)) The list of destination lists that the rules triggered.

        • ruleid

          (Required, number) The ID of the rule in the policy.

        • rulesetid

          (Required, number) The ID of the ruleset in the policy.

      • requestmethod

        (Optional, string) The HTTP request method.

      • responsesize

        (Required, number) The response size in bytes.

      • requestsize

        (Required, number) The response size in bytes.

      • statuscode

        (Required, number) The HTTP status code (200 or 201).

      • useragent

        (Required, string) The name of the browser that made the request.

      • referer

        (Required, string) The referring domain or URL.

      • warnstatus

        (Required, string) The warning status.

      • sha256

        (Required, string) The hex digest of the response content.

      • isolated

        (Required, object) The properties of the isolated file.

        • state

          (Required, string) The state of the isolated file.

        • fileaction

          (Required, string) The action taken for the file.

      • datalossprevention

        (Required, object) The information about the Data Loss Prevention state.

        • state

          (Required, string) Indicates the status of the DLP. The state is either blocked or the empty string ( ).

      • securityoverridden

        (Required, boolean) Specifies whether security overrides are configured.

      • contenttype

        (Required, string) The type of web content, typically text/html.

      • forwardingmethod

        (Required, string) The request method (GET, POST, HEAD, etc.)

      • httperrors

        (Required, array (object)) Certificate & TLS Errors

        • type

          (Optional, string) The type of the error, either CertificateError or TLSError.

        • code

          (Optional, number) The HTTP error code.

        • reason

          (Optional, string) The name of the error.

        • attributes

          (Optional, object) The properties of the additional information for the error.

      • threats

        (Required, array (object))

        • label

          (Optional, string) The descriptive label for the threat name.

        • type

          (Optional, string) The type of the threat.

      • egress

        (Required, object) The information about the egress IP.

        • ip

          (Required, string) The egress IP.

        • type

          (Required, string) The type of the egress IP.

      • datacenter

        (Required, object) The information about the data center.

        • id

          (Required, string) The unique ID for the data center.

        • label

          (Required, string) The name of the data center.

      • date

        (Required, string) The date from the timestamp based on the timezone parameter.

      • time

        (Required, string) The time in 24-hour format based on the timezone parameter.

      • destinationip

        (Required, string) The destination IP for the entry.

      • url

        (Required, string) The URL that was requested.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "meta": {},
    "data": [
        {
            "externalip": "52.8.160.247",
            "internalip": "52.8.160.247",
            "policycategories": [
                {
                    "id": 66,
                    "label": "Malware",
                    "type": "security",
                    "integration": true
                }
            ],
            "categories": [
                {
                    "id": 66,
                    "label": "Malware",
                    "type": "security",
                    "integration": true
                }
            ],
            "verdict": "allowed",
            "domain": "google.com",
            "timestamp": 1731002169000,
            "time": "06:31:46",
            "date": "2019-01-24",
            "identities": [
                {
                    "id": 1,
                    "label": "Catch Rate Testing System",
                    "type": {
                        "id": 21,
                        "label": "Sites",
                        "type": "site"
                    },
                    "deleted": true
                }
            ],
            "threats": [
                {
                    "label": "Wannacry",
                    "type": "Ransomware"
                }
            ],
            "allapplications": [
                {
                    "id": 1,
                    "label": "label",
                    "type": "NBAR",
                    "category": {
                        "id": 1,
                        "label": "category"
                    }
                }
            ],
            "allowedapplications": [
                {
                    "id": 1,
                    "label": "label",
                    "type": "NBAR",
                    "category": {
                        "id": 1,
                        "label": "category"
                    }
                }
            ],
            "querytype": "MX",
            "returncode": 2,
            "blockedapplications": [],
            "type": "dns"
        }
    ]
}

Get Activity DNS

GET https://api.umbrellagov.com/reports/v2/activity/dns

Description

List all DNS entries within the timeframe.

Access Scope: Reports > Aggregations > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • order

    (Optional, string) A string that describes how to order the results: ascending (asc) or descending (desc).

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

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

Response Schema (object)

  • data

    (Required, array (object))

    • externalip

      (Required, string) The external IP for the entry.

    • internalip

      (Required, string) The internal IP for the entry.

    • policycategories

      (Required, array (object)) The list of the policy categories.

      • id

        (Optional, number) The ID of the category.

      • label

        (Optional, string) The descriptive label for the category.

      • type

        (Optional, string) The type of the category.

      • integration

        (Optional, boolean) Specifies whether the category is an integration.

      • deprecated

        (Optional, boolean) Specifies whether the category is a legacy category.

    • categories

      (Required, array (object)) The list of categories.

      • id

        (Optional, number) The ID of the category.

      • label

        (Optional, string) The descriptive label for the category.

      • type

        (Optional, string) The type of the category.

      • integration

        (Optional, boolean) Specifies whether the category is an integration.

      • deprecated

        (Optional, boolean) Specifies whether the category is a legacy category.

    • verdict

      (Required, string) The verdict for the entry.

    • domain

      (Required, string) The domain name for the entry.

    • timestamp

      (Required, number) The timestamp represented in milliseconds.

    • identities

      (Required, array (object)) The list of identities for the entry.

      • id

        (Required, number) The ID of the identity.

      • label

        (Required, string) The descriptive label for the identity.

      • type

        (Required, object) The information about the identity including the type.

        • id

          (Optional, number) The ID of the origin type for the identity.

        • label

          (Optional, string) The label of the origin type for the identity.

        • type

          (Optional, string) The name of the origin type for the identity.

      • deleted

        (Required, boolean) Indicates whether the identity was deleted.

    • allapplications

      (Required, array (object)) The list of all applications for the entry.

      • id

        (Optional, number) The ID of the application.

      • label

        (Optional, string) The descriptive label for the application.

      • type

        (Optional, string) The type of the application: NBAR or AVC.

      • category

        (Optional, object) The category of the application.

        • id

          (Optional, number) The ID of the application category.

        • label

          (Optional, string) The label of the application category.

    • threats

      (Required, array (object)) The list of threats for the entry.

      • label

        (Optional, string) The descriptive label for the threat name.

      • type

        (Optional, string) The type of the threat.

    • type

      (Required, string) The type of the request. A DNS request always has the type dns.

    • querytype

      (Required, string) The type of DNS request that was made. For more information, see Common DNS Request Types.

    • date

      (Required, string) The date from the timestamp based on the timezone parameter.

    • time

      (Required, string) The time in 24-hour format based on the timezone parameter.

    • returncode

      (Required, number) The DNS return code for this request. For more information, see Common DNS return codes for any DNS service (and Umbrella).

    • allowedapplications

      (Required, array (object)) The list of allowed applications.

      • id

        (Optional, number) The ID of the application.

      • label

        (Optional, string) The descriptive label for the application.

      • type

        (Optional, string) The type of the application: NBAR or AVC.

      • category

        (Optional, object) The category of the application.

        • id

          (Optional, number) The ID of the application category.

        • label

          (Optional, string) The label of the application category.

    • blockedapplications

      (Required, array (object)) The list of blocked applications.

      • id

        (Optional, number) The ID of the application.

      • label

        (Optional, string) The descriptive label for the application.

      • type

        (Optional, string) The type of the application: NBAR or AVC.

      • category

        (Optional, object) The category of the application.

        • id

          (Optional, number) The ID of the application category.

        • label

          (Optional, string) The label of the application category.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "externalip": "52.8.160.247",
            "internalip": "52.8.160.247",
            "policycategories": [
                {
                    "id": 66,
                    "label": "Malware",
                    "type": "security",
                    "integration": true
                }
            ],
            "categories": [
                {
                    "id": 66,
                    "label": "Malware",
                    "type": "security",
                    "integration": true
                }
            ],
            "verdict": "allowed",
            "domain": "google.com",
            "timestamp": 1731002169000,
            "time": "06:31:46",
            "date": "2019-01-24",
            "identities": [
                {
                    "id": 1,
                    "label": "Catch Rate Testing System",
                    "type": {
                        "id": 21,
                        "label": "Sites",
                        "type": "site"
                    },
                    "deleted": true
                }
            ],
            "threats": [
                {
                    "label": "Wannacry",
                    "type": "Ransomware"
                }
            ],
            "allapplications": [
                {
                    "id": 1,
                    "label": "label",
                    "type": "NBAR",
                    "category": {
                        "id": 1,
                        "label": "category"
                    }
                }
            ],
            "allowedapplications": [
                {
                    "id": 1,
                    "label": "label",
                    "type": "NBAR",
                    "category": {
                        "id": 1,
                        "label": "category"
                    }
                }
            ],
            "querytype": "MX",
            "returncode": 2,
            "blockedapplications": [],
            "type": "dns"
        }
    ],
    "meta": {}
}

Get Activity Proxy

GET https://api.umbrellagov.com/reports/v2/activity/proxy

Description

List all proxy entries within the timeframe.

Access Scope: Reports > Aggregations > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • order

    (Optional, string) A string that describes how to order the results: ascending (asc) or descending (desc).

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • ports

    (Optional, string) A port number or comma-delimited list of port numbers.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • ruleid

    (Optional, number) The firewall policy rule ID.

  • filename

    (Optional, string) A string that identifies a filename. Filter the request by the filename. Supports globbing or use of the wildcard character (''). The asterisk () matches zero or more occurrences of any character.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • tenantcontrols

    (Optional, boolean) If set to true, filter data for requests that are part of a tenant control policy.

  • isolatedstate

    (Optional, string) A string that describes the remote browser isolation (RBI) isolation type.

  • isolatedFileAction

    (Optional, string) A string that describes the remote browser isolation (RBI) file action type.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • httperrors

    (Optional, string) Filter data for requests that resulted in a TLS error or a certificate error.

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

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

Response Schema (object)

  • data

    (Required, array (object))

    • externalip

      (Required, string) The external IP for the entry.

    • internalip

      (Required, string) The internal IP for the entry.

    • policycategories

      (Required, array (object)) The list of policy categories.

      • id

        (Optional, number) The ID of the category.

      • label

        (Optional, string) The descriptive label for the category.

      • type

        (Optional, string) The type of the category.

      • integration

        (Optional, boolean) Specifies whether the category is an integration.

      • deprecated

        (Optional, boolean) Specifies whether the category is a legacy category.

    • categories

      (Required, array (object)) The list of categories.

      • id

        (Optional, number) The ID of the category.

      • label

        (Optional, string) The descriptive label for the category.

      • type

        (Optional, string) The type of the category.

      • integration

        (Optional, boolean) Specifies whether the category is an integration.

      • deprecated

        (Optional, boolean) Specifies whether the category is a legacy category.

    • verdict

      (Required, string) The verdict for the entry.

    • timestamp

      (Required, number) The timestamp represented in milliseconds.

    • identities

      (Required, array (object)) The list of identities for the entry.

      • id

        (Required, number) The ID of the identity.

      • label

        (Required, string) The descriptive label for the identity.

      • type

        (Required, object) The information about the identity including the type.

        • id

          (Optional, number) The ID of the origin type for the identity.

        • label

          (Optional, string) The label of the origin type for the identity.

        • type

          (Optional, string) The name of the origin type for the identity.

      • deleted

        (Required, boolean) Indicates whether the identity was deleted.

    • allapplications

      (Required, array (object)) The list of applications for the entry.

      • id

        (Optional, number) The ID of the application.

      • label

        (Optional, string) The descriptive label for the application.

      • type

        (Optional, string) The type of the application: NBAR or AVC.

      • category

        (Optional, object) The category of the application.

        • id

          (Optional, number) The ID of the application category.

        • label

          (Optional, string) The label of the application category.

    • allowedapplications

      (Required, array (object)) The list of allowed applications for the entry.

      • id

        (Optional, number) The ID of the application.

      • label

        (Optional, string) The descriptive label for the application.

      • type

        (Optional, string) The type of the application: NBAR or AVC.

      • category

        (Optional, object) The category of the application.

        • id

          (Optional, number) The ID of the application category.

        • label

          (Optional, string) The label of the application category.

    • blockedapplications

      (Required, array (object)) The list of blocked applications for the entry.

      • id

        (Optional, number) The ID of the application.

      • label

        (Optional, string) The descriptive label for the application.

      • type

        (Optional, string) The type of the application: NBAR or AVC.

      • category

        (Optional, object) The category of the application.

        • id

          (Optional, number) The ID of the application category.

        • label

          (Optional, string) The label of the application category.

    • responsefilename

      (Required, string) The response filename for the entry.

    • blockedfiletype

      (Required, string) The blocked file type for the entry.

    • bundleid

      (Required, number) The ID of the bundle type.

    • amp

      (Required, object) The properties of the AMP disposition and score for the malware.

      • score

        (Required, number) The AMP score.

      • disposition

        (Required, string) The AMP disposition.

      • malware

        (Required, string) The AMP malware.

    • type

      (Required, string) The type of the request. A proxy request is always of type 'proxy'.

    • tenantcontrols

      (Required, boolean) Specifies whether the request is part of a tenant control policy.

    • port

      (Required, number) The port used to make the request.

    • antivirusthreats

      (Required, object) The information about the antivirus threats.

      • puas

        (Required, array (object)) The list of potentially unwanted applications.

      • viruses

        (Required, array (string)) The list of viruses.

      • others

        (Required, array (object)) The list of other antivirus threats.

    • policy

      (Required, object) The properties of the rules in the policy.

      • timebasedrule

        (Required, boolean) Specify whether the policy triggered a time-of-day rule.

      • destinationlistids

        (Required, array (number)) The list of destination lists that the rules triggered.

      • ruleid

        (Required, number) The ID of the rule in the policy.

      • rulesetid

        (Required, number) The ID of the ruleset in the policy.

    • requestmethod

      (Optional, string) The HTTP request method.

    • responsesize

      (Required, number) The response size in bytes.

    • requestsize

      (Required, number) The response size in bytes.

    • statuscode

      (Required, number) The HTTP status code (200 or 201).

    • useragent

      (Required, string) The name of the browser that made the request.

    • referer

      (Required, string) The referring domain or URL.

    • warnstatus

      (Required, string) The warning status.

    • sha256

      (Required, string) The hex digest of the response content.

    • isolated

      (Required, object) The properties of the isolated file.

      • state

        (Required, string) The state of the isolated file.

      • fileaction

        (Required, string) The action taken for the file.

    • datalossprevention

      (Required, object) The information about the Data Loss Prevention state.

      • state

        (Required, string) Indicates the status of the DLP. The state is either blocked or the empty string ( ).

    • securityoverridden

      (Required, boolean) Specifies whether security overrides are configured.

    • contenttype

      (Required, string) The type of web content, typically text/html.

    • forwardingmethod

      (Required, string) The request method (GET, POST, HEAD, etc.)

    • httperrors

      (Required, array (object)) Certificate & TLS Errors

      • type

        (Optional, string) The type of the error, either CertificateError or TLSError.

      • code

        (Optional, number) The HTTP error code.

      • reason

        (Optional, string) The name of the error.

      • attributes

        (Optional, object) The properties of the additional information for the error.

    • threats

      (Required, array (object))

      • label

        (Optional, string) The descriptive label for the threat name.

      • type

        (Optional, string) The type of the threat.

    • egress

      (Required, object) The information about the egress IP.

      • ip

        (Required, string) The egress IP.

      • type

        (Required, string) The type of the egress IP.

    • datacenter

      (Required, object) The information about the data center.

      • id

        (Required, string) The unique ID for the data center.

      • label

        (Required, string) The name of the data center.

    • date

      (Required, string) The date from the timestamp based on the timezone parameter.

    • time

      (Required, string) The time in 24-hour format based on the timezone parameter.

    • destinationip

      (Required, string) The destination IP for the entry.

    • url

      (Required, string) The URL that was requested.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "destinationip": "",
            "externalip": "32.4.91.7",
            "responsesize": 3329530,
            "allapplications": [
                {
                    "id": 1313,
                    "label": "Netflix",
                    "category": {
                        "id": 47,
                        "label": "Media"
                    }
                }
            ],
            "date": "2022-02-18",
            "datalossprevention": {
                "state": ""
            },
            "antivirusthreats": {
                "puas": [],
                "viruses": [],
                "others": []
            },
            "internalip": "192.168.1.43",
            "referer": "",
            "contenttype": "",
            "tenantcontrols": false,
            "securityoverridden": false,
            "useragent": "",
            "time": "23:29:42",
            "amp": {
                "disposition": "",
                "score": 0,
                "malware": ""
            },
            "policycategories": [],
            "type": "proxy",
            "requestsize": 1996,
            "port": 443,
            "policy": {
                "ruleid": 0,
                "rulesetid": 0,
                "destinationlistids": [],
                "timebasedrule": false
            },
            "forwardingmethod": "",
            "categories": [
                {
                    "id": 17,
                    "type": "content",
                    "label": "Movies",
                    "integration": false,
                    "deprecated": true
                }
            ],
            "isolated": {
                "state": "not-isolated",
                "fileaction": ""
            },
            "statuscode": 200,
            "egress": {
                "ip": "155.190.3.8",
                "type": "shared"
            },
            "blockedfiletype": "",
            "url": "https://ipv4-lax2-ix.1.oca.anothervideo.net",
            "verdict": "allowed",
            "responsefilename": "",
            "warnstatus": "",
            "sha256": "",
            "timestamp": 1645226982000,
            "blockedapplications": [],
            "allowedapplications": [],
            "identities": [
                {
                    "id": 1,
                    "type": {
                        "id": 34,
                        "type": "anyconnect",
                        "label": "Anyconnect Roaming Client"
                    },
                    "label": "Vincent's Macbook",
                    "deleted": false
                }
            ],
            "datacenter": {
                "label": "Los Angeles, US",
                "id": "LAX"
            },
            "threats": [],
            "httperrors": [],
            "bundleid": 3
        }
    ],
    "meta": {}
}

Get Activity Firewall

GET https://api.umbrellagov.com/reports/v2/activity/firewall

Description

List all firewall activity within the timeframe.

Access Scope: Reports > Aggregations > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • ruleid

    (Optional, number) The firewall policy rule ID.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • ip

    (Optional, string) An IP address.

  • ports

    (Optional, string) A port number or comma-delimited list of port numbers.

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.


Request Sample

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

Response Schema (object)

  • data

    (Required, array (object))

    • date

      (Required, string) The date from the timestamp based on the timezone parameter.

    • destinationip

      (Required, string) The destination IP for the entry.

    • sourceip

      (Required, string) The source IP for the entry.

    • sourceport

      (Required, number) The source port for the entry.

    • destinationport

      (Required, number) The destination port for entry.

    • categories

      (Optional, array (object)) The list of categories.

      • id

        (Optional, number) The ID of the category.

      • label

        (Optional, string) The descriptive label for the category.

      • type

        (Optional, string) The type of the category.

      • integration

        (Optional, boolean) Specifies whether the category is an integration.

      • deprecated

        (Optional, boolean) Specifies whether the category is a legacy category.

    • verdict

      (Required, string) The verdict for the entry.

    • time

      (Required, string) The time in 24-hour format based on the timezone parameter.

    • timestamp

      (Required, number) The timestamp represented in milliseconds.

    • identities

      (Required, array (object)) The list of identities for the entry.

      • id

        (Required, number) The ID of the identity.

      • label

        (Required, string) The descriptive label for the identity.

      • type

        (Required, object) The information about the identity including the type.

        • id

          (Optional, number) The ID of the origin type for the identity.

        • label

          (Optional, string) The label of the origin type for the identity.

        • type

          (Optional, string) The name of the origin type for the identity.

      • deleted

        (Required, boolean) Indicates whether the identity was deleted.

    • protocol

      (Required, object) The properties of the protocol.

      • id

        (Required, number) The ID of protocol.

      • label

        (Required, string) The name of the protocol.

    • rule

      (Required, object) The properties of the firewall rule.

      • id

        (Required, number) The ID of the rule.

      • label

        (Required, string) The name of the rule.

      • privateapplicationgroup

        (Optional, object) The private application group.

        • id

          (Optional, number) The ID of application group.

        • label

          (Optional, string) The name of the application group.

    • type

      (Required, string) The type of the request. A firewall request always has type firewall.

    • allapplications

      (Required, array (object)) A list of firewall applications

      • id

        (Optional, number) The ID of the application or protocol.

      • label

        (Optional, string) The descriptive label for the application or protocol.

      • app

        (Optional, string) The information about the app type.

    • applicationprotocols

      (Required, array (object)) A list of firewall application protocols.

      • id

        (Optional, number) The ID of the application or protocol.

      • label

        (Optional, string) The descriptive label for the application or protocol.

      • app

        (Optional, string) The information about the app type.

    • direction

      (Required, string) The direction of the packet. It is destined either towards the internet or to the customer's network.

    • packetsize

      (Required, number) The size of the packet that was received.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "date": "2019",
            "destinationip": "52.8.160.247",
            "sourceip": "192.168.0.1",
            "sourceport": 0,
            "destinationport": 0,
            "categories": [
                {
                    "id": 66,
                    "label": "Malware",
                    "type": "security",
                    "integration": true
                }
            ],
            "verdict": "allowed",
            "time": "12:34",
            "timestamp": 1731002169000,
            "identities": [
                {
                    "id": 1,
                    "label": "Catch Rate Testing System",
                    "type": {
                        "id": 21,
                        "label": "Sites",
                        "type": "site"
                    },
                    "deleted": false
                }
            ],
            "protocol": {
                "id": 17,
                "label": "UDP"
            },
            "rule": {
                "id": 1,
                "label": "Default Rule"
            },
            "type": "firewall",
            "allapplications": [
                {
                    "id": 72,
                    "label": "dns IT Service Management",
                    "app": ""
                }
            ],
            "applicationprotocols": [
                {
                    "id": 72,
                    "label": "dns IT Service Management",
                    "app": ""
                }
            ],
            "packetsize": 32,
            "direction": "towards"
        }
    ],
    "meta": {}
}

Get Activity Intrusion

GET https://api.umbrellagov.com/reports/v2/activity/intrusion

Description

List all Intrusion Prevention System (IPS) activity within the timeframe.

Access Scope: Reports > Aggregations > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • signatures

    (Optional, string) The signature or comma-separated list of - signatures.

  • signaturelistids

    (Optional, string) The signature ID or comma-separated list of signature list IDs.

  • intrusionaction

    (Optional, string) An action or list of comma-separated intrusion actions. Valid values are: would_block, blocked, and detected.

  • ip

    (Optional, string) An IP address.

  • ports

    (Optional, string) A port number or comma-delimited list of port numbers.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

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

Response Schema (object)

  • data

    (Required, array (object))

    • classification

      (Required, string) The category of attack detected by a rule that is part of a more general type of attack class, such as trojan-activity, attempted-user, and unknown.

    • date

      (Required, string) The date from the timestamp based on the timezone parameter.

    • destinationip

      (Required, string) The destination IP for the entry.

    • destinationport

      (Required, number) The destination port for entry.

    • identities

      (Required, array (object)) The list of identities for the entry.

      • id

        (Required, number) The ID of the identity.

      • label

        (Required, string) The descriptive label for the identity.

      • type

        (Required, object) The information about the identity including the type.

        • id

          (Optional, number) The ID of the origin type for the identity.

        • label

          (Optional, string) The label of the origin type for the identity.

        • type

          (Optional, string) The name of the origin type for the identity.

      • deleted

        (Required, boolean) Indicates whether the identity was deleted.

    • protocol

      (Required, object) The properties of the protocol.

      • id

        (Required, number) The ID of protocol.

      • label

        (Required, string) The name of the protocol.

    • sessionid

      (Required, number) The unique identifier of a session, which is used to group the correlated events between various services.

    • severity

      (Required, string) The severity level of the rule.

    • signature

      (Required, object) The properties of the signature.

      • generatorid

        (Required, number) The unique ID that is assigned to the part of the IPS, which generated the event.

      • id

        (Required, number) The ID that is used to uniquely identify signatures.

      • label

        (Required, string) A descriptive label for the the signature.

      • cves

        (Required, array (string)) The list of common vulnerabilites and exposures (CVEs).

    • signaturelist

      (Required, object) The properties of the signature list.

      • id

        (Required, number) The unique ID assigned to a default or custom signature list.

    • sourceip

      (Required, string) The source IP for the entry.

    • sourceport

      (Required, number) The source port for the entry.

    • time

      (Required, string) The time in 24-hour format based on the timezone parameter.

    • timestamp

      (Required, number) The timestamp represented in milliseconds.

    • type

      (Required, string) The type of the request. An intrusion request always has type intrusion.

    • verdict

      (Required, string) The verdict for the entry.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "type": "intrusion",
            "date": "12-02-22",
            "destinationip": "10.10.10.10",
            "protocol": {
                "id": 17,
                "label": "UDP"
            },
            "sourceip": "10.10.10.10",
            "signaturelist": {
                "id": 1111
            },
            "classification": "malicious",
            "rule": [
                {
                    "id": 391327,
                    "label": "UNKNOWN"
                }
            ],
            "ipsProfile": "PROFILE",
            "sourceport": 22,
            "sessionid": 190898098,
            "verdict": "detected",
            "destinationport": 33,
            "timestamp": 1594557262000,
            "time": "09:30",
            "identities": [
                {
                    "id": 211034846,
                    "type": {
                        "id": 34,
                        "type": "anyconnect",
                        "label": "Anyconnect Roaming Client"
                    },
                    "label": "omerta",
                    "deleted": false
                }
            ],
            "severity": "HIGH",
            "signature": {
                "generatorid": 1,
                "id": 47829,
                "label": "SERVER-OTHER JBoss Richfaces expression language injection attempt",
                "cves": [
                    "cve-2015-0279",
                    "cve-2018-12532"
                ]
            }
        }
    ],
    "meta": {}
}

Get Activity IP

GET https://api.umbrellagov.com/reports/v2/activity/ip

Description

(Deprecated) List all IP activity within the timeframe.

Access Scope: Reports > Aggregations > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • ip

    (Optional, string) An IP address.

  • ports

    (Optional, string) A port number or comma-delimited list of port numbers.


Request Sample

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

Response Schema (object)

  • data

    (Required, array ())

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [],
    "meta": {}
}

Get Activity AMP Retrospective

GET https://api.umbrellagov.com/reports/v2/activity/amp-retrospective

Description

List all AMP retrospective activity within the timeframe.

Access Scope: Reports > Aggregations > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • sha256

    (Optional, string) A SHA-256 hash.

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

Code Snippet
Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/reports/v2/activity/amp-retrospective?from=<value>&to=<value>&limit=<value>' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (object)

  • data

    (Required, array (object))

    • timestamp

      (Required, number) The timestamp represented in seconds.

    • firstseenat

      (Required, number) The date and time (a timestamp expressed in seconds) when the malware event was first recorded.

    • disposition

      (Required, string) The disposition for the entry.

    • score

      (Required, number) The score for the entry.

    • hostname

      (Required, string) The hostname for the entry.

    • malwarename

      (Required, string) The name of the malware for the entry.

    • sha256

      (Required, string) The SHA256 hash for the entry.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "timestamp": 1548311506,
            "firstseenat": 1548311506,
            "disposition": "clean",
            "score": 10,
            "hostname": "google.com",
            "malwarename": "malware",
            "sha256": "9495b6c155044053953efe30ebaf804780c114e7b721b14f6a5b0a782769696e"
        }
    ],
    "meta": {}
}

Get Top Identities (All)

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

Description

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

Access Scope: Reports > Aggregations > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • ports

    (Optional, string) A port number or comma-delimited list of port numbers.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • sha256

    (Optional, string) A SHA-256 hash.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

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

Response Schema (object)

  • data

    (Required, array (object))

    • requests

      (Required, number) The total number of requests made by this identity.

    • bandwidth

      (Required, number) The amount of bandwidth

    • identity

      (Required, object) The information about the identity.

      • id

        (Required, number) The ID of the identity.

      • label

        (Required, string) The descriptive label for the identity.

      • type

        (Required, object) The information about the identity including the type.

        • id

          (Optional, number) The ID of the origin type for the identity.

        • label

          (Optional, string) The label of the origin type for the identity.

        • type

          (Optional, string) The name of the origin type for the identity.

      • deleted

        (Required, boolean) Indicates whether the identity was deleted.

    • counts

      (Required, object) The information about the requests.

      • requests

        (Optional, number) The total number of requests.

      • allowedrequests

        (Optional, number) The number of requests that were allowed.

      • blockedrequests

        (Optional, number) The number of requests that were blocked.

    • rank

      (Required, number) The rank of the result based on the number of requests.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "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": {}
}

Get Top Identities

GET https://api.umbrellagov.com/reports/v2/top-identities/{type}

Description

List the identities for the specific traffic type by the number of requests. Sort the results in descending order.

Access Scope: Reports > Aggregations > Read-Only

Path Parameters

  • type

    (Required, string) Specify the type of traffic.

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • ports

    (Optional, string) A port number or comma-delimited list of port numbers.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • sha256

    (Optional, string) A SHA-256 hash.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

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

Response Schema (object)

  • data

    (Required, array (object))

    • requests

      (Required, number) The total number of requests made by this identity.

    • bandwidth

      (Required, number) The amount of bandwidth

    • identity

      (Required, object) The information about the identity.

      • id

        (Required, number) The ID of the identity.

      • label

        (Required, string) The descriptive label for the identity.

      • type

        (Required, object) The information about the identity including the type.

        • id

          (Optional, number) The ID of the origin type for the identity.

        • label

          (Optional, string) The label of the origin type for the identity.

        • type

          (Optional, string) The name of the origin type for the identity.

      • deleted

        (Required, boolean) Indicates whether the identity was deleted.

    • counts

      (Required, object) The information about the requests.

      • requests

        (Optional, number) The total number of requests.

      • allowedrequests

        (Optional, number) The number of requests that were allowed.

      • blockedrequests

        (Optional, number) The number of requests that were blocked.

    • rank

      (Required, number) The rank of the result based on the number of requests.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "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": {}
}

Get Identity Distribution (All)

GET https://api.umbrellagov.com/reports/v2/identity-distribution

Description

List the number of requests by identity types.

Access Scope: Reports > Aggregations > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • ports

    (Optional, string) A port number or comma-delimited list of port numbers.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • sha256

    (Optional, string) A SHA-256 hash.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

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

Response Schema (object)

  • data

    (Required, array (object))

    • counts

      (Required, object) The information about the requests.

      • requests

        (Optional, number) The total number of requests.

      • allowedrequests

        (Optional, number) The number of requests that were allowed.

      • blockedrequests

        (Optional, number) The number of requests that were blocked.

    • requests

      (Required, number) The requests made by the identity type.

    • unique_identity_count

      (Required, number) The number unique identities associated with the identity type.

    • identitytype

      (Required, object) The information about the identity including the type.

      • id

        (Optional, number) The ID of the origin type for the identity.

      • label

        (Optional, string) The label of the origin type for the identity.

      • type

        (Optional, string) The name of the origin type for the identity.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "counts": {
                "requests": 123,
                "allowedrequests": 60,
                "blockedrequests": 63
            },
            "requests": 312,
            "unique_identity_count": 12,
            "identitytype": {
                "id": 21,
                "label": "Sites",
                "type": "site"
            }
        }
    ],
    "meta": {}
}

Get Identity Distribution By Type

GET https://api.umbrellagov.com/reports/v2/identity-distribution/{type}

Description

List the number of requests by identity for the type of traffic.

Access Scope: Reports > Aggregations > Read-Only

Path Parameters

  • type

    (Required, string) Specify the type of traffic.

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • ports

    (Optional, string) A port number or comma-delimited list of port numbers.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • sha256

    (Optional, string) A SHA-256 hash.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

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

Response Schema (object)

  • data

    (Required, array (object)) The list of identity distributions.

    • counts

      (Required, object) The information about the requests.

      • requests

        (Optional, number) The total number of requests.

      • allowedrequests

        (Optional, number) The number of requests that were allowed.

      • blockedrequests

        (Optional, number) The number of requests that were blocked.

    • requests

      (Required, number) The requests made by the identity type.

    • unique_identity_count

      (Required, number) The number unique identities associated with the identity type.

    • identitytype

      (Required, object) The information about the identity including the type.

      • id

        (Optional, number) The ID of the origin type for the identity.

      • label

        (Optional, string) The label of the origin type for the identity.

      • type

        (Optional, string) The name of the origin type for the identity.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "counts": {
                "requests": 123,
                "allowedrequests": 60,
                "blockedrequests": 63
            },
            "requests": 312,
            "unique_identity_count": 12,
            "identitytype": {
                "id": 21,
                "label": "Sites",
                "type": "site"
            }
        }
    ],
    "meta": {}
}

Get Top Destinations

GET https://api.umbrellagov.com/reports/v2/top-destinations

Description

List the destinations by the number of requests made to this destination. Return the results in descending order.

Access Scope: Reports > Aggregations > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • ports

    (Optional, string) A port number or comma-delimited list of port numbers.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • sha256

    (Optional, string) A SHA-256 hash.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

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

Response Schema (object)

  • data

    (Required, array (object))

    • bandwidth

      (Required, number) The amount of bandwidth

    • rank

      (Required, number) The rank of the result based on the number of requests.

    • domain

      (Required, string) The domain name.

    • count

      (Required, number) The total number of requests made for this destination.

    • counts

      (Required, object) The information about the requests.

      • requests

        (Optional, number) The total number of requests.

      • allowedrequests

        (Optional, number) The number of requests that were allowed.

      • blockedrequests

        (Optional, number) The number of requests that were blocked.

    • categories

      (Required, array (object)) The list of categories.

      • id

        (Optional, number) The ID of the category.

      • label

        (Optional, string) The descriptive label for the category.

      • type

        (Optional, string) The type of the category.

      • integration

        (Optional, boolean) Specifies whether the category is an integration.

      • deprecated

        (Optional, boolean) Specifies whether the category is a legacy category.

    • policycategories

      (Required, array (object)) The policy categories that are associated with the destination.

      • id

        (Optional, number) The ID of the category.

      • label

        (Optional, string) The descriptive label for the category.

      • type

        (Optional, string) The type of the category.

      • integration

        (Optional, boolean) Specifies whether the category is an integration.

      • deprecated

        (Optional, boolean) Specifies whether the category is a legacy category.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "bandwidth": 223437,
            "rank": 4,
            "domain": "google.com",
            "count": 3827,
            "counts": {
                "requests": 123,
                "allowedrequests": 60,
                "blockedrequests": 63
            },
            "categories": [
                {
                    "id": 66,
                    "label": "Malware",
                    "type": "security",
                    "integration": true
                }
            ],
            "policycategories": [
                {
                    "id": 66,
                    "label": "Malware",
                    "type": "security",
                    "integration": true
                }
            ]
        }
    ],
    "meta": {}
}

Get Top Destinations By Type

GET https://api.umbrellagov.com/reports/v2/top-destinations/{type}

Description

List the destinations by type of destination and the number of requests made to this destination. Return the collection in descending order.

Access Scope: Reports > Aggregations > Read-Only

Path Parameters

  • type

    (Required, string) Specify the type of traffic.

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • ports

    (Optional, string) A port number or comma-delimited list of port numbers.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • sha256

    (Optional, string) A SHA-256 hash.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

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

Response Schema (object)

  • data

    (Required, array (object))

    • bandwidth

      (Required, number) The amount of bandwidth

    • rank

      (Required, number) The rank of the result based on the number of requests.

    • domain

      (Required, string) The domain name.

    • count

      (Required, number) The total number of requests made for this destination.

    • counts

      (Required, object) The information about the requests.

      • requests

        (Optional, number) The total number of requests.

      • allowedrequests

        (Optional, number) The number of requests that were allowed.

      • blockedrequests

        (Optional, number) The number of requests that were blocked.

    • categories

      (Required, array (object)) The list of categories.

      • id

        (Optional, number) The ID of the category.

      • label

        (Optional, string) The descriptive label for the category.

      • type

        (Optional, string) The type of the category.

      • integration

        (Optional, boolean) Specifies whether the category is an integration.

      • deprecated

        (Optional, boolean) Specifies whether the category is a legacy category.

    • policycategories

      (Required, array (object)) The policy categories that are associated with the destination.

      • id

        (Optional, number) The ID of the category.

      • label

        (Optional, string) The descriptive label for the category.

      • type

        (Optional, string) The type of the category.

      • integration

        (Optional, boolean) Specifies whether the category is an integration.

      • deprecated

        (Optional, boolean) Specifies whether the category is a legacy category.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "bandwidth": 223437,
            "rank": 4,
            "domain": "google.com",
            "count": 3827,
            "counts": {
                "requests": 123,
                "allowedrequests": 60,
                "blockedrequests": 63
            },
            "categories": [
                {
                    "id": 66,
                    "label": "Malware",
                    "type": "security",
                    "integration": true
                }
            ],
            "policycategories": [
                {
                    "id": 66,
                    "label": "Malware",
                    "type": "security",
                    "integration": true
                }
            ]
        }
    ],
    "meta": {}
}

Get Top URLs

GET https://api.umbrellagov.com/reports/v2/top-urls

Description

List the top number of URLs that are requested for a certain domain.

Access Scope: Reports > Aggregations > Read-Only

Query Parameters

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • sha256

    (Optional, string) A SHA-256 hash.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

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

Response Schema (object)

  • data

    (Required, array (object))

    • count

      (Required, number) The total number of requests.

    • path

      (Required, string) The URL path.

    • categories

      (Required, array (object)) The list of categories.

      • id

        (Optional, number) The ID of the category.

      • label

        (Optional, string) The descriptive label for the category.

      • type

        (Optional, string) The type of the category.

      • integration

        (Optional, boolean) Specifies whether the category is an integration.

      • deprecated

        (Optional, boolean) Specifies whether the category is a legacy category.

    • rank

      (Required, number) The numeric rank of the top URL.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "count": 884,
            "path": "/backend-api/conversation",
            "categories": [
                {
                    "id": 132,
                    "type": "content",
                    "label": "SaaS and B2B",
                    "integration": false,
                    "deprecated": false
                }
            ],
            "rank": 1
        },
        {
            "count": 123,
            "path": "",
            "categories": [
                {
                    "id": 66,
                    "label": "Malware",
                    "type": "security",
                    "integration": true
                }
            ],
            "rank": 2
        }
    ],
    "meta": {}
}

Get Top Categories (All)

GET https://api.umbrellagov.com/reports/v2/top-categories

Description

List the categories that received the greatest number of requests. Order the number of requests in descending order.

Access Scope: Reports > Aggregations > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • sha256

    (Optional, string) A SHA-256 hash.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

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

Response Schema (object)

  • data

    (Required, array (object))

    • rank

      (Required, number) The rank of the result based on the number of requests.

    • category

      (Required, object) The properties of the category.

      • id

        (Optional, number) The ID of the category.

      • label

        (Optional, string) The descriptive label for the category.

      • type

        (Optional, string) The type of the category.

      • integration

        (Optional, boolean) Specifies whether the category is an integration.

      • deprecated

        (Optional, boolean) Specifies whether the category is a legacy category.

    • count

      (Required, number) The number of requests that match this category.

    • bandwidth

      (Optional, number) The amount of bandwidth

  • meta

    (Required, object) The properties of the metadata.

Response Sample

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

Get Top Categories By Type

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

Description

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

Access Scope: Reports > Aggregations > Read-Only

Path Parameters

  • type

    (Required, string) Specify the type of traffic.

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • sha256

    (Optional, string) A SHA-256 hash.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

Code Snippet
Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.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

    (Required, array (object))

    • rank

      (Required, number) The rank of the result based on the number of requests.

    • category

      (Required, object) The properties of the category.

      • id

        (Optional, number) The ID of the category.

      • label

        (Optional, string) The descriptive label for the category.

      • type

        (Optional, string) The type of the category.

      • integration

        (Optional, boolean) Specifies whether the category is an integration.

      • deprecated

        (Optional, boolean) Specifies whether the category is a legacy category.

    • count

      (Required, number) The number of requests that match this category.

    • bandwidth

      (Optional, number) The amount of bandwidth

  • meta

    (Required, object) The properties of the metadata.

Response Sample

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

Get Top Event Types (All)

GET https://api.umbrellagov.com/reports/v2/top-eventtypes

Description

List the top event types by the number of requests made for each type of event. Order the number of requests in descending order. The valid event types are: domain_security, domain_integration, url_security, url_integration, cisco_amp, and antivirus.

Access Scope: Reports > Aggregations > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

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

Response Schema (object)

  • data

    (Required, array (object))

    • eventtype

      (Required, string) The type of the event.

    • count

      (Required, number) The number of requests that match the event type (eventtype).

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "eventtype": "antivirus",
            "count": 3827
        }
    ],
    "meta": {}
}

Get Top DNS Query Types

GET https://api.umbrellagov.com/reports/v2/top-dns-query-types

Description

List the top types of DNS query.

Access Scope: Reports > Aggregations > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • order

    (Optional, string) A string that describes how to order the results: ascending (asc) or descending (desc).

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

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

Response Schema (object)

  • data

    (Required, array (object))

    • requests

      (Required, number) The total number of requests.

    • querytype

      (Required, string) The type of the DNS query.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "requests": 123,
            "querytype": "A"
        }
    ],
    "meta": {}
}

Get Requests by Hour (All)

GET https://api.umbrellagov.com/reports/v2/requests-by-hour

Description

List the activity volume within the timeframe.

Access Scope: Reports > Granular Events > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • ports

    (Optional, string) A port number or comma-delimited list of port numbers.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • sha256

    (Optional, string) A SHA-256 hash.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

Code Snippet
Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/reports/v2/requests-by-hour?from=<value>&to=<value>&limit=<value>' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (object)

  • data

    (Required, array (object))

    • count

      (Required, number) The number of requests in the hour.

    • counts

      (Required, object) The information about the requests.

      • requests

        (Optional, number) The total number of requests.

      • allowedrequests

        (Optional, number) The number of requests that were allowed.

      • blockedrequests

        (Optional, number) The number of requests that were blocked.

    • timestamp

      (Required, number) The timestamp represented in milliseconds for the bucket.

    • date

      (Required, string) The date from the timestamp based on the timezone parameter.

    • time

      (Required, string) The time in 24-hour format based on the timezone parameter.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "count": 123,
            "counts": {
                "requests": 123,
                "allowedrequests": 60,
                "blockedrequests": 63
            },
            "timestamp": 1559836800000,
            "date": "2019",
            "time": "16:00:00"
        }
    ],
    "meta": {}
}

Get Requests by Hour

GET https://api.umbrellagov.com/reports/v2/requests-by-hour/{type}

Description

List the activity volume within the timeframe.

Access Scope: Reports > Granular Events > Read-Only

Path Parameters

  • type

    (Required, string) Specify the type of traffic.

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • ports

    (Optional, string) A port number or comma-delimited list of port numbers.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • sha256

    (Optional, string) A SHA-256 hash.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

Code Snippet
Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/reports/v2/requests-by-hour/{type}?from=<value>&to=<value>&limit=<value>' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (object)

  • data

    (Required, array (object))

    • count

      (Required, number) The number of requests in the hour.

    • counts

      (Required, object) The information about the requests.

      • requests

        (Optional, number) The total number of requests.

      • allowedrequests

        (Optional, number) The number of requests that were allowed.

      • blockedrequests

        (Optional, number) The number of requests that were blocked.

    • timestamp

      (Required, number) The timestamp represented in milliseconds for the bucket.

    • date

      (Required, string) The date from the timestamp based on the timezone parameter.

    • time

      (Required, string) The time in 24-hour format based on the timezone parameter.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "count": 123,
            "counts": {
                "requests": 123,
                "allowedrequests": 60,
                "blockedrequests": 63
            },
            "timestamp": 1559836800000,
            "date": "2019",
            "time": "16:00:00"
        }
    ],
    "meta": {}
}

Get Requests by Timerange (All)

GET https://api.umbrellagov.com/reports/v2/requests-by-timerange

Description

List the activity volume within the timeframe.

Access Scope: Reports > Granular Events > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • ports

    (Optional, string) A port number or comma-delimited list of port numbers.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

Code Snippet
Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/reports/v2/requests-by-timerange?from=<value>&to=<value>&limit=<value>' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (object)

  • data

    (Required, array (object)) The information about the requests within the timerange.

    • count

      (Required, number) The number of requests in the hour.

    • counts

      (Required, object) The information about the requests.

      • requests

        (Optional, number) The total number of requests.

      • allowedrequests

        (Optional, number) The number of requests that were allowed.

      • blockedrequests

        (Optional, number) The number of requests that were blocked.

    • timestamp

      (Required, number) The timestamp represented in milliseconds for the bucket.

    • date

      (Required, string) The date from the timestamp based on the timezone parameter.

    • time

      (Required, string) The time in 24-hour format based on the timezone parameter.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "count": 123,
            "counts": {
                "requests": 123,
                "allowedrequests": 60,
                "blockedrequests": 63
            },
            "timestamp": 1559836800000,
            "date": "2019",
            "time": "16:00:00"
        }
    ],
    "meta": {}
}

Get Requests by Timerange

GET https://api.umbrellagov.com/reports/v2/requests-by-timerange/{type}

Description

List the activity volume within the timeframe.

Access Scope: Reports > Granular Events > Read-Only

Path Parameters

  • type

    (Required, string) Specify the type of traffic.

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • ports

    (Optional, string) A port number or comma-delimited list of port numbers.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

Code Snippet
Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/reports/v2/requests-by-timerange/{type}?from=<value>&to=<value>&limit=<value>' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (object)

  • data

    (Required, array (object))

    • count

      (Required, number) The number of requests in the hour.

    • counts

      (Required, object) The information about the requests.

      • requests

        (Optional, number) The total number of requests.

      • allowedrequests

        (Optional, number) The number of requests that were allowed.

      • blockedrequests

        (Optional, number) The number of requests that were blocked.

    • timestamp

      (Required, number) The timestamp represented in milliseconds for the bucket.

    • date

      (Required, string) The date from the timestamp based on the timezone parameter.

    • time

      (Required, string) The time in 24-hour format based on the timezone parameter.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "count": 123,
            "counts": {
                "requests": 123,
                "allowedrequests": 60,
                "blockedrequests": 63
            },
            "timestamp": 1559836800000,
            "date": "2019",
            "time": "16:00:00"
        }
    ],
    "meta": {}
}

Get Requests by Hour and Category (All)

GET https://api.umbrellagov.com/reports/v2/categories-by-hour

Description

List the activity volume within the timeframe by type of category.

Access Scope: Reports > Granular Events > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • sha256

    (Optional, string) A SHA-256 hash.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

Code Snippet
Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/reports/v2/categories-by-hour?from=<value>&to=<value>&limit=<value>' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (object)

  • data

    (Required, array (object))

    • timestamp

      (Required, number) The timestamp represented in milliseconds for the bucket.

    • date

      (Required, string) The date from the timestamp based on the timezone parameter.

    • time

      (Required, string) The time in 24-hour format based on the timezone parameter.

    • counts

      (Required, array (object)) The list of counts for the category.

      • category

        (Required, object) The properties of the category.

        • id

          (Optional, number) The ID of the category.

        • label

          (Optional, string) The descriptive label for the category.

        • type

          (Optional, string) The type of the category.

        • integration

          (Optional, boolean) Specifies whether the category is an integration.

        • deprecated

          (Optional, boolean) Specifies whether the category is a legacy category.

      • requests

        (Required, number) The total number of requests for the category.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "timestamp": 1559836800000,
            "date": "2019",
            "time": "16:00:00",
            "counts": [
                {
                    "category": {
                        "id": 66,
                        "label": "Malware",
                        "type": "security",
                        "integration": true
                    },
                    "requests": 123
                }
            ]
        }
    ],
    "meta": {}
}

Get Requests by Hour and Category

GET https://api.umbrellagov.com/reports/v2/categories-by-hour/{type}

Description

List the activity volume for the type of category within the timeframe.

Access Scope: Reports > Granular Events > Read-Only

Path Parameters

  • type

    (Required, string) Specify the type of traffic.

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • sha256

    (Optional, string) A SHA-256 hash.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

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

Response Schema (object)

  • data

    (Required, array (object))

    • timestamp

      (Required, number) The timestamp represented in milliseconds for the bucket.

    • date

      (Required, string) The date from the timestamp based on the timezone parameter.

    • time

      (Required, string) The time in 24-hour format based on the timezone parameter.

    • counts

      (Required, array (object)) The list of counts for the category.

      • category

        (Required, object) The properties of the category.

        • id

          (Optional, number) The ID of the category.

        • label

          (Optional, string) The descriptive label for the category.

        • type

          (Optional, string) The type of the category.

        • integration

          (Optional, boolean) Specifies whether the category is an integration.

        • deprecated

          (Optional, boolean) Specifies whether the category is a legacy category.

      • requests

        (Required, number) The total number of requests for the category.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "timestamp": 1559836800000,
            "date": "2019",
            "time": "16:00:00",
            "counts": [
                {
                    "category": {
                        "id": 66,
                        "label": "Malware",
                        "type": "security",
                        "integration": true
                    },
                    "requests": 123
                }
            ]
        }
    ],
    "meta": {}
}

Get Requests by Timerange and Category (All)

GET https://api.umbrellagov.com/reports/v2/categories-by-timerange

Description

List the activity volume within the timeframe by category.

Access Scope: Reports > Granular Events > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

Code Snippet
Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/reports/v2/categories-by-timerange?from=<value>&to=<value>&limit=<value>' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (object)

  • data

    (Required, array (object))

    • timestamp

      (Required, number) The timestamp represented in milliseconds for the bucket.

    • date

      (Required, string) The date from the timestamp based on the timezone parameter.

    • time

      (Required, string) The time in 24-hour format based on the timezone parameter.

    • counts

      (Required, array (object)) The list of counts for the category.

      • category

        (Required, object) The properties of the category.

        • id

          (Optional, number) The ID of the category.

        • label

          (Optional, string) The descriptive label for the category.

        • type

          (Optional, string) The type of the category.

        • integration

          (Optional, boolean) Specifies whether the category is an integration.

        • deprecated

          (Optional, boolean) Specifies whether the category is a legacy category.

      • requests

        (Required, number) The total number of requests for the category.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "timestamp": 1559836800000,
            "date": "2019",
            "time": "16:00:00",
            "counts": [
                {
                    "category": {
                        "id": 66,
                        "label": "Malware",
                        "type": "security",
                        "integration": true
                    },
                    "requests": 123
                }
            ]
        }
    ],
    "meta": {}
}

Get Requests by Timerange and Category

GET https://api.umbrellagov.com/reports/v2/categories-by-timerange/{type}

Description

List the activity volume within the timeframe by category.

Access Scope: Reports > Granular Events > Read-Only

Path Parameters

  • type

    (Required, string) Specify the type of traffic.

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

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

Response Schema (object)

  • data

    (Required, array (object))

    • timestamp

      (Required, number) The timestamp represented in milliseconds for the bucket.

    • date

      (Required, string) The date from the timestamp based on the timezone parameter.

    • time

      (Required, string) The time in 24-hour format based on the timezone parameter.

    • counts

      (Required, array (object)) The list of counts for the category.

      • category

        (Required, object) The properties of the category.

        • id

          (Optional, number) The ID of the category.

        • label

          (Optional, string) The descriptive label for the category.

        • type

          (Optional, string) The type of the category.

        • integration

          (Optional, boolean) Specifies whether the category is an integration.

        • deprecated

          (Optional, boolean) Specifies whether the category is a legacy category.

      • requests

        (Required, number) The total number of requests for the category.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "timestamp": 1559836800000,
            "date": "2019",
            "time": "16:00:00",
            "counts": [
                {
                    "category": {
                        "id": 66,
                        "label": "Malware",
                        "type": "security",
                        "integration": true
                    },
                    "requests": 123
                }
            ]
        }
    ],
    "meta": {}
}

Get Deployment Status

GET https://api.umbrellagov.com/reports/v2/deployment-status

Description

List the deployment status within the timeframe.

Access Scope: Reports > Granular Events > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

Code Snippet
Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/reports/v2/deployment-status?from=<value>&to=<value>' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (object)

  • data

    (Required, array (object))

    • type

      (Required, object) The information about the identity including the type.

      • id

        (Optional, number) The ID of the origin type for the identity.

      • label

        (Optional, string) The label of the origin type for the identity.

      • type

        (Optional, string) The name of the origin type for the identity.

    • activecount

      (Required, number) The count of the active identity type.

    • count

      (Required, number) The total count of the identity type.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "id": 21,
            "label": "Sites",
            "type": {
                "id": 1,
                "label": "Sites",
                "type": "Sites"
            },
            "activecount": 1,
            "count": 1
        }
    ],
    "meta": {}
}

Get Bandwidth by Hour (All)

GET https://api.umbrellagov.com/reports/v2/bandwidth-by-hour

Description

List the bandwidth in bytes within the timeframe. Only returns proxy data.

Access Scope: Reports > Granular Events > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • sha256

    (Optional, string) A SHA-256 hash.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

Code Snippet
Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/reports/v2/bandwidth-by-hour?from=<value>&to=<value>&limit=<value>' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (object)

  • data

    (Required, array (object))

    • inboundbytes

      (Required, number) The number of inbound bytes.

    • outboundbytes

      (Required, number) The number of outbound bytes.

    • timestamp

      (Required, number) The timestamp represented in milliseconds for the bucket.

    • date

      (Required, string) The date from the timestamp based on the timezone parameter.

    • time

      (Required, string) The time in 24-hour format based on the timezone parameter.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "inboundbytes": 123,
            "outboundbytes": 456,
            "timestamp": 1559836800000,
            "date": "2019",
            "time": "16:00:00"
        }
    ],
    "meta": {}
}

Get Bandwidth by Timerange (All)

GET https://api.umbrellagov.com/reports/v2/bandwidth-by-timerange

Description

List the bandwidth in bytes within the timeframe. Only returns proxy data.

Access Scope: Reports > Granular Events > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • sha256

    (Optional, string) A SHA-256 hash.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

Code Snippet
Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/reports/v2/bandwidth-by-timerange?from=<value>&to=<value>&limit=<value>' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (object)

  • data

    (Required, array (object))

    • inboundbytes

      (Required, number) The number of inbound bytes.

    • outboundbytes

      (Required, number) The number of outbound bytes.

    • timestamp

      (Required, number) The timestamp represented in milliseconds for the bucket.

    • date

      (Required, string) The date from the timestamp based on the timezone parameter.

    • time

      (Required, string) The time in 24-hour format based on the timezone parameter.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "inboundbytes": 123,
            "outboundbytes": 456,
            "timestamp": 1559836800000,
            "date": "2019",
            "time": "16:00:00"
        }
    ],
    "meta": {}
}

Get Top Files (Proxy)

GET https://api.umbrellagov.com/reports/v2/top-files

Description

List the top files within the timeframe. Only returns proxy data.

Access Scope: Reports > Aggregations > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • sha256

    (Optional, string) A SHA-256 hash.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

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

Response Schema (object)

  • data

    (Required, array (object))

    • requests

      (Required, number) The number of requests for the file.

    • sha256

      (Required, string) The SHA256 hash for the entry.

    • categories

      (Required, array (object)) The list of categories.

      • id

        (Optional, number) The ID of the category.

      • label

        (Optional, string) The descriptive label for the category.

      • type

        (Optional, string) The type of the category.

      • integration

        (Optional, boolean) Specifies whether the category is an integration.

      • deprecated

        (Optional, boolean) Specifies whether the category is a legacy category.

    • identitycount

      (Required, number) The count of the identities for the entry.

    • filenames

      (Required, array (string)) The list of filenames for the entry.

    • filetypes

      (Required, array (string)) The list of filetypes for the entry.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "requests": 123,
            "sha256": "9495b6c155044053953efe30ebaf804780c114e7b721b14f6a5b0a782769696e",
            "categories": [
                {
                    "id": 66,
                    "label": "Malware",
                    "type": "security",
                    "integration": true
                }
            ],
            "identitycount": 1,
            "filenames": [],
            "filetypes": []
        }
    ],
    "meta": {}
}

Get Total Requests (All)

GET https://api.umbrellagov.com/reports/v2/total-requests

Description

Get the count of the total requests.

Access Scope: Reports > Aggregations > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • ports

    (Optional, string) A port number or comma-delimited list of port numbers.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • ruleid

    (Optional, number) The firewall policy rule ID.

  • sha256

    (Optional, string) A SHA-256 hash.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

Code Snippet
Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/reports/v2/total-requests?from=<value>&to=<value>' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (object)

  • data

    (Required, object) The total number of requests.

    • count

      (Required, number) The total number of requests.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": {
        "count": 42
    },
    "meta": {}
}

Get Total Requests (By Type)

GET https://api.umbrellagov.com/reports/v2/total-requests/{type}

Description

Get the count of the total requests for the request type.

Access Scope: Reports > Aggregations > Read-Only

Path Parameters

  • type

    (Required, string) Specify the type of traffic.

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • ports

    (Optional, string) A port number or comma-delimited list of port numbers.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • ruleid

    (Optional, number) The firewall policy rule ID.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

Code Snippet
Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/reports/v2/total-requests/{type}?from=<value>&to=<value>' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (object)

  • data

    (Required, object) The total number of requests.

    • count

      (Required, number) The total number of requests.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": {
        "count": 42
    },
    "meta": {}
}

Get Top Threats (All)

GET https://api.umbrellagov.com/reports/v2/top-threats

Description

Get the top threats within the timeframe. Returns both DNS and proxy data.

Access Scope: Reports > Aggregations > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

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

Response Schema (object)

  • data

    (Required, array (object))

    • threat

      (Required, string) The name of the threat.

    • threattype

      (Required, string) The type of the threat.

    • count

      (Required, number) The number of requests for the threat name.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "threat": "Wannacry",
            "threattype": "Ransomware",
            "count": 361
        }
    ],
    "meta": {}
}

Get Top Threats (By Type)

GET https://api.umbrellagov.com/reports/v2/top-threats/{type}

Description

Get the top threats within the timeframe.

Access Scope: Reports > Aggregations > Read-Only

Path Parameters

  • type

    (Required, string) Specify the type of traffic.

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

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

Response Schema (object)

  • data

    (Required, array (object))

    • threat

      (Required, string) The name of the threat.

    • threattype

      (Required, string) The type of the threat.

    • count

      (Required, number) The number of requests for the threat name.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "threat": "Wannacry",
            "threattype": "Ransomware",
            "count": 361
        }
    ],
    "meta": {}
}

Get Top Threat Types (All)

GET https://api.umbrellagov.com/reports/v2/top-threat-types

Description

List the top types of threat within the timeframe. Returns both DNS and proxy data.

Access Scope: Reports > Aggregations > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

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

Response Schema (object)

  • data

    (Required, array (object))

    • threattype

      (Required, string) The type of the threat.

    • threatscount

      (Required, number) The count of the threats for the threat type.

    • count

      (Required, number) The number of requests for the threat type.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "threattype": "Ransomware",
            "threatscount": 10,
            "count": 361
        }
    ],
    "meta": {}
}

Get Top Threat Types By Type

GET https://api.umbrellagov.com/reports/v2/top-threat-types/{type}

Description

List the top threat-types within the timeframe.

Access Scope: Reports > Aggregations > Read-Only

Path Parameters

  • type

    (Required, string) Specify the type of traffic.

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

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

Response Schema (object)

  • data

    (Required, array (object))

    • threattype

      (Required, string) The type of the threat.

    • threatscount

      (Required, number) The count of the threats for the threat type.

    • count

      (Required, number) The number of requests for the threat type.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "threattype": "Ransomware",
            "threatscount": 10,
            "count": 361
        }
    ],
    "meta": {}
}

Get Applications

GET https://api.umbrellagov.com/reports/v2/applications

Description

List the applications.

Access Scope: Reports > Utilities > Read-Only

Query Parameters

  • application

    (Optional, string) Filter on the name of the application.


Request Sample

Code Snippet
Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/reports/v2/applications' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (object)

  • data

    (Required, object) The information about the applications and categories.

    • applications

      (Optional, array (object)) The list of applications.

      • id

        (Optional, number) The ID of the application.

      • label

        (Optional, string) The descriptive label for the application.

      • type

        (Optional, string) The type of the application: NBAR or AVC.

      • category

        (Optional, object) The category of the application.

        • id

          (Optional, number) The ID of the application category.

        • label

          (Optional, string) The label of the application category.

    • categories

      (Optional, array (object)) The list of application categories.

      • id

        (Optional, number) The ID of the application category.

      • name

        (Optional, string) The name of the application category.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": {
        "applications": [
            {
                "id": 1,
                "label": "Web Hosting",
                "type": "AVC",
                "category": {
                    "id": 40,
                    "label": "Hosting Services"
                }
            }
        ],
        "categories": [
            {
                "id": 42,
                "name": "Education"
            }
        ]
    },
    "meta": {}
}

Get Categories

GET https://api.umbrellagov.com/reports/v2/categories

Description

List the categories.

Access Scope: Reports > Utilities > Read-Only


Request Sample

Code Snippet
Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/reports/v2/categories' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (object)

  • data

    (Required, array (object))

    • id

      (Required, number) The ID of the category.

    • legacyid

      (Required, number) The legacy category ID.

    • label

      (Required, string) The label of the category.

    • type

      (Required, string) The type of the category.

    • integration

      (Required, boolean) Specifies whether the category is an integration.

    • deprecated

      (Required, boolean) Specifies whether the legacy category is deprecated.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "id": 66,
            "legacyid": 94,
            "label": "Malware",
            "type": "security",
            "integration": true,
            "deprecated": true
        },
        {
            "id": 110,
            "legacyid": 176,
            "label": "DNS Tunneling VPN",
            "type": "security",
            "integration": true,
            "deprecated": false
        }
    ],
    "meta": {}
}

Get Identities

GET https://api.umbrellagov.com/reports/v2/identities

Description

List the identities.

Access Scope: Reports > Utilities > Read-Only

Query Parameters

  • limit

    (Required, number) (Identities utility endpoint) The number of records to return from the collection. The default limit is 100. In a single response, the server returns at most 5000 records from the collection.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • search

    (Optional, string) A string that represents a search parameter. Filter data for requests where the search string appears in the endpoint data.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.


Request Sample

Code Snippet
Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/reports/v2/identities?limit=<value>' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (object)

  • data

    (Required, array (object))

    • id

      (Required, number) The ID of the identity.

    • label

      (Required, string) The descriptive label for the identity.

    • type

      (Required, object) The information about the identity including the type.

      • id

        (Optional, number) The ID of the origin type for the identity.

      • label

        (Optional, string) The label of the origin type for the identity.

      • type

        (Optional, string) The name of the origin type for the identity.

    • deleted

      (Required, boolean) Indicates whether the identity was deleted.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "id": 1,
            "label": "Catch Rate Testing System",
            "type": {
                "id": 21,
                "label": "Sites",
                "type": "site"
            },
            "deleted": false
        }
    ],
    "meta": {}
}

Get Identities By IDs

POST https://api.umbrellagov.com/reports/v2/identities

Description

Get the identities information by providing a list of identity IDs in the request body.

Access Scope: Reports > Utilities > Read-Only

Query Parameters

  • limit

    (Required, number) The maximum number of records to return from the collection.

Request Body Schema (object)

  • identityids

    (Optional, array (integer)) A list of identity ID.


Request Sample

Code Snippet
Copy
curl -L --location-trusted --request POST --url 'https://api.umbrellagov.com/reports/v2/identities?limit=<value>' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json' \
-d '{
    "identityids": [
        234567891,
        234567892
    ]
}'

Response Schema (object)

  • data

    (Required, array (object))

    • id

      (Required, number) The ID of the identity.

    • label

      (Required, string) The descriptive label for the identity.

    • type

      (Required, object) The information about the identity including the type.

      • id

        (Optional, number) The ID of the origin type for the identity.

      • label

        (Optional, string) The label of the origin type for the identity.

      • type

        (Optional, string) The name of the origin type for the identity.

    • deleted

      (Required, boolean) Indicates whether the identity was deleted.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "id": 1,
            "label": "Catch Rate Testing System",
            "type": {
                "id": 21,
                "label": "Sites",
                "type": "site"
            },
            "deleted": false
        }
    ],
    "meta": {}
}

Get Identity

GET https://api.umbrellagov.com/reports/v2/identities/{identityid}

Description

Get identity by identity ID.

Access Scope: Reports > Utilities > Read-Only

Path Parameters

  • identityid

    (Required, number) An identity ID.


Request Sample

Code Snippet
Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/reports/v2/identities/{identityid}' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (object)

  • data

    (Required, object) The information about the identity.

    • id

      (Required, number) The ID of the identity.

    • label

      (Required, string) The descriptive label for the identity.

    • type

      (Required, object) The information about the identity including the type.

      • id

        (Optional, number) The ID of the origin type for the identity.

      • label

        (Optional, string) The label of the origin type for the identity.

      • type

        (Optional, string) The name of the origin type for the identity.

    • deleted

      (Required, boolean) Indicates whether the identity was deleted.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": {
        "id": 1,
        "label": "Catch Rate Testing System",
        "type": {
            "id": 21,
            "label": "Sites",
            "type": "site"
        },
        "deleted": true
    },
    "meta": {}
}

Get Threat Types

GET https://api.umbrellagov.com/reports/v2/threat-types

Description

List the threat types.

Access Scope: Reports > Utilities > Read-Only


Request Sample

Code Snippet
Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/reports/v2/threat-types' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (object)

  • data

    (Required, array (object))

    • name

      (Required, string) The name of the threat type.

    • description

      (Required, string) The name of the threat type.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "name": "Ransomware",
            "description": "a description"
        }
    ],
    "meta": {}
}

Get Threat Type By Threat ID

GET https://api.umbrellagov.com/reports/v2/threat-types/{threattypeid}

Description

List the threat types by threat ID.

Access Scope: Reports > Utilities > Read-Only

Path Parameters

  • threattypeid

    (Required, string) The name of the threat type.


Request Sample

Code Snippet
Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/reports/v2/threat-types/{threattypeid}' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (object)

  • data

    (Required, object) The properties of the threat type.

    • name

      (Required, string) The name of the threat type.

    • description

      (Required, string) The name of the threat type.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": {
        "name": "Ransomware",
        "description": "a description"
    },
    "meta": {}
}

Get Threat Names

GET https://api.umbrellagov.com/reports/v2/threat-names

Description

List the threat names.

Access Scope: Reports > Utilities > Read-Only


Request Sample

Code Snippet
Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/reports/v2/threat-names' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (object)

  • data

    (Required, array (object))

    • name

      (Required, string) The name of the threat.

    • description

      (Required, string) The description of the threat name.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "name": "WannaCry",
            "description": "a description"
        }
    ],
    "meta": {}
}

Get Threat Name By Threat ID

GET https://api.umbrellagov.com/reports/v2/threat-names/{threatnameid}

Description

Get the threat name by threat ID.

Access Scope: Reports > Utilities > Read-Only

Path Parameters

  • threatnameid

    (Required, string) The name of the threat.


Request Sample

Code Snippet
Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/reports/v2/threat-names/{threatnameid}' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (object)

  • data

    (Required, object) The properties of the threat name.

    • name

      (Required, string) The name of the threat.

    • description

      (Required, string) The description of the threat name.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": {
        "name": "WannaCry",
        "description": "WannaCry threat description"
    },
    "meta": {}
}

Get Top IPs

GET https://api.umbrellagov.com/reports/v2/top-ips

Description

List the top IP addresses.

Access Scope: Reports > Aggregations > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

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

Response Schema (object)

  • data

    (Required, array (object))

    • ip

      (Required, string) The comma-delimited list of IP addresses.

    • count

      (Required, number) The number of requests to the top IP addresses.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "ip": "10.0.0.1",
            "count": 42
        }
    ],
    "meta": {}
}

Get Top IPs Internal

GET https://api.umbrellagov.com/reports/v2/top-ips/internal

Description

List the top internal IP addresses.

Access Scope: Reports > Aggregations > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

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

Response Schema (object)

  • data

    (Required, array (object))

    • ip

      (Required, string) The comma-delimited list of IP addresses.

    • count

      (Required, number) The number of requests to the top IP addresses.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "ip": "10.0.0.1",
            "count": 42
        }
    ],
    "meta": {}
}

Get Summary (All)

GET https://api.umbrellagov.com/reports/v2/summary

Description

Get the summary report.

Access Scope: Reports > Aggregations > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • ports

    (Optional, string) A port number or comma-delimited list of port numbers.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • ruleid

    (Optional, number) The firewall policy rule ID.

  • filename

    (Optional, string) A string that identifies a filename. Filter the request by the filename. Supports globbing or use of the wildcard character (''). The asterisk () matches zero or more occurrences of any character.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

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

Response Schema (object)

  • data

    (Required, object) The summary information about the requests.

    • applications

      (Required, number) The total number of applications (avc or total).

    • domains

      (Required, number) The total number of domains.

    • requestsblocked

      (Required, number) The total number of domains.

    • filetypes

      (Required, number) The total number of domains.

    • policycategories

      (Required, number) The total number of blocked categories.

    • policyrequests

      (Required, number) The total number of policy requests.

    • requests

      (Required, number) The total number of requests.

    • requestsallowed

      (Required, number) The total number of allowed requests.

    • categories

      (Required, number) The total number of categories.

    • identitytypes

      (Required, number) The total number of identity types.

    • applicationsblocked

      (Required, number) The total number of blocked applications.

    • files

      (Required, number) The total number of files.

    • identities

      (Required, number) The total number of identities.

    • applicationsallowed

      (Required, number) The total number of allowed applications.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": {
        "applications": 123,
        "domains": 82,
        "requestsblocked": 189,
        "filetypes": 0,
        "policycategories": 2,
        "policyrequests": 2,
        "requests": 189,
        "requestsallowed": 10,
        "categories": 11,
        "identitytypes": 1,
        "applicationsblocked": 2,
        "files": 5,
        "identities": 1,
        "applicationsallowed": 2
    },
    "meta": {}
}

Get Summary By Type

GET https://api.umbrellagov.com/reports/v2/summary/{type}

Description

Get the summary of requests by the traffic type.

Access Scope: Reports > Aggregations > Read-Only

Path Parameters

  • type

    (Required, string) Specify the type of traffic.

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • ports

    (Optional, string) A port number or comma-delimited list of port numbers.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • ruleid

    (Optional, number) The firewall policy rule ID.

  • filename

    (Optional, string) A string that identifies a filename. Filter the request by the filename. Supports globbing or use of the wildcard character (''). The asterisk () matches zero or more occurrences of any character.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).

  • timezone

    (Optional, string) Display the timestamp of the traffic events in the specified timezone. For the timezone, provide a continent and city separated by an url-encoded forward slash ('/'), for example: timezone='ASIA%2fCALCUTTA'.


Request Sample

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

Response Schema (object)

  • data

    (Required, object) The summary information about the requests.

    • applications

      (Required, number) The total number of applications (avc or total).

    • domains

      (Required, number) The total number of domains.

    • requestsblocked

      (Required, number) The total number of domains.

    • filetypes

      (Required, number) The total number of domains.

    • policycategories

      (Required, number) The total number of blocked categories.

    • policyrequests

      (Required, number) The total number of policy requests.

    • requests

      (Required, number) The total number of requests.

    • requestsallowed

      (Required, number) The total number of allowed requests.

    • categories

      (Required, number) The total number of categories.

    • identitytypes

      (Required, number) The total number of identity types.

    • applicationsblocked

      (Required, number) The total number of blocked applications.

    • files

      (Required, number) The total number of files.

    • identities

      (Required, number) The total number of identities.

    • applicationsallowed

      (Required, number) The total number of allowed applications.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": {
        "applications": 123,
        "domains": 82,
        "requestsblocked": 189,
        "filetypes": 0,
        "policycategories": 2,
        "requests": 189,
        "requestsallowed": 10,
        "categories": 11,
        "identitytypes": 1,
        "applicationsblocked": 2,
        "files": 5,
        "identities": 1,
        "applicationsallowed": 2,
        "policyrequests": 3
    },
    "meta": {}
}

Get Summaries by Category (All)

GET https://api.umbrellagov.com/reports/v2/summaries-by-category

Description

List the summaries of requests by category.

Access Scope: Reports > Aggregations > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • ruleid

    (Optional, number) The firewall policy rule ID.

  • filename

    (Optional, string) A string that identifies a filename. Filter the request by the filename. Supports globbing or use of the wildcard character (''). The asterisk () matches zero or more occurrences of any character.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).


Request Sample

Code Snippet
Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/reports/v2/summaries-by-category?from=<value>&to=<value>&limit=<value>' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (object)

  • data

    (Required, array (object))

    • category

      (Required, object) The properties of the category.

      • id

        (Optional, number) The ID of the category.

      • label

        (Optional, string) The descriptive label for the category.

      • type

        (Optional, string) The type of the category.

      • integration

        (Optional, boolean) Specifies whether the category is an integration.

      • deprecated

        (Optional, boolean) Specifies whether the category is a legacy category.

    • summary

      (Required, object) The summary information about the requests.

      • applications

        (Required, number) The total number of applications (avc or total).

      • domains

        (Required, number) The total number of domains.

      • requestsblocked

        (Required, number) The total number of domains.

      • filetypes

        (Required, number) The total number of domains.

      • policycategories

        (Required, number) The total number of blocked categories.

      • policyrequests

        (Required, number) The total number of policy requests.

      • requests

        (Required, number) The total number of requests.

      • requestsallowed

        (Required, number) The total number of allowed requests.

      • categories

        (Required, number) The total number of categories.

      • identitytypes

        (Required, number) The total number of identity types.

      • applicationsblocked

        (Required, number) The total number of blocked applications.

      • files

        (Required, number) The total number of files.

      • identities

        (Required, number) The total number of identities.

      • applicationsallowed

        (Required, number) The total number of allowed applications.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "category": {
                "id": 66,
                "label": "Malware",
                "type": "security",
                "integration": true
            },
            "summary": {
                "applications": 123,
                "domains": 82,
                "requestsblocked": 189,
                "filetypes": 0,
                "policycategories": 2,
                "requests": 189,
                "requestsallowed": 10,
                "categories": 11,
                "identitytypes": 1,
                "applicationsblocked": 2,
                "files": 5,
                "identities": 1,
                "applicationsallowed": 2,
                "policyrequests": 6
            }
        }
    ],
    "meta": {}
}

Get Summaries by Category For Type

GET https://api.umbrellagov.com/reports/v2/summaries-by-category/{type}

Description

List the summaries by category for the type of request.

Access Scope: Reports > Aggregations > Read-Only

Path Parameters

  • type

    (Required, string) Specify the type of traffic.

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • ruleid

    (Optional, number) The firewall policy rule ID.

  • filename

    (Optional, string) A string that identifies a filename. Filter the request by the filename. Supports globbing or use of the wildcard character (''). The asterisk () matches zero or more occurrences of any character.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).


Request Sample

Code Snippet
Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/reports/v2/summaries-by-category/{type}?from=<value>&to=<value>&limit=<value>' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (object)

  • data

    (Required, array (object))

    • category

      (Required, object) The properties of the category.

      • id

        (Optional, number) The ID of the category.

      • label

        (Optional, string) The descriptive label for the category.

      • type

        (Optional, string) The type of the category.

      • integration

        (Optional, boolean) Specifies whether the category is an integration.

      • deprecated

        (Optional, boolean) Specifies whether the category is a legacy category.

    • summary

      (Required, object) The summary information about the requests.

      • applications

        (Required, number) The total number of applications (avc or total).

      • domains

        (Required, number) The total number of domains.

      • requestsblocked

        (Required, number) The total number of domains.

      • filetypes

        (Required, number) The total number of domains.

      • policycategories

        (Required, number) The total number of blocked categories.

      • policyrequests

        (Required, number) The total number of policy requests.

      • requests

        (Required, number) The total number of requests.

      • requestsallowed

        (Required, number) The total number of allowed requests.

      • categories

        (Required, number) The total number of categories.

      • identitytypes

        (Required, number) The total number of identity types.

      • applicationsblocked

        (Required, number) The total number of blocked applications.

      • files

        (Required, number) The total number of files.

      • identities

        (Required, number) The total number of identities.

      • applicationsallowed

        (Required, number) The total number of allowed applications.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "category": {
                "id": 66,
                "label": "Malware",
                "type": "security",
                "integration": true
            },
            "summary": {
                "applications": 123,
                "domains": 82,
                "requestsblocked": 189,
                "filetypes": 0,
                "policycategories": 2,
                "requests": 189,
                "requestsallowed": 10,
                "categories": 11,
                "identitytypes": 1,
                "applicationsblocked": 2,
                "files": 5,
                "identities": 1,
                "applicationsallowed": 2,
                "policyrequests": 4
            }
        }
    ],
    "meta": {}
}

Get Summaries by Destination (All)

GET https://api.umbrellagov.com/reports/v2/summaries-by-destination

Description

List the summaries by destination.

Access Scope: Reports > Aggregations > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • ruleid

    (Optional, number) The firewall policy rule ID.

  • filename

    (Optional, string) A string that identifies a filename. Filter the request by the filename. Supports globbing or use of the wildcard character (''). The asterisk () matches zero or more occurrences of any character.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).


Request Sample

Code Snippet
Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/reports/v2/summaries-by-destination?from=<value>&to=<value>&limit=<value>' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (object)

  • data

    (Required, array (object))

    • domain

      (Required, string) destination domain

    • summary

      (Required, object) The summary information about the requests.

      • applications

        (Required, number) The total number of applications (avc or total).

      • domains

        (Required, number) The total number of domains.

      • requestsblocked

        (Required, number) The total number of domains.

      • filetypes

        (Required, number) The total number of domains.

      • policycategories

        (Required, number) The total number of blocked categories.

      • policyrequests

        (Required, number) The total number of policy requests.

      • requests

        (Required, number) The total number of requests.

      • requestsallowed

        (Required, number) The total number of allowed requests.

      • categories

        (Required, number) The total number of categories.

      • identitytypes

        (Required, number) The total number of identity types.

      • applicationsblocked

        (Required, number) The total number of blocked applications.

      • files

        (Required, number) The total number of files.

      • identities

        (Required, number) The total number of identities.

      • applicationsallowed

        (Required, number) The total number of allowed applications.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "domain": "www.google.com",
            "summary": {
                "applications": 123,
                "domains": 82,
                "requestsblocked": 189,
                "filetypes": 0,
                "policycategories": 2,
                "policyrequests": 2,
                "requests": 189,
                "requestsallowed": 10,
                "categories": 11,
                "identitytypes": 1,
                "applicationsblocked": 2,
                "files": 5,
                "identities": 1,
                "applicationsallowed": 2
            }
        }
    ],
    "meta": {}
}

Get Summaries by Destination For Type

GET https://api.umbrellagov.com/reports/v2/summaries-by-destination/{type}

Description

List the summaries by destination for the type of traffic.

Access Scope: Reports > Aggregations > Read-Only

Path Parameters

  • type

    (Required, string) Specify the type of traffic.

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • domains

    (Optional, string) A domain name or comma-delimited list of domain name.

  • urls

    (Optional, string) A URL or comma-delimited list of URL.

  • categories

    (Optional, string) A category ID or comma-delimited list of category ID.

  • policycategories

    (Optional, string) A category ID or comma-delimited list of category ID. Filter the request by the categories that trigger a policy.

  • ip

    (Optional, string) An IP address.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • applicationid

    (Optional, string) The ID of the application.

  • verdict

    (Optional, string) A string or comma-delimited string that describes whether the traffic can reach the destination.

  • ruleid

    (Optional, number) The firewall policy rule ID.

  • filename

    (Optional, string) A string that identifies a filename. Filter the request by the filename. Supports globbing or use of the wildcard character (''). The asterisk () matches zero or more occurrences of any character.

  • securityoverridden

    (Optional, boolean) Specify whether to filter on requests that override security.

  • bundleid

    (Optional, number) A proxy bundle ID.

  • threats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • threattypes

    (Optional, string) A threat type or comma-delimited list of threat types.

  • ampdisposition

    (Optional, string) An AMP disposition string or a comma-delimited list of AMP disposition strings.

  • antivirusthreats

    (Optional, string) A threat name or comma-delimited list of threat names.

  • datalosspreventionstate

    (Optional, string) A string that describes the status of a destination. Filter for requests that are blocked by the DLP layer security.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).


Request Sample

Code Snippet
Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/reports/v2/summaries-by-destination/{type}?from=<value>&to=<value>&limit=<value>' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (object)

  • data

    (Required, array (object))

    • domain

      (Required, string) destination domain

    • summary

      (Required, object) The summary information about the requests.

      • applications

        (Required, number) The total number of applications (avc or total).

      • domains

        (Required, number) The total number of domains.

      • requestsblocked

        (Required, number) The total number of domains.

      • filetypes

        (Required, number) The total number of domains.

      • policycategories

        (Required, number) The total number of blocked categories.

      • policyrequests

        (Required, number) The total number of policy requests.

      • requests

        (Required, number) The total number of requests.

      • requestsallowed

        (Required, number) The total number of allowed requests.

      • categories

        (Required, number) The total number of categories.

      • identitytypes

        (Required, number) The total number of identity types.

      • applicationsblocked

        (Required, number) The total number of blocked applications.

      • files

        (Required, number) The total number of files.

      • identities

        (Required, number) The total number of identities.

      • applicationsallowed

        (Required, number) The total number of allowed applications.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "domain": "www.google.com",
            "summary": {
                "applications": 123,
                "domains": 82,
                "requestsblocked": 189,
                "filetypes": 0,
                "policycategories": 2,
                "policyrequests": 2,
                "requests": 189,
                "requestsallowed": 10,
                "categories": 11,
                "identitytypes": 1,
                "applicationsblocked": 2,
                "files": 5,
                "identities": 1,
                "applicationsallowed": 2
            }
        }
    ],
    "meta": {}
}

Get Summaries by Rule

GET https://api.umbrellagov.com/reports/v2/summaries-by-rule/intrusion

Description

List the summaries by rule for the intrusion type.

Access Scope: Reports > Summaries by rule > Read-Only

Query Parameters

  • from

    (Required, string) A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time.

  • to

    (Required, string) A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time.

  • offset

    (Optional, number) A number that represents an index in the collection.

  • limit

    (Required, number) The maximum number of records to return from the collection.

  • signatures

    (Optional, string) The signature or comma-separated list of - signatures.

  • signaturelistids

    (Optional, string) The signature ID or comma-separated list of signature list IDs.

  • ip

    (Optional, string) An IP address.

  • identityids

    (Optional, string) An identity ID or comma-delimited list of identity IDs.

  • identitytypes

    (Optional, string) An identity type or comma-delimited list of identity types.

  • intrusionaction

    (Optional, string) An action or list of comma-separated intrusion actions. Valid values are: would_block, blocked, and detected.

  • ports

    (Optional, string) A port number or comma-delimited list of port numbers.

  • filternoisydomains

    (Optional, boolean) Filter out domains that generate a lot of insignificant traffic (noise).


Request Sample

Code Snippet
Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/reports/v2/summaries-by-rule/intrusion?from=<value>&to=<value>&limit=<value>' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (object)

  • data

    (Required, array (object))

    • signaturelist

      (Optional, object) The properties of the signature list.

      • id

        (Required, number) The unique ID assigned to a default or custom signature list.

    • signatures

      (Optional, array (object)) The list of information about the signatures.

      • generatorid

        (Optional, number) The generator ID of the signature.

      • id

        (Optional, number) The ID of the signature.

      • lasteventat

        (Optional, number) The date and time in milliseconds of the last event.

      • counts

        (Optional, object)

        • blocked

          (Required, number) The number of blocked signatures.

        • detected

          (Required, number) The number of detected signatures.

        • wouldblock

          (Required, number) The number of signatures to block.

    • rule

      (Optional, object) The properties of the rule parameter.

      • id

        (Optional, number) The ID of the ruleset for the signature.

  • meta

    (Required, object) The properties of the metadata.

Response Sample

Click to view the sample response (200, OK)
Code Snippet
Copy{
    "data": [
        {
            "signaturelist": {
                "id": 1111
            },
            "signatures": [
                {
                    "counts": {
                        "blocked": 0,
                        "detected": 1,
                        "wouldblock": 0
                    },
                    "generatorid": 1,
                    "lasteventat": 1594557262000,
                    "id": 47829
                }
            ],
            "rule": {
                "id": 47
            }
        }
    ],
    "meta": {}
}
Next