Overview
API Concepts Manage API Key
Internet Data
DNSIQ® WHOISIQ™ SSL Certificates Blacklist Lookup Host Attributes
Attack Analytics
Newly Observed Domains Newly Observed Hosts Malware Phishing Scam Content
Digital Footprint
Global Inventory API Global Inventory Schema
Coming Soon
Enrich
PassiveTotal
Getting Started Actions Artifact Articles Attack Surface Intelligence Intel Profiles Data Card Enrichment Services Monitor Project SSL Certificates Tag Artifact Trackers Host Attributes Cookies Components Passive DNS Whois Bulk Enrichment Reputation
Additional Resources
Workspace Management API
RiskIQ.com

Global Inventory

The global inventory endpoint allows you to query RiskIQ's inventory of assets.

Asset Inventory consists of the following asset types: Domain, Host, IP_Address, IP_Block, AS, Page, SSL_Cert, Contact.

Each asset has a unique name which can be used to retrieve the asset from inventory.

 

What It Looks Like

Recency

Currently GI API and UI search both default to searching against "recent" data. There is a special dropdown in the UI and a search history API that will search against historical data.

We define recency based on the datasource from which the various asset fields come from and whether the last seen on those fields makes the cutoff. Breakdown is as follows:

Source Cutoff
Open Ports 14 days
Minicrawls 7 days
Full Crawls 60 days
Cert Stream 90 days
WHOIS 180 days
PDNS 90 days

Get Asset

Retrieve the details for a specific asset by type and name.

Get Asset Example

curl -X GET --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/assets/Domain?name=riskiq.net&global=true'

Get Asset by UUID

Retrieve the details for a specific asset by the assets UUID.

Get Asset by UUID Example

curl -X GET --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/assets/id/d743b76e-567f-67b6-f313-1a4d91b0ffa9'

Bulk Get Asset

Bulk retrieve the details for assets by name and type.

Bulk Get Asset Example

curl -X POST --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/assets/bulk' -H "Content-Type: application/json" -d '{
   "assets": [
      {
        "name": "riskiq.com",
        "type": "DOMAIN"    
      },
      {
        "name": "community.riskiq.com",
        "type": "HOST"
      }
   ]
}'
            

Get Connected Assets

Retrieve the set of assets which are connected to the requested asset. The response contains a page of assets for each related asset type. Additional connected assets can be retrieved by adjusting the page parameter.

Get Connected Asset Example

curl -X GET --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/assets/Domain/connected?name=riskiq.net&page=0&size=20'

Get Attributes

Retrieve the set of attributes which are associated with the requested asset. The response contains a page of attributes. Additional attributes can be retrieved by adjusting the page parameter.

Get Attributes Example

curl -X GET --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/assets/Host/attributes?name=www.riskiq.net&page=0&size=20'

Get Cookies

Retrieve the set of cookies which are associated with the requested asset. The response contains a page of cookies. Additional cookies can be retrieved by adjusting the page parameter.

Get Cookies Example

curl -X GET --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/assets/Host/cookies?name=www.riskiq.net&page=0&size=20'

Get Host Pairs

Retrieve the set of host pairs which are associated with the requested asset. The response contains a page of host pairs. Additional host pairs can be retrieved by adjusting the page parameter.

Get Host Pairs Example

curl -X GET --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/assets/Host/hostPairs?name=www.riskiq.net&page=0&size=20'

Get Mini Crawls

Retrieve the set of mini crawls which are associated with the requested asset. The response contains a page of mini crawls. Additional mini crawls can be retrieved by adjusting the page parameter.

Get Mini Crawls Example

curl -X GET --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/assets/Host/miniCrawls?name=www.riskiq.net&page=0&size=20'

Get SSL Certificates

Retrieve the set of SSL certificates which are associated with the requested asset. The response contains a page of SSL certificates. Additional SSL certificates can be retrieved by adjusting the page parameter.

Get SSL Certificates Example

curl -X GET --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/assets/Host/sslCerts?name=www.riskiq.net&page=0&size=20'

Get Web Components

Retrieve the set of web components which are associated with the requested asset. The response contains a page of web components. Additional web components can be retrieved by adjusting the page parameter.

Get Web Components Example

curl -X GET --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/assets/Host/sslCerts?name=www.riskiq.net&page=0&size=20'

Get Brands

Retrieve the set of brands which are defined for the workspace associated with the API key.

Get Brands Example

curl -X GET --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/brands'

Get Organizations

Retrieve the set of organization which are defined for the workspace associated with the API key.

Get Organizations Example

curl -X GET --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/organizations'

Get Tags

Retrieve the set of tags which are defined for the workspace associated with the API key.

Get Tags Example

curl -X GET --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/tags'

Search

Search Global Inventory for a set of assets that match the criteria. The search body contains a filters element which contains either a single filter or a list of filters combined by an associated condition (AND/OR).

Supported Fields

