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, Resource, SSL_Cert, Name_Server, Mail_Server, Contact, Social.

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'

Search

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 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
LIKE, CONTAINS, CONTAINS_EQ Returns results where the field contains the search value
NOT_LIKE, NOT_CONTAINS, NOT_CONTAINS_EQ Returns results where the field does not contain the search value
GT, GTE Returns results where the field is greater than or equal to the search value
LT, LTE Returns results where the field is less than or equal to the search value
NULL Returns results not having the field identified by the search filter
NOT_NULL Returns results having 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
CONTAINS_IN Returns results where the field contains one of the search values
NOT_CONTAINS_IN Returns results where the field does not contain any of the search values

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.

Supported Fields

Field Asset Types Description Facetable Tokenized
id All Numeric id of asset in traditional inventory. Note that this id is deprecated.
state All Asset state. Possible values: Candidate, Confirmed, Archived, Dismissed
confidence All Discovery confidence level. Possible values: Absoulte, High, Medium, Low, Unlikely, Unknown
priority All Asset Priority. Possible values: High, Medium, Low
autoConfirmed All Was the asset auto-confirmed. Possible values: True, False
enterprise All Has the asset been designated as an enterprise asset. Possible values: True, False
brand All Name or numeric id of a brand applied to assets
organization All Name or numeric id of an organization applied to assets
tag All Name or numeric id of a tag applied to assets
primaryContact All The email address of the primary contact assigned to the asset
secondaryContact All The email address of the secondary contact assigned to the asset
discoveryRun All The id of the discovery run in which the asset was discovered
name All Name of the asset
type All Asset type. Possible values: DOMAIN, HOST, IP_ADDRESS, IP_BLOCK, AS, PAGE, RESOURCE, SSL_CERT, NAME_SERVER, MAIL_SERVER, CONTACT, SOCIAL
firstSeen All The date that the asset was first observed.
lastSeen All The date that the asset was most recently observed.
parkedDomain Domain Has the domain been identified as parked. Possible values: True, False
ianaId Domain The IANA id associated with the domain registrar
nameServer Domain Name Server registered on a domain
domainStatus Domain Domain status observed on a domain
email Domain, IP Block Any email address identified by the whois record for an asset
adminEmail Domain, IP Block The administrative contact email address identified by the whois record for an asset
techEmail Domain, IP Block The technical contact email address identified by the whois record for an asset
registrantEmail Domain, IP Block The registrant email address identified by the whois record for an asset
registrantOrg Domain, IP Block The registrant organization identified by the whois record for an asset
asnNumber AS, IP Address, IP Block The autonomous system number that the asset is related to
bgpPrefix IP Block The BGP prefix for the IP Block
reputationName IP Address, IP Block The name of the IP reputation list that this asset was found on
reputationType IP Address, IP Block The threat type associated with the reputation list that this asset was found on
port IP Address Port identified on an IP Address. Supported operators: EQ, IN, NE, NOT_IN
portLastSeen IP Address Period in which the port has been observed open. Possible values: 7, 14, 30. Supported operators: EQ, IN
banner IP Address Banner content observed from a port scan of the IP Address
ipAddress Host IP addresses which the host has resolved to
domain Host, Mail Server, Name Server, Page The domain on which the asset was registered
webComponentName Page, Host, IP Address Name of web component observed on the asset
webComponentVersion Page, Host, IP Address Version of web component observed on the asset
webComponentType Page, Host, IP Address Type of WebComponent observed on the asset
cveID Page, Host, IP Address The id of a CVE identified on the asset
cvssScore Page, Host, IP Address CVSS score reflecting the severity of a CVE found on an asset
host Page The host that the page was served from
parkedPage Page Has the page been identified as parked. Possible values: True, False
server Page Name of a server web component identified on the page asset
framework Page Name of a framework web component identified on the page asset
pageTitle Page Title of the page
responseCode Page The http response code returned by the page
scheme Page The scheme component of the URI for the page
pageLive Page Is the page active. Possible values: True, False
sslCertExpiration SSL Cert Date that the SSL certificate will expire
sslCertOrganization SSL Cert The name of the organization which registered the SSL certificate
sslCertOrganizationalUnit SSL Cert The unit within the organization which registered the SSL certificate
issuerCommonName SSL Cert The SSL certificate issuer common name
subjectCommonName SSL Cert The SSL certificate subject common name
issuerAlternativeName SSL Cert The SSL certificate alternative issuer names
subjectAlternativeName SSL Cert The SSL certificate alternative subject names
signatureAlgorithm SSL Cert The SSL certificate signature algorithm
serialNumber 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 around one or more delimiters. In this case the fields are tokenized around the period (.) character. This impacts the results of contains searches. For example, if the value is riskiq.net then it is split into 2 parts, 'riskiq' and 'net'. A contains search on tokenized fields will find a match on any asset where one of the values matches the search critieria. In this example a contains search for 'riskiq' will return the asset. A contains search for 'risk' will not.

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 containing 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": "CONTAINS",  "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"  }
      ]
   }
}'
            

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