RiskIQ Digital Footprint (Preview)

RiskIQ Digital Footprint for Microsoft enables security teams to take control of their attack surface, reducing their risk and creating a better defense. The RiskIQ Digital Footprint connector for Microsoft will automatically make your external asset inventory including asset metadata available to your team for automated operations. Use this data to build reports, trigger alerts or aid in the identification of vulnerabilities or exposures against your assets.

This connector is available in the following products and regions:

Service Class Regions
Logic Apps Standard All Logic Apps regions except the following:
     -   Azure Government regions
     -   Azure China regions
Power Automate Premium All Power Automate regions except the following:
     -   US Government (GCC)
     -   US Government (GCC High)
     -   China Cloud operated by 21Vianet
Power Apps Premium All Power Apps regions except the following:
     -   US Government (GCC)
     -   US Government (GCC High)
     -   China Cloud operated by 21Vianet
Contact
Name RiskIQ Digital Footprint
URL https://www.riskiq.com/integrations/microsoft/
Email support@riskiq.com
Connector Metadata
Publisher RiskIQ
Website https://www.riskiq.com/products/digital-footprint/
Privacy policy https://www.riskiq.com/privacy-policy/
Categories Security;IT Operations

RiskIQ Digital Footprint provides information about the Global Inventory. The Global Inventory endpoints 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.

Pre-requisites

You will need the following to proceed:

How to get credentials

Register for a test API key at RiskIQ Security Intelligence Services or contact your account representative (support@riskiq.com) to identify your existing customer keys.

Creating a connection

The connector supports the following authentication types:

Default Required parameters for creating connection. All regions

Default

Applicable: All regions

Required parameters for creating connection.

Name Type Description
Token securestring The Token for this api
Secret securestring The Secret for this api

Throttling Limits

Name Calls Renewal Period
API calls per connection10060 seconds

Actions

Add the assets to global inventory

Add one or more assets and a set of properties.

Cancel the task for global inventory update

Cancel further processing of an asynchronous Global Inventory update task.

Get asset by ID

Retrieve the asset of the specified UUID from Global Inventory.

Get assets by type

Retrieve the asset of the specified type and name from Global Inventory.

Get assets from recent dataset by search id or name

Search Global Inventory recent dataset for assets that match the criteria.

Get connected assets by type

Retrieve the set of assets which are connected to the requested asset.

Get task by ID

Retrieve the status of an asynchronous global inventory update task.

Get the count of confirmed assets added or removed

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

Get the list of brands

Retrieve the list of brands defined for a workspace.

Get the list of confirmed assets added or removed by type

Retrieve the list of confirmed assets that have been added or removed from inventory over the given time period. Retrieve the list of asset detail changes in inventory over the given time period.

Get the list of newly opened ports

Retrieve the list of newly opened ports hits.

Get the list of organizations

Retrieve the list of organizations defined for a workspace.

Get the list of saved searches

Retrieve the list of saved searches for a workspace.

Get the list of tags

Retrieve the list of tags defined for a workspace.

Request to get the assets from the historical dataset that match the criteria

Search Global Inventory historical dataset for a set of assets that match the criteria.

Request to get the assets from the recent dataset that match the criteria

Search Global Inventory recent dataset for a set of assets that match the criteria.

Request to search the list of assets by type

Bulk retrieve a set of assets by name and type.

Update the assets to global inventory

Update one or more properties on a set of assets.

Update the assets to global inventory using historical search

Update one or more properties on a set of assets. This will use historical search if updating via a query, otherwise it works the same as /update.

Add the assets to global inventory

Add one or more assets and a set of properties.

Parameters

Name Key Required Type Description
Fail On Error
failOnError boolean

If true then the request will fail if an invalid update is detected. If false then any invalid updates will be skipped but others will continue.

Returns

Global Inventory Add Response

response
object

Cancel the task for global inventory update

Cancel further processing of an asynchronous Global Inventory update task.

Parameters

Name Key Required Type Description
Task Id
id True string

The id of the asynchronous task to cancel

Returns

Get asset by ID

Retrieve the asset of the specified UUID from Global Inventory.

Parameters

Name Key Required Type Description
UUID
uuid True string

The UUID of the asset to retrieve.

Global
global boolean

Setting this value to true will search all of global inventory. Setting it to false will search for assets in the workspace associated with the authentication token.

Recent
recent boolean

If specified and 'true', then only return recent data on the asset

Returns

Global Inventory Asset

response
object

Get assets by type

Retrieve the asset of the specified type and name from Global Inventory.

Parameters

Name Key Required Type Description
Type
type True string

The type of asset to retrieve. Valid Types: (Domain, Host, IP_Address, IP_Block, AS, Page, SSL_Cert, Name_Server, Mail_Server, Contact)

Name
name True string

The name of the asset to retrieve

Global
global boolean

Setting this value to true will search all of global inventory. Setting it to false will search for assets in the workspace associated with the authentication token.

Size
size integer