Field Field Type Asset Types Description
stateEnumeration All Asset state. Possible values API[User-friendly Name]: CANDIDATE[Candidate], CONFIRMED[Approved Inventory], CANDIDATE_INVESTIGATE[Requires Investigation], ASSOCIATED_THIRDPARTY[Dependencies], ASSOCIATED_PARTNER[Monitor Only]
removedStateEnumeration All Remove an asset from inventory. Possible values API[User-friendly Name]: DISMISSED[Dismissed], ARCHIVED[Archived]
confidenceEnumeration All Discovery confidence level. Possible values: Absoulte, High, Medium, Low, Unlikely, Unknown
priorityEnumeration All Asset Priority. Possible values: High, Medium, Low
autoConfirmed Boolean All Was the asset auto-confirmed. Possible values: True, False
enterprise Boolean All Has the asset been designated as an enterprise asset. Possible values: True, False
keystone Boolean All Was this asset designated as a discovery keystone. Possible values: True, False
wildcard Boolean All Has the asset been identified as a wildcard. Possible values: True, False
brand Numeric All Name or numeric id of a brand applied to assets. Supported operators: EQ, NE, IN, NOT_IN, CONTAINS, NOT_CONTAINS, CONTAINS_IN, NOT_CONTAINS_IN, NULL, NOT_NULL
organization Numeric All Name or numeric id of an organization applied to assets. Supported operators: EQ, NE, IN, NOT_IN, CONTAINS, NOT_CONTAINS, CONTAINS_IN, NOT_CONTAINS_IN, NULL, NOT_NULL
tag Numeric All Name or numeric id of a tag applied to assets. Supported operators: EQ, NE, IN, NOT_IN, CONTAINS, NOT_CONTAINS, CONTAINS_IN, NOT_CONTAINS_IN, NULL, NOT_NULL
primaryContact Numeric All The email address or id of the primary contact assigned to the asset. Supported operators: EQ, NE, IN, NOT_IN, CONTAINS, NOT_CONTAINS, CONTAINS_IN, NOT_CONTAINS_IN, NULL, NOT_NULL
secondaryContact Numeric All The email address or id of the secondary contact assigned to the asset. Supported operators: EQ, NE, IN, NOT_IN, CONTAINS, NOT_CONTAINS, CONTAINS_IN, NOT_CONTAINS_IN, NULL, NOT_NULL
discoveryRun Numeric All The id of the discovery run in which the asset was discovered
externalID String All The external ID assigned to the asset
uuid String All Asset unique identifier. Supported Operators: EQ, NE, IN, NOT_IN
name String All Name of the asset. Supported Operators: EQ, NE, STARTS_WITH, NOT_STARTS_WITH, IN, NOT_IN, STARTS_WITH_IN, NOT_STARTS_WITH_IN
type Enumeration All Asset type. Possible values: DOMAIN, HOST, IP_ADDRESS, IP_BLOCK, AS, PAGE, SSL_CERT, CONTACT
firstSeen Date All The date that the asset was first observed.
lastSeen Date All The date that the asset was most recently observed.
createdAt Date All The date that the asset was added to inventory. Supported operators: EQ, NE, IN, NOT_IN, GTE, LTE, BETWEEN
updatedAt Date All The date of the most recent update performed by a user action. Supported operators: EQ, IN, NE, NOT_IN, GTE, LTE, BETWEEN
connected String All Returns assets connected to the given asset. The value of the request must include the asset type and name. For example DOMAIN$$riskiq.net
alexaBucket Enumeration Domain, Host, Page The Alexa rank bucket that the domain is within. Possible values: Bucket0, Bucket1, NotRanked. Where Bucket0 means Top 10k and Bucket 1 means Top 100k
parkedDomain Boolean Domain Has the domain been identified as parked. Possible values: True, False
ianaId String Domain The IANA id associated with the domain registrar
nameServer Tokenized hostname Domain Name Server registered on a domain
domainStatus String Domain Domain status observed on a domain
registrar Tokenized String Domain The registrar identified by the whois record for an asset
email Tokenized String Domain, IP Block, Host, Page, AS Any email address identified by the whois record for an asset
admin Tokenized String Domain, IP Block, Host, Page, AS, Host, Page, AS The administrator name identified by the whois record for an asset
adminOrg Tokenized String Domain, IP Block, Host, Page, AS The administrative organization identified by the whois record for an asset
adminEmail Tokenized String Domain, IP Block, Host, Page, AS The administrative contact email address identified by the whois record for an asset
technical Tokenized String Domain, IP Block, Host, Page, AS, Host, Page, AS The technical contact name identified by the whois record for an asset
techEmail Tokenized String Domain, IP Block, Host, Page, AS The technical contact email address identified by the whois record for an asset
technicalOrg Tokenized String Domain, IP Block, Host, Page, AS The technical contact organization identified by the whois record for an asset
registrant Tokenized String Domain, IP Block, Host, Page, AS, Host, Page, AS The registrant name identified by the whois record for an asset
registrantEmail Tokenized String Domain, IP Block, Host, Page, AS The registrant email address identified by the whois record for an asset
registrantOrg Tokenized String Domain, IP Block, Host, Page, AS The registrant organization identified by the whois record for an asset
domainExpirationExpiration Range Domain The 30 day period in which the domain expires. Possible values: Expired, Expires30, Expires60, Expires90, ExpiresAfter90
asnNumber Numeric AS, IP Address, IP Block, Host, Page The autonomous system number that the asset is related to
bgpPrefix String IP Block The BGP prefix for the IP Block
reputationName String IP Address, IP Block The name of the IP reputation list that this asset was found on
reputationType String IP Address, IP Block The threat type associated with the reputation list that this asset was found on
port Numeric IP Address Port identified on an IP Address. Supported operators: EQ, IN, NE, NOT_IN
portLastSeen Enumeration IP Address Period in which the port has been observed open. Possible values: 7, 14, 30. Supported operators: EQ, IN
banner Tokenized String IP Address Banner content observed from a port scan of the IP Address. Supported operators: MATCHES, NOT_MATCHES, MATCHES_IN, NOT_MATCHES_IN, NULL, NOT_NULL
hostExcluded Boolean IP Address If true then only IP Addresses associated with confirmed IP Blocks will be included in the results. Possible values: True, False
ipBlock String IP Address IP Block containing the IP Address
cname Tokenized hostname Host The CNAME that the host DNS record refers to
cnameDomain Tokenized hostname Host The domain from the CNAME that the host DNS record refers to
ipAddress Tokenized String Host IP addresses which the host has resolved to. Supported operators include the Tokenized String operators plus BETWEEN where the value can be a start and end IP Address or a single IP Block
hasNameServerRecord Boolean IP Address, Host Has the asset been identified as a Name Server
hasMailServerRecord Boolean IP Address, Host Has the asset been identified as a Mail Server
webServer Boolean Host Has the asset been identified as a Web Server
domain Tokenized hostname Host, Page The domain on which the asset was registered
webComponentName Tokenized String Page, Host, IP Address Name of web component observed on the asset
webComponentVersion Tokenized String Page, Host, IP Address Version of web component observed on the asset
webComponentNameVersion Tokenized String Page, Host, IP Address Full name including the name and version of web component observed on the asset
webComponentType Tokenized Page, Host, IP Address Type of WebComponent observed on the asset
cweID String Page, Host, IP Address The id of a CWE identified on the asset
cveID Tokenized String Page, Host, IP Address The id of a CVE identified on the asset
cvssScore Numeric Page, Host, IP Address CVSS score reflecting the severity of a CVE found on an asset. Supported operators: EQ, NE, IN, NOT_IN, NULL, NOT_NULL, GTE, LTE, BETWEEN, EMPTY, NOT_EMPTY
cvss3BaseScore Numeric Page, Host, IP Address CVSS v3 base score reflecting the severity of a CVE found on an asset. Supported operators: EQ, NE, IN, NOT_IN, NULL, NOT_NULL, GTE, LTE, BETWEEN, EMPTY, NOT_EMPTY
host Tokenized hostname Page The host that the page was served from
parkedPage Boolean Page Has the page been identified as parked. Possible values: True, False
rootUrl Boolean Page Is the page a root page, meaning a hostname prepended with the http or https protocol. Possible values: True, False
server Tokenized String Page Name of a server web component identified on the page asset
framework Tokenized String Page Name of a framework web component identified on the page asset
pageTitle Tokenized String Page Title of the page
url Tokenized URL Page URL of the page
finalUrl Tokenized URL Page Final URL of the page after following one or more redirects
responseCode Numeric Page The http response code returned by the page
finalResponse Numeric Page The final http response code returned by the page after following one or more redirects
scheme String Page The scheme component of the URI for the page
finalScheme String Page The scheme component of the final URI for the page after following one or more redirects
pageLive Boolean Page Is the page active. Possible values: True, False
language String Page The language of the the page
securityPolicy String Page Security policy violations identified on the page
error Tokenized String Page The error encountered while crawling the page
resourceUrl Tokenized URL Page The url of a dependent resource found on the page
resourceMd5 String Page The md5 hash of the content of a dependent resource found on the page
resourceHost Tokenized hostname Page The hostname of a dependent resource found on the page
sslCertExpirationExpiration Range SSL Cert The 30 day period in which the SSL certificate expires. Possible values: Expired, Expires30, Expires60, Expires90, ExpiresAfter90
sslCertOrganization Tokenized String SSL Cert The name of the organization which registered the SSL certificate
sslCertOrganizationalUnit Tokenized String SSL Cert The unit within the organization which registered the SSL certificate
issuerCommonName Tokenized String SSL Cert The SSL certificate issuer common name
subjectCommonName Tokenized String SSL Cert The SSL certificate subject common name
issuerAlternativeName Tokenized String SSL Cert The SSL certificate alternative issuer names
subjectAlternativeName Tokenized String SSL Cert The SSL certificate alternative subject names
sslCertSubjectOrganization Tokenized String SSL Cert The SSL certificate subject organization
sslCertSubjectOrganizationalUnit Tokenized String SSL Cert The SSL certificate subject organizational uni
signatureAlgorithm String SSL Cert The SSL certificate signature algorithm
signatureAlgorithmOid String SSL Cert The SSL certificate signature algorithm OID
serialNumber String SSL Cert The ssl certificate serial number
keySize Numeric SSL Cert The key size of the SSL certificate
selfSigned Boolean SSL Cert Is the SSL certificate self signed. Possible values: True, False

