Connectors Reference

RiskIQ Digital Footprint

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.

 

Status: Preview

Tier: Premium

Version: 1.0

 

Actions:

Name

Summary

Tags ()

Get the list of tags

SavedSearches ()

Get the list of saved searches

Brands ()

Get the list of brands

Organizations ()

Get the list of organizations

DeltasSummary ([advanced][Optional]string date, [advanced][Optional]integer range, [advanced][Optional]string brand, [advanced][Optional]string organization, [advanced][Optional]string tag)

Get the count of confirmed assets added or removed

NewlyOpenedPorts ([advanced][Optional]integer period, [advanced][Optional]string ports, [advanced][Optional]string excludedPorts, [advanced][Optional]integer after, [advanced][Optional]boolean stream, [advanced][Optional]integer size)

Get the list of newly opened ports

GetRecentSearch ([Optional]integer savedSearchID, [Optional]string savedSearchName, [advanced][Optional]boolean global, [advanced][Optional]integer page, [advanced][Optional]integer size)

Get assets from recent dataset by search id or name

SearchRecent (SearchQuery query, [advanced][Optional]boolean global, [advanced][Optional]integer page, [advanced][Optional]integer size)

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

ConnectedAssetsByType (string type, string name, [advanced][Optional]boolean global, [advanced][Optional]integer page, [advanced][Optional]integer size)

Get connected assets by type

CancelTask ([Optional]CancelTaskParameterBody Body, string id)

Cancel the task for global inventory update

AssetsAdd (AssetAddRequest request, [advanced][Optional]boolean failOnError)

Add the assets to global inventory

BulkRetrieve (BulkGetAssetRequest assets)

Request to search the list of assets by type

GetTask (string id)

Get task by ID

Deltas ([Optional]string type, [advanced][Optional]string date, [advanced][Optional]integer range, [advanced][Optional]string measure, [advanced][Optional]string brand, [advanced][Optional]string organization, [advanced][Optional]string tag, [advanced][Optional]integer page, [advanced][Optional]integer size)

Get the list of confirmed assets added or removed by type

AssetType (string type, string name, [advanced][Optional]boolean global, [advanced][Optional]integer size, [advanced][Optional]boolean recent)

Get assets by type

AssetID (string uuid, [advanced][Optional]boolean global, [advanced][Optional]boolean recent)

Get asset by ID

AssetsUpdate (AssetUpdateRequest request, [advanced][Optional]boolean failOnError)

Update the assets to global inventory

SearchHistory (SearchQuery query, [advanced][Optional]boolean global, [advanced][Optional]integer page, [advanced][Optional]integer size, [advanced][Optional]boolean recent)

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

UpdateHistory (AssetUpdateRequest request, [advanced][Optional]boolean FailOnError)

Update the assets to global inventory using historical search

 

Triggers:

Name

Summary

 

Objects:

Name

Summary

aggregation

 

ApeHit

 

AssetAddRequest

 

AssetIdentifier

 

AssetUpdateRequest

 

brand

 

BulkGetAssetRequest

 

BulkRetrieveResponseItem

 

CancelTaskParameterBody

 

DeltasSummaryResponseItem

 

deltaSummary

 

GlobalInventoryAddResponse

 

GlobalInventoryAsset

 

GlobalInventoryDeltasResponse

 

GlobalInventorySearchResponse

 

GlobalInventoryUpdateResponse

 

organization

 

savedSearch

 

SearchQuery

 

tag

 

TaskResponse

 

 

Actions:

Tags

Summary: Get the list of tags

Description: Retrieve the list of tags defined for a workspace.

 

Syntax:

RiskIQDigitalFootprint.Tags ()

 

Returns:

          Type:array of (tag)

 

SavedSearches

Summary: Get the list of saved searches

Description: Retrieve the list of saved searches for a workspace.

 

Syntax:

RiskIQDigitalFootprint.SavedSearches ()

 

Returns:

          Type:array of (savedSearch)

 

Brands

Summary: Get the list of brands

Description: Retrieve the list of brands defined for a workspace.

 

Syntax:

RiskIQDigitalFootprint.Brands ()

 

Returns:

          Type:array of (brand)

 

Organizations

Summary: Get the list of organizations

Description: Retrieve the list of organizations defined for a workspace.

 