Global Inventory assets potentially contain pages of related data, for example attributes, cookies and host pairs. Size determines the number of these associated items that are returned.

Recent
recent boolean

If specified and 'true', then only return recent data on the asset

Returns

Global Inventory Asset

response
object

Get assets from recent dataset by search id or name

Search Global Inventory recent dataset for assets that match the criteria.

Parameters

Name Key Required Type Description
Saved Search ID
savedSearchID integer

The ID of the Saved Search you want to execute.

Saved Search Name
savedSearchName string

The name of the Saved Search you want to execute.

Global
global boolean

Setting this value to true will search all of global inventory. Setting it to false will search for assets in the workspace associated with the authentication token.

Page
page integer

The index of the page to retrieve. The index is zero based so the first page is page 0.

Size
size integer

The number of matching assets to return per page

Returns

Global Inventory Search Response

response
object

Get connected assets by type

Retrieve the set of assets which are connected to the requested asset.

Parameters

Name Key Required Type Description
Type
type True string

The type of the asset to find connected assets for. Valid Types: (Domain, Host, IP_Address, IP_Block, AS, Page, SSL_Cert, Name_Server, Mail_Server, Contact)

Name
name True string

The name of the asset to find connected assets for

Global
global boolean

Setting this value to true will search all of global inventory. Setting it to false will search for assets in the workspace associated with the authentication token.

Page
page integer

The index of the page to retrieve. The index is zero based so the first page is page 0.

Size
size integer

The response contains a page of assets for each related asset type. Size determines the number of associated assets of each type that are returned.

Returns

Global Inventory Asset

response
object

Get task by ID

Retrieve the status of an asynchronous global inventory update task.

Parameters

Name Key Required Type Description
Task Id
id True string

The id of the asynchronous task to retrieve.

Returns

Get the count of confirmed assets added or removed

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

Parameters

Name Key Required Type Description
Date
date string

The date of the run in which the changes were identified.

Range
range integer

The period of time over which the changes were identified. Supported ranges are 1, 7 and 30 days.

Brand
brand string

Summary counts will only include assets having this brand.

Organization
organization string

Summary counts will only include assets having this organization.

Tag
tag string

Summary counts will only include assets having this tag.

Returns

Get the list of brands

Retrieve the list of brands defined for a workspace.

Returns

Items
brands

Get the list of confirmed assets added or removed by type

Retrieve the list of confirmed assets that have been added or removed from inventory over the given time period. Retrieve the list of asset detail changes in inventory over the given time period.

Parameters

Name Key Required Type Description
Type
type string

Either the type of asset to retrieve or the type of asset detail to retrieve. Valid asset types: (Domain, Host, IP_Address, IP_Block, AS, Page, SSL_Cert, Name_Server, Mail_Server, Contact). Valid asset detail types: (Self_Hosted_Resource, ThirdParty_Hosted_Resource)

Date
date string

The date of the run in which the changes were identified.

Range
range integer

The period of time over which the changes were identified. Supported ranges are 1, 7 and 30 days.

Measure
measure string

The type of change. Valid options are ADDED or REMOVED

Brand
brand string

Only assets having this brand will be returned.

Organization
organization string

Only assets having this organization will be returned.

Tag
tag string

Only assets having this tag will be returned.

Page
page integer

The index of the page to retrieve. The index is zero based so the first page is page 0.

Size
size integer

The number of matching assets to return per page

Returns

Get the list of newly opened ports

Retrieve the list of newly opened ports hits.

Parameters

Name Key Required Type Description
Period
period integer

The newly open port period in days. Valid options are 7, 14 & 30. If the period is not specified then newly opened ports from the all time period will be returned.

Ports
ports string

Comma delimited list of ports used to limit the results to those which include a port in the list.

Excluded Ports
excludedPorts string

Comma delimited list of ports used to limit the results to those which do not include a port in the list

After
after integer

Timestamp in milliseconds used to limit the results to newly opened port hits seen since after the timestamp.

Stream
stream boolean

Used to indicate if the request is using the streaming feature of the endpoint.

Size
size integer

The maximum number of newly opened port hits that will be returned.

Returns

Items
ApeHits

Get the list of organizations

Retrieve the list of organizations defined for a workspace.

Returns

Get the list of saved searches

Retrieve the list of saved searches for a workspace.

Returns

Get the list of tags

Retrieve the list of tags defined for a workspace.

Returns

Items
tags

Request to get the assets from the historical dataset that match the criteria

Search Global Inventory historical dataset for a set of assets that match the criteria.

Parameters

Name Key Required Type Description
Global
global boolean

Setting this value to true will search all of global inventory. Setting it to false will search for assets in the workspace associated with the authentication token

Page
page integer

The index of the page to retrieve. The index is zero based so the first page is page 0.

Size
size integer

The number of matching assets to return per page

Recent
recent boolean

If specified and 'true', then only return recent data on the asset

Returns

Global Inventory Search Response

response
object

Request to get the assets from the recent dataset that match the criteria

