InsightVM API (v3)

Download OpenAPI specification: Download

Contact: support@rapid7.com

Overview

This guide documents the InsightVM Application Programming Interface (API) Version 3. This API supports the Representation State Transfer (REST) design pattern. Unless noted otherwise this API accepts and produces the application/json media type. This API uses Hypermedia as the Engine of Application State (HATEOAS) and is hypermedia friendly. All API connections must be made to the security console using HTTPS.

Versioning

Versioning is specified in the URL and the base path of this API is: https://<host>:<port>/api/3/.

Specification

An OpenAPI v2 specification (also known as Swagger 2) of this API is available. Tools such as swagger-codegen can be used to generate an API client in the language of your choosing using this specification document.

Download the specification: Download

Authentication

Authorization to the API uses HTTP Basic Authorization (see RFC 2617 for more information). Requests must supply authorization credentials in the Authorization header using a Base64 encoded hash of "username:password".

Basic

Security scheme type: Basic Authorization

2FA

This API supports two-factor authentication (2FA) by supplying an authentication token in addition to the Basic Authorization. The token is specified using the Token request header. To leverage two-factor authentication, this must be enabled on the console and be configured for the account accessing the API.

Resources

Naming

Resource names represent nouns and identify the entity being manipulated or accessed. All collection resources are pluralized to indicate to the client they are interacting with a collection of multiple resources of the same type. Singular resource names are used when there exists only one resource available to interact with.

The following naming conventions are used by this API:

TypeCase
Resource nameslower_snake_case
Header, body, and query parameters parameterscamelCase
JSON fields and property namescamelCase

Collections

A collection resource is a parent resource for instance resources, but can itself be retrieved and operated on independently. Collection resources use a pluralized resource name. The resource path for collection resources follow the convention:

/api/3/{resource_name}

Instances

An instance resource is a "leaf" level resource that may be retrieved, optionally nested within a collection resource. Instance resources are usually retrievable with opaque identifiers. The resource path for instance resources follows the convention:

/api/3/{resource_name}/{instance_id}...

Verbs

The following HTTP operations are supported throughout this API. The general usage of the operation and both its failure and success status codes are outlined below.

VerbUsageSuccessFailure
GETUsed to retrieve a resource by identifier, or a collection of resources by type.200400, 401, 402, 404, 405, 408, 410, 415, 500
POSTCreates a resource with an application-specified identifier.201400, 401, 404, 405, 408, 413, 415, 500
POSTPerforms a request to queue an asynchronous job.202400, 401, 405, 408, 410, 413, 415, 500
PUTCreates a resource with a client-specified identifier.200400, 401, 403, 405, 408, 410, 413, 415, 500
PUTPerforms a full update of a resource with a specified identifier.201400, 401, 403, 405, 408, 410, 413, 415, 500
DELETEDeletes a resource by identifier or an entire collection of resources.204400, 401, 405, 408, 410, 413, 415, 500
OPTIONSRequests what operations are available on a resource.200401, 404, 405, 408, 500

Common Operations

OPTIONS

All resources respond to the OPTIONS request, which allows discoverability of available operations that are supported. The OPTIONS response returns the acceptable HTTP operations on that resource within the Allow header. The response is always a 200 OK status.

Collection Resources

Collection resources can support the GET, POST, PUT, and DELETE operations.

GET

The GET operation invoked on a collection resource indicates a request to retrieve all, or some, of the entities contained within the collection. This also includes the optional capability to filter or search resources during the request. The response from a collection listing is a paginated document. See hypermedia links for more information.

POST

The POST is a non-idempotent operation that allows for the creation of a new resource when the resource identifier is not provided by the system during the creation operation (i.e. the Security Console generates the identifier). The content of the POST request is sent in the request body. The response to a successful POST request should be a 201 CREATED with a valid Location header field set to the URI that can be used to access to the newly created resource.

The POST to a collection resource can also be used to interact with asynchronous resources. In this situation, instead of a 201 CREATED response, the 202 ACCEPTED response indicates that processing of the request is not fully complete but has been accepted for future processing. This request will respond similarly with a Location header with link to the job-oriented asynchronous resource that was created and/or queued.

PUT

The PUT is an idempotent operation that either performs a create with user-supplied identity, or a full replace or update of a resource by a known identifier. The response to a PUT operation to create an entity is a 201 Created with a valid Location header field set to the URI that can be used to access to the newly created resource.

PUT on a collection resource replaces all values in the collection. The typical response to a PUT operation that updates an entity is hypermedia links, which may link to related resources caused by the side-effects of the changes performed.

DELETE

The DELETE is an idempotent operation that physically deletes a resource, or removes an association between resources. The typical response to a DELETE operation is hypermedia links, which may link to related resources caused by the side-effects of the changes performed.

Instance Resources

Instance resources can support the GET, PUT, POST, PATCH and DELETE operations.

GET

Retrieves the details of a specific resource by its identifier. The details retrieved can be controlled through property selection and property views. The content of the resource is returned within the body of the response in the acceptable media type.

PUT

Allows for and idempotent "full update" (complete replacement) on a specific resource. If the resource does not exist, it will be created; if it does exist, it is completely overwritten. Any omitted properties in the request are assumed to be undefined/null. For "partial updates" use POST or PATCH instead.

The content of the PUT request is sent in the request body. The identifier of the resource is specified within the URL (not the request body). The response to a successful PUT request is a 201 CREATED to represent the created status, with a valid Location header field set to the URI that can be used to access to the newly created (or fully replaced) resource.

POST

Performs a non-idempotent creation of a new resource. The POST of an instance resource most commonly occurs with the use of nested resources (e.g. searching on a parent collection resource). The response to a POST of an instance resource is typically a 200 OK if the resource is non-persistent, and a 201 CREATED if there is a resource created/persisted as a result of the operation. This varies by endpoint.

PATCH

The PATCH operation is used to perform a partial update of a resource. PATCH is a non-idempotent operation that enforces an atomic mutation of a resource. Only the properties specified in the request are to be overwritten on the resource it is applied to. If a property is missing, it is assumed to not have changed.