Date Fields: Date fields should be in the 'yyyy-MM-dd' or 'yyyy-MM-dd HH-mm-ss' format. For example: 2018-12-25 20:00:00. Date fields also support human readable values such as today, yesterday, last week, 10 days ago, 2 weeks ago, 1 month ago, etc.

Tokenized Fields: When a field is tokenized it means that the value is split on whitespace and punctuation characters.
The "@" character is among the set of token-splitting punctuation, so the local-part and domain in an email addresses are distinct terms.
There are some special rules for tokenizing on the period character. Host-names and URLs are tokenized on each period character. Non-host-name tokenized string values are not tokenized on periods that are not followed by whitespace.
The MATCHES and NOT_MATCHES operators can be used to search by tokenized terms within a string value.

Tokenization Examples:
Value: "community.riskiq.com"                        Tokenized Value: "community", "riskiq", "com"
Value: "Email john.doe@foo.com"                   Tokenized Value: "Email", "john.doe", "foo.com"
Value: "https://www.riskiq.net/index.html"    Tokenized Value: "https", "www", "riskiq", "net", "index", "html"

Supported Operators

Operator Description
EQ Returns results where the field exactly matches the search value
NE Returns results where the field does not exactly match the search value
STARTS_WITH Returns results where the field starts with the search value
NOT_STARTS_WITH Returns results where the field does not start with the search value
MATCHES Returns results where a tokenized term in the field exactly matches the search value
NOT_MATCHES Returns results where a tokenized term in the field does not exactly matches the search value
CONTAINS Returns results where the field content contains the search value
NOT_CONTAINS Returns results where the field content does not contain the search value
GTE Returns results where the field is greater than or equal to the search value
LTE Returns results where the field is less than or equal to the search value
NULL Returns results having an empty value in the field identified by the search filter
NOT_NULL Returns results having a non-empty value the field identified by the search filter
BETWEEN Returns results where the field is between the two search values
IN Returns results where the field exactly matches one of the search values
NOT_IN Returns results where the field does not exactly match any of the search values
STARTS_WITH_IN Returns results where the field starts with one of the search values
NOT_STARTS_WITH_IN Returns results where the field does not start with any of the search values
MATCHES_IN Returns results where a tokenized term in the field exactly matches one of the search values
NOT_MATCHES_IN Returns results where a tokenized term in the field does not exactly match any of the search values
CONTAINS_IN Returns results where the field content contains one of the search values
NOT_CONTAINS_IN Returns results where a tokenized term in the field content does not contain the any of the search values

