Request Samples

To get started, register a list of domains with Umbrella Investigate. For more information, see Post Domains and List Category and Status Information.

Get Domain Status and Category

Get the domain status, and security and content category information.

GET /domains/categorization/{domain}

Request Path Parameters

Request Query Parameters

Request

curl -i GET "https://investigate.api.umbrella.com/domains/categorization/example.com?showlabels" \
-H 'Authorization: Bearer %YourToken%' \
-H 'Content-Type: application/json'

Response

Sample response (200, OK):

{
    "example.com": {
      "status": 1,
      "security_categories": [],
      "content_categories": ["Ecommerce/Shopping"]
    }
}

Post Domains and List Category and Status Information

List security settings, categories, and status information for the list of domains provided in the request body. In a single request, the payload must not exceed 100KB and contain no more than 1000 domains. The status is a numerical value determined by the Cisco Security Labs team. The valid status values are: '-1' (malicious), '1' (safe), or '0' (undetermined status).

POST /domains/categorization

Request Query Parameters

Request Body Parameters

Request

curl -i -X POST "https://investigate.api.umbrella.com/domains/categorization" \
-H 'Authorization: Bearer %YourToken%' \
-H 'Content-Type: application/json'
-d '["example.com", "amazon.com"]'

Response

Sample response (200, OK):

[
    "example.com": {
      "status": 1,
      "security_categories": [],
      "content_categories": ["23"]
    },
    "amazon.com": {
      "status": 1,
      "security_categories": [],
      "content_categories": ["8"]
    }
]

Get Domain Query Volume

List the number of domain requests (query volume) in the last 30 days.

GET /domains/volume/{domain}

Request Path Parameters

Request Query Parameters

Request

curl -i GET "https://investigate.api.umbrella.com/domains/volume/{domain}" \
-H 'Authorization: Bearer %YourToken%' \
-H 'Content-Type: application/json'

Response

Sample response (200, OK):

{
    "dates": [
      "1510873200000",
      "1510959600000"
    ],
    "queries": [
      "1238823",
      "1245126",
      "1215994",
      "1256917",
      "1200190",
      "1245963",
      "1355719",
      "1332685",
      "1319825",
      "1362464",
      "1457174",
      "1695448"
    ]
}

Get Co-occurring Domains

List the domains accessed at the same time as the requested domain.

GET /recommendations/name/{domain}.json

Request Path Parameters

Request

curl -i GET "https://investigate.api.umbrella.com/recommendations/name/{domain}.json" \
-H 'Authorization: Bearer %YourToken%' \
-H 'Content-Type: application/json'

Response

Sample response (200, OK):

{
    "pfs2": [
      "download.example.com",
      "query.example.com"
    ],
    "found": true
}

Get Passive DNS Data

The Umbrella Investigate API includes four Passive DNS endpoints:

• GET /pdns/name/{domain}

  Get information from the passive DNS endpoint (historical data from our resolvers for domains and IPs), and other resource records.

• GET /pdns/domain/{domain}

  Get the Resource Record (RR) data for DNS responses and categorization data, where the answer (or rdata) is the domains.

• GET /pdns/ip/{ip}

  Get the Resource Record (RR) data for DNS responses and categorization data, where the answer (or rdata) is the domains.

• GET /pdns/raw/{anystring}

  Get the Resource Record (RR) data for DNS responses and categorization data, where the answer (or rdata) could be any type of data.

Request Path Parameters

/pdns/name/{domain}

/pdns/domain/{domain}

/pdns/ip/{ip}

/pdns/raw/{anystring}

Request Query Parameters

For each Passive DNS endpoint, you can set the following request query parameters:

Security Categories

To filter Passive DNS records, provide a comma-separated list of security category strings. For example:

Dynamic DNS,Malware,Cryptomining

Note: Security category strings are case-sensitive.

Security Categories:

• Drive-by Downloads/Exploits
• Mobile Threats
• Dynamic DNS
• High Risk Sites and Locations
• Command and Control
• Malware
• Phishing
• Newly Seen Domains
• Potentially Harmful
• DNS Tunneling VPN
• Cryptomining