Syntax:

RiskIQDigitalFootprint.Organizations ()

 

Returns:

          Type:array of (organization)

 

DeltasSummary

Summary: Get the count of confirmed assets added or removed

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

 

Syntax:

RiskIQDigitalFootprint.DeltasSummary ([advanced][Optional]string date, [advanced][Optional]integer range, [advanced][Optional]string brand, [advanced][Optional]string organization, [advanced][Optional]string tag)

 

Parameters:

Name

Type

Summary

Required

Related Action

date

string

(Date)

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

False

range

integer(int32)

(Range)Values: [, , ]

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

False

brand

string

(Brand)

Summary counts will only include assets having this brand.

False

organization

string

(Organization)

Summary counts will only include assets having this organization.

False

tag

string

(Tag)

Summary counts will only include assets having this tag.

False

 

Returns:

          Type:array of (DeltasSummaryResponseItem)

 

NewlyOpenedPorts

Summary: Get the list of newly opened ports

Description: Retrieve the list of newly opened ports hits.

 

Syntax:

RiskIQDigitalFootprint.NewlyOpenedPorts ([advanced][Optional]integer period, [advanced][Optional]string ports, [advanced][Optional]string excludedPorts, [advanced][Optional]integer after, [advanced][Optional]boolean stream, [advanced][Optional]integer size)

 

Parameters:

Name

Type

Summary

Required

Related Action

period

integer(int32)

(Period)Values: [, , ]

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.

False

ports

string

(Ports)

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

False

excludedPorts

string

(Excluded Ports)

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

False

after

integer(int64)

(After)

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

False

stream

boolean

(Stream)Values: [, ]

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

False

size

integer(int32)

(Size)

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

False

 

Returns:

          Type:array of (ApeHit)

 

GetRecentSearch

Summary: Get assets from recent dataset by search id or name

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

 

Syntax:

RiskIQDigitalFootprint.GetRecentSearch ([Optional]integer savedSearchID, [Optional]string savedSearchName, [advanced][Optional]boolean global, [advanced][Optional]integer page, [advanced][Optional]integer size)

 

Parameters:

Name

Type

Summary

Required

Related Action

savedSearchID

integer(int32)

(Saved Search ID)

The ID of the Saved Search you want to execute.

False

savedSearchName

string

(Saved Search Name)

The name of the Saved Search you want to execute.

False

global

boolean

(Global)Values: [, ]

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.

False

page

integer(int32)

(Page)

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

False

size

integer(int32)

(Size)

The number of matching assets to return per page

False

 

Returns:

          Type:GlobalInventorySearchResponse

          Description: Global Inventory Search Response

 

SearchRecent

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

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

 

Syntax:

RiskIQDigitalFootprint.SearchRecent (SearchQuery query, [advanced][Optional]boolean global, [advanced][Optional]integer page, [advanced][Optional]integer size)

 

Parameters:

Name

Type

Summary

Required

Related Action

query

SearchQuery

 

 

True

global

boolean

(Global)

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

False

page

integer(int32)

(Page)

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

False

size

integer(int32)

(Size)

The number of matching assets to return per page

False

 

Returns:

          Type:GlobalInventorySearchResponse

          Description: Global Inventory Search Response

 

ConnectedAssetsByType

Summary: Get connected assets by type

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

 

Syntax:

RiskIQDigitalFootprint.ConnectedAssetsByType (string type, string name, [advanced][Optional]boolean global, [advanced][Optional]integer page, [advanced][Optional]integer size)

 

Parameters:

Name

Type

Summary

Required

Related Action

type

string

(Type)Values: [Domain, Host, IP_Address, IP_Block, AS, Page, SSL_Cert, Name_Server, Mail_Server, Contact]

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)

True

name

string

(Name)

The name of the asset to find connected assets for

True

global

boolean

(Global)Values: [, ]

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.

False

page

integer(int32)

(Page)

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

False

size

integer(int32)

(Size)

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.

False

 

Returns:

          Type:GlobalInventoryAsset

          Description: Global Inventory Asset

 

CancelTask

Summary: Cancel the task for global inventory update

Description: Cancel further processing of an asynchronous Global Inventory update task.

 

Syntax:

RiskIQDigitalFootprint.CancelTask ([Optional]CancelTaskParameterBody Body, string id)

 

Parameters:

Name

Type

Summary

Required

Related Action

Body

CancelTaskParameterBody

 

 

False

id

string

(Task Id)

The id of the asynchronous task to cancel

True

 

Returns:

          Type:TaskResponse

 

AssetsAdd

Summary: Add the assets to global inventory

Description: Add one or more assets and a set of properties.

 

Syntax:

RiskIQDigitalFootprint.AssetsAdd (AssetAddRequest request, [advanced][Optional]boolean failOnError)

 

Parameters:

Name

Type

Summary

Required

Related Action

request

AssetAddRequest

 

 

True

failOnError

boolean

(Fail On Error)

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.

False

 

Returns:

          Type:GlobalInventoryAddResponse

          Description: Global Inventory Add Response

 

BulkRetrieve

Summary: Request to search the list of assets by type

Description: Bulk retrieve a set of assets by name and type.

 

Syntax:

RiskIQDigitalFootprint.BulkRetrieve (BulkGetAssetRequest assets)

 

Parameters:

Name

Type

Summary

Required

Related Action

assets

BulkGetAssetRequest

 

 

True

 

Returns:

          Type:array of (BulkRetrieveResponseItem)

 

GetTask

Summary: Get task by ID

Description: Retrieve the status of an asynchronous global inventory update task.

 

Syntax:

RiskIQDigitalFootprint.GetTask (string id)

 

Parameters:

Name

Type

Summary

Required

Related Action

id

string

(Task Id)

The id of the asynchronous task to retrieve.

True

 

Returns:

          Type:TaskResponse

 

Deltas

Summary: Get the list of confirmed assets added or removed by type

Description: 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.

 

Syntax:

RiskIQDigitalFootprint.Deltas ([Optional]string type, [advanced][Optional]string date, [advanced][Optional]integer range, [advanced][Optional]string measure, [advanced][Optional]string brand, [advanced][Optional]string organization, [advanced][Optional]string tag, [advanced][Optional]integer page, [advanced][Optional]integer size)

 

Parameters:

Name

Type

Summary

Required

Related Action

type

string

(Type)Values: [Domain, Host, IP_Address, IP_Block, AS, Page, SSL_Cert, Name_Server, Mail_Server, Contact, Self_Hosted_Resource, ThirdParty_Hosted_Resource]

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)

False

date

string

(Date)

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

False

range

integer(int32)

(Range)

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

False

measure

string

(Measure)Values: [ADDED, REMOVED]

The type of change.  Valid options are ADDED or REMOVED

False

brand

string

(Brand)

Only assets having this brand will be returned.

False

organization

string

(Organization)

Only assets having this organization will be returned.

False

tag

string

(Tag)

Only assets having this tag will be returned.

False

page

integer(int32)

(Page)

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

False

size

integer(int32)

(Size)

The number of matching assets to return per page

False

 

Returns:

          Type:GlobalInventoryDeltasResponse

 

AssetType

Summary: Get assets by type

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

 

Syntax:

RiskIQDigitalFootprint.AssetType (string type, string name, [advanced][Optional]boolean global, [advanced][Optional]integer size, [advanced][Optional]boolean recent)

 

Parameters:

Name

Type

Summary

Required

Related Action

type

string

(Type)Values: [Domain, Host, IP_Address, IP_Block, AS, Page, SSL_Cert, Name_Server, Mail_Server, Contact]

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

True

name

string

(Name)

The name of the asset to retrieve

True

global

boolean

(Global)Values: [, ]

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.

False

size

integer(int32)

(Size)

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.

False

recent

boolean

(Recent)Values: [, ]

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

False

 

Returns:

          Type:GlobalInventoryAsset

          Description: Global Inventory Asset

 

AssetID

Summary: Get asset by ID

Description: Retrieve the asset of the specified UUID from Global Inventory.

 

Syntax:

RiskIQDigitalFootprint.AssetID (string uuid, [advanced][Optional]boolean global, [advanced][Optional]boolean recent)

 

Parameters:

Name

Type

Summary

Required

Related Action

uuid

string

(UUID)

The UUID of the asset to retrieve.

True

global

boolean

(Global)

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.

False

recent

boolean

(Recent)

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

False

 

Returns:

          Type:GlobalInventoryAsset

          Description: Global Inventory Asset

 

AssetsUpdate

Summary: Update the assets to global inventory

Description: Update one or more properties on a set of assets.

 

Syntax:

RiskIQDigitalFootprint.AssetsUpdate (AssetUpdateRequest request, [advanced][Optional]boolean failOnError)

 

Parameters:

Name

Type

Summary

Required

Related Action

request

AssetUpdateRequest

 

 

True

failOnError

boolean

(Fail On Error)

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

False

 

Returns:

          Type:GlobalInventoryUpdateResponse

          Description: Global Inventory Update Response

 

SearchHistory

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

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

 

Syntax:

RiskIQDigitalFootprint.SearchHistory (SearchQuery query, [advanced][Optional]boolean global, [advanced][Optional]integer page, [advanced][Optional]integer size, [advanced][Optional]boolean recent)

 

Parameters:

Name

Type

Summary

Required

Related Action

query

SearchQuery

 

 

True

global

boolean

(Global)

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

False

page

integer(int32)

(Page)

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

False

size

integer(int32)

(Size)

The number of matching assets to return per page

False

recent

boolean

(Recent)

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

False

 

Returns:

          Type:GlobalInventorySearchResponse

          Description: Global Inventory Search Response

 

UpdateHistory

Summary: Update the assets to global inventory using historical search

Description: 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.

 

Syntax:

RiskIQDigitalFootprint.UpdateHistory (AssetUpdateRequest request, [advanced][Optional]boolean FailOnError)

 

Parameters:

Name

Type

Summary

Required

Related Action

request

AssetUpdateRequest

 

 

True

FailOnError

boolean

(Fail On Error)

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.

False

 

Returns:

          Type:GlobalInventoryUpdateResponse

          Description: Global Inventory Update Response

 


 

aggregation

Summary:

Description:

 

          Properties:

Name

Type

Summary

removed

integer(int32)

 

 

added

integer(int32)

 

 

changed

integer(int32)

 

 

count

integer(int32)

 

 

range

integer(int32)

 

Values: [, , ]

difference

integer(int32)

 

 


 

ApeHit

Summary:

Description:

 

          Properties:

Name

Type

Summary

workspaceId

integer(int32)

 

 

policyId

string

 

 

createdAt

integer(int32)

 

 

source

string

 

 

asset

GlobalInventoryAsset

 

Global Inventory Asset

actions

array of (ActionsItem)

 

 

metadata

array of (MetadataItem)

 

 

storedAt

integer(int32)

 

 

 

ActionsItem

Summary:

Description:

 

          Properties:

Name

Type

Summary

actionId

integer(int32)

 

 

name

string

 

 

action

string

 

 

actionParameters

string

 

 

 

MetadataItem

Summary:

Description:

 

          Properties:

Name

Type

Summary

key

string

 

 

value

string

 

 

 


 

AssetAddRequest

Summary:

Description:

 

          Properties:

Name

Type

Summary


 

AssetIdentifier

Summary:

Description:

 

          Properties:

Name

Type

Summary

name

string

 

 

type

string

 

 


 

AssetUpdateRequest

Summary:

Description:

 

          Properties:

Name

Type

Summary


 

brand

Summary:

Description:

 

          Properties:

Name

Type

Summary

createdAt

integer(int32)

 

 

updatedAt

integer(int32)

 

 

status

string

 

 

workspaceBrandID

integer(int32)

 

 

workspaceID

integer(int32)

 

 

name

string

 

 

id

integer(int32)

 

 


 

BulkGetAssetRequest

Summary:

Description:

 

          Properties:

Name

Type

Summary


 

BulkRetrieveResponseItem

Summary:

Description:

 

          Properties:

Name

Type

Summary


 

CancelTaskParameterBody

Summary:

Description:

 

          Properties:

Name

Type

Summary


 

DeltasSummaryResponseItem

Summary:

Description:

 

          Properties:

Name

Type

Summary

runDate

string

 

 

deltas

array of (deltaSummary)

 

 


 

deltaSummary

Summary:

Description:

 

          Properties:

Name

Type

Summary

type

string

 

Values: [CONTACT, SSL_CERT, MAIL_SERVER, IP_BLOCK, PAGE, AS, DOMAIN, IP_ADDRESS, HOST, NAME_SERVER, SELF_HOSTED_RESOURCE, THIRDPARTY_HOSTED_RESOURCE]

aggregations

array of (aggregation)

 

 


 

GlobalInventoryAddResponse

Summary:

Description: Global Inventory Add Response

 

          Properties:

Name

Type

Summary


 

GlobalInventoryAsset

Summary:

Description: Global Inventory Asset

 

          Properties:

Name

Type

Summary


 

GlobalInventoryDeltasResponse

Summary:

Description:

 

          Properties:

Name

Type

Summary

totalElements

integer(int32)

 

 

totalPages

integer(int32)

 

 

last

boolean

 

 

numberOfElements

integer(int32)

 

 

first

boolean

 

 

size

integer(int32)

 

 

number

integer(int32)

 

 

content

array of (ContentItem)

 

 

 

ContentItem

Summary:

Description:

 

          Properties:

Name

Type

Summary

name

string

 

 

runDate

string

 

 

measure

string

 

 

createdAt

integer(int32)

 

 

autoconfirmed

boolean

 

Values: [, ]

enterprise

boolean

 

Values: [, ]

state

string

 

 

source

boolean

 

Values: [, ]

keystone

boolean

 

Values: [, ]

updatedAt

integer(int32)

 

 

wildcard

boolean

 

Values: [, ]

type

string

 

 

description

string

 

 

 


 

GlobalInventorySearchResponse

Summary:

Description: Global Inventory Search Response

 

          Properties:

Name

Type

Summary


 

GlobalInventoryUpdateResponse

Summary:

Description: Global Inventory Update Response

 

          Properties:

Name

Type

Summary


 

organization

Summary:

Description:

 

          Properties:

Name

Type

Summary

createdAt

integer(int32)

 

 

updatedAt

integer(int32)

 

 

status

string

 

 

workspaceOrganizationID

integer(int32)

 

 

workspaceID

integer(int32)

 

 

name

string

 

 

id

integer(int32)

 

 


 

savedSearch

Summary:

Description:

 

          Properties:

Name

Type

Summary

savedSearchID

integer(int32)

 

 

globalSearch

boolean

 

Values: [, ]

savedSearchName

string

 

 

workspaceSearch

boolean

 

Values: [, ]


 

SearchQuery

Summary:

Description:

 

          Properties:

Name

Type

Summary


 

tag

Summary:

Description:

 

          Properties:

Name

Type

Summary

createdAt

integer(int32)

 

 

updatedAt

integer(int32)

 

 

status

string

 

 

workspaceTagID

integer(int32)

 

 

workspaceTagType

string

 

 

color

string

 

 

workspaceID

integer(int32)

 

 

name

string

 

 

id

integer(int32)

 

 


 

TaskResponse

Summary:

Description:

 

          Properties:

Name

Type

Summary

taskClass

string

 

 

userID

integer(int32)

 

 

startedAt

integer(int32)

 

 

completedAt

integer(int32)

 

 

state

string

 

 

phase

string

 

 

reason

string

 

 

taskName

string

 

 

key

Key

 

 

data

Data

 

 

supportedActions

array of (SupportedActionsItem)

 

 

polling

boolean

 

 

 

Key

Summary:

Description:

 

          Properties:

Name

Type

Summary

workspaceID

integer(int32)

 

 

uuid

string

 

 

 

Data

Summary:

Description:

 

          Properties:

Name

Type

Summary

targetAssetTypes

array of (TargetAssetTypesItem)

 

 

assets

array of (AssetIdentifier)

 

 

requestType

string

 

 

estimated

integer(int32)

 

 

apiToken

string

 

 

application

string

 

 

requestLag

integer(int32)

 

 

progress

integer(int32)

 

 

updated

integer(int32)

 

 

totalUpdates

integer(int32)

 

 

countersByType

CountersByType

 

 

processedUpdates

integer(int32)

 

 

properties

array of (PropertiesItem)

 

 

 

TargetAssetTypesItem

Summary:

Description:

 

          Properties:

Name

Type

Summary

 

CountersByType

Summary:

Description:

 

          Properties:

Name

Type

Summary

 

PropertiesItem

Summary:

Description:

 

          Properties:

Name

Type

Summary

 

SupportedActionsItem

Summary:

Description:

 

          Properties:

Name

Type

Summary