Supported Operators By Field Type

Unless specifically noted in the Supported Fields list above each field supports a set of operators specific to the field type.

Field Type Supported Operators
String EQ, NE, STARTS_WITH, NOT_STARTS_WITH, IN, NOT_IN, STARTS_WITH_IN, NOT_STARTS_WITH_IN, CONTAINS, NOT_CONTAINS, CONTAINS_IN, NOT_CONTAINS_IN, NULL, NOT_NULL
Tokenized String EQ, NE, STARTS_WITH, NOT_STARTS_WITH, MATCHES, NOT_MATCHES, IN, NOT_IN, STARTS_WITH_IN, NOT_STARTS_WITH_IN, MATCHES_IN, NOT_MATCHES_IN, CONTAINS, NOT_CONTAINS, CONTAINS_IN, NOT_CONTAINS_IN, NULL, NOT_NULL
Boolean EQ, NE
Numeric EQ, NE, IN, NOT_IN, NULL, NOT_NULL
Date EQ, NE, IN, NOT_IN, GTE, LTE, BETWEEN, NULL, NOT_NULL
Enumeration EQ, NE, IN, NOT_IN, NULL, NOT_NULL
Expiration Range EQ, NE, IN, NOT_IN

Pagination

Global Inventory search supports two mutually exclusive methods of pagination: 1) Paging by cursor. 2) Paging by page number.

Paging by cursor: When using a cursor the sort values of the last document returned are used to compute a "mark" representing a logical point in the ordered space of sort values. That "mark" can be specified in the parameters of subsequent requests to tell the search where to continue. In addition to returning the top N (determined by the size parameter) sorted results the search response will also include an encoded String named "mark". You then take the "mark" String value from the response, url encode it, and pass it back as the "mark" parameter for your next request.