Sample Passive DNS Request

curl -i GET "https://investigate.api.umbrella.com/pdns/raw/{anystring}" \
-H 'Authorization: Bearer %YourToken%' \
-H 'Content-Type: application/json'

Response

Sample response (200, OK):

[
    {
      "minTtl": 3600,
      "maxTtl": 3600,
      "firstSeen": 1544386020,
      "lastSeen": 1555327199,
      "name": "926723159-3188410",
      "type": "TXT",
      "rr": "cisco.com",
      "securityCategories": [],
      "contentCategories": [
        "Software/Technology",
        "Business Services"
        ],
      "firstSeenISO": "2018-12-09T20:07Z",
      "lastSeenISO": "2019-04-15T11:19Z"
    }
]

Get Tagging Timeline

List the historical tagging timeline for an IP address, a domain, or a URL.

GET /timeline/{name}

Request Path Parameters

Request

curl -i GET "https://investigate.api.umbrella.com/timeline/{name}" \
-H 'Authorization: Bearer %YourToken%' \
-H 'Content-Type: application/json'

Response

Sample response (200, OK):

[
    {
      "categories": [
        "Malware"
      ],
      "attacks": [],
      "threatTypes": [],
      "timestamp": 1561574807853
    },
    {
      "categories": [],
      "attacks": [
        "Trojan"
      ],
      "threatTypes": [],
      "timestamp": 1559545774604
    }
]

Security Categories

• Drive-by Downloads/Exploits
• Mobile Threats
• Dynamic DNS
• High Risk Sites and Locations
• Command and Control
• Malware
• Phishing
• Newly Seen Domains
• Potentially Harmful
• DNS Tunneling VPN
• Cryptomining

Get Subdomains of Domain

Get the subdomains of the domain, and list the security categories and time when the subdomain was first related to the domain in the resource record.

GET /subdomains/{domain}

Request Path Parameters

Request Query Parameters

Request

curl -i GET "https://investigate.api.umbrella.com/subdomains/{domain}" \
-H 'Authorization: Bearer %YourToken%' \
-H 'Content-Type: application/json'

Response

Sample response (200, OK):

[
  {
    "securityCategories": [
        "Cryptomining"
      ],
    "firstSeen": 1612088333,
    "name": "api.c3pool.com"
  },
  {
    "securityCategories": [
        "Cryptomining"
      ],
    "firstSeen": 1615427410,
    "name": "asia.c3pool.com"
  }
]

Security Categories

• Drive-by Downloads/Exploits
• Mobile Threats
• Dynamic DNS
• High Risk Sites and Locations
• Command and Control
• Malware
• Phishing
• Newly Seen Domains
• Potentially Harmful
• DNS Tunneling VPN
• Cryptomining

Get Related Domains

List the domain names frequently requested around the same time (up to 60 seconds before or after) as the given domain name.

GET /links/name/{domain}

Request Path Parameters

Request

curl -i GET "https://investigate.api.umbrella.com/links/name/example.com" \
-H 'Authorization: Bearer %YourToken%' \
-H 'Content-Type: application/json'

Response

Sample response (200, OK):

{
    "tb1": [
      {
        "www.example1.com",
        10
      },
      {
        "info.example2.com.com",
        9
      },
      {
        "support.example.com",
        3
      }
    ],
    "found": true
}

Get Security Domain Information

List multiple scores or security features to gain insight into the reputation or security risk of the site.

GET /security/name/{domain}

Request Path Parameters

Request

curl -i GET "https://investigate.api.umbrella.com/security/name/example.com" \
-H 'Authorization: Bearer %YourToken%' \
-H 'Content-Type: application/json'

Response

Sample response (200, OK):