Search Global Inventory recent dataset for a set of assets that match the criteria.

Parameters

Name Key Required Type Description
Global
global boolean

Setting this value to true will search all of global inventory Setting it to false will search for assets in the workspace associated with the authentication token

Page
page integer

The index of the page to retrieve.The index is zero based so the first page is page 0

Size
size integer

The number of matching assets to return per page

Returns

Global Inventory Search Response

response
object

Request to search the list of assets by type

Bulk retrieve a set of assets by name and type.

Returns

Update the assets to global inventory

Update one or more properties on a set of assets.

Parameters

Name Key Required Type Description
Fail On Error
failOnError boolean

If true then the request will fail if an invalid update is detected. If false then any invalid updates will be skipped but others will continue

Returns

Global Inventory Update Response

response
object

Update one or more properties on a set of assets. This will use historical search if updating via a query, otherwise it works the same as /update.

Parameters

Name Key Required Type Description
Fail On Error
FailOnError boolean

If true then the request will fail if an invalid update is detected. If false then any invalid updates will be skipped but others will continue.

Returns

Global Inventory Update Response

response
object

Definitions

savedSearches

Name Path Type Description
Items
savedSearch

savedSearch

Name Path Type Description
Saved Search ID
savedSearchID integer
Global Search
globalSearch boolean
Saved Search Name
savedSearchName string
Workspace Search
workspaceSearch boolean

tags

Name Path Type Description
Items
tag

tag

Name Path Type Description
Created At
createdAt integer
Updated At
updatedAt integer
Status
status string
Workspace Tag ID
workspaceTagID integer
Workspace Tag Type
workspaceTagType string
Color
color string
Workspace ID
workspaceID integer
Name
name string
ID
id integer

brands

Name Path Type Description
Items
brand

brand

Name Path Type Description
Created At
createdAt integer
Updated At
updatedAt integer
Status
status string
Workspace Brand ID
workspaceBrandID integer
Workspace ID
workspaceID integer
Name
name string
ID
id integer

organizations

Name Path Type Description
Items
organization

organization

Name Path Type Description
Created At
createdAt integer
Updated At
updatedAt integer
Status
status string
Workspace Organization ID
workspaceOrganizationID integer
Workspace ID
workspaceID integer
Name
name string
ID
id integer

GlobalInventoryDeltasSummaryResponse

Name Path Type Description
Run Date
runDate string
deltas
deltas array of deltaSummary

deltaSummary

Name Path Type Description
Type
type string
aggregations
aggregations array of aggregation

aggregation

Name Path Type Description
Removed
removed integer
Added
added integer
Changed
changed integer
Count
count integer
Range
range integer
Difference
difference integer

ApeHits

Name Path Type Description
Items
ApeHit

ApeHit

Name Path Type Description
Workspace ID
workspaceId integer
Policy ID
policyId string
Created At
createdAt integer
Source
source string
asset
asset GlobalInventoryAsset

Global Inventory Asset

actions
actions array of object
Action ID
actions.actionId integer
Name
actions.name string
Action
actions.action string
Action Parameters
actions.actionParameters string
metadata
metadata array of object
Key
metadata.key string
Value
metadata.value string
StoredAt
storedAt integer

GlobalInventoryAsset

Global Inventory Asset

Name Path Type Description
object

Global Inventory Asset

TaskResponse

Name Path Type Description
Task Class
taskClass string
User ID
userID integer
Started At
startedAt integer
Completed At
completedAt integer
State
state string
Phase
phase string
Reason
reason string
Task Name
taskName string
Workspace ID
key.workspaceID integer
UUID
key.uuid string
Target Asset Types
data.targetAssetTypes array of
assets
data.assets array of AssetIdentifier
RequestType
data.requestType string
Estimated
data.estimated integer
ApiToken
data.apiToken string
Application
data.application string
RequestLog
data.requestLag integer
Progress
data.progress integer
Updated
data.updated integer
Total Updates
data.totalUpdates integer
countersByType
data.countersByType object
Processed Updates
data.processedUpdates integer
Properties
data.properties array of object
items
data.properties object
Supported Actions
supportedActions array of
Polling
polling boolean

AssetIdentifier

Name Path Type Description
Name
name string
Type
type string

BulkGetAssetResponse

Name Path Type Description
Items

GlobalInventoryDeltasResponse

Name Path Type Description
Total Elements
totalElements integer
Total Pages
totalPages integer
Last
last boolean
Number of Elements
numberOfElements integer
First
first boolean
Size
size integer
Number
number integer
content
content array of object
Name
content.name string
Run Date
content.runDate string
Measure
content.measure string
Created At
content.createdAt integer
Auto Confirmed
content.autoconfirmed boolean
Enterprise
content.enterprise boolean
State
content.state string
Source
content.source boolean
Key Stone
content.keystone boolean
Updated At
content.updatedAt integer
Wild Card
content.wildcard boolean
Type
content.type string
Description
content.description string

object

This is the type 'object'.