Paging by page number: When paging by number a "page" parameter must be included which indicates the page of sorted results to retrieve. This paging option is limited to 10,000 results (i.e., page + size must be less than 10,000). If accessing more results or if retrieving all results, then paging by cursor should be used instead.

Parameter Description
size Indicates the number of items to be returned per page. The default value is 20.
mark Indicates that a cursor will be used to page through the search results. A value of '*' must be used to start at the beginning of the search results. This value must be url encoded.
page Indicates the index of the page to be returned. The first page is indicated by a value of 0. This value is ignored if a mark is specified.

If neither mark or page are included in the request then the first page of results will be returned.

Search Examples

Search for IP_Address assets in your workspace

curl -X POST --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/search?mark=*&size=20' -H "Content-Type: application/json" -d '{
   "filters": {
      "operator": "EQ",  "name": "type",  "value": "IP_ADDRESS"
   }
}'

{
  "totalElements": 31401,
  "totalPages": 1571,
  "last": false,
  "numberOfElements": 20,
  "first": true,
  "size": 20,
  "number": 0,
  "content": [
    {
      "name": "194.233.211.33",
      "type": "IP_ADDRESS",
      "uuid": "41beb2eb-6078-5fa8-5d76-d4c7aabb4f75",
      "description": "194.233.211.33",
      "asset": ...
    },
    ...
  ],
  "mark": "AoJ0/PP+pvICOjE5NC4yMzMuMjExLjMzJCRJUF9BRERSRVNT",
  "facets": []
}
            

Search for IP_Address assets in your workspace with ports 80 and 443 observed open in the past 14 days

curl -X POST --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/search?mark=*&size=20' -H "Content-Type: application/json" -d '{
	"filters": {
         "condition": "AND",
         "value": [
            {  "operator": "EQ",  "name": "type",  "value": "IP_ADDRESS"  },
            {  "operator": "IN",  "name": "port",  "value": [80, 443]  },
            {  "operator": "EQ",  "name": "portLastSeen",  "value": "14"  }
      ]
   }
}'
            

Search for Domain asset by name

curl -X POST --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/search?mark=*&size=20' -H "Content-Type: application/json" -d '{
      "filters": {
         "condition": "AND",
         "value": [
            {  "operator": "EQ",  "name": "type",  "value": "DOMAIN"  },
            {  "operator": "EQ",  "name": "name",  "value": "riskiq.net"  }
      ]
   }
}'
            

Search for Pages by partial domain

curl -X POST --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/search?mark=*&size=20' -H "Content-Type: application/json" -d '{
      "filters": {
         "condition": "AND",
         "value": [
            {  "operator": "EQ",  "name": "type",  "value": "PAGE"  },
            {  "operator": "MATCHES",  "name": "domain",  "value": "riskiq"  }
      ]
   }
}'
            

Search for Hosts seen this week

curl -X POST --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/search?mark=*&size=20' -H "Content-Type: application/json" -d '{
      "filters": {
         "condition": "AND",
         "value": [
            {  "operator": "EQ",  "name": "type",  "value": "HOST"  },
            {  "operator": "GTE",  "name": "lastSeen",  "value": "7 days ago"  }
      ]
   }
}'
            

Search for Hosts by brand

curl -X POST --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/search?mark=*&size=20' -H "Content-Type: application/json" -d '{
      "filters": {
         "condition": "AND",
         "value": [
            {  "operator": "EQ",  "name": "type",  "value": "HOST"  },
            {  "operator": "EQ",  "name": "brand",  "value": "RiskIQ"  }
      ]
   }
}'
            

Historical search for parked pages in your workspace

curl -X POST --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/search/history?mark=*&size=20' -H "Content-Type: application/json" -d '{
   "filters":
	{
		"condition": "AND",
		"value": [
			{ "name": "parkedPage", "operator": "IN", "value": [false] },
			{ "name": "type", "operator": "IN", "value": [ "PAGE" ] },
			{ "name": "name", "operator": "EQ", "value": "http://www.botasdeinviernoguadalajara.com/" }
		]
	}
}'
            

Add Assets

Add one or more assets. The request is comprised of one or more asset identifiers and a list of one or more properties indicating the assets to add along with the properties to apply to all assets.

Asset Identifier

Field Description
name Name of the asset
type Asset type. Possible values: DOMAIN, HOST, IP_ADDRESS, IP_BLOCK, AS, PAGE, SSL_CERT, CONTACT

Properties

See properties examples here

Asset State

Field Description
confirm A boolean value to indicate if the asset state should be CONFIRMED into inventory (confirm: true) or as a CANDIDATE asset in inventory (confirm: false or not specified)

Target Asset Types

Field Description
targetAssetTypes An array of target asset types to also add to inventory, along with any supplied properties, that are connected to the asset identifiers (e.g. an asset identifier for a PAGE can cascade the properties to all known IPs for that PAGE).

Add Example

