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 - US Department of Defense (DoD) |
| Power Automate | Premium | All Power Automate regions except the following: - US Government (GCC) - US Government (GCC High) - China Cloud operated by 21Vianet - US Department of Defense (DoD) |
| Power Apps | Premium | All Power Apps regions except the following: - US Government (GCC) - US Government (GCC High) - China Cloud operated by 21Vianet - US Department of Defense (DoD) |
| Contact | |
|---|---|
| Name | RiskIQ Digital Footprint |
| URL | https://www.riskiq.com/integrations/microsoft/ |
| [email protected] |
| 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 ([email protected]) to identify your existing customer keys.
Creating a connection
The connector supports the following authentication types:
| Default | Parameters for creating connection. | All regions | Not shareable |
Default
Applicable: All regions
Parameters for creating connection.
This is not shareable connection. If the power app is shared with another user, another user will be prompted to create new connection explicitly.
| Name | Type | Description | Required |
|---|---|---|---|
| Token | securestring | The Token for this api | True |
| Secret | securestring | The Secret for this api | True |
Throttling Limits
| Name | Calls | Renewal Period |
|---|---|---|
| API calls per connection | 100 | 60 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 |
|---|---|---|---|---|
|
|
object | |||
|
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 |
|---|---|---|---|---|
|
|
object | |||
|
Task Id
|
id | True | string |
The id of the asynchronous task to cancel |
Returns
- Body
- TaskResponse
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
- Body
- TaskResponse
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
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
Get the list of saved searches
Get the list of 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 |
|---|---|---|---|---|
|
|
object | |||
|
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 |
|---|---|---|---|---|
|
|
object | |||
|
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.
Parameters
| Name | Key | Required | Type | Description |
|---|---|---|---|---|
|
|
object |
Returns
- Items
- BulkGetAssetResponse
Update the assets to global inventory
Update one or more properties on a set of assets.
Parameters
| Name | Key | Required | Type | Description |
|---|---|---|---|---|
|
|
object | |||
|
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 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.
Parameters
| Name | Key | Required | Type | Description |
|---|---|---|---|---|
|
|
object | |||
|
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'.