{
    "dga_score": 38.301771886101335,
    "perplexity": 0.4540313302593146,
    "entropy": 2.5216406363433186,
    "securerank2": -1.3135141095601992,
    "pagerank": 0.0262532,
    "asn_score": -29.75810625887133,
    "prefix_score": -64.9070502788884,
    "rip_score": -75.64720536038982,
    "popularity": 25.335450495507196,
    "geodiversity": [
      0.24074075,
      0.018518519
    ],
    "geodiversity_normalized": [
      0.3761535390278368,
      0.0005015965168831449
    ],
    "tld_geodiversity": [],
    "geoscore": 0,
    "ks_test": 0,
    "attack": "",
    "threat_type": "",
    "found": true
}

Get Risk Score

Get the risk score for the domain. Umbrella Investigate scores the domain from 0 to 100. A score of 100 represents the highest risk whereas a score of 0 indicates no risk. A domain blocked by Umbrella receives a score of 100.

GET /domains/risk-score/{domain}

Request Path Parameters

Request

curl -i GET "https://investigate.api.umbrella.com/domains/risk-score/example.com" \
-H 'Authorization: Bearer %YourToken%' \
-H 'Content-Type: application/json'

Response

Sample response (200, OK):

{
  "indicators": [
      {"indicator": "Geo Popularity Score", "normalized_score": 2, "score": -3.610878169999999},
      {"indicator": "Keyword Score", "normalized_score": 3, "score": 0.03586190445512534},
      {"indicator": "Lexical", "normalized_score": 52, "score": 0.525},
      {"indicator": "Popularity 1 Day", "normalized_score": 100, "score": 113.14},
      {"indicator": "Popularity 30 Day", "normalized_score": 100, "score": 112.01},
      {"indicator": "Popularity 7 Day", "normalized_score": 100, "score": 112.86},
      {"indicator": "Popularity 90 Day", "normalized_score": 100, "score": 111.4},
      {"indicator": "TLD Rank Score", "normalized_score": 1, "score": 0.010000315765229171},
      {"indicator": "Umbrella Block Status", "normalized_score": 0, "score": false}
    ],
  "risk_score": 4
}

Get ASN for IP Address

List the information about the Autonomous System Number (ASN) and IP relationship. Describe how IP addresses relate to each other and to the regional registries. The Autonomous System (AS) is part of the Border Gateway Protocol (BGP) routing for that IP. Each response contains the ASN, the CIDR prefix of the AS, the Internet Registry (RIR) number (0 through 6), the description of the AS, and the creation date for the AS.

GET /bgp_routes/ip/{ip}/as_for_ip.json

The IR number corresponds to one of the five Regional Internet Registries (RIR).

Request Path Parameters

Request

curl -i GET "https://investigate.api.umbrella.com/bgp_routes/ip/{ip}/as_for_ip.json" \
-H 'Authorization: Bearer %YourToken%' \
-H 'Content-Type: application/json'

Response

Sample response (200, OK):

{
    "creation_date": "2002-08-01",
    "ir": 2,
    "description": "CHINANET-BACKBONE No.31,Jin-rong Street,CN 86400",
    "asn": 4134,
    "cidr": "123.172.0.0/15"
}

Get Top Million Domains

List the most requested domains in Umbrella.

GET /topmillion

Request Query Parameters

Request

curl -i GET "https://investigate.api.umbrella.com/topmillion?limit=1000" \
-H 'Authorization: Bearer %YourToken%' \
-H 'Content-Type: application/json'

Response

Sample response (200, OK):

[
    "google.com",
    "netflix.com",
    "api-global.netflix.com",
    "microsoft.com",
    "www.google.com",
    "facebook.com",
    "doubleclick.net",
    "g.doubleclick.net",
    "googleads.g.doubleclick.net",
    "hola.org"
]

Get Newly Seen Domains by Search

List newly seen domains in which the domain matches a specified regular expression pattern. Find the set of domains requested for the first time, within the specified time period. The response does not include domains seen before the specified time period, including well-known domains.

Note: The response may include domains that do not resolve. Occasionally, non-existent domains may appear in the response.

GET /search/{expression}

Search Operators

• An asterisk (*) matches zero or more instances of the previous token.
• A period (.) matches exactly one character.
• Brackets ([]) matches a class of characters, for example: [0-9] for all numbers, or [a-z] for all letters.
• Parentheses (()) group tokens together for modifiers, for example: (ya)* matches ya, yaya, or yayaya.
• Question mark (?) matches one or zero instances of the previous token. For example, hi(ya)? matches hi or hiya.

Note: You can use the period (.) character as a wildcard and as a literal in domain names. If you include the period (.) character as part of your pattern, you must escape it using the backslash (\\) character. For example, \\.umbrella\\.com matches a.umbrella.com or b.umbrella.com.

Request Path Parameters

Request Query Parameters

Request

curl -i GET "https://investigate.api.umbrella.com/search/exa\[a-z\]ple.com?start=-30days&limit=10&includecategory=true" \
-H 'Authorization: Bearer %YourToken%' \
-H 'Content-Type: application/json'

Response

Sample response (200, OK):

{
  "expression": "exa[a-z]ple.com",
  "totalResults": 1,
  "moreDataAvailable": false,
  "limit": 1000,
  "matches": [
    {
      "name": "example",
      "firstSeen": 1432330927421,
      "firstSeenISO": "2015-05-22T21:42:07.421Z",
      "securityCategories": [
        "Botnet"
      ]
    }
  ]
}

Get WHOIS Domain

List the WHOIS information for the domain.

GET /whois/{domain}

Request

curl -i GET "https://investigate.api.umbrella.com/whois/google.com" \
-H 'Authorization: Bearer %YourToken%' \
-H 'Content-Type: application/json'

Response

{
    "administrativeContactFax": null,
    "whoisServers": "whois.markmonitor.com",
    "addresses": [],
    "administrativeContactName": null,
    "zoneContactEmail": null,
    "billingContactFax": null,
    "administrativeContactTelephoneExt": null,
    "administrativeContactEmail": null,
    "technicalContactEmail": null,
    "technicalContactFax": null,
    "nameServers": [
        "ns1.google.com",
        "ns2.google.com",
        "ns3.google.com",
        "ns4.google.com"
    ],
    "zoneContactName": null,
    "billingContactPostalCode": null,
    "zoneContactFax": null,
    "registrantTelephoneExt": null,
    "zoneContactFaxExt": null,
    "technicalContactTelephoneExt": null,
    "billingContactCity": null,
    "zoneContactStreet": [],
    "created": "1997-09-15",
    "administrativeContactCity": null,
    "registrantName": null,
    "zoneContactCity": null,
    "domainName": "google.com",
    "zoneContactPostalCode": null,
    "administrativeContactFaxExt": null,
    "technicalContactCountry": "UNITED STATES",
    "registrarIANAID": "292",
    "updated": "2019-09-09",
    "administrativeContactStreet": [],
    "billingContactEmail": null,
    "status": [
        "clientDeleteProhibited clientTransferProhibited clientUpdateProhibited serverDeleteProhibited serverTransferProhibited serverUpdateProhibited"
    ],
    "registrantCity": null,
    "billingContactCountry": null,
    "expires": "2028-09-14",
    "technicalContactStreet": [],
    "registrantOrganization": "Google LLC",
    "billingContactStreet": [],
    "registrarName": "MarkMonitor, Inc.",
    "registrantPostalCode": null,
    "zoneContactTelephone": null,
    "registrantEmail": null,
    "technicalContactFaxExt": null,
    "technicalContactOrganization": "Google LLC",
    "emails": [],
    "registrantStreet": [],
    "technicalContactTelephone": null,
    "technicalContactState": "CA",
    "technicalContactCity": null,
    "registrantFax": null,
    "registrantCountry": "UNITED STATES",
    "billingContactFaxExt": null,
    "timestamp": null,
    "zoneContactOrganization": null,
    "administrativeContactCountry": "UNITED STATES",
    "billingContactName": null,
    "registrantState": "CA",
    "registrantTelephone": null,
    "administrativeContactState": "CA",
    "registrantFaxExt": null,
    "technicalContactPostalCode": null,
    "zoneContactTelephoneExt": null,
    "administrativeContactOrganization": "Google LLC",
    "billingContactTelephone": null,
    "billingContactTelephoneExt": null,
    "zoneContactState": null,
    "administrativeContactTelephone": null,
    "billingContactOrganization": null,
    "technicalContactName": null,
    "administrativeContactPostalCode": null,
    "zoneContactCountry": null,
    "billingContactState": null,
    "auditUpdatedDate": "2021-06-25 06:47:48 UTC",
    "recordExpired": false,
    "timeOfLatestRealtimeCheck": 1624607404215,
    "hasRawText": true
}

Get WHOIS by Search Field and Search

List the WHOIS records that match the specified regular expression. Search the WHOIS domain, nameserver, or email fields which were updated or created within the specified time period. You can set the offset and limit query parameters to paginate the collection. By default, Umbrella Investigate sorts the collection by the updated search field.

GET /whois/search/{searchField}/{regularExpression}

Search Operators

• An asterisk (*) matches zero or more instances of the previous token.
• A period (.) matches exactly one character.
• Brackets ([]) matches a class of characters, for example: [0-9] for all numbers, or [a-z] for all letters.
• Parentheses (()) group tokens together for modifiers, for example: (ya)* matches ya, yaya, or yayaya.
• Question mark (?) matches one or zero instances of the previous token. For example, hi(ya)? matches hi or hiya.

Note: You can use the period (.) character as a wildcard and as a literal in domain names. If you include the period (.) character as part of your pattern, you must escape it using the backslash (\\) character. For example, \\.umbrella\\.com matches a.umbrella.com or b.umbrella.com.

Request Path Parameters

Request Query Parameters

Request

curl -i GET "https://investigate.api.umbrella.com/whois/search/domain/exa\[a-z\]ple.com?start=-30days&limit=10&sortField=updated" \
-H 'Authorization: Bearer %YourToken%' \
-H 'Content-Type: application/json'

Response

Sample response (200, OK):

{
  "totalResults": 500,
  "offset": 0,
  "moreDataAvailable": true,
  "limit": 10,
  "sortField": "updated",
  "records": []
}

Get Samples for Domain, IP, or URL

Specify a domain, IP, or URL. Use the destination to search for all samples associated with the destination. The default number of items in a response is 10. You can extend the limit. You must have a license for Cisco Secure Malware Analytics to receive the samples data.

Cisco Secure Malware Analytics retains checksum samples for one year. You may find that Umbrella Investigate previously listed an associated checksum sample for an IP or domain, but the sample is no longer considered related to the destination by Cisco Secure Malware Analytics.

An error may occur when the requested destination is not in a valid format, if the requested host is not found in our database, or if there is no data available for the destination that you have requested. CIDR subnets (for example: 10.10.10.0/24) and pattern search is not supported.

GET https://investigate.api.um/samples/{destination}

Request Path Parameters

Request Query Parameters

Request

curl -L --location-trusted --request GET --url "https://investigate.api.um/samples/{destination}" \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response

[
    {
        "query": "google.com",
        "totalResults": 10,
        "moreDataAvailable": true,
        "limit": 10,
        "offset": 0,
        "samples": [
            {
                "sha256": "e9d3470c37dada28d5a32fb53a243c5b20def35bb01abf8f5403182cc2b91fdd",
                "sha1": "de182fdcc3c0d473b90a0df0ad14c2074d1e7c50",
                "md5": "282f80e8a2cf9e0e0dd72093787d99c6",
                "magicType": "PE32 executable (GUI) Intel 80386, for MS Windows",
                "threatScore": 100,
                "size": 192512,
                "firstSeen": "1460108539000",
                "lastSeen": "1460108539000",
                "visible": true,
                "avresults": [
                    {
                        "signature": "Win.Trojan.Ramnit",
                        "product": "ClamAV"
                    },
                    {
                        "signature": "Win.Trojan.Parite",
                        "product": "ClamAV"
                    }
                ]
            }
        ]
    }
]