curl -X POST --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/assets/add' -H "Content-Type: application/json" -d '{
   "assets" : [
        {"name" : "http://www.riskiq.net/", "type" : "PAGE"},
        {"name" : "riskiq.net", "type" : "DOMAIN"}
    ],
    "properties" : [
        {"name" : "priority", "value" : "HIGH"},
        {"name" : "primaryContact", "value" : "john.doe@riskiq.net"},
        {"name" : "brand", "value" : ["RiskIQ"], "action" : "ADD"},
        {"name" : "tag", "value" : ["hello", "world"], "action" : "UPDATE"}
    ],
    "confirm": true,
    "targetAssetTypes": [
        "IP_ADDRESS"
    ]
}'
            

Update Assets

Update one or more properties on a set of assets. The request identifies the assets to be updated and includes a list of one or more properties indicating the values to be updated. The assets to be updated can be updated in one of two ways. The request can include the asset identifiers explicitly indicating the assets to be updated. The request can include a search query, the results of which will be updated with the requested properties.

Assets

Field Description
name Name of the asset
type Asset type. Possible values: DOMAIN, HOST, IP_ADDRESS, IP_BLOCK, AS, PAGE, SSL_CERT, CONTACT

Query

See search examples here

Properties

See properties examples here

Target Asset Types

Field Description
targetAssetTypes An array of related asset types which will also be updated (e.g. an asset identifier for a PAGE can cascade the properties to all known IPs for that PAGE).

Update Examples

Update including asset identifiers

curl -X POST --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/update' -H "Content-Type: application/json" -d '{
   "assets" : [
        {"name" : "http://www.riskiq.net/", "type" : "PAGE"},
        {"name" : "riskiq.net", "type" : "DOMAIN"}
    ],
    "properties" : [
        {"name" : "state", "value" : "CONFIRMED"},
        {"name" : "priority", "value" : "HIGH"},
        {"name" : "primaryContact", "value" : "john.doe@riskiq.net"},
        {"name" : "brand", "value" : ["RiskIQ"], "action" : "ADD"},
        {"name" : "tag", "value" : ["hello", "world"], "action" : "UPDATE"}
    ],
    "targetAssetTypes": [
        "IP_ADDRESS"
    ]
}'
            

Update including a search query

curl -X POST --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/update' -H "Content-Type: application/json" -d '{
    "query":{
        "filters":{
            "condition":"AND",
            "value":[
                {"name":"type","operator":"IN","value":["IP_BLOCK"]},
                {"name":"state","operator":"IN","value":["CANDIDATE"]}
            ]
        }
    },
    "properties":[{"name":"tag","value":["Tag1"],"action":"ADD"}]
}'
            

Removing assets from inventory

curl -X POST --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/update' -H "Content-Type: application/json" -d '{
   "assets" : [
        {"name" : "http://www.riskiq.net/", "type" : "PAGE"},
        {"name" : "riskiq.net", "type" : "DOMAIN"}
    ],
    "properties" : [
        {"name" : "removedState", "value" : "DISMISSED"}
    ]
}'
            

Response Information

Global Inventory updates are processed asynchronously. The update response will include an identifier which can be used in the Get Task Status request to check on the status of the update.

{
  "asynchronous": true,
  "identifier": "680e8fbf-0f2c-42dc-9b85-5042c7e220d3"
}
            

Properties

Property Property Type Description
stateEnumeration Set the asset state. Possible values API[User-friendly Name]: CANDIDATE[Candidate], CONFIRMED[Approved Inventory], CANDIDATE_INVESTIGATE[Requires Investigation], ASSOCIATED_THIRDPARTY[Dependencies], ASSOCIATED_PARTNER[Monitor Only]
removedStateEnumeration Remove an asset from inventory. Possible values API[User-friendly Name]: DISMISSED[Dismissed], ARCHIVED[Archived]
priorityEnumeration Set the asset Priority. Possible values: High, Medium, Low
enterprise Boolean Designated as an enterprise asset. Possible values: True, False
brand Collection Name or numeric id of a brand to be applied to the asset.
organization Collection Name or numeric id of an organization to be applied to the asset.
tag Collection Name or numeric id of a tag to be applied to the asset.
primaryContact Numeric The email address or id of the primary contact to be assigned to the asset.
secondaryContact Numeric The email address or id of the secondary contact to be assigned to the asset.
externalID String The external ID to be applied to the asset.
externalMetadata String The external metadata to be applied to the asset.
note String A note to be applied to the asset.

Collection Properties: Collection properties support an optional action. The possible values are: UPDATE, ADD, REMOVE with UPDATE being the default.
UPDATE means replace the current set of items with the given set.
ADD means add the given items to the existing set.
REMOVE means remove the given items from the existing set.


Get Task Status

Check the status of an asynchronous Global Inventory update task. The response includes the state of the request. Potential values are PENDING, RUNNING, COMPLETE, INCOMPLETE, FAILED, WARNING

Get Task Example

curl -X GET --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/task/680e8fbf-0f2c-42dc-9b85-5042c7e220d3'

Sample Response

{
  "taskClass": "com.riskiq.globalinventory.service.GlobalInventoryUpdateTask",
  "key": {
    "workspaceID": 4639,
    "uuid": "680e8fbf-0f2c-42dc-9b85-5042c7e220d3"
  },
  "userID": 4590,
  "startedAt": 1586268466216,
  "completedAt": 1586268491805,
  "state": "COMPLETE",
  "reason": null,
  "data": {
    "estimated": 3266,
    "progress": 57,
    "updated": 3266,
    "properties": [
      {
        "name": "tag",
        "value": [
          9684
        ],
        "action": "ADD"
      }
    ]
  },
  "taskName": "GlobalInventoryUpdateTask"
}
            

Cancel Update Task

Cancel further processing of an asynchronous Global Inventory update task. Note: Changes which have been applied are not reverted.

Cancel Update Task Example

curl -X POST --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/task/680e8fbf-0f2c-42dc-9b85-5042c7e220d3/cancel' -d {}

Sample Response

{
  "taskClass": "com.riskiq.globalinventory.service.GlobalInventoryUpdateTask",
  "key": {
    "workspaceID": 4639,
    "uuid": "680e8fbf-0f2c-42dc-9b85-5042c7e220d3"
  },
  "userID": 4590,
  "startedAt": 1598900074786,
  "lastPolledAt": 1598900222445,
  "state": "INCOMPLETE",
  "phase": "POLLING",
  "reason": "Cancelled by user",
  "data": {
    ...
  },
  "taskName": "GlobalInventoryUpdateTask",
  "polling": false
}
            

Deltas

RiskIQ runs a daily process which compares the current state of your inventory against the state of your inventory the previous day, from 7 days ago and from 30 days ago. This daily process also compares specific asset details and identifies assets which have changed in your inventory over those time periods. The deltas endpoint returns the set of assets which were found to be added to or removed from your inventory as well as the set of assets that include changes of the given type over those time periods. The following details are included in that comparison:

  • Resource Changes: Hosts that include resources which have been added or changed.

Deltas Examples: Assets Added or Removed

Retrieve the list of Host assets that were identified as added to inventory in the latest deltas report

curl -X GET --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/deltas?type=HOST&page=0&size=20'

Retrieve the list of Host assets that were identified as added to inventory in the deltas report that ran on 2018-10-31

curl -X GET --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/deltas?date=2018-10-31&type=HOST&page=0&size=20'

Retrieve the list of Host assets that were identified as removed inventory from inventory in the 7 days prior to the deltas report that ran on 2018-10-31

curl -X GET --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/deltas?date=2018-10-31&type=HOST&measure=REMOVED&range=7&page=0&size=20'

Sample Response

{
  "content": [
    {
      "runId": "20181030",
      "name": "www.riskiq.net",
      "type": "HOST",
      "measure": "added",
      "enterprise": false,
      "state": "CONFIRMED",
      "priority": "HIGH"
    },
    {
      "runId": "20181030",
      "name": "www.riskiq.com",
      "type": "HOST",
      "measure": "added",
      "enterprise": false,
      "state": "CONFIRMED",
      "priority": "HIGH"
    }
  ],
  "totalElements": 10,
  "totalPages": 5,
  "last": false,
  "numberOfElements": 2,
  "first": true,
  "size": 2,
  "number": 0
}
            

Deltas Examples: Asset Detail Changes

Retrieve the list of Host assets that were identified in the latest deltas report as including resources hosted internally which have been added or changed.

curl -X GET --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/deltas?type=SELF_HOSTED_RESOURCE'

Retrieve the list of Host assets that were identified in the deltas report for the given date as including resources hosted by a third party which have been added or changed.

curl -X GET --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/deltas?date=2018-10-31&type=THIRDPARTY_HOSTED_RESOURCE'

Sample Response

{
  "content": [
    {
      "name": "remote.riskiq.net",
      "runDate": "2019-02-13",
      "measure": "added",
      "autoConfirmed": false,
      "enterprise": false,
      "confidence": "ABSOLUTE",
      "id": 40198599,
      "state": "CONFIRMED",
      "discoveryRun": [
        151073
      ],
      "priority": "HIGH",
      "brand": [
        {
          "createdAt": 1462568961000,
          "updatedAt": 1462568961000,
          "status": "ACTIVE",
          "workspaceBrandID": 1239,
          "workspaceID": 2695,
          "name": "RiskIQ",
          "id": 1239
        }
      ],
      "childUrlFirstSeen": "1550088309054",
      "resourceFirstSeen": "1550088309054",
      "childUrlLastSeen": "1550127582161",
      "dynamicScore": "0.4",
      "lastSeenResourceGuid": "498cd816-98ab-4b22-84e6-7a44e93351cb",
      "lastSeenCrawlGuid": "b3f6fcda-42e4-437a-9568-88717e54904e",
      "firstSeenPageGuid": "8f7e965a-dd14-4a94-9362-346929b5e11f",
      "lastSeenPageGuid": "1d9072e4-ed3f-4e43-9a92-cc606f9f50a3",
      "firstSeenResourceGuid": "cba1483f-5f19-41fb-a6be-2045907f6ec5",
      "resourceLastSeen": "1550127582161",
      "responseBodySize": "6992",
      "firstSeenCrawlGuid": "be75bbbc-1b92-48b1-859a-6e12d3b64790",
      "md5": "f8ed87eacf479aae7793f3ef31be72b5",
      "resource": "https://remote.riskiq.net/crawlview/static/js/riq/riq_v0.0.1-7554-gac7c36e.js",
      "type": "HOST",
      "microDeltaType": "SELF_HOSTED_RESOURCE",
      "description": "remote.riskiq.net"
    }
  ],
  "totalElements": 12,
  "totalPages": 12,
  "last": false,
  "numberOfElements": 1,
  "first": true,
  "size": 1,
  "number": 0
}
            

Deltas Summary

Retrieve summary information describing counts of confirmed assets that have been added or removed from inventory over the given time period.

Deltas Summary Examples

Retrieve delta summary information for a date

curl -X GET --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/deltas/summary?date=2019-01-15'

Response Information

The delta summary response includes a node similar to the following for each asset type. Each asset type includes an aggregation over a single day, 7 days and 30 days as denoted by the range. The added and removed nodes indicate the number of confirmed assets added and removed during that time period. The difference node is added minus removed. The count node in the single day aggregation indicates the number of confirmed assets of that type in inventory.

{
    "type": "DOMAIN",
    "aggregations": [
        {
            "removed": 0,
            "added": 0,
            "count": 158,
            "range": 1,
            "difference": 0
        },
        {
            "removed": 0,
            "added": 2,
            "range": 7,
            "difference": 2
        },
        {
            "removed": 1,
            "added": 3,
            "range": 30,
            "difference": 2
        }
    ]
}
            

Newly Observed Ports

Retrieve the list of Asset Policy Engine newly opened ports hits

Request Parameters

Parameter Description
period Determines the newly open port period in days. Valid options are 7, 14 & 30. The 7 day period means that any port seen on an IP address that had not been seen in the previous 7 days is considered a newly opened port. If the period is not specified then newly opened ports from the all time period will be returned.
ports Comma delimited list of ports used to limit the results to those which include a port in the list.
excludedPorts Comma delimited list of ports used to limit the results to those which do not include a port in the list
after Timestamp in milliseconds used to limit the results to newly opened port hits seen since after the timestamp.
stream Used to indicate if the request is using the streaming feature of the endpoint.
size The maximum number of newly opened port hits that will be returned. The default value is 100.

Streaming Functionality

The newly opened port endpoint supports streaming which means that if requested the service will track the timestamp of the last newly opened port hit that was returned. A subsequent request will continue at the point where the previous request completed. The service will track newly opened port streams per unique request. A request is uniquely identified by the api token used to authenticate the request plus the period, ports and excludedPorts parameters included in the request. For example a request to retrieve newly opened ports for period 7 and ports 80,8080 will be streamed independently of another request using the same api token requesting newly opened ports for period 7 and ports 443.

Note: Including the after parameter with stream=true will reset the stream for that unique request parameter combination to the specified timestamp.

Example Requests

Retrieve the list of newly opened port hits for the 7 day period for specific ports since a point in time deltas report

curl -X GET --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/ape/hit/nop?period=7&ports=80,443&after=1590987600000&size=20'

Retrieve the list of newly opened port hits for the 14 day period, excluding specific ports, using the streaming functionality deltas report

curl -X GET --header 'Accept: application/json' --header "Authorization: Basic $ENCODED_API_KEY" 'https://api.riskiq.net/v1/globalinventory/ape/hit/nop?period=14&excludedPorts=80,443&stream=true&size=20'

Response Information

Each newly opened port hit includes a createdAt date which indicates the time that the newly opened port hit was created. It will also include a partially populated Global Inventory IP Address asset that the hit occurred on. The asset will include the IP address, the open port and banner information for the open port if it was detected. The sample below is a snippet of the response showing the relevant information.

{
    "workspaceId": 1000,
    "policyId": "NEWLY_OBSERVED_PORTS_7_DAYS-80",
    "createdAt": 1591294895716,
    "source": "newlyObservedPorts",
    "asset": {
      "name": "156.244.72.60",
      "type": "IP_ADDRESS",
      "ipAddressAsset": {
        "ipAddress": "156.244.72.60",
        "services": [
          {
            "scheme": "unknown",
            "port": 80,
            "firstSeen": 1590801474000,
            "lastSeen": 1590801474000,
          }
        ],
        "banners": [
          {
            "port": 80,
            "banner": "...",
            "firstSeen": 1590801474000,
            "lastSeen": 1590801474000,
            "bannerMetadata": null,
          }
        ]