What can I do with the API?

This article provides script snippets and use cases for starting with vRx API

vRx's API interface provides a programmatic interface for pulling data and performing actions including patching, running scripts, creating asset groups and more. In this article you can find Postman basic configuration example & PowerShell siplets in RestMethod. Make sure to replace the API key and dashboard name in the requests.

Postman Example

You can use postman (or any other RESTapi tool) queries. we will use the "Get asset information" example:

Powershell Examples

Here are some powershell examples for API usage. You can also refer to the API library.

Tip: In the following commands, when executing large and iterate requests, it is best practice to use pagination by splitting the command to multiple requests until receiving an empty object. For example, increment 100 in the "from= until" & "size="until you recive an empty object.

Assets

Get asset information

$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("vicarius-token", "API_KEY")

$response = Invoke-RestMethod 'https://DASHBOARD_NAME.vicarius.cloud/vicarius-external-data-api/endpoint/search?from=0&size=100' -Method 'GET' -Headers $headers
$response | ConvertTo-Json

Get activity logs

$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add( "vicarius-token", "API_KEY")

$response = Invoke-RestMethod 'https://DASHBOARD_NAME.vicarius.cloud/vicarius-external-data-api/taskEndpointsEvent/filter?from=0&size=100' -Method 'GET' -Headers $headers
$response | ConvertTo-Json

Get asset's vulnerabilities

$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("vicarius-token", "API_KEY")

$response = Invoke-RestMethod 'https://DASHBOARD_NAME.vicarius.cloud/vicarius-external-data-api/organizationEndpointVulnerabilities/search?from=0&size=100' -Method 'GET' -Headers $headers
$response | ConvertTo-Json -Depth 3

Get Asset Groups

$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("vicarius-token", "API_KEY")

$response = Invoke-RestMethod 'https://DASHBOARD_NAME.vicarius.cloud/vicarius-external-data-api/organizationEndpointGroup/search?from=0&size=100' -Method 'GET' -Headers $headers
$response | ConvertTo-Json

Create new Asset Group

$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"

$headers.Add("vicarius-token", "API_KEY")

$body = "{`"organizationEndpointGroupName`":`"New AssetGroup`",`"organizationEndpointGroupDescription`":`"`",`"organizationEndpointGroupQuery`":`"`",`"organizationEndpointGroupSearchQueries`":`"[{`\`"searchQueryName`\`":`\`"assetQuery`\`",`\`"searchQueryObjectName`\`":`\`"Endpoint`\`",`\`"searchQueryObjectJoinByFieldName`\`":`\`"endpointId`\`",`\`"searchQueryObjectJoinByForeignFieldName`\`":`\`"endpointId`\`",`\`"searchQueryQuery`\`":`\`"endpointAlive=in=(true)`\`"}]`",`"organizationEndpointGroupFilters`":`"[{`\`"fieldValues`\`":{`\`"status`\`":`\`"true`\`"},`\`"countParams`\`":0}]`"}"

$response = Invoke-RestMethod 'https://DASHBOARD_NAME.vicarius.cloud/vicarius-external-data-api/organizationEndpointGroup/createOrGet' -Method 'POST' -Headers $headers -Body $body

$response | ConvertTo-Json

Apps

Get APP's name and risk level

$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"

$headers.Add("vicarius-token", "API_KEY")

$response = Invoke-RestMethod 'https://DASHBOARD_NAME.vicarius.cloud/vicarius-external-data-api/organizationPublisherProducts/search?from=0&size=100' -Method 'GET' -Headers $headers

$response | ConvertTo-Json

Get App's versions info

$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"

$headers.Add("vicarius-token", "API_KEY")

$response = Invoke-RestMethod 'https://DASHBOARD_NAME.vicarius.cloud/vicarius-external-data-api/aggregation/searchGroup?from=0&size=1&objectName=OrganizationEndpointPublisherProductVersions&group=publisherProductHash%3BorganizationEndpointPublisherProductVersionsVersion.versionName.raw%3B%3E%3BorganizationEndpointPublisherProductVersionsVersion.versionUniqueIdentifier%3B%3E%3BorganizationEndpointPublisherProductVersionsSubVersion.subVersionName.raw%3BorganizationEndpointPublisherProductVersionsSubVersion.subVersionUniqueIdentifier%3B%3E%3BorganizationEndpointPublisherProductVersionsOperatingSystemFamily.operatingSystemFamilyName%3BorganizationEndpointPublisherProductVersionsOperatingSystemFamily.operatingSystemFamilyId%3BendpointId%3BorganizationEndpointPublisherProductVersionsExternalReferenceSecondary.externalReferenceId%3B&includeOriginalDoc=false&q=publisherProductHash%3Din%3D(PUBLISHER_PRODUCT_HASH)&sumLastSubAggregationBuckets=3&newParser=true' -Method 'GET' -Headers $headers

$response | ConvertTo-Json

Get App's available patches

$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"

$headers.Add("vicarius-token", "API_KEY")

$headers.Add("Content-Type", "application/json")

$body = "[{`"searchQueryName`":`"appPatchQuery`",`"searchQueryObjectName`":`"OrganizationEndpointPublisherProductHashtags`",`"searchQueryObjectJoinByFieldName`":`"publisherProductHash`",`"searchQueryObjectJoinByForeignFieldName`":`"publisherProductHash`",`"searchQueryQuery`":`"publisherProductHash=in=(PUBLISHER_PRODUCT_HASH);organizationEndpointPublisherProductHashtagsHashtag.hashtagTag=in=(#has_patch)`"}]"

$response = Invoke-RestMethod 'https://DASHBOARD_NAME.vicarius.cloud/vicarius-external-data-api/aggregation/searchGroup?from=0&size=1&objectName=OrganizationEndpointPublisherProductVersions&group=publisherProductHash%3BorganizationEndpointPublisherProductVersionsVersion.versionName.raw%3B%3E%3BorganizationEndpointPublisherProductVersionsVersion.versionUniqueIdentifier%3B%3E%3BorganizationEndpointPublisherProductVersionsSubVersion.subVersionName.raw%3BorganizationEndpointPublisherProductVersionsSubVersion.subVersionUniqueIdentifier%3B%3E%3BorganizationEndpointPublisherProductVersionsOperatingSystemFamily.operatingSystemFamilyName%3BorganizationEndpointPublisherProductVersionsOperatingSystemFamily.operatingSystemFamilyId%3BendpointId%3BorganizationEndpointPublisherProductVersionsExternalReferenceSecondary.externalReferenceId%3B&includeOriginalDoc=false&q=&sumLastSubAggregationBuckets=3&newParser=true' -Method 'POST' -Headers $headers -Body $body

$response | ConvertTo-Json