Investigate
Get Domain Status and Categorization
GET https://api.sse.cisco.com/investigate/v2/domains/categorization/{domain}
Description
Look up the status, and security and content category IDs for the domain.
The domain status is a numerical value determined by the Cisco Security Labs team.
Valid status values are: '-1' (malicious), '1' (safe), or '0' (undetermined status).
Path Parameters
Query Parameters
Request Sample
Response Schema (object)
- status
(Optional, integer)
- If the domain is considered malicious, the status returned is
-1.
- If the domain is considered benign, the status returned is
1.
- If the domain is unclassified, the status returned is 0.
- security_categories
(Optional, array (string)) The security categories that match this domain.
If the domain does not match any security categories, the server returns an empty list.
- content_categories
(Optional, array (string)) The content categories that match this domain.
If the domain does not match any content categories, the server returns an empty list.
Response Sample
Click to view the sample response (200, OK)
Check Status and Categorization of Domains
POST https://api.sse.cisco.com/investigate/v2/domains/categorization
Description
Provide a list of domains and look up the status, and security and content category IDs for each domain.
The domain status is a numerical value determined by the Cisco Security Labs team.
Valid status values are: '-1' (malicious), '1' (safe), or '0' (undetermined status).
Query Parameters
Request Body Schema (array)
(Optional, string) A domain name.
Request Sample
Response Schema (array)
- status
(Optional, integer)
- If the domain is considered malicious, the status returned is
-1.
- If the domain is considered benign, the status returned is
1.
- If the domain is unclassified, the status returned is 0.
- security_categories
(Optional, array (string)) The security categories that match this domain.
If the domain does not match any security categories, the server returns an empty list.
- content_categories
(Optional, array (string)) The content categories that match this domain.
If the domain does not match any content categories, the server returns an empty list.
Response Sample
Click to view the sample response (200, OK)
Get Domain Volume
GET https://api.sse.cisco.com/investigate/v2/domains/volume/{domain}
Description
List the query volume for a domain over the last 30 days.
If there is no information about the domain, Investigate returns an empty array.
As the query takes time to generate, the last two hours may be blank.
Path Parameters
Query Parameters
- start
(Required, string) Specifies a relative or absolute start time. If specifying an absolute time,
use an epoch time (Unix time) millisecond timestamp within the last 30 days.
Filter for data that appears after this time.
If specifying a relative time, use either seconds, minutes, hours, days
or weeks with a minus sign in front.
As an example, -1days, -1000minutes, or -2weeks are all valid.
You cannot combine timestamps. Only use one of the relative time enumerators per query.
- stop
(Optional, string) Point in time in the past expressed as a timestamp in milliseconds or relative time.
Filter for data that appears before this time.
Valid formats: stop=-1days, stop=now, stop=1509642000000. The maximum time range is 30 days.
- match
(Optional, string) Valid values are: exact, component, or all. The default value is all.
Request Sample
Response Schema (object)
- dates
(Optional, array (string)) The list of dates recorded for the domain.
- queries
(Optional, array (string)) The list of the numbers of DNS queries requested for the domain in one hour, listed in ascending order.
Response Sample
Click to view the sample response (200, OK)
Get Recommendations by Name
GET https://api.sse.cisco.com/investigate/v2/recommendations/name/{domain}.json
Description
List the co-occurences for the specified domain.
A co-occurrence is when two or more domains are accessed by the same users within a small window of time.
Co-occurring domains are not necessarily problematic; legitimate sites co-occur with each other as a part
of normal web activity. However, unusual or suspicious co-occurences can provide additional information regarding attacks.
To determine co-occurrences for a domain, a small time window of traffic across all of our datacenters is taken.
Investigate checks the sites that end users visited before and after the domain was requested in the API call.
Path Parameters
Request Sample
Response Schema (object)
- pfs2
(Optional, array (string)) The list of the co-occurring domains.
- found
(Optional, boolean) Specify whether the domain is co-occurring.
Response Sample
Click to view the sample response (200, OK)
Get Resource Records for Name
GET https://api.sse.cisco.com/investigate/v2/pdns/name/{domain}
Description
The Passive DNS endpoint provides historical data from the Secure Access resolvers for domains, IPs, and other resource records.
Path Parameters
Query Parameters
- limit
(Optional, integer) The number of records to return in the collection.
The default limit is 500 records. The maximum number of records
returned for all requests to the endpoint is 10,000.
- offset
(Optional, integer) A number that represents an index in the collection. By default, the offset is 0 (the first record).
- sortorder
(Optional, string) Sort records by ascending (asc) or descending (desc) order. By default, the records are returned in descending order.
- sortby
(Optional, string) Sort records by one of the following fields: minTtl, maxTtl, firstSeen, or lastSeen.
- recordType
(Optional, string) The type of records. For example: 'A', 'CNAME', 'NS', 'MX'.
Use commas to separate multiple types of record.
- includefeatures
(Optional, boolean) Specify whether to add the feature sections to the response. The default value is 'false'.
- minFirstSeen
(Optional, integer) Only returns records with the value of firstSeen >= the value of minFirstSeen.
- maxFirstSeen
(Optional, integer) Only returns records with the value of firstSeen <= the value of maxFirstSeen.
- minLastSeen
(Optional, integer) Only returns records with the value of lastSeen >= the value of minLastSeen.
- maxLastSeen
(Optional, integer) Only returns records with the value of lastSeen <= the value of maxLastSeen.
- sortCategories
(Optional, string) Sort the records by the specified security categories or all security categories (All).
The case-sensitive security category strings are: 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, and Cryptomining. Use commas to separate multiple security category strings.
Investigate lists the records that have at least one of these security categories at the top of the list.
The rest of the sorting parameters are applied within the records with and without any of
the security categories.
- requiredCategories
(Optional, string) Filter for records that are assigned the specified security categories.
The case-sensitive security category strings are: 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, and Cryptomining. Use commas to separate multiple security category strings.
Request Sample
Response Schema (array)
- minTtl
(Optional, integer) The minimum TTL for the record in seconds.
- maxTtl
(Optional, integer) The maximum TTL for the record in seconds.
- firstSeen
(Optional, integer) The first time Secure Access related the domain for the resource record, specified
in Unix Epoch time.
- lastSeen
(Optional, integer) The last time Secure Access related the domain for the resource record, specified
in Unix Epoch time.
- name
(Optional, string) The name of the query.
- type
(Optional, string) The DNS record type. For example: A, CNAME, NS, MX.
- securityCategories
(Optional, array (string)) The Secure Access security categories, if any, that match the domain.
- contentCategories
(Optional, array (string)) The Secure Access content categories, if any, that match the domain.
- firstSeenISO
(Optional, string) The first time Secure Access related the domain for the resource record,
specified in ISO date and time format.
- lastSeenISO
(Optional, string) The last time Secure Access related the domain for the resource record,
specified in ISO date and time format.
Response Sample
Click to view the sample response (200, OK)
Get Resource Records for Domain
GET https://api.sse.cisco.com/investigate/v2/pdns/domain/{domain}
Description
Get the Resource Record (RR) data for DNS responses, and categorization data, where the answer (or rdata) is the domain(s).
Path Parameters
Query Parameters
- limit
(Optional, integer) The number of records to return in the collection.
The default limit is 500 records. The maximum number of records
returned for all requests to the endpoint is 10,000.
- offset
(Optional, integer) A number that represents an index in the collection. By default, the offset is 0 (the first record).
- sortorder
(Optional, string) Sort records by ascending (asc) or descending (desc) order. By default, the records are returned in descending order.
- sortby
(Optional, string) Sort records by one of the following fields: minTtl, maxTtl, firstSeen, or lastSeen.
- recordType
(Optional, string) The type of records. For example: 'A', 'CNAME', 'NS', 'MX'.
Use commas to separate multiple types of record.
- includefeatures
(Optional, boolean) Specify whether to add the feature sections to the response. The default value is 'false'.
- minFirstSeen
(Optional, integer) Only returns records with the value of firstSeen >= the value of minFirstSeen.
- maxFirstSeen
(Optional, integer) Only returns records with the value of firstSeen <= the value of maxFirstSeen.
- minLastSeen
(Optional, integer) Only returns records with the value of lastSeen >= the value of minLastSeen.
- maxLastSeen
(Optional, integer) Only returns records with the value of lastSeen <= the value of maxLastSeen.
- sortCategories
(Optional, string) Sort the records by the specified security categories or all security categories (All).
The case-sensitive security category strings are: 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, and Cryptomining. Use commas to separate multiple security category strings.
Investigate lists the records that have at least one of these security categories at the top of the list.
The rest of the sorting parameters are applied within the records with and without any of
the security categories.
- requiredCategories
(Optional, string) Filter for records that are assigned the specified security categories.
The case-sensitive security category strings are: 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, and Cryptomining. Use commas to separate multiple security category strings.
Request Sample
Response Schema (array)
- minTtl
(Optional, integer) The minimum TTL for the record in seconds.
- maxTtl
(Optional, integer) The maximum TTL for the record in seconds.
- firstSeen
(Optional, integer) The first time Secure Access related the domain for the resource record, specified
in Unix Epoch time.
- lastSeen
(Optional, integer) The last time Secure Access related the domain for the resource record, specified
in Unix Epoch time.
- name
(Optional, string) The name of the query.
- type
(Optional, string) The DNS record type. For example: A, CNAME, NS, MX.
- securityCategories
(Optional, array (string)) The Secure Access security categories, if any, that match the domain.
- contentCategories
(Optional, array (string)) The Secure Access content categories, if any, that match the domain.
- firstSeenISO
(Optional, string) The first time Secure Access related the domain for the resource record,
specified in ISO date and time format.
- lastSeenISO
(Optional, string) The last time Secure Access related the domain for the resource record,
specified in ISO date and time format.
Response Sample
Click to view the sample response (200, OK)
Get Resource Records for IP
GET https://api.sse.cisco.com/investigate/v2/pdns/ip/{ip}
Description
Get the Resource Record (RR) data for DNS responses, and categorization data, where the answer (or rdata) is the domain(s).
Path Parameters
Query Parameters
- limit
(Optional, integer) The number of records to return in the collection.
The default limit is 500 records. The maximum number of records
returned for all requests to the endpoint is 10,000.
- offset
(Optional, integer) A number that represents an index in the collection. By default, the offset is 0 (the first record).
- sortorder
(Optional, string) Sort records by ascending (asc) or descending (desc) order. By default, the records are returned in descending order.
- sortby
(Optional, string) Sort records by one of the following fields: minTtl, maxTtl, firstSeen, or lastSeen.
- recordType
(Optional, string) The type of records. For example: 'A', 'CNAME', 'NS', 'MX'.
Use commas to separate multiple types of record.
- includefeatures
(Optional, boolean) Specify whether to add the feature sections to the response. The default value is 'false'.
- minFirstSeen
(Optional, integer) Only returns records with the value of firstSeen >= the value of minFirstSeen.
- maxFirstSeen
(Optional, integer) Only returns records with the value of firstSeen <= the value of maxFirstSeen.
- minLastSeen
(Optional, integer) Only returns records with the value of lastSeen >= the value of minLastSeen.
- maxLastSeen
(Optional, integer) Only returns records with the value of lastSeen <= the value of maxLastSeen.
- sortCategories
(Optional, string) Sort the records by the specified security categories or all security categories (All).
The case-sensitive security category strings are: 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, and Cryptomining. Use commas to separate multiple security category strings.
Investigate lists the records that have at least one of these security categories at the top of the list.
The rest of the sorting parameters are applied within the records with and without any of
the security categories.
- requiredCategories
(Optional, string) Filter for records that are assigned the specified security categories.
The case-sensitive security category strings are: 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, and Cryptomining. Use commas to separate multiple security category strings.
Request Sample
Response Schema (array)
- minTtl
(Optional, integer) The minimum TTL for the record in seconds.
- maxTtl
(Optional, integer) The maximum TTL for the record in seconds.
- firstSeen
(Optional, integer) The first time Secure Access related the domain for the resource record, specified
in Unix Epoch time.
- lastSeen
(Optional, integer) The last time Secure Access related the domain for the resource record, specified
in Unix Epoch time.
- name
(Optional, string) The name of the query.
- type
(Optional, string) The DNS record type. For example: A, CNAME, NS, MX.
- securityCategories
(Optional, array (string)) The Secure Access security categories, if any, that match the domain.
- contentCategories
(Optional, array (string)) The Secure Access content categories, if any, that match the domain.
- firstSeenISO
(Optional, string) The first time Secure Access related the domain for the resource record,
specified in ISO date and time format.
- lastSeenISO
(Optional, string) The last time Secure Access related the domain for the resource record,
specified in ISO date and time format.
Response Sample
Click to view the sample response (200, OK)
Get Resource Records for Raw Data
GET https://api.sse.cisco.com/investigate/v2/pdns/raw/{anystring}
Description
Get the Resource Record (RR) data for DNS responses, and categorization data, where the answer (or rdata) could be anything.
Path Parameters
- anystring
(Required, string) The text representation of the data. When querying TXT records, add quotes around the text.
For example, to search for the 'abc', provide the string as a path parameter
in an API request: 'https://api.sse.cisco.com/investigate/v2/pdns/raw/"abc"'.
Query Parameters
- limit
(Optional, integer) The number of records to return in the collection.
The default limit is 500 records. The maximum number of records
returned for all requests to the endpoint is 10,000.
- offset
(Optional, integer) A number that represents an index in the collection. By default, the offset is 0 (the first record).
- sortorder
(Optional, string) Sort records by ascending (asc) or descending (desc) order. By default, the records are returned in descending order.
- sortby
(Optional, string) Sort records by one of the following fields: minTtl, maxTtl, firstSeen, or lastSeen.
- recordType
(Optional, string) The type of records. For example: 'A', 'CNAME', 'NS', 'MX'.
Use commas to separate multiple types of record.
- includefeatures
(Optional, boolean) Specify whether to add the feature sections to the response. The default value is 'false'.
- minFirstSeen
(Optional, integer) Only returns records with the value of firstSeen >= the value of minFirstSeen.
- maxFirstSeen
(Optional, integer) Only returns records with the value of firstSeen <= the value of maxFirstSeen.
- minLastSeen
(Optional, integer) Only returns records with the value of lastSeen >= the value of minLastSeen.
- maxLastSeen
(Optional, integer) Only returns records with the value of lastSeen <= the value of maxLastSeen.
- sortCategories
(Optional, string) Sort the records by the specified security categories or all security categories (All).
The case-sensitive security category strings are: 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, and Cryptomining. Use commas to separate multiple security category strings.
Investigate lists the records that have at least one of these security categories at the top of the list.
The rest of the sorting parameters are applied within the records with and without any of
the security categories.
- requiredCategories
(Optional, string) Filter for records that are assigned the specified security categories.
The case-sensitive security category strings are: 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, and Cryptomining. Use commas to separate multiple security category strings.
Request Sample
Response Schema (array)
- minTtl
(Optional, integer) The minimum TTL for the record in seconds.
- maxTtl
(Optional, integer) The maximum TTL for the record in seconds.
- firstSeen
(Optional, integer) The first time Secure Access related the domain for the resource record, specified
in Unix Epoch time.
- lastSeen
(Optional, integer) The last time Secure Access related the domain for the resource record, specified
in Unix Epoch time.
- name
(Optional, string) The name of the query.
- type
(Optional, string) The DNS record type. For example: A, CNAME, NS, MX.
- securityCategories
(Optional, array (string)) The Secure Access security categories, if any, that match the domain.
- contentCategories
(Optional, array (string)) The Secure Access content categories, if any, that match the domain.
- firstSeenISO
(Optional, string) The first time Secure Access related the domain for the resource record,
specified in ISO date and time format.
- lastSeenISO
(Optional, string) The last time Secure Access related the domain for the resource record,
specified in ISO date and time format.
Response Sample
Click to view the sample response (200, OK)
Get Related Domains for Domain
GET https://api.sse.cisco.com/investigate/v2/links/name/{domain}
Description
List the domain names that are frequently requested around
the same time (up to 60 seconds before or after) as the given domain name,
but that are not frequently associated with other domain names.
Path Parameters
Request Sample
Response Schema (object)
- tb1
(Optional, array (object)) The list of domain name and score pairs where score is the number of client IP requests
to the site around the same time that the site is looked up.
- domain
(Optional, string) A domain name.
- score
(Optional, number) The number of client IP requests to the site around the same time
that the site is looked up.
- found
(Optional, boolean) Specifies whether the results are available.
Response Sample
Click to view the sample response (200, OK)
Get Security Score Information for Domain
GET https://api.sse.cisco.com/investigate/v2/security/name/{domain}
Description
List multiple scores or security features for a domain. You can use the scores
or security features to determine relevant data points and build insights on the reputation
or security risk posed by the site. No one security information feature is conclusive.
Instead, consider these features as part of your security research.
Path Parameters
Request Sample
Response Schema (object)
- dga_score
(Optional, number) A domain generation algorithm (DGA) is used by malware to generate large lists of domain names.
This score is created based on the likeliness
of the domain name being generated by an algorithm
rather than a human. This algorithm is designed to identify domains which
have been created using an automated randomization
strategy, which is a common evasion technique in malware kits or botnets.
This score ranges from -100 (suspicious) to 0 (benign).
- perplexity
(Optional, number) A second score on the likeliness of the name to be algorithmically
generated, on a scale from 0 to 100. This score is used in conjunction with DGA.
- entropy
(Optional, number) The number of bits required to encode the domain name as a score. This score is used in conjunction with DGA and Perplexity.
- securerank2
(Optional, number) The suspicious rank for a domain that reviews base on the lookup behavior
of client IP for the domain.
Securerank is designed to identify hostnames requested by known infected
clients but never requested by clean clients,
assuming these domains are more likely to be bad.
Scores returned range from -100 (suspicious) to 100 (benign).
- pagerank
(Optional, number) A popularity score according to Google's PageRank algorithm.
- asn_score
(Optional, number) The ASN reputation score ranges from -100 to 0 where -100 is very suspicious.
- prefix_score
(Optional, number) The prefix ranks domains given their IP prefixes
(an IP prefix is the first three octets in an IP address)
and the reputation score of these prefixes. The scores range from -100 to 0 where -100 is
very suspicious.
- rip_score
(Optional, number) The RIP ranks domains given their IP addresses and the reputation score
of these IP addresses. The scores ranges from -100 to 0 where -100 is very suspicious.
- popularity
(Optional, number) The number of unique client IPs visiting this site, relative to all
requests to all sites. A score of how many different client or unique IPs requested
to this domain compared to others.
- geodiversity
(Optional, array (number)) The list of scores that represent the number of queries from clients visiting the domain, broken down by country.
- geodiversity_normalized
(Optional, array (number)) The list of scores that represents the amount of queries for clients visiting the domain,
broken down by country.
- tld_geodiversity
(Optional, array (number)) The list of scores that represent the top-level domain country code geodiversity as a percentage
of clients visiting the domain.
- geoscore
(Optional, number) A score that represents how far the different physical locations serving this name
are from each other.
- ks_test
(Optional, number) A number that represents the Kolmogorov-Smirnov test on geodiversity.
Zero indicates that the client traffic matches what is expected for this top-level domain.
- attack
(Optional, string) The name of any known attacks associated with this domain.
Returns an empty string if no known threat associated with domain.
- threat_type
(Optional, string) The type of the known attack, such as botnet or APT. Returns an empty string if no known
threat associated with domain.
- found
(Optional, boolean) Specifies whether the results are available.
Response Sample
Click to view the sample response (200, OK)
Get Risk Score for Domain
GET https://api.sse.cisco.com/investigate/v2/domains/risk-score/{domain}
Description
The Investigate Risk Score is based on an analysis of
the lexical characteristics of the domain name
and patterns in queries and requests to the domain.
The risk score is scaled from 0 to 100 where 100 is the highest risk
and 0 represents no risk at all. Periodically, Investigate updates this score based
on additional inputs.
A domain blocked by Secure Access receives a score of 100.
Path Parameters
Request Sample
Response Schema (object)
- indicators
(Optional, array (object)) A list of `indicator`, `normalized_score`, and `score` tuples. Each element is a behavioral
or lexical feature that contributes to the calculation of the risk score.
The values of `normalized_score` range between 0 and 100,
while `score` is the raw outcome from the statistical algorithms.
- indicator
(Optional, string)
- normalized_score
(Optional, integer)
- score
(Optional, number)
- risk_score
(Optional, number) The risk score.
Response Sample
Click to view the sample response (200, OK)
GET https://api.sse.cisco.com/investigate/v2/bgp_routes/ip/{ip}/as_for_ip.json
Description
This endpoint provides data about ASN and IP relationships,
showing how IP addresses are related to each other and to the regional registries.
You can find out more about the IP space associated with an AS
and correlate BGP routing information between AS.
When querying an IP to find which AS (Autonomous System), it is helpful
to find associated IP addresses. The AS is part of the BGP routing for that IP.
A valid result returns an array of hash references.
The hash reference contains information about the AS such as 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.
An empty response returns an empty array ([]).
Path Parameters
Request Sample
Response Schema (object)
- creation_date
(Optional, string) The date when the AS was first created.
- ir
(Optional, integer) The IR number corresponds to one of the 5 Regional Internet Registries (RIR).
| Registry |
Number |
Region |
| Registry |
1 |
AfriNIC: Africa |
| Registry |
2 |
APNIC: Asia, Australia, New Zealand, and neighboring countries. |
| Registry |
3 |
ARIN: United States, Canada, several parts of the Caribbean region, and Antarctica. |
| Registry |
4 |
LACNIC: Latin America and parts of the Caribbean region. |
| Registry |
5 |
RIPE NCC: Europe, Russia, the Middle East, and Central Asia. |
| Registry |
0 |
Unknown / Not Available |
- description
(Optional, string) Network Owner Description as provided by the network owner.
- asn
(Optional, string) The autonomous system number (ASN) associated with the IP address.
- cidr
(Optional, string) The IP CIDR for the ASN.
Response Sample
Click to view the sample response (200, OK)
GET https://api.sse.cisco.com/investigate/v2/bgp_routes/asn/{asn}/prefixes_for_asn.json
Description
A response to a valid ASN returns an array of hash references.
Each hash reference contains two keys: geo and cidr.
Geo is a hash reference with the country name and country code
(the code corresponds to the country code list for ISO-3166-1 alpha-2).
CIDR contains the IP prefix for this ASN.
Path Parameters
Request Sample
Response Schema (object)
- cidr
(Optional, array (string)) A list of the CIDR range of IP addresses associated with this AS.
The CIDR contains the IP prefix for the ASN.
- geo
(Optional, object) Geo is a hash reference with the country name and country code
(the code corresponds to the country code list for ISO-3166-1 alpha-2).
For more information, see [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
- id
(Optional, integer) The ID of the geolocation.
- name
(Optional, string) The name of the geolocation.
Response Sample
Click to view the sample response (200, OK)
Get WHOIS Information for Domain
GET https://api.sse.cisco.com/investigate/v2/whois/{domain}
Description
Get the WHOIS information for the specified email addresses,
nameservers, and domains. You can search by multiple email addresses or multiple nameservers.
This documentation outlines the following API endpoints:
email (single and multiple), domain record (current and historical), and nameserver (single and multiple).
In some instances, WHOIS information can be irregular as there are no standards
between domain registrars and large volumes of information can be returned from a query.
As such, both the email and nameserver WHOIS endpoints have a limit of 500 results,
which you can reduce to a smaller set of results.
There is an offset parameter that can be leveraged to retrieve the entire set
of domain entries for a given email without any limitation. Only the email parameter
supports this.
You can sort the email parameter by filtering the entries based on the timestamp field.
If a domain, email, or nameserver has no known WHOIS information, Investigate returns HTTP 404.
If a domain, email or nameserver does not exist, Investigate returns HTTP 404.
Path Parameters
Request Sample
Response Schema (array)
- administrativeContactFax
(Optional, string)
- whoisServers
(Optional, string)
- addresses
(Optional, array (string))
- administrativeContactName
(Optional, string)
- zoneContactEmail
(Optional, string)
- billingContactFax
(Optional, string)
- administrativeContactTelephoneExt
(Optional, string)
- administrativeContactEmail
(Optional, string)
- technicalContactEmail
(Optional, string)
- technicalContactFax
(Optional, string)
- nameServers
(Optional, array (string))
- zoneContactName
(Optional, string)
- billingContactPostalCode
(Optional, string)
- zoneContactFax
(Optional, string)
- registrantTelephoneExt
(Optional, string)
- zoneContactFaxExt
(Optional, string)
- technicalContactTelephoneExt
(Optional, string)
- billingContactCity
(Optional, string)
- zoneContactStreet
(Optional, array (string))
- created
(Optional, string)
- administrativeContactCity
(Optional, string)
- registrantName
(Optional, string)
- zoneContactCity
(Optional, string)
- domainName
(Optional, string)
- zoneContactPostalCode
(Optional, string)
- administrativeContactFaxExt
(Optional, string)
- technicalContactCountry
(Optional, string)
- registrarIANAID
(Optional, string)
- updated
(Optional, string)
- administrativeContactStreet
(Optional, array (string))
- billingContactEmail
(Optional, string)
- status
(Optional, array (string))
- registrantCity
(Optional, string)
- billingContactCountry
(Optional, string)
- expires
(Optional, string)
- technicalContactStreet
(Optional, array (string))
- registrantOrganization
(Optional, string)
- billingContactStreet
(Optional, array (string))
- registrarName
(Optional, string)
- registrantPostalCode
(Optional, string)
- zoneContactTelephone
(Optional, string)
- registrantEmail
(Optional, string)
- technicalContactFaxExt
(Optional, string)
- technicalContactOrganization
(Optional, string)
- emails
(Optional, array (string))
- registrantStreet
(Optional, array (string))
- technicalContactTelephone
(Optional, string)
- technicalContactState
(Optional, string)
- technicalContactCity
(Optional, string)
- registrantFax
(Optional, string)
- registrantCountry
(Optional, string)
- billingContactFaxExt
(Optional, string)
- timestamp
(Optional, integer)
- zoneContactOrganization
(Optional, string)
- administrativeContactCountry
(Optional, string)
- billingContactName
(Optional, string)
- registrantState
(Optional, string)
- registrantTelephone
(Optional, string)
- administrativeContactState
(Optional, string)
- registrantFaxExt
(Optional, string)
- technicalContactPostalCode
(Optional, string)
- zoneContactTelephoneExt
(Optional, string)
- administrativeContactOrganization
(Optional, string)
- billingContactTelephone
(Optional, string)
- billingContactTelephoneExt
(Optional, string)
- zoneContactState
(Optional, string)
- administrativeContactTelephone
(Optional, string)
- billingContactOrganization
(Optional, string)
- technicalContactName
(Optional, string)
- administrativeContactPostalCode
(Optional, string)
- zoneContactCountry
(Optional, string)
- billingContactState
(Optional, string)
- auditUpdatedDate
(Optional, string)
Response Sample
Click to view the sample response (200, OK)
Get WHOIS History for Domain
GET https://api.sse.cisco.com/investigate/v2/whois/{domain}/history
Description
Get a standard WHOIS response record for a single domain with available historical
WHOIS data returned in an object. The information displayed varies by registrant.
The default limit for history is 10. You can set another value with the limit query parameter.
Path Parameters
Query Parameters
Request Sample
Response Schema (array)
- administrativeContactFax
(Optional, string)
- whoisServers
(Optional, string)
- addresses
(Optional, array (string))
- administrativeContactName
(Optional, string)
- zoneContactEmail
(Optional, string)
- billingContactFax
(Optional, string)
- administrativeContactTelephoneExt
(Optional, string)
- administrativeContactEmail
(Optional, string)
- technicalContactEmail
(Optional, string)
- technicalContactFax
(Optional, string)
- nameServers
(Optional, array (string))
- zoneContactName
(Optional, string)
- billingContactPostalCode
(Optional, string)
- zoneContactFax
(Optional, string)
- registrantTelephoneExt
(Optional, string)
- zoneContactFaxExt
(Optional, string)
- technicalContactTelephoneExt
(Optional, string)
- billingContactCity
(Optional, string)
- zoneContactStreet
(Optional, array (string))
- created
(Optional, string)
- administrativeContactCity
(Optional, string)
- registrantName
(Optional, string)
- zoneContactCity
(Optional, string)
- domainName
(Optional, string)
- zoneContactPostalCode
(Optional, string)
- administrativeContactFaxExt
(Optional, string)
- technicalContactCountry
(Optional, string)
- registrarIANAID
(Optional, string)
- updated
(Optional, string)
- administrativeContactStreet
(Optional, array (string))
- billingContactEmail
(Optional, string)
- status
(Optional, array (string))
- registrantCity
(Optional, string)
- billingContactCountry
(Optional, string)
- expires
(Optional, string)
- technicalContactStreet
(Optional, array (string))
- registrantOrganization
(Optional, string)
- billingContactStreet
(Optional, array (string))
- registrarName
(Optional, string)
- registrantPostalCode
(Optional, string)
- zoneContactTelephone
(Optional, string)
- registrantEmail
(Optional, string)
- technicalContactFaxExt
(Optional, string)
- technicalContactOrganization
(Optional, string)
- emails
(Optional, array (string))
- registrantStreet
(Optional, array (string))
- technicalContactTelephone
(Optional, string)
- technicalContactState
(Optional, string)
- technicalContactCity
(Optional, string)
- registrantFax
(Optional, string)
- registrantCountry
(Optional, string)
- billingContactFaxExt
(Optional, string)
- timestamp
(Optional, integer)
- zoneContactOrganization
(Optional, string)
- administrativeContactCountry
(Optional, string)
- billingContactName
(Optional, string)
- registrantState
(Optional, string)
- registrantTelephone
(Optional, string)
- administrativeContactState
(Optional, string)
- registrantFaxExt
(Optional, string)
- technicalContactPostalCode
(Optional, string)
- zoneContactTelephoneExt
(Optional, string)
- administrativeContactOrganization
(Optional, string)
- billingContactTelephone
(Optional, string)
- billingContactTelephoneExt
(Optional, string)
- zoneContactState
(Optional, string)
- administrativeContactTelephone
(Optional, string)
- billingContactOrganization
(Optional, string)
- technicalContactName
(Optional, string)
- administrativeContactPostalCode
(Optional, string)
- zoneContactCountry
(Optional, string)
- billingContactState
(Optional, string)
- auditUpdatedDate
(Optional, string)
Response Sample
Click to view the sample response (200, OK)
GET https://api.sse.cisco.com/investigate/v2/whois/nameservers/{nameserver}
Description
Get WHOIS information for the nameserver.
As a nameserver can potentially register hundreds or thousands of domains,
the server limits the number of results to 500.
Path Parameters
Query Parameters
- limit
(Optional, integer) Specify the number of records to return from the collection.
The default limit is 500.
- offset
(Optional, integer) A number that represents an index in the collection. By default, the offset is 0 (the first record).
- sortField
(Optional, string) Valid values are: created, updated, expires, or domainname.
Request Sample
Response Schema (object)
- totalResults
(Optional, integer) The total number of WHOIS records found for this query.
- moreDataAvailable
(Optional, boolean) Specifies whether more samples are available for the destination.
- limit
(Optional, integer) The maximum number of records to include in the response.
- sortField
(Optional, string) The field that is used to sort the collection.
- domains
(Optional, array (object)) The list of information about the WHOIS emails and nameservers.
- domain
(Optional, string) The domain name.
- current
(Optional, boolean) Specifies whether the domain name is current.
Response Sample
Click to view the sample response (200, OK)
GET https://api.sse.cisco.com/investigate/v2/whois/nameservers
Description
Get WHOIS information for the nameservers. To search by multiple nameservers, provide
a comma-delimited list of domain names for the nameServerList query parameter.
For example: ns1.google.com,ns2.google.com.
Query Parameters
- nameServerList
(Required, string) The nameserver's domain names.
- limit
(Optional, integer) The number of records to return in the response from the collection.
The default limit is 500.
- offset
(Optional, integer) A number that represents an index in the collection. By default, the offset is 0 (the first record).
- sortField
(Optional, string) Valid values are: created, updated, expires, or domainname.
Request Sample
Response Schema (object)
- totalResults
(Optional, integer) The total number of samples.
- moreDataAvailable
(Optional, boolean) Specifies whether more samples are available for the destination.
- limit
(Optional, integer) The maximum number of records to include in the response.
- sortField
(Optional, string) The field that is used to sort the collection.
- domains
(Optional, array (object)) The list of WHOIS nameserver domain information.
- domain
(Optional, string) The domain name.
- current
(Optional, boolean) Specifies whether the domain name is current.
Response Sample
Click to view the sample response (200, OK)
GET https://api.sse.cisco.com/investigate/v2/whois/emails/{email}
Description
Get the email address or addresses of the registrar for the domain or domains. The results include
the total number of results for domains registered by this email address and a list
of the first 500 domains associated with this email.
You can pivot on the email address to find other malicious domains registered by the same email.
This endpoint is limited to a maximum of 500 results, which are the first 500 gathered from the database.
Reduce the number of results by setting the limit query parameter.
Note: Due to the sample length, Investigate may truncate a sample.
Path Parameters
Query Parameters
- limit
(Optional, integer) Specify the number of results to return.
The default limit is 500.
- offset
(Optional, integer) A number that represents an index in the collection. By default, the offset is 0 (the first record).
- sortField
(Optional, string) Valid values are: created, updated, expires, or domainname.
Request Sample
Response Schema (object)
- totalResults
(Optional, integer) The total number of results for this email address.
- offset
(Optional, integer) The place to start reading in the collection.
- moreDataAvailable
(Optional, boolean) Specifies whether there is more than 500 results for this email.
- limit
(Optional, integer) The number of results returned in the response. The default
limit is 500.
- sortField
(Optional, string) The field that is used to sort the collection.
- domains
(Optional, array (object)) The list of domains registered by this email and if the domain is currently registered
by this email address.
- domain
(Optional, string) The domain name.
- current
(Optional, boolean) Specifies whether the domain name is current.
Response Sample
Click to view the sample response (200, OK)
GET https://api.sse.cisco.com/investigate/v2/whois/search/{searchField}/{regexExpression}
Description
Performs a regular expression (RegEx) search on the WHOIS data (domain, nameserver, and email fields)
that was updated or created in the specified time range.
Returns a list of ten WHOIS records that match the specified RegEx expression.
Use the offset query parameter to paginate the collection.
By default, Investigate sorts by the updated field.
Path Parameters
- searchField
(Required, string) Specifies the field name to use in the RegEx search.
Valid field names are: domain, nameserver, and email.
- regexExpression
(Required, string) A standard regular expression pattern search.
Query Parameters
- start
(Required, string) Specifies a relative or absolute start time. If specifying an absolute time,
use an epoch time (Unix time) millisecond timestamp within the last 30 days.
Filter for data that appears after this time.
If specifying a relative time, use either seconds, minutes, hours, days
or weeks with a minus sign in front.
As an example, -1days, -1000minutes, or -2weeks are all valid.
You cannot combine timestamps. Only use one of the relative time enumerators per query.
- stop
(Optional, string) Point in time in the past expressed as a timestamp in milliseconds or relative time.
Filter for data that appears before this time.
Valid formats: stop=-1days, stop=now, stop=1509642000000. The maximum time range is 30 days.
- limit
(Optional, integer) The number of items to return in the response from the collection. The default limit is 10.
Increase the limit to request a larger set of data.
- offset
(Optional, integer) A number that represents an index in the collection. By default, the offset is 0 (the first record).
- sortField
(Optional, string) Valid values are: created, updated, expires, or domainname.
Request Sample
Response Schema (object)
- totalResults
(Optional, integer) The total number of results for this search.
- offset
(Optional, integer) The place to start reading in the collection.
- moreDataAvailable
(Optional, boolean) Specifies whether there is more than 10 results for this search.
- limit
(Optional, integer) The total number of results for this page. Default limit is 10.
- sortField
(Optional, string) The field that is used to sort the collection.
- records
(Optional, array (object)) The list of WHOIS records.
- administrativeContactFax
(Optional, string)
- whoisServers
(Optional, string)
- addresses
(Optional, array (string))
- administrativeContactName
(Optional, string)
- zoneContactEmail
(Optional, string)
- billingContactFax
(Optional, string)
- administrativeContactTelephoneExt
(Optional, string)
- administrativeContactEmail
(Optional, string)
- technicalContactEmail
(Optional, string)
- technicalContactFax
(Optional, string)
- nameServers
(Optional, array (string))
- zoneContactName
(Optional, string)
- billingContactPostalCode
(Optional, string)
- zoneContactFax
(Optional, string)
- registrantTelephoneExt
(Optional, string)
- zoneContactFaxExt
(Optional, string)
- technicalContactTelephoneExt
(Optional, string)
- billingContactCity
(Optional, string)
- zoneContactStreet
(Optional, array (string))
- created
(Optional, string)
- administrativeContactCity
(Optional, string)
- registrantName
(Optional, string)
- zoneContactCity
(Optional, string)
- domainName
(Optional, string)
- zoneContactPostalCode
(Optional, string)
- administrativeContactFaxExt
(Optional, string)
- technicalContactCountry
(Optional, string)
- registrarIANAID
(Optional, string)
- updated
(Optional, string)
- administrativeContactStreet
(Optional, array (string))
- billingContactEmail
(Optional, string)
- status
(Optional, array (string))
- registrantCity
(Optional, string)
- billingContactCountry
(Optional, string)
- expires
(Optional, string)
- technicalContactStreet
(Optional, array (string))
- registrantOrganization
(Optional, string)
- billingContactStreet
(Optional, array (string))
- registrarName
(Optional, string)
- registrantPostalCode
(Optional, string)
- zoneContactTelephone
(Optional, string)
- registrantEmail
(Optional, string)
- technicalContactFaxExt
(Optional, string)
- technicalContactOrganization
(Optional, string)
- emails
(Optional, array (string))
- registrantStreet
(Optional, array (string))
- technicalContactTelephone
(Optional, string)
- technicalContactState
(Optional, string)
- technicalContactCity
(Optional, string)
- registrantFax
(Optional, string)
- registrantCountry
(Optional, string)
- billingContactFaxExt
(Optional, string)
- timestamp
(Optional, integer)
- zoneContactOrganization
(Optional, string)
- administrativeContactCountry
(Optional, string)
- billingContactName
(Optional, string)
- registrantState
(Optional, string)
- registrantTelephone
(Optional, string)
- administrativeContactState
(Optional, string)
- registrantFaxExt
(Optional, string)
- technicalContactPostalCode
(Optional, string)
- zoneContactTelephoneExt
(Optional, string)
- administrativeContactOrganization
(Optional, string)
- billingContactTelephone
(Optional, string)
- billingContactTelephoneExt
(Optional, string)
- zoneContactState
(Optional, string)
- administrativeContactTelephone
(Optional, string)
- billingContactOrganization
(Optional, string)
- technicalContactName
(Optional, string)
- administrativeContactPostalCode
(Optional, string)
- zoneContactCountry
(Optional, string)
- billingContactState
(Optional, string)
- auditUpdatedDate
(Optional, string)
Response Sample
Click to view the sample response (200, OK)
Get Domains by Search
GET https://api.sse.cisco.com/investigate/v2/search/{expression}
Description
List the newly seen domains that match a regular expression pattern.
Path Parameters
Query Parameters
- start
(Required, string) Specifies a relative or absolute start time. If specifying an absolute time,
use an epoch time (Unix time) millisecond timestamp within the last 30 days.
Filter for data that appears after this time.
If specifying a relative time, use either seconds, minutes, hours, days
or weeks with a minus sign in front.
As an example, -1days, -1000minutes, or -2weeks are all valid.
You cannot combine timestamps. Only use one of the relative time enumerators per query.
- stop
(Optional, string) Point in time in the past expressed as a timestamp in milliseconds or relative time.
Filter for data that appears before this time.
Valid formats: stop=-1days, stop=now, stop=1509642000000. The maximum time range is 30 days.
- limit
(Optional, integer) The number of items to return in the response from the collection. The default limit is 10.
Increase the limit to request a larger set of data.
- offset
(Optional, integer) A number that represents an index in the collection. By default, the offset is 0 (the first record).
- includeCategory
(Optional, boolean) Enables or disables the inclusion of security categories in the response.
The default value is false.
- type
(Optional, string) Specifies the search database node type. Valid values are: URL, IP, or HOST.
Request Sample
Response Schema (object)
- expression
(Optional, string) Specifies the regular expression used in the search.
- totalResults
(Optional, integer) The total number of samples.
- moreDataAvailable
(Optional, boolean) Specifies whether more samples are available for the destination.
- limit
(Optional, integer) The maximum number of records to include in the response.
- matches
(Optional, array (object)) The list of matching records.
- firstSeen
(Optional, integer) The first time Secure Access related the domain for the resource record, specified
in Unix Epoch time.
- name
(Optional, string) The name of the query.
- securityCategories
(Optional, array (string)) The list of Secure Access security categories that match the domain.
- firstSeenISO
(Optional, string) The first time Secure Access related the domain for the resource record,
specified in ISO date and time format.
Response Sample
Click to view the sample response (200, OK)
Get Top Most Seen Domains
GET https://api.sse.cisco.com/investigate/v2/topmillion
Description
List the most seen domains in Secure Access. You can download the data in a zip file,
or use the Investigate API to stream the data into a SIEM.
The popularity list contains our most queried domains based on passive DNS usage across
the Secure Access global network of more than 180 billion requests per day with many tens of millions
of unique active users, in more than 165 countries.
The metric does not only consist of browser-based http requests from users but also takes
in to account the number of unique client IPs invoking this domain relative to the sum of all requests
to all domains.
Our popularity ranking reflects the domain's relative internet activity agnostic
to the invocation protocols and applications where as site ranking models (such as Alexa) focus
on the web activity over port 80 (primarily from browsers).
In addition, the Secure Access popularity algorithm also applies data normalization techniques
to smooth potential biases that may occur due to sampling of DNS usage data.
Query Parameters
Request Sample
Response Schema (array)
(Optional, string) A popular domain name identified by the Secure Access DNS resolvers.
Response Sample
Click to view the sample response (200, OK)
Get Samples for Domain, IP, or URL
GET https://api.sse.cisco.com/investigate/v2/samples/{destination}
Description
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 Investigate previously listed a sample related
to a destination. If Cisco Secure Malware Analytics no longer contains a sample
related to the destination, Investigate does not display the sample in the list
of associated samples.
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.
Path Parameters
Query Parameters
- limit
(Optional, integer) The number of items to return in the response from the collection. The default limit is 10.
Increase the limit to request a larger set of data.
- offset
(Optional, integer) A number that represents an index in the collection. By default, the offset is 0 (the first record).
- sortby
(Optional, string) Sort the sample based on optional values: first-seen, last-seen, or score.
The default value is score.
Request Sample
Response Schema (array)
- query
(Optional, string) The domain, IP, or URL.
- totalresults
(Optional, integer) The number of total results.
- moreDataAvailable
(Optional, boolean) Specifies whether more samples are available for the destination.
- limit
(Optional, integer) The maximum number of records to include in the response.
- offset
(Optional, integer) The place to start reading in the collection.
- samples
(Optional, array (object)) The list of hash samples and information for the destination.
- sha256
(Optional, string) The sha256 hash string.
- sha1
(Optional, string) The sha1 hash string.
- md5
(Optional, string) The md5 hash string.
- magictype
(Optional, string)
- threatscore
(Optional, integer) The threat score assigned to the sample.
- size
(Optional, integer) The size of the sample.
- firstSeen
(Optional, integer) The first time Secure Access related the domain for the resource record, specified
in Unix Epoch time.
- lastSeen
(Optional, integer) The last time Secure Access related the domain for the resource record, specified
in Unix Epoch time.
- visible
(Optional, boolean) Specifies whether the threat is visible.
- avresults
(Optional, array (object)) The list of antivirus results.
- signature
(Optional, string) The signature of the antivirus.
- product
(Optional, string) The name of the product associated with the antivirus.
Response Sample
Click to view the sample response (200, OK)
Get Samples for Hash
GET https://api.sse.cisco.com/investigate/v2/sample/{hash}
Description
Gather the information from the /samples endpoint, then pivot using the checksums
of the samples revealed in your initial query.
This pivot can reveal large chunks of new data about the malware being researched.
Returns a variety of data as nested JSON arrays.
The initial results array contains the information about the original sample.
These results are described first and are, in effect, the samples of the sample.
Path Parameters
Request Sample
Response Schema (object)
- sha256
(Optional, string) The sha256 hash string.
- sha1
(Optional, string) The sha1 hash string.
- md5
(Optional, string) The md5 hash string.
- magictype
(Optional, string)
- threatscore
(Optional, integer) The threat score assigned to the sample.
- size
(Optional, integer) The size of the sample.
- firstSeen
(Optional, integer) The first time Secure Access related the domain for the resource record, specified
in Unix Epoch time.
- lastSeen
(Optional, integer) The last time Secure Access related the domain for the resource record, specified
in Unix Epoch time.
- visible
(Optional, boolean) Specifies whether the threat is visible.
- avresults
(Optional, array (object)) The list of antivirus results.
- signature
(Optional, string) The signature of the antivirus.
- product
(Optional, string) The name of the product associated with the antivirus.
Response Sample
Click to view the sample response (200, OK)
Get Samples for Hash Artifacts
GET https://api.sse.cisco.com/investigate/v2/sample/{hash}/artifacts
Description
Other samples associated with this sample. The sample data does not include a threat score.
Artifacts are only available for Cisco Secure Malware Analytics customers.
Path Parameters
Query Parameters
- limit
(Optional, integer) The number of items to return in the response from the collection. The default limit is 10.
Increase the limit to request a larger set of data.
- offset
(Optional, integer) A number that represents an index in the collection. By default, the offset is 0 (the first record).
Request Sample
Response Schema (object)
- totalresults
(Optional, integer) The total number of samples.
- moreDataAvailable
(Optional, boolean) Specifies whether more samples are available for the destination.
- limit
(Optional, integer) The maximum number of records to include in the response.
- offset
(Optional, integer) The place to start reading in the collection.
- artifacts
(Optional, array (object)) The list of samples.
- sha256
(Optional, string) The sha256 hash string.
- sha1
(Optional, string) The sha1 hash string.
- md5
(Optional, string) The md5 hash string.
- magictype
(Optional, string)
- threatscore
(Optional, integer) The threat score assigned to the sample.
- size
(Optional, integer) The size of the sample.
- firstSeen
(Optional, integer) The first time Secure Access related the domain for the resource record, specified
in Unix Epoch time.
- lastSeen
(Optional, integer) The last time Secure Access related the domain for the resource record, specified
in Unix Epoch time.
- visible
(Optional, boolean) Specifies whether the threat is visible.
- avresults
(Optional, array (object)) The list of antivirus results.
- signature
(Optional, string) The signature of the antivirus.
- product
(Optional, string) The name of the product associated with the antivirus.
- samples
(Optional, array (array)) The list of all samples associated with the destination and related sample information.
Response Sample
Click to view the sample response (200, OK)
Get Samples for Hash Connections
GET https://api.sse.cisco.com/investigate/v2/sample/{hash}/connections
Description
Information about network activity associated with this sample, such as connections to other domains or IPs.
Path Parameters
Query Parameters
- limit
(Optional, integer) The number of items to return in the response from the collection. The default limit is 10.
Increase the limit to request a larger set of data.
- offset
(Optional, integer) A number that represents an index in the collection. By default, the offset is 0 (the first record).
Request Sample
Response Schema (object)
- totalresults
(Optional, integer)
- moreDataAvailable
(Optional, boolean) Specifies whether more samples are available for the destination.
- limit
(Optional, integer) The maximum number of records to include in the response.
- offset
(Optional, integer) The place to start reading in the collection.
- connections
(Optional, array (object)) The list of connection information.
- name
(Optional, string)
- firstSeen
(Optional, integer) The first time Secure Access related the domain for the resource record, specified
in Unix Epoch time.
- lastSeen
(Optional, integer) The last time Secure Access related the domain for the resource record, specified
in Unix Epoch time.
- securityCategories
(Optional, array (string))
- attacks
(Optional, array (string))
- threatTypes
(Optional, array (string))
- type
(Optional, string)
- ips
(Optional, array (string))
- urls
(Optional, array (string))
Response Sample
Click to view the sample response (200, OK)
Get Samples for Hash Behaviors
GET https://api.sse.cisco.com/investigate/v2/sample/{hash}/behaviors
Description
Get the information about specific actions or unique properties of this sample,
especially local to your network or the computer where the sample is run.
Path Parameters
Query Parameters
- limit
(Optional, integer) The number of items to return in the response from the collection. The default limit is 10.
Increase the limit to request a larger set of data.
- offset
(Optional, integer) A number that represents an index in the collection. By default, the offset is 0 (the first record).
Request Sample
Response Schema (object)
- totalresults
(Optional, integer)
- moreDataAvailable
(Optional, boolean) Specifies whether more samples are available for the destination.
- limit
(Optional, integer) The maximum number of records to include in the response.
- offset
(Optional, integer) The place to start reading in the collection.
- behaviors
(Optional, array (object)) The list of behavioral information related to the destination.
- name
(Optional, string)
- title
(Optional, string)
- hits
(Optional, integer)
- confidence
(Optional, integer)
- severity
(Optional, integer)
- tags
(Optional, array (string))
- threat
(Optional, integer)
- category
(Optional, array (string))
Response Sample
Click to view the sample response (200, OK)
Get Tagging Timeline for Destination
GET https://api.sse.cisco.com/investigate/v2/timeline/{name}
Description
List the historical tagging timeline for a given IP, domain, or URL.
Investigate sorts the timeline items in descending order using the timestamp field.
Each timeline item includes lists of security category,
attack, or threat type associated with the destination.
Use the Tagging Timeline endpoint to verify when Secure Access assigned or removed
a security category, attack, or threat type.
If the current timeline item contains the security category, type of attack,
or threat type not found in the previous timeline item,
Secure Access updated the current timeline item.
If the current timeline item does not contain the security category, attack,
or threat type found in the previous timeline item,
Secure Access removed the security category, type of attack,
or threat type.
Path Parameters
Request Sample
Response Schema (array)
- categories
(Optional, array (string)) The list of security categories assigned at this date and time on the domain, IP, or URL.
If no security categories are assigned, Investigate returns an empty array.
- attacks
(Optional, array (string)) The list of threats assigned at this date and time on the domain, IP, or URL.
If no threats are assigned, Investigate returns an empty array.
- threatTypes
(Optional, array (string)) The list of threat types assigned at this date and time on the domain, IP, or URL.
If no threat types are tagged, Investigate returns an empty array.
- timestamp
(Optional, integer) The date and time of the tagging of the domain, IP, or URL.
The date and time is specified in milliseconds elapsed since the Unix epoch.
Response Sample
Click to view the sample response (200, OK)
Get Subdomains for Domain
GET https://api.sse.cisco.com/investigate/v2/subdomains/{domain}
Description
Get the subdomains of a given domain. If there is no subdomain for the domain, Investigate returns an empty array.
Path Parameters
Query Parameters
Request Sample
Response Schema (array)
- name
(Optional, string) The name of the subdomain.
- securityCategories
(Optional, array (string))
- firstSeen
(Optional, integer) The first time Secure Access related the domain for the resource record, specified
in Unix Epoch time.
Response Sample
Click to view the sample response (200, OK)