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
Coming Soon
Enrich Global Inventory
Additional Resources
PassiveTotal 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, Name_Server, Mail_Server, Contact.

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

 

What It Looks Like

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 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 Host Pairs 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'

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: Candidate, Confirmed, Archived, Dismissed
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
brand Numeric All Name or numeric id of a brand applied to assets
organization Numeric All Name or numeric id of an organization applied to assets
tag Numeric All Name or numeric id of a tag applied to assets
primaryContact Numeric All The email address or id of the primary contact assigned to the asset
secondaryContact Numeric All The email address or id of the secondary contact assigned to the asset
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
name String All Name of the asset
type Enumeration All Asset type. Possible values: DOMAIN, HOST, IP_ADDRESS, IP_BLOCK, AS, PAGE, SSL_CERT, NAME_SERVER, MAIL_SERVER, 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.
updatedAt Date All The date of the most recent update performed by a user action.
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 Any email address identified by the whois record for an asset
adminEmail Tokenized String Domain, IP Block The administrative contact email address identified by the whois record for an asset
techEmail Tokenized String Domain, IP Block The technical contact email address identified by the whois record for an asset
registrantEmail Tokenized String Domain, IP Block The registrant email address identified by the whois record for an asset
registrantOrg Tokenized String Domain, IP Block The registrant organization identified by the whois record for an asset
domainExpirationEnumeration Domain The 30 day period in which the domain expires. Possible values: Expired, Expires30, Expires60, Expires90, ExpiresAfter90
asnNumber Numeric AS, IP Address, IP Block The autonomous system number that the asset is related to
asName Tokenized String AS, IP Address, IP Block The name of 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
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
ipAddress String Host IP addresses which the host has resolved to
domain Tokenized hostname Host, Mail Server, Name Server, 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
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
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 String 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
sslCertExpirationEnumeration 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
signatureAlgorithm String SSL Cert The SSL certificate signature algorithm
serialNumber String SSL Cert The ssl certificate serial number

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 are tokenized on each period character. Non-host-name tokenized string values are not tokenized on periods that are not followed by whitespace.
Url fields are split into the protocol, host and path components
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
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 one 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 matches one 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, 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, 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

Pagination

Parmeter Description
page Indicates the index of the page to be returned. The first page is indicated by a value of 0
size Indicates the number of items to be returned per page. The default value is 20.

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?page=0&size=20' -H "Content-Type: application/json" -d '{
   "filters": {
      "operator": "EQ",  "name": "type",  "value": "IP_ADDRESS"
   }
}'
            

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?page=0&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?page=0&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?page=0&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?page=0&size=20' -H "Content-Type: application/json" -d '{
      "filters": {
         "condition": "AND",
         "value": [
            {  "operator": "EQ",  "name": "type",  "value": "HOST"  },
            {  "operator": "GT",  "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?page=0&size=20' -H "Content-Type: application/json" -d '{
      "filters": {
         "condition": "AND",
         "value": [
            {  "operator": "EQ",  "name": "type",  "value": "HOST"  },
            {  "operator": "EQ",  "name": "brands",  "value": "RiskIQ"  }
      ]
   }
}'
            

Update Assets

Update one or more properties on a set of assets. The request is comprised of one or more asset identifiers and a list of one or more properties indicating the values to be updated.

Asset Identifier

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

Properties

Property Property Type Description
stateEnumeration Set the asset state. Possible values: Candidate, Confirmed, Archived, Dismissed
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.

Update Example

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"}
    ]
}'
            

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
        }
    ]
}