DELETE

Permanently removes the individual resource from the system. If the resource is an association between resources, only the association is removed, not the resources themselves. A successful deletion of the resource should return 204 NO CONTENT with no response body. This operation is not fully idempotent, as follow-up requests to delete a non-existent resource should return a 404 NOT FOUND.

Requests

Unless otherwise indicated, the default request body media type is application/json.

Headers

Commonly used request headers include:

HeaderExamplePurpose
Acceptapplication/jsonDefines what acceptable content types are allowed by the client. For all types, use */*.
Accept-Encodingdeflate, gzipAllows for the encoding to be specified (such as gzip).
Accept-Languageen-USIndicates to the server the client's locale (defaults en-US).
AuthorizationBasic Base64("username:password")Basic authentication
Token123456Two-factor authentication token (if enabled)

Dates & Times

Dates and/or times are specified as strings in the ISO 8601 format(s). The following formats are supported as input:

ValueFormatNotes
DateYYYY-MM-DDDefaults to 12 am UTC (if used for a date & time
Date & time onlyYYYY-MM-DD'T'hh:mm:ss[.nnn]Defaults to UTC
Date & time in UTCYYYY-MM-DD'T'hh:mm:ss[.nnn]Z
Date & time w/ offsetYYYY-MM-DD'T'hh:mm:ss[.nnn][+|-]hh:mm
Date & time w/ zone-offsetYYYY-MM-DD'T'hh:mm:ss[.nnn][+|-]hh:mm[<zone-id>]

Timezones

Timezones are specified in the regional zone format, such as "America/Los_Angeles", "Asia/Tokyo", or "GMT".

Paging

Pagination is supported on certain collection resources using a combination of two query parameters, page and size. As these are control parameters, they are prefixed with the underscore character. The page parameter dictates the zero-based index of the page to retrieve, and the size indicates the size of the page.

For example, /resources?page=2&size=10 will return page 3, with 10 records per page, giving results 21-30.

The maximum page size for a request is 500.

Sorting

Sorting is supported on paginated resources with the sort query parameter(s). The sort query parameter(s) supports identifying a single or multi-property sort with a single or multi-direction output. The format of the parameter is:

sort=property[,ASC|DESC]...

Therefore, the request /resources?sort=name,title,DESC would return the results sorted by the name and title descending, in that order. The sort directions are either ascending ASC or descending DESC. With single-order sorting, all properties are sorted in the same direction. To sort the results with varying orders by property, multiple sort parameters are passed.

For example, the request /resources?sort=name,ASC&sort=title,DESC would sort by name ascending and title descending, in that order.

Responses

The following response statuses may be returned by this API.

StatusMeaningUsage
200OKThe operation performed without error according to the specification of the request, and no more specific 2xx code is suitable.
201CreatedA create request has been fulfilled and a resource has been created. The resource is available as the URI specified in the response, including the Location header.
202AcceptedAn asynchronous task has been accepted, but not guaranteed, to be processed in the future.
400Bad RequestThe request was invalid or cannot be otherwise served. The request is not likely to succeed in the future without modifications.
401UnauthorizedThe user is unauthorized to perform the operation requested, or does not maintain permissions to perform the operation on the resource specified.
403ForbiddenThe resource exists to which the user has access, but the operating requested is not permitted.
404Not FoundThe resource specified could not be located, does not exist, or an unauthenticated client does not have permissions to a resource.
405Method Not AllowedThe operations may not be performed on the specific resource. Allowed operations are returned and may be performed on the resource.
408Request TimeoutThe client has failed to complete a request in a timely manner and the request has been discarded.
413Request Entity Too LargeThe request being provided is too large for the server to accept processing.
415Unsupported Media TypeThe media type is not supported for the requested resource.
500Internal Server ErrorAn internal and unexpected error has occurred on the server at no fault of the client.

Security

The response statuses 401, 403 and 404 need special consideration for security purposes. As necessary, error statuses and messages may be obscured to strengthen security and prevent information exposure. The following is a guideline for privileged resource response statuses:

Use CaseAccessResourcePermissionStatus
Unauthenticated access to an unauthenticated resource.UnauthenticatedUnauthenticatedYes20x
Unauthenticated access to an authenticated resource.UnauthenticatedAuthenticatedNo401
Unauthenticated access to an authenticated resource.UnauthenticatedNon-existentNo401
Authenticated access to a unauthenticated resource.AuthenticatedUnauthenticatedYes20x
Authenticated access to an authenticated, unprivileged resource.AuthenticatedAuthenticatedNo404
Authenticated access to an authenticated, privileged resource.AuthenticatedAuthenticatedYes20x
Authenticated access to an authenticated, non-existent resourceAuthenticatedNon-existentYes404

Headers

Commonly used response headers include:

HeaderExamplePurpose
AllowOPTIONS, GETDefines the allowable HTTP operations on a resource.
Cache-Controlno-store, must-revalidateDisables caching of resources (as they are all dynamic).
Content-EncodinggzipThe encoding of the response body (if any).
LocationRefers to the URI of the resource created by a request.
Transfer-EncodingchunkedSpecified the encoding used to transform response.
Retry-After5000Indicates the time to wait before retrying a request.
X-Content-Type-OptionsnosniffDisables MIME type sniffing.
X-XSS-Protection1; mode=blockEnables XSS filter protection.
X-Frame-OptionsSAMEORIGINPrevents rendering in a frame from a different origin.
X-UA-CompatibleIE=edge,chrome=1Specifies the browser mode to render in.

Format

When application/json is returned in the response body it is always pretty-printed (indented, human readable output). Additionally, gzip compression/encoding is supported on all responses.

Dates & Times

Dates or times are returned as strings in the ISO 8601 'extended' format. When a date and time is returned (instant) the value is converted to UTC.

For example:

ValueFormatExample
DateYYYY-MM-DD2017-12-03
Date & TimeYYYY-MM-DD'T'hh:mm:ss[.nnn]Z2017-12-03T10:15:30Z

Content

In some resources a Content data type is used. This allows for multiple formats of representation to be returned within resource, specifically "html" and "text". The "text" property returns a flattened representation suitable for output in textual displays. The "html" property returns an HTML fragment suitable for display within an HTML element. Note, the HTML returned is not a valid stand-alone HTML document.

Paging

The response to a paginated request follows the format:

{
   resources": [ 
      ... 
   ],
   "page": { 
      "number" : ...,
      "size" : ...,
      "totalResources" : ...,
      "totalPages" : ...
   },
   "links": [ 
      "first" : {
         "href" : "..."
       },
       "prev" : {
         "href" : "..."
       },
       "self" : {
         "href" : "..."
       },
       "next" : {
         "href" : "..."
       },
       "last" : {
         "href" : "..."
       } 
   ]
}

The resources property is an array of the resources being retrieved from the endpoint, each which should contain at minimum a "self" relation hypermedia link. The page property outlines the details of the current page and total possible pages. The object for the page includes the following properties:

  • number - The page number (zero-based) of the page returned.
  • size - The size of the pages, which is less than or equal to the maximum page size.
  • totalResources - The total amount of resources available across all pages.
  • totalPages - The total amount of pages.

The last property of the paged response is the links array, which contains all available hypermedia links. For paginated responses, the "self", "next", "previous", "first", and "last" links are returned. The "self" link must always be returned and should contain a link to allow the client to replicate the original request against the collection resource in an identical manner to that in which it was invoked.

The "next" and "previous" links are present if either or both there exists a previous or next page, respectively. The "next" and "previous" links have hrefs that allow "natural movement" to the next page, that is all parameters required to move the next page are provided in the link. The "first" and "last" links provide references to the first and last pages respectively.

Requests outside the boundaries of the pageable will result in a 404 NOT FOUND. Paginated requests do not provide a "stateful cursor" to the client, nor does it need to provide a read consistent view. Records in adjacent pages may change while pagination is being traversed, and the total number of pages and resources may change between requests within the same filtered/queries resource collection.

Property Views

The "depth" of the response of a resource can be configured using a "view". All endpoints supports two views that can tune the extent of the information returned in the resource. The supported views are summary and details (the default). View are specified using a query parameter, in this format:

/<resource>?view={viewName}

Error

Any error responses can provide a response body with a message to the client indicating more information (if applicable) to aid debugging of the error. All 40x and 50x responses will return an error response in the body. The format of the response is as follows:

{
   "status": <statusCode>,
   "message": <message>,
   "links" : [ {
      "rel" : "...",
      "href" : "..."
    } ]
} 

The status property is the same as the HTTP status returned in the response, to ease client parsing. The message property is a localized message in the request client's locale (if applicable) that articulates the nature of the error. The last property is the links property. This may contain additional hypermedia links to troubleshoot.

Search Criteria

Multiple resources make use of search criteria to match assets. Search criteria is an array of search filters. Each search filter has a generic format of:

{ 
   "field": "<field-name>", 
   "operator": "<operator>", 
   ["value": "<value>",]
   ["lower": "<value>",]
   ["upper": "<value>"]
}
   

Every filter defines two required properties field and operator. The field is the name of an asset property that is being filtered on. The operator is a type and property-specific operating performed on the filtered property. The valid values for fields and operators are outlined in the table below.

Every filter also defines one or more values that are supplied to the operator. The valid values vary by operator and are outlined below.

Fields

The following table outlines the search criteria fields and the available operators:

FieldOperators
alternate-address-typein
container-imageis is not starts with ends with contains does not contain is like not like
container-statusis is not
containersare
criticality-tagis is not is greater than is less than is applied is not applied
custom-tagis is not starts with ends with contains does not contain is applied is not applied
cveis is not contains does not contain
cvss-access-complexityis is not
cvss-authentication-requiredis is not
cvss-access-vectoris is not
cvss-availability-impactis is not
cvss-confidentiality-impactis is not
cvss-integrity-impactis is not
cvss-v3-confidentiality-impactis is not
cvss-v3-integrity-impactis is not
cvss-v3-availability-impactis is not
cvss-v3-attack-vectoris is not
cvss-v3-attack-complexityis is not
cvss-v3-user-interactionis is not
cvss-v3-privileges-requiredis is not
host-nameis is not starts with ends with contains does not contain is empty is not empty is like not like
host-typein not in
ip-addressis is not in range not in range is like not like
ip-address-typein not in
last-scan-dateis-on-or-before is on or after is between is earlier than is within the last
location-tagis is not starts with ends with contains does not contain is applied is not applied
mobile-device-last-sync-timeis-within-the-last is earlier than
open-portsis is not in range
operating-systemcontains does not contain is empty is not empty
owner-tagis is not starts with ends with contains does not contain is applied is not applied
pci-complianceis
risk-scoreis is not in range greater than less than
service-namecontains does not contain
site-idin not in
softwarecontains does not contain
vAsset-clusteris is not contains does not contain starts with
vAsset-datacenteris is not
vAsset-host-nameis is not contains does not contain starts with
vAsset-power-statein not in
vAsset-resource-pool-pathcontains does not contain
vulnerability-assessedis-on-or-before is on or after is between is earlier than is within the last
vulnerability-categoryis is not starts with ends with contains does not contain
vulnerability-cvss-v3-scoreis is not
vulnerability-cvss-scoreis is not in range is greater than is less than
vulnerability-exposuresincludes does not include
vulnerability-titlecontains does not contain is is not starts with ends with
vulnerability-validated-statusare
Enumerated Properties

The following fields have enumerated values:

FieldAcceptable Values
alternate-address-type0=IPv4, 1=IPv6
containers0=present, 1=not present
container-statuscreated running paused restarting exited dead unknown
cvss-access-complexity
  • L = Low
  • M = Medium
  • H = High
cvss-integrity-impact
  • N = None
  • P = Partial
  • C = Complete
cvss-confidentiality-impact
  • N = None
  • P = Partial
  • C = Complete
cvss-availability-impact
  • N = None
  • P = Partial
  • C = Complete
cvss-access-vector
  • L = Local
  • A = Adjacent
  • N = Network
cvss-authentication-required
  • N = None
  • S = Single
  • M = Multiple
cvss-v3-confidentiality-impact
  • L = Local
  • L = Low
  • N = None
  • H = High
cvss-v3-integrity-impact
  • L = Local
  • L = Low
  • N = None
  • H = High
cvss-v3-availability-impact
  • N = None
  • L = Low
  • H = High
cvss-v3-attack-vector
  • N = Network
  • A = Adjacent
  • L = Local
  • P = Physical
cvss-v3-attack-complexity
  • L = Low
  • H = High
cvss-v3-user-interaction
  • N = None
  • R = Required
cvss-v3-privileges-required
  • N = None
  • L = Low
  • H = High
host-type0=Unknown, 1=Guest, 2=Hypervisor, 3=Physical, 4=Mobile
ip-address-type0=IPv4, 1=IPv6
pci-compliance0=fail, 1=pass
vulnerability-validated-status0=present, 1=not present
Operator Properties

The following table outlines which properties are required for each operator and the appropriate data type(s):

Operatorvaluelowerupper
arestring
containsstring
does-not-containstring
ends withstring
inArray[ string ]
in-rangenumericnumeric
includesArray[ string ]
isstring
is-applied
is-betweennumericnumeric
is-earlier-thannumeric
is-empty
is-greater-thannumeric
is-on-or-afterstring (yyyy-MM-dd)
is-on-or-beforestring (yyyy-MM-dd)
is-notstring
is-not-applied
is-not-empty
is-within-the-laststring
less-thanstring
likestring
not-containsstring
not-inArray[ string ]
not-in-rangenumericnumeric
not-likestring
starts-withstring

Discovery Connection Search Criteria

Dynamic sites make use of search criteria to match assets from a discovery connection. Search criteria is an array of search filters.

Each search filter has a generic format of:

{ 
   "field": "<field-name>", 
   "operator": "<operator>", 
   ["value": "<value>",]
   ["lower": "<value>",]
   ["upper": "<value>"]
}
   

Every filter defines two required properties field and operator. The field is the name of an asset property that is being filtered on. The list of supported fields vary depending on the type of discovery connection configured for the dynamic site (e.g vSphere, ActiveSync, etc.). The operator is a type and property-specific operating performed on the filtered property. The valid values for fields outlined in the tables below and are grouped by the type of connection.

Every filter also defines one or more values that are supplied to the operator. See Search Criteria Operator Properties for more information on the valid values for each operator.

Fields (ActiveSync)

This section documents search criteria information for ActiveSync discovery connections. The discovery connections must be one of the following types: "activesync-ldap", "activesync-office365", or "activesync-powershell".

The following table outlines the search criteria fields and the available operators for ActiveSync connections:

FieldOperators
last-sync-timeis-within-the-last is-earlier-than
operating-systemcontains does-not-contain
useris is-not contains does-not-contain starts-with
Fields (AWS)

This section documents search criteria information for AWS discovery connections. The discovery connections must be the type "aws".

The following table outlines the search criteria fields and the available operators for AWS connections:

FieldOperators
availability-zonecontains does-not-contain
guest-os-familycontains does-not-contain
instance-idcontains does-not-contain
instance-nameis is-not contains does-not-contain starts-with
instance-statein not-in
instance-typein not-in
ip-addressin-range not-in-range is is-not
regionin not-in
vpc-idis is-not contains does-not-contain starts-with
Fields (DHCP)

This section documents search criteria information for DHCP discovery connections. The discovery connections must be the type "dhcp".

The following table outlines the search criteria fields and the available operators for DHCP connections:

FieldOperators
host-nameis is-not contains does-not-contain starts-with
ip-addressin-range not-in-range is is-not
mac-addressis is-not contains does-not-contain starts-with
Fields (Sonar)

This section documents search criteria information for Sonar discovery connections. The discovery connections must be the type "sonar".

The following table outlines the search criteria fields and the available operators for Sonar connections:

FieldOperators
search-domaincontains is
ip-addressin-range is
sonar-scan-dateis-within-the-last
Fields (vSphere)

This section documents search criteria information for vSphere discovery connections. The discovery connections must be the type "vsphere".

The following table outlines the search criteria fields and the available operators for vSphere connections:

FieldOperators
clusteris is-not contains does-not-contain starts-with
data-centeris is-not
discovered-timeis-on-or-before is-on-or-after is-between is-earlier-than is-within-the-last
guest-os-familycontains does-not-contain
host-nameis is-not contains does-not-contain starts-with
ip-addressin-range not-in-range is is-not
power-statein not-in
resource-pool-pathcontains does-not-contain
last-time-seenis-on-or-before is-on-or-after is-between is-earlier-than is-within-the-last
vmis is-not contains does-not-contain starts-with
Enumerated Properties (vSphere)

The following fields have enumerated values:

FieldAcceptable Values
power-statepoweredOn poweredOff suspended

HATEOAS

This API follows Hypermedia as the Engine of Application State (HATEOAS) principals and is therefore hypermedia friendly. Hyperlinks are returned in the links property of any given resource and contain a fully-qualified hyperlink to the corresponding resource. The format of the hypermedia link adheres to both the {json:api} v1 "Link Object" and JSON Hyper-Schema "Link Description Object" formats. For example:

"links": [{
  "rel": "<relation>",
  "href": "<href>"
  ...
}]

Where appropriate link objects may also contain additional properties than the rel and href properties, such as id, type, etc.

See the Root resources for the entry points into API discovery.

Root

Provides access to primary entry point for discovering the available resources in this API.

Resources

get
/api/3

Server URL

https://help.rapid7.com/insightvm/en-us/api/3

Returns a listing of the resources (endpoints) that are available to be invoked in this API.

Responses

200 OK

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

404 Not Found

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema

Response samples
  • 200 OK

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

  • 503 Service Unavailable

{}
{}
{}
{}
{}

Asset

Resources and operations for managing assets. Assets can be created under the Site Assets resource.

Assets

get
/api/3/assets

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/assets

Returns all assets for which you have access.

Parameters
query Parameters ?
page
integer <int32>
0

The index of the page (zero-based) to retrieve.

size
integer <int32>
10

The number of records per page to retrieve.

sort
Multiple query params of string

The criteria to sort the records by, in the format: property[,ASC|DESC]. The default sort order is ascending. Multiple sort criteria can be specified using multiple sort query parameters.

Responses

200 OK

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

404 Not Found

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema

Response samples
  • 200 OK

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

  • 503 Service Unavailable

{
  • "links":
    [],
  • "page":
    {
    },
  • "resources":
    [
    ]
}
{}
{}
{}
{}

Assets

post
/api/3/sites/{id}/assets

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/sites/{id}/assets

Creates or updates an asset with the specified details.

Parameters
path Parameters ?
id
integer <int32>

The identifier of the site.

Request Body

The details of the asset being added or updated. The operating system can be specified in one of three ways, with the order of precedence: "osFingerprint", "os", "cpe"


addresses
Address

All addresses discovered on the asset.

configurations
Configuration

Configuration key-values pairs enumerated on the asset.

cpe
string

The Common Platform Enumeration (CPE) of the operating system. This is the tertiary means of specifying the operating system fingerprint. Use "osFingerprint" or "os" as a more accurate means of defining the operating system.

databases
Database

The databases enumerated on the asset.

date
string Required

The date the data was collected on the asset.

description
string

The description of the source or collection of information on the asset. This description will appear in the history of the asset for future auditing purposes.

files
File

The files discovered with searching on the asset.

hostName
HostName

The primary host name (local or FQDN) of the asset.

hostNames
HostName

Additional host names for the asset.

id
integer <int64>

The identifier of the asset.

ids
UniqueId

Unique identifiers found on the asset, such as hardware or operating system identifiers.

ip
string

The primary IPv4 or IPv6 address of the asset.

links
Link
mac
string

The primary Media Access Control (MAC) address of the asset. The format is six groups of two hexadecimal digits separated by colons.

os
string

Free-form textual description of the operating system of the asset, typically from a fingerprinting source. This input will be parsed to produce a full fingerprint. This is the secondary means of specifying the operating system. Use osFingerprint for a more accurate definition.

osFingerprint
OperatingSystem

The details of the operating system of the asset.

services
Service

The services discovered on the asset.

software
Software

The software discovered on the asset.

type
string

The type of asset.

userGroups
GroupAccount

The group accounts enumerated on the asset.

users
UserAccount

The user accounts enumerated on the asset.

vulnerabilities
AssetVulnerabilities

Summary information for vulnerabilities on the asset.

Responses

200 OK

Headers
Response Schema

201 Created

Headers
Response Schema

400 Bad Request

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema
Request samples
{
  • "addresses":
    [
    ],
  • "configurations":
    [
    ],
  • "cpe": "",
  • "databases":
    [
    ],
  • "date": "",
  • "description": "",
  • "files":
    [
    ],
  • "hostName":
    {
    },
  • "hostNames":
    [
    ],
  • "id": 282,
  • "ids":
    [
    ],
  • "ip": "182.34.74.202",
  • "links":
    [],
  • "mac": "AB:12:CD:34:EF:56",
  • "os": "",
  • "osFingerprint":
    {
    },
  • "services":
    [
    ],
  • "software":
    [
    ],
  • "type": "",
  • "userGroups":
    [
    ],
  • "users":
    [
    ],
  • "vulnerabilities": { }
}

Response samples
  • 200 OK

  • 201 Created

  • 400 Bad Request

  • 401 Unauthorized

  • 500 Internal Server Error

  • 503 Service Unavailable

{}
{}
{}
{}
{}
{}

Asset Search

post
/api/3/assets/search

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/assets/search

Returns all assets for which you have access that match the given search criteria.

Parameters
query Parameters ?
page
integer <int32>
0

The index of the page (zero-based) to retrieve.

size
integer <int32>
10

The number of records per page to retrieve.

sort
Multiple query params of string

The criteria to sort the records by, in the format: property[,ASC|DESC]. The default sort order is ascending. Multiple sort criteria can be specified using multiple sort query parameters.

Request Body

param1


filters
SwaggerSearchCriteriaFilter

Filters used to match assets. See Search Criteria for more information on the structure and format.

match
string
"any" "all"

Operator to determine how to match filters. all requires that all filters match for an asset to be included. any requires only one filter to match for an asset to be included.

Responses

200 OK

Headers
Response Schema

400 Bad Request

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema
Request samples
  • JSON
  • Assets Running SSH
  • High Risk Windows Assets Running SSH
  • Windows 10 Assets
  • Assets with High CVSS Scores assigned to Bob
  • Assets with SSH running containers in Los Angeles
{
  • "filters":
    [
    ],
  • "match": "all"
}
{
  "match": "all",
  "filters": [
     { "field": "service-name", "operator": "contains", "value": "ssh"}
  ]
}
{
  "match": "all",
  "filters": [
     { "field": "risk-score", "operator": "is-greater-than", "value": 5000 },
     { "field": "operating-system", "operator": "contains", "value": "windows" },
     { "field": "service-name", "operator": "contains", "value": "ssh" }
  ]
}
{
  "match": "all",
  "filters": [
     { "field": "operating-system", "operator": "contains", "value": "Microsoft Windows 10" }
  ]
}
{
   "match": "all",
   "filters": [
      { "field": "owner-tag", "operator": "contains", "value": "Bob" },
      { "field": "vulnerability-cvss-score", "operator": "is-greater-than", "value": 8 }
   ]
}
{
   "match": "all",
   "filters": [
      { "field": "location-tag", "operator": "contains", "value": "Los Angeles Datacenter" },
      { "field": "containers", "operator": "are", "value": "0" },
      { "field": "service-name", "operator": "contains", "value": "ssh" }
   ]
}

Response samples
  • 200 OK

  • 400 Bad Request

  • 401 Unauthorized

  • 500 Internal Server Error

  • 503 Service Unavailable

{
  • "links":
    [],
  • "page":
    {
    },
  • "resources":
    [
    ]
}
{}
{}
{}
{}

Asset

get
/api/3/assets/{id}

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}

Returns the specified asset.

Parameters
path Parameters ?
id
integer <int64>

The identifier of the asset.

Responses

200 OK

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

404 Not Found

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema

Response samples
  • 200 OK

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

  • 503 Service Unavailable

{
  • "addresses":
    [
    ],
  • "assessedForPolicies": false,
  • "assessedForVulnerabilities": true,
  • "configurations":
    [
    ],
  • "databases":
    [
    ],
  • "files":
    [
    ],
  • "history":
    [
    ],
  • "hostName": "corporate-workstation-1102DC.acme.com",
  • "hostNames":
    [
    ],
  • "id": 282,
  • "ids":
    [
    ],
  • "ip": "182.34.74.202",
  • "links":
    [],
  • "mac": "AB:12:CD:34:EF:56",
  • "os": "Microsoft Windows Server 2008 Enterprise Edition SP1",
  • "osFingerprint":
    {
    },
  • "rawRiskScore": 31214.3,
  • "riskScore": 37457.16,
  • "services":
    [
    ],
  • "software":
    [
    ],
  • "type": "",
  • "userGroups":
    [
    ],
  • "users":
    [
    ],
  • "vulnerabilities":
    {
    }
}
{}
{}
{}
{}

Asset

delete
/api/3/assets/{id}

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}

Deletes the specified asset.

Parameters
path Parameters ?
id
integer <int64>

The identifier of the asset.

Responses

200 OK

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

404 Not Found

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema

Response samples
  • 200 OK

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

  • 503 Service Unavailable

{}
{}
{}
{}
{}

Asset Databases

get
/api/3/assets/{id}/databases

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/databases

Returns the databases enumerated on an asset.

Parameters
path Parameters ?
id
integer <int64>

The identifier of the asset.

Responses

200 OK

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

404 Not Found

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema

Response samples
  • 200 OK

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

  • 503 Service Unavailable

{}
{}
{}
{}
{}

Asset Files

get
/api/3/assets/{id}/files

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/files

Returns the files discovered on an asset.

Parameters
path Parameters ?
id
integer <int64>

The identifier of the asset.

Responses

200 OK

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

404 Not Found

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema

Response samples
  • 200 OK

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

  • 503 Service Unavailable

{
  • "links":
    [],
  • "resources":
    [
    ]
}
{}
{}
{}
{}

Asset Services

get
/api/3/assets/{id}/services

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/services

Returns the services discovered on an asset.

Parameters
path Parameters ?
id
integer <int64>

The identifier of the asset.

Responses

200 OK

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

404 Not Found

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema

Response samples
  • 200 OK

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

  • 503 Service Unavailable

{}
{}
{}
{}
{}

Asset Service

get
/api/3/assets/{id}/services/{protocol}/{port}

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/services/{protocol}/{port}

Returns the service running a port and protocol on the asset.

Parameters
path Parameters ?
id
integer <int64>

The identifier of the asset.

protocol
string
"ip" "icmp" "igmp" "ggp" "tcp" "pup" "udp" "idp" "esp" "nd" "raw"

The protocol of the service.

port
integer <int32>

The port of the service.

Responses

200 OK

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

404 Not Found

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema

Response samples
  • 200 OK

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

  • 503 Service Unavailable

{
  • "configurations":
    [
    ],
  • "databases":
    [
    ],
  • "family": "",
  • "links":
    [],
  • "name": "CIFS Name Service",
  • "port": 139,
  • "product": "Samba",
  • "protocol": "tcp",
  • "userGroups":
    [
    ],
  • "users":
    [
    ],
  • "vendor": "",
  • "version": "3.5.11",
  • "webApplications":
    [
    ]
}
{}
{}
{}
{}

Asset Service Configurations

get
/api/3/assets/{id}/services/{protocol}/{port}/configurations

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/services/{protocol}/{port}/configurations

Returns the configuration (properties) of a port and protocol on an asset.

Parameters
path Parameters ?
id
integer <int64>

The identifier of the asset.

protocol
string
"ip" "icmp" "igmp" "ggp" "tcp" "pup" "udp" "idp" "esp" "nd" "raw"

The protocol of the service.

port
integer <int32>

The port of the service.

Responses

200 OK

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

404 Not Found

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema

Response samples
  • 200 OK

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

  • 503 Service Unavailable

{}
{}
{}
{}
{}

Asset Service Databases

get
/api/3/assets/{id}/services/{protocol}/{port}/databases

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/services/{protocol}/{port}/databases

Returns the databases running on a port and protocol on an asset.

Parameters
path Parameters ?
id
integer <int64>

The identifier of the asset.

protocol
string
"ip" "icmp" "igmp" "ggp" "tcp" "pup" "udp" "idp" "esp" "nd" "raw"

The protocol of the service.

port
integer <int32>

The port of the service.

Responses

200 OK

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

404 Not Found

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema

Response samples
  • 200 OK

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

  • 503 Service Unavailable

{}
{}
{}
{}
{}

Asset Service User Groups

get
/api/3/assets/{id}/services/{protocol}/{port}/user_groups

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/services/{protocol}/{port}/user_groups

Returns the user groups enumerated on a port and protocol on an asset.

Parameters
path Parameters ?
id
integer <int64>

The identifier of the asset.

protocol
string
"ip" "icmp" "igmp" "ggp" "tcp" "pup" "udp" "idp" "esp" "nd" "raw"

The protocol of the service.

port
integer <int32>

The port of the service.

Responses

200 OK

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

404 Not Found

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema

Response samples
  • 200 OK

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

  • 503 Service Unavailable

{}
{}
{}
{}
{}

Asset Service Users

get
/api/3/assets/{id}/services/{protocol}/{port}/users

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/services/{protocol}/{port}/users

Returns the users enumerated on a port and protocol on an asset.

Parameters
path Parameters ?
id
integer <int64>

The identifier of the asset.

protocol
string
"ip" "icmp" "igmp" "ggp" "tcp" "pup" "udp" "idp" "esp" "nd" "raw"

The protocol of the service.

port
integer <int32>

The port of the service.

Responses

200 OK

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

404 Not Found

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema

Response samples
  • 200 OK

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

  • 503 Service Unavailable

{}
{}
{}
{}
{}

Asset Service Web Applications

get
/api/3/assets/{id}/services/{protocol}/{port}/web_applications

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/services/{protocol}/{port}/web_applications

Returns the web applications running on a port and protocol on an asset.

Parameters
path Parameters ?
id
integer <int64>

The identifier of the asset.

protocol
string
"ip" "icmp" "igmp" "ggp" "tcp" "pup" "udp" "idp" "esp" "nd" "raw"

The protocol of the service.

port
integer <int32>

The port of the service.

Responses

200 OK

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

404 Not Found

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema

Response samples
  • 200 OK

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

  • 503 Service Unavailable

{}
{}
{}
{}
{}

Asset Service Web Application

get
/api/3/assets/{id}/services/{protocol}/{port}/web_applications/{webApplicationId}

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/services/{protocol}/{port}/web_applications/{webApplicationId}

Returns a web application running on a port and protocol on an asset.

Parameters
path Parameters ?
id
integer <int64>

The identifier of the asset.

protocol
string
"ip" "icmp" "igmp" "ggp" "tcp" "pup" "udp" "idp" "esp" "nd" "raw"

The protocol of the service.

port
integer <int32>

The port of the service.

webApplicationId
integer <int64>

The identifier of the web application.

Responses

200 OK

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

404 Not Found

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema

Response samples
  • 200 OK

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

  • 503 Service Unavailable

{
  • "id": 30712,
  • "pages":
    [
    ],
  • "root": "/",
  • "virtualHost": "102.89.22.253"
}
{}
{}
{}
{}

Asset Software

get
/api/3/assets/{id}/software

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/software

Returns the software on an asset.

Parameters
path Parameters ?
id
integer <int64>

The identifier of the asset.

Responses

200 OK

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

404 Not Found

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema

Response samples
  • 200 OK

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

  • 503 Service Unavailable

{
  • "links":
    [],
  • "resources":
    [
    ]
}
{}
{}
{}
{}

Asset Tags

get
/api/3/assets/{id}/tags

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/tags

Returns tags assigned to an asset.

Parameters
path Parameters ?
id
integer <int64>

The identifier of the asset.

Responses

200 OK

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

404 Not Found

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema

Response samples
  • 200 OK

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

  • 503 Service Unavailable

{
  • "links":
    [],
  • "resources":
    [
    ]
}
{}
{}
{}
{}

Asset Tag

put
/api/3/assets/{id}/tags/{tagId}

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/tags/{tagId}

Assigns the specified tag to the asset.

Parameters
path Parameters ?
id
integer <int64>

The identifier of the asset.

tagId
integer <int32>

The identifier of the tag.

Responses

200 OK

Headers
Response Schema

400 Bad Request

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

404 Not Found

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema

Response samples
  • 200 OK

  • 400 Bad Request

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

  • 503 Service Unavailable

{}
{}
{}
{}
{}
{}

Asset Tag

delete
/api/3/assets/{id}/tags/{tagId}

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/tags/{tagId}

Removes the specified tag from the asset's tags.

Parameters
path Parameters ?
id
integer <int64>

The identifier of the asset.

tagId
integer <int32>

The identifier of the tag.

Responses

200 OK

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

404 Not Found

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema

Response samples
  • 200 OK

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

  • 503 Service Unavailable

{}
{}
{}
{}
{}

Asset User Groups

get
/api/3/assets/{id}/user_groups

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/user_groups

Returns user groups enumerated on an asset.

Parameters
path Parameters ?
id
integer <int64>

The identifier of the asset.

Responses

200 OK

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

404 Not Found

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema

Response samples
  • 200 OK

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

  • 503 Service Unavailable

{}
{}
{}
{}
{}

Asset Users

get
/api/3/assets/{id}/users

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/users

Returns users enumerated on an asset.

Parameters
path Parameters ?
id
integer <int64>

The identifier of the asset.

Responses

200 OK

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

404 Not Found

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema

Response samples
  • 200 OK

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

  • 503 Service Unavailable

{}
{}
{}
{}
{}

Operating Systems

get
/api/3/operating_systems

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/operating_systems

Returns all operating systems discovered across all assets.

Parameters
query Parameters ?
page
integer <int32>
0

The index of the page (zero-based) to retrieve.

size
integer <int32>
10

The number of records per page to retrieve.

sort
Multiple query params of string

The criteria to sort the records by, in the format: property[,ASC|DESC]. The default sort order is ascending. Multiple sort criteria can be specified using multiple sort query parameters.

Responses

200 OK

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

404 Not Found

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema

Response samples
  • 200 OK

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

  • 503 Service Unavailable

{
  • "links":
    [],
  • "page":
    {
    },
  • "resources":
    [
    ]
}
{}
{}
{}
{}

Operating System

get
/api/3/operating_systems/{id}

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/operating_systems/{id}

Returns the details for an operating system.

Parameters
path Parameters ?
id
integer <int64>

The identifier of the operating system.

Responses

200 OK

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

404 Not Found

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema

Response samples
  • 200 OK

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

  • 503 Service Unavailable

{
  • "architecture": "x86",
  • "configurations":
    [
    ],
  • "cpe":
    {
    },
  • "description": "Microsoft Windows Server 2008 Enterprise Edition SP1",
  • "family": "Windows",
  • "id": 35,
  • "product": "Windows Server 2008 Enterprise Edition",
  • "systemName": "Microsoft Windows",
  • "type": "Workstation",
  • "vendor": "Microsoft",
  • "version": "SP1"
}
{}
{}
{}
{}

Software

get
/api/3/software

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/software

Returns all software enumerated on any asset.

Parameters
query Parameters ?
page
integer <int32>
0

The index of the page (zero-based) to retrieve.

size
integer <int32>
10

The number of records per page to retrieve.

sort
Multiple query params of string

The criteria to sort the records by, in the format: property[,ASC|DESC]. The default sort order is ascending. Multiple sort criteria can be specified using multiple sort query parameters.

Responses

200 OK

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

404 Not Found

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema

Response samples
  • 200 OK

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

  • 503 Service Unavailable

{
  • "links":
    [],
  • "page":
    {
    },
  • "resources":
    [
    ]
}
{}
{}
{}
{}

Software

get
/api/3/software/{id}

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/software/{id}

Returns the details for software.

Parameters
path Parameters ?
id
integer <int64>

The identifier of the software.

Responses

200 OK

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

404 Not Found

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema

Response samples
  • 200 OK

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

  • 503 Service Unavailable

{
  • "configurations":
    [
    ],
  • "cpe":
    {
    },
  • "description": "Microsoft Outlook 2013 15.0.4867.1000",
  • "family": "Office 2013",
  • "id": 0,
  • "product": "Outlook 2013",
  • "type": "Productivity",
  • "vendor": "Microsoft",
  • "version": "15.0.4867.1000"
}
{}
{}
{}
{}

Asset Discovery

Resources for managing and viewing the mechanisms used to automatically discover assets.

Discovery Connections

get
/api/3/discovery_connections

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/discovery_connections

Returns all discovery connections.

Parameters
query Parameters ?
page
integer <int32>
0

The index of the page (zero-based) to retrieve.

size
integer <int32>
10

The number of records per page to retrieve.

sort
Multiple query params of string

The criteria to sort the records by, in the format: property[,ASC|DESC]. The default sort order is ascending. Multiple sort criteria can be specified using multiple sort query parameters.

Responses

200 OK

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

404 Not Found

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema

Response samples
  • 200 OK

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

  • 503 Service Unavailable

{
  • "links":
    [],
  • "page":
    {
    },
  • "resources":
    [
    ]
}
{}
{}
{}
{}

Discovery Connection

get
/api/3/discovery_connections/{id}

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/discovery_connections/{id}

Returns a discovery connection.

Parameters
path Parameters ?
id
integer <int64>

The identifier of the discovery connection.

Responses

200 OK

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

404 Not Found

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema

Response samples
  • 200 OK

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

  • 503 Service Unavailable

{
  • "accessKeyId": "",
  • "address": "",
  • "arn": "",
  • "awsSessionName": "",
  • "connectionType": "",
  • "eventSource": "",
  • "exchangeServerHostname": "",
  • "exchangeUser": "",
  • "folderPath": "",
  • "id": "",
  • "ldapServer": "",
  • "links":
    [],
  • "name": "Connection 1",
  • "port": "",
  • "protocol": "",
  • "region": "",
  • "scanEngineIsInsideAWS": false,
  • "secretAccessKey": "",
  • "status": "",
  • "username": "",
  • "winRMServer": ""
}
{}
{}
{}
{}

Discovery Connection Reconnect

post
/api/3/discovery_connections/{id}/connect

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/discovery_connections/{id}/connect

Attempts to reconnect the discovery connection.

Parameters
path Parameters ?
id
integer <int64>

The identifier of the discovery connection.

Responses

200 OK

Headers

400 Bad Request

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema

Response samples
  • 400 Bad Request

  • 401 Unauthorized

  • 500 Internal Server Error

  • 503 Service Unavailable

{}
{}
{}
{}

Sonar Queries

get
/api/3/sonar_queries

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/sonar_queries

Returns all sonar queries.

Responses

200 OK

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

404 Not Found

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema

Response samples
  • 200 OK

  • 401 Unauthorized

  • 404 Not Found

  • 500 Internal Server Error

  • 503 Service Unavailable

{}
{}
{}
{}
{}

Sonar Queries

post
/api/3/sonar_queries

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/sonar_queries

Creates a sonar query.

Request Body

param0


criteria
SonarCriteria

The search criteria used to search for assets from the Sonar API.

links
Link
name
string

The name of the Sonar query.

Responses

200 OK

Headers
Response Schema

400 Bad Request

Headers
Response Schema

401 Unauthorized

Headers
Response Schema

500 Internal Server Error

Headers
Response Schema

503 Service Unavailable

Headers
Response Schema
Request samples
  • JSON
  • Assets in IP Range
  • Recently Scanned Rapid7 Assets
  • Recently Scanned Assets in IP Range
{
  • "criteria":
    {
    },
  • "links":
    [],
  • "name": "Assets in Domain"
}
{
    "criteria": {
        "filters": [
            { "type": "ip-address-range", "lower": "192.168.1.1", "upper": "192.168.1.254" }
        ]
    },
    "name": "Assets In IP Range"
}
{
    "criteria": {
        "filters": [
            { "type": "domain-contains", "domain": "acme.com" },
            { "type": "scan-date-within-the-last", "days": "30" }
        ]
    },
    "name": "Recently Scanned ACME Assets"
}
{
    "criteria": {
        "filters": [
            { "type": "ip-address-range", "lower": "192.168.1.1", "upper": "192.168.1.254" },
            { "type": "scan-date-within-the-last", "days": "30" }
        ]
    },
    "name": "Recently Scanned Assets in IP Range"
}

Response samples
  • 200 OK

  • 400 Bad Request

  • 401 Unauthorized

  • 500 Internal Server Error

  • 503 Service Unavailable

{}
{}
{}
{}
{}

Sonar Query Search

post
/api/3/sonar_queries/search

Server URL

https://help.rapid7.com/insightvm/en-us/api/3/sonar_queries/search

Executes a Sonar query to discover assets with the given search criteria.

Request Body

param0


filters
SonarCriterion

The filters in the Sonar query.