wPFnG8sr

1
2
3Search
4OVERVIEW
5ROOT
6ASSET
7ASSET DISCOVERY
8ASSET GROUP
9CREDENTIAL
10POLICY
11POLICY OVERRIDE
12REMEDIATION
13REPORT
14SCAN
15SCAN ENGINE
16SCAN TEMPLATE
17SITE
18TAG
19USER
20VULNERABILITY
21VULNERABILITY CHECK
22VULNERABILITY EXCEPTION
23VULNERABILITY RESULT
24ADMINISTRATION
25INSIGHTVM API (V3)
26Contact: support@rapid7.com
27
28OVERVIEW
29This 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.
30
31Versioning
32Versioning is specified in the URL and the base path of this API is: https://<host>:<port>/api/3/.
33
34Specification
35An 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.
36
37Download the specification: Download
38
39Authentication
40Authorization 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".
41
422FA
43This 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.
44
45Resources
46Naming
47Resource 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.
48
49The following naming conventions are used by this API:
50
51Type	Case
52Resource names	lower_snake_case
53Header, body, and query parameters parameters	camelCase
54JSON fields and property names	camelCase
55Collections
56A 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:
57
58/api/3/{resource_name}
59Instances
60An 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:
61
62/api/3/{resource_name}/{instance_id}...
63Verbs
64The 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.
65
66Verb	Usage	Success	Failure
67GET	Used to retrieve a resource by identifier, or a collection of resources by type.	200	400, 401, 402, 404, 405, 408, 410, 415,  500
68POST	Creates a resource with an application-specified identifier.	201	400, 401, 404, 405, 408, 413, 415, 500
69POST	Performs a request to queue an asynchronous job.	202	400, 401, 405, 408, 410, 413, 415, 500
70PUT	Creates a resource with a client-specified identifier.	200	400, 401, 403, 405, 408, 410, 413, 415,  500
71PUT	Performs a full update of a resource with a specified identifier.	201	400, 401, 403, 405, 408, 410, 413, 415,  500
72DELETE	Deletes a resource by identifier or an entire collection of resources.	204	400, 401, 405, 408, 410, 413, 415, 500
73OPTIONS	Requests what operations are available on a resource.	200	401, 404, 405, 408, 500
74Common Operations
75OPTIONS
76All 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.
77
78Collection Resources
79Collection resources can support the GET, POST, PUT, and DELETE operations.
80
81GET
82The 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.
83
84POST
85The 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.
86
87The 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.
88
89PUT
90The 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.
91
92PUT 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.
93
94DELETE
95The 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.
96
97Instance Resources
98Instance resources can support the GET, PUT, POST, PATCH and DELETE operations.
99
100GET
101Retrieves 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.
102
103PUT
104Allows 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.
105
106The 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.
107
108POST
109Performs 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.
110
111PATCH
112The 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.
113
114DELETE
115Permanently 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.
116
117Requests
118Unless otherwise indicated, the default request body media type is application/json.
119
120Headers
121Commonly used request headers include:
122
123Header	Example	Purpose
124Accept	application/json	Defines what acceptable content types are allowed by the client. For all types, use  */*.
125Accept-Encoding	deflate, gzip	Allows for the encoding to be specified (such as gzip).
126Accept-Language	en-US	Indicates to the server the client's locale (defaults en-US).
127Authorization	Basic Base64("username:password")	Basic authentication
128Token	123456	Two-factor authentication token (if enabled)
129Dates & Times
130Dates and/or times are specified as strings in the ISO 8601 format(s). The following formats are supported as input:
131
132Value	Format	Notes
133Date	YYYY-MM-DD	Defaults to 12 am UTC (if used for a date & time
134Date & time only	YYYY-MM-DD'T'hh:mm:ss[.nnn]	Defaults to UTC
135Date & time in UTC	YYYY-MM-DD'T'hh:mm:ss[.nnn]Z	
136Date & time w/ offset	YYYY-MM-DD'T'hh:mm:ss[.nnn][+|-]hh:mm	
137Date & time w/ zone-offset	YYYY-MM-DD'T'hh:mm:ss[.nnn][+|-]hh:mm[<zone-id>]	
138Timezones
139Timezones are specified in the regional zone format, such as "America/Los_Angeles", "Asia/Tokyo", or "GMT".
140
141Paging
142Pagination 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.
143
144For example, /resources?page=2&size=10 will return page 3, with 10 records per page, giving results 21-30.
145
146The maximum page size for a request is 500.
147
148Sorting
149Sorting 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:
150
151sort=property[,ASC|DESC]...
152Therefore, 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.
153
154For example, the request /resources?sort=name,ASC&sort=title,DESC would sort by name ascending and title descending, in that order.
155
156Responses
157The following response statuses may be returned by this API.
158
159Status	Meaning	Usage
160200	OK	The operation performed without error according to the specification of the request, and no more specific 2xx code is suitable.
161201	Created	A 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.
162202	Accepted	An asynchronous task has been accepted, but not guaranteed, to be processed in the future.
163400	Bad Request	The request was invalid or cannot be otherwise served. The request is not likely to succeed in the future without modifications.
164401	Unauthorized	The user is unauthorized to perform the operation requested, or does not maintain permissions to perform the operation on the resource specified.
165403	Forbidden	The resource exists to which the user has access, but the operating requested is not permitted.
166404	Not Found	The resource specified could not be located, does not exist, or an unauthenticated client does not have permissions to a resource.
167405	Method Not Allowed	The operations may not be performed on the specific resource. Allowed operations are returned and may be performed on the resource.
168408	Request Timeout	The client has failed to complete a request in a timely manner and the request has been discarded.
169413	Request Entity Too Large	The request being provided is too large for the server to accept processing.
170415	Unsupported Media Type	The media type is not supported for the requested resource.
171500	Internal Server Error	An internal and unexpected error has occurred on the server at no fault of the client.
172Security
173The 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:
174
175Use Case	Access	Resource	Permission	Status
176Unauthenticated access to an unauthenticated resource.	Unauthenticated	Unauthenticated	Yes	20x
177Unauthenticated access to an authenticated resource.	Unauthenticated	Authenticated	No	401
178Unauthenticated access to an authenticated resource.	Unauthenticated	Non-existent	No	401
179Authenticated access to a unauthenticated resource.	Authenticated	Unauthenticated	Yes	20x
180Authenticated access to an authenticated, unprivileged resource.	Authenticated	Authenticated	No	404
181Authenticated access to an authenticated, privileged resource.	Authenticated	Authenticated	Yes	20x
182Authenticated access to an authenticated, non-existent resource	Authenticated	Non-existent	Yes	404
183Headers
184Commonly used response headers include:
185
186Header	Example	Purpose
187Allow	OPTIONS, GET	Defines the allowable HTTP operations on a resource.
188Cache-Control	no-store, must-revalidate	Disables caching of resources (as they are all dynamic).
189Content-Encoding	gzip	The encoding of the response body (if any).
190Location		Refers to the URI of the resource created by a request.
191Transfer-Encoding	chunked	Specified the encoding used to transform response.
192Retry-After	5000	Indicates the time to wait before retrying a request.
193X-Content-Type-Options	nosniff	Disables MIME type sniffing.
194X-XSS-Protection	1; mode=block	Enables XSS filter protection.
195X-Frame-Options	SAMEORIGIN	Prevents rendering in a frame from a different origin.
196X-UA-Compatible	IE=edge,chrome=1	Specifies the browser mode to render in.
197Format
198When 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.
199
200Dates & Times
201Dates 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.
202
203For example:
204
205Value	Format	Example
206Date	YYYY-MM-DD	2017-12-03
207Date & Time	YYYY-MM-DD'T'hh:mm:ss[.nnn]Z	2017-12-03T10:15:30Z
208Content
209In 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.
210
211Paging
212The response to a paginated request follows the format:
213
214{
215   resources": [ 
216      ... 
217   ],
218   "page": { 
219      "number" : ...,
220      "size" : ...,
221      "totalResources" : ...,
222      "totalPages" : ...
223   },
224   "links": [ 
225      "first" : {
226         "href" : "..."
227       },
228       "prev" : {
229         "href" : "..."
230       },
231       "self" : {
232         "href" : "..."
233       },
234       "next" : {
235         "href" : "..."
236       },
237       "last" : {
238         "href" : "..."
239       } 
240   ]
241}
242The 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:
243
244number - The page number (zero-based) of the page returned.
245size - The size of the pages, which is less than or equal to the maximum page size.
246totalResources - The total amount of resources available across all pages.
247totalPages - The total amount of pages.
248The 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.
249
250The "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.
251
252Requests 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.
253
254Property Views
255The "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:
256
257/<resource>?view={viewName}
258Error
259Any 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:
260
261{
262   "status": <statusCode>,
263   "message": <message>,
264   "links" : [ {
265      "rel" : "...",
266      "href" : "..."
267    } ]
268} 
269The 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.
270
271Search Criteria
272Multiple 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:
273
274{ 
275   "field": "<field-name>", 
276   "operator": "<operator>", 
277   ["value": "<value>",]
278   ["lower": "<value>",]
279   ["upper": "<value>"]
280}
281   
282Every 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.
283
284Every filter also defines one or more values that are supplied to the operator. The valid values vary by operator and are outlined below.
285
286Fields
287The following table outlines the search criteria fields and the available operators:
288
289Field	Operators
290alternate-address-type	in
291container-image	is is not starts with ends with contains does not contain is like not like
292container-status	is is not
293containers	are
294criticality-tag	is is not is greater than is less than is applied is not applied
295custom-tag	is is not starts with ends with contains does not contain is applied is not applied
296cve	is is not contains does not contain
297cvss-access-complexity	is is not
298cvss-authentication-required	is is not
299cvss-access-vector	is is not
300cvss-availability-impact	is is not
301cvss-confidentiality-impact	is is not
302cvss-integrity-impact	is is not
303cvss-v3-confidentiality-impact	is is not
304cvss-v3-integrity-impact	is is not
305cvss-v3-availability-impact	is is not
306cvss-v3-attack-vector	is is not
307cvss-v3-attack-complexity	is is not
308cvss-v3-user-interaction	is is not
309cvss-v3-privileges-required	is is not
310host-name	is is not starts with ends with contains does not contain is empty is not empty is like not like
311host-type	in not in
312ip-address	is is not in range not in range is like not like
313ip-address-type	in not in
314last-scan-date	is-on-or-before is on or after is between is earlier than is within the last
315location-tag	is is not starts with ends with contains does not contain is applied is not applied
316mobile-device-last-sync-time	is-within-the-last is earlier than
317open-ports	is is not in range
318operating-system	contains does not contain is empty is not empty
319owner-tag	is is not starts with ends with contains does not contain is applied is not applied
320pci-compliance	is
321risk-score	is is not in range greater than less than
322service-name	contains does not contain
323site-id	in not in
324software	contains does not contain
325vAsset-cluster	is is not contains does not contain starts with
326vAsset-datacenter	is is not
327vAsset-host-name	is is not contains does not contain starts with
328vAsset-power-state	in not in
329vAsset-resource-pool-path	contains does not contain
330vulnerability-assessed	is-on-or-before is on or after is between is earlier than is within the last
331vulnerability-category	is is not starts with ends with contains does not contain
332vulnerability-cvss-v3-score	is is not
333vulnerability-cvss-score	is is not in range is greater than is less than
334vulnerability-exposures	includes does not include
335vulnerability-title	contains does not contain is is not starts with ends with
336vulnerability-validated-status	are
337Enumerated Properties
338The following fields have enumerated values:
339
340Field	Acceptable Values
341alternate-address-type	0=IPv4, 1=IPv6
342containers	0=present, 1=not present
343container-status	created running paused restarting exited dead unknown
344cvss-access-complexity	
345L = Low
346M = Medium
347H = High
348cvss-integrity-impact	
349N = None
350P = Partial
351C = Complete
352cvss-confidentiality-impact	
353N = None
354P = Partial
355C = Complete
356cvss-availability-impact	
357N = None
358P = Partial
359C = Complete
360cvss-access-vector	
361L = Local
362A = Adjacent
363N = Network
364cvss-authentication-required	
365N = None
366S = Single
367M = Multiple
368cvss-v3-confidentiality-impact	
369L = Local
370L = Low
371N = None
372H = High
373cvss-v3-integrity-impact	
374L = Local
375L = Low
376N = None
377H = High
378cvss-v3-availability-impact	
379N = None
380L = Low
381H = High
382cvss-v3-attack-vector	
383N = Network
384A = Adjacent
385L = Local
386P = Physical
387cvss-v3-attack-complexity	
388L = Low
389H = High
390cvss-v3-user-interaction	
391N = None
392R = Required
393cvss-v3-privileges-required	
394N = None
395L = Low
396H = High
397host-type	0=Unknown, 1=Guest, 2=Hypervisor, 3=Physical, 4=Mobile
398ip-address-type	0=IPv4, 1=IPv6
399pci-compliance	0=fail, 1=pass
400vulnerability-validated-status	0=present, 1=not present
401Operator Properties
402The following table outlines which properties are required for each operator and the appropriate data type(s):
403
404Operator	value	lower	upper
405are	string		
406contains	string		
407does-not-contain	string		
408ends with	string		
409in	Array[ string ]		
410in-range		numeric	numeric
411includes	Array[ string ]		
412is	string		
413is-applied			
414is-between		numeric	numeric
415is-earlier-than	numeric		
416is-empty			
417is-greater-than	numeric		
418is-on-or-after	string (yyyy-MM-dd)		
419is-on-or-before	string (yyyy-MM-dd)		
420is-not	string		
421is-not-applied			
422is-not-empty			
423is-within-the-last	string		
424less-than	string		
425like	string		
426not-contains	string		
427not-in	Array[ string ]		
428not-in-range		numeric	numeric
429not-like	string		
430starts-with	string		
431Discovery Connection Search Criteria
432Dynamic sites make use of search criteria to match assets from a discovery connection. Search criteria is an array of search filters.
433
434Each search filter has a generic format of:
435
436{ 
437   "field": "<field-name>", 
438   "operator": "<operator>", 
439   ["value": "<value>",]
440   ["lower": "<value>",]
441   ["upper": "<value>"]
442}
443   
444Every 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.
445
446Every 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.
447
448Fields (ActiveSync)
449This 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".
450
451The following table outlines the search criteria fields and the available operators for ActiveSync connections:
452
453Field	Operators
454last-sync-time	is-within-the-last is-earlier-than
455operating-system	contains does-not-contain
456user	is is-not contains does-not-contain starts-with
457Fields (AWS)
458This section documents search criteria information for AWS discovery connections. The discovery connections must be the type "aws".
459
460The following table outlines the search criteria fields and the available operators for AWS connections:
461
462Field	Operators
463availability-zone	contains does-not-contain
464guest-os-family	contains does-not-contain
465instance-id	contains does-not-contain
466instance-name	is is-not contains does-not-contain starts-with
467instance-state	in not-in
468instance-type	in not-in
469ip-address	in-range not-in-range is is-not
470region	in not-in
471vpc-id	is is-not contains does-not-contain starts-with
472Fields (DHCP)
473This section documents search criteria information for DHCP discovery connections. The discovery connections must be the type "dhcp".
474
475The following table outlines the search criteria fields and the available operators for DHCP connections:
476
477Field	Operators
478host-name	is is-not contains does-not-contain starts-with
479ip-address	in-range not-in-range is is-not
480mac-address	is is-not contains does-not-contain starts-with
481Fields (Sonar)
482This section documents search criteria information for Sonar discovery connections. The discovery connections must be the type "sonar".
483
484The following table outlines the search criteria fields and the available operators for Sonar connections:
485
486Field	Operators
487search-domain	contains is
488ip-address	in-range is
489sonar-scan-date	is-within-the-last
490Fields (vSphere)
491This section documents search criteria information for vSphere discovery connections. The discovery connections must be the type "vsphere".
492
493The following table outlines the search criteria fields and the available operators for vSphere connections:
494
495Field	Operators
496cluster	is is-not contains does-not-contain starts-with
497data-center	is is-not
498discovered-time	is-on-or-before is-on-or-after is-between is-earlier-than is-within-the-last
499guest-os-family	contains does-not-contain
500host-name	is is-not contains does-not-contain starts-with
501ip-address	in-range not-in-range is is-not
502power-state	in not-in
503resource-pool-path	contains does-not-contain
504last-time-seen	is-on-or-before is-on-or-after is-between is-earlier-than is-within-the-last
505vm	is is-not contains does-not-contain starts-with
506Enumerated Properties (vSphere)
507The following fields have enumerated values:
508
509Field	Acceptable Values
510power-state	poweredOn poweredOff suspended
511HATEOAS
512This 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:
513
514"links": [{
515  "rel": "<relation>",
516  "href": "<href>"
517  ...
518}]
519Where appropriate link objects may also contain additional properties than the rel and href properties, such as id, type, etc.
520
521See the Root resources for the entry points into API discovery.
522
523ROOT
524
525Provides access to primary entry point for discovering the available resources in this API.
526
527Resources
528GET /api/3
529Server URL
530
531https://help.rapid7.com/insightvm/en-us/api/3
532
533Returns a listing of the resources (endpoints) that are available to be invoked in this API.
534
535RESPONSES
536200 OK
537
538401 Unauthorized
539
540404 Not Found
541
542500 Internal Server Error
543
544503 Service Unavailable
545
546
547RESPONSE SAMPLES
548200 OK
549401 Unauthorized
550404 Not Found
551500 Internal Server Error
552503 Service Unavailable
553Expand all Collapse all
554{
555"links": [
556{}
557]
558}
559ASSET
560
561Resources and operations for managing assets. Assets can be created under the Site Assets resource.
562
563Assets
564GET /api/3/assets
565Server URL
566
567https://help.rapid7.com/insightvm/en-us/api/3/assets
568
569Returns all assets for which you have access.
570
571PARAMETERS
572Query Parameters
573 page	
574integer <int32>
5750
576The index of the page (zero-based) to retrieve.
577
578 size	
579integer <int32>
58010
581The number of records per page to retrieve.
582
583 sort	
584Multiple query params of string
585The 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.
586
587RESPONSES
588200 OK
589
590401 Unauthorized
591
592404 Not Found
593
594500 Internal Server Error
595
596503 Service Unavailable
597
598
599RESPONSE SAMPLES
600200 OK
601401 Unauthorized
602404 Not Found
603500 Internal Server Error
604503 Service Unavailable
605Expand all Collapse all
606{
607"links": [
608{}
609],
610"page": {
611"number": 6,
612"size": 10,
613"totalPages": 13,
614"totalResources": 123
615},
616"resources": [
617{}
618]
619}
620Assets
621POST /api/3/sites/{id}/assets
622Server URL
623
624https://help.rapid7.com/insightvm/en-us/api/3/sites/{id}/assets
625
626Creates or updates an asset with the specified details.
627
628PARAMETERS
629Path Parameters
630 id	
631integer <int32>
632The identifier of the site.
633
634REQUEST BODY
635The 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"
636
637
638 addresses 	
639All addresses discovered on the asset.
640
641 configurations 	
642Configuration key-values pairs enumerated on the asset.
643
644 cpe	
645string
646The 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.
647
648 databases 	
649The databases enumerated on the asset.
650
651 date	
652string REQUIRED
653The date the data was collected on the asset.
654
655 description	
656string
657The 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.
658
659 files 	
660The files discovered with searching on the asset.
661
662 hostName 	
663The primary host name (local or FQDN) of the asset.
664
665 hostNames 	
666Additional host names for the asset.
667
668 id	
669integer <int64>
670The identifier of the asset.
671
672 ids 	
673Unique identifiers found on the asset, such as hardware or operating system identifiers.
674
675 ip	
676string
677The primary IPv4 or IPv6 address of the asset.
678
679 links 	
680 mac	
681string
682The primary Media Access Control (MAC) address of the asset. The format is six groups of two hexadecimal digits separated by colons.
683
684 os	
685string
686Free-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.
687
688 osFingerprint 	
689The details of the operating system of the asset.
690
691 services 	
692The services discovered on the asset.
693
694 software 	
695The software discovered on the asset.
696
697 type	
698string
699The type of asset.
700
701 userGroups 	
702The group accounts enumerated on the asset.
703
704 users 	
705The user accounts enumerated on the asset.
706
707 vulnerabilities 	
708Summary information for vulnerabilities on the asset.
709
710RESPONSES
711200 OK
712
713201 Created
714
715400 Bad Request
716
717401 Unauthorized
718
719500 Internal Server Error
720
721503 Service Unavailable
722
723REQUEST SAMPLES
724Expand all Collapse all
725{
726"addresses": [
727{}
728],
729"configurations": [
730{}
731],
732"cpe": "",
733"databases": [
734{}
735],
736"date": "",
737"description": "",
738"files": [
739{}
740],
741"hostName": {
742"name": "corporate-workstation-1102DC.acme.com",
743"source": "DNS"
744},
745"hostNames": [
746{}
747],
748"id": 282,
749"ids": [
750{}
751],
752"ip": "182.34.74.202",
753"links": [
754{}
755],
756"mac": "AB:12:CD:34:EF:56",
757"os": "",
758"osFingerprint": {
759"architecture": "x86",
760"configurations": [],
761"cpe": {},
762"description": "Microsoft Windows Server 2008 Enterprise Edition SP1",
763"family": "Windows",
764"id": 35,
765"product": "Windows Server 2008 Enterprise Edition",
766"systemName": "Microsoft Windows",
767"type": "Workstation",
768"vendor": "Microsoft",
769"version": "SP1"
770},
771"services": [
772{}
773],
774"software": [
775{}
776],
777"type": "",
778"userGroups": [
779{}
780],
781"users": [
782{}
783],
784"vulnerabilities": { }
785}
786
787RESPONSE SAMPLES
788200 OK
789201 Created
790400 Bad Request
791401 Unauthorized
792500 Internal Server Error
793503 Service Unavailable
794Expand all Collapse all
795{
796"id": "1",
797"links": [
798{}
799]
800}
801Asset Search
802POST /api/3/assets/search
803Server URL
804
805https://help.rapid7.com/insightvm/en-us/api/3/assets/search
806
807Returns all assets for which you have access that match the given search criteria.
808
809PARAMETERS
810Query Parameters
811 page	
812integer <int32>
8130
814The index of the page (zero-based) to retrieve.
815
816 size	
817integer <int32>
81810
819The number of records per page to retrieve.
820
821 sort	
822Multiple query params of string
823The 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.
824
825REQUEST BODY
826param1
827
828
829 filters 	
830Filters used to match assets. See Search Criteria for more information on the structure and format.
831
832 match	
833string
834"any" "all"
835Operator 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.
836
837RESPONSES
838200 OK
839
840400 Bad Request
841
842401 Unauthorized
843
844500 Internal Server Error
845
846503 Service Unavailable
847
848REQUEST SAMPLES
849JSON
850Assets Running SSH
851High Risk Windows Assets Running SSH
852Windows 10 Assets
853Assets with High CVSS Scores assigned to Bob
854Assets with SSH running containers in Los Angeles
855Expand all Collapse all
856{
857"filters": [
858{}
859],
860"match": "all"
861}
862
863RESPONSE SAMPLES
864200 OK
865400 Bad Request
866401 Unauthorized
867500 Internal Server Error
868503 Service Unavailable
869Expand all Collapse all
870{
871"links": [
872{}
873],
874"page": {
875"number": 6,
876"size": 10,
877"totalPages": 13,
878"totalResources": 123
879},
880"resources": [
881{}
882]
883}
884Asset
885GET /api/3/assets/{id}
886Server URL
887
888https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}
889
890Returns the specified asset.
891
892PARAMETERS
893Path Parameters
894 id	
895integer <int64>
896The identifier of the asset.
897
898RESPONSES
899200 OK
900
901401 Unauthorized
902
903404 Not Found
904
905500 Internal Server Error
906
907503 Service Unavailable
908
909
910RESPONSE SAMPLES
911200 OK
912401 Unauthorized
913404 Not Found
914500 Internal Server Error
915503 Service Unavailable
916Expand all Collapse all
917{
918"addresses": [
919{}
920],
921"assessedForPolicies": false,
922"assessedForVulnerabilities": true,
923"configurations": [
924{}
925],
926"databases": [
927{}
928],
929"files": [
930{}
931],
932"history": [
933{}
934],
935"hostName": "corporate-workstation-1102DC.acme.com",
936"hostNames": [
937{}
938],
939"id": 282,
940"ids": [
941{}
942],
943"ip": "182.34.74.202",
944"links": [
945{}
946],
947"mac": "AB:12:CD:34:EF:56",
948"os": "Microsoft Windows Server 2008 Enterprise Edition SP1",
949"osFingerprint": {
950"architecture": "x86",
951"configurations": [],
952"cpe": {},
953"description": "Microsoft Windows Server 2008 Enterprise Edition SP1",
954"family": "Windows",
955"id": 35,
956"product": "Windows Server 2008 Enterprise Edition",
957"systemName": "Microsoft Windows",
958"type": "Workstation",
959"vendor": "Microsoft",
960"version": "SP1"
961},
962"rawRiskScore": 31214.3,
963"riskScore": 37457.16,
964"services": [
965{}
966],
967"software": [
968{}
969],
970"type": "",
971"userGroups": [
972{}
973],
974"users": [
975{}
976],
977"vulnerabilities": {
978"critical": 16,
979"exploits": 4,
980"malwareKits": 0,
981"moderate": 3,
982"severe": 76,
983"total": 95
984}
985}
986Asset
987DELETE /api/3/assets/{id}
988Server URL
989
990https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}
991
992Deletes the specified asset.
993
994PARAMETERS
995Path Parameters
996 id	
997integer <int64>
998The identifier of the asset.
999
1000RESPONSES
1001200 OK
1002
1003401 Unauthorized
1004
1005404 Not Found
1006
1007500 Internal Server Error
1008
1009503 Service Unavailable
1010
1011
1012RESPONSE SAMPLES
1013200 OK
1014401 Unauthorized
1015404 Not Found
1016500 Internal Server Error
1017503 Service Unavailable
1018Expand all Collapse all
1019{
1020"links": [
1021{}
1022]
1023}
1024Asset Databases
1025GET /api/3/assets/{id}/databases
1026Server URL
1027
1028https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/databases
1029
1030Returns the databases enumerated on an asset.
1031
1032PARAMETERS
1033Path Parameters
1034 id	
1035integer <int64>
1036The identifier of the asset.
1037
1038RESPONSES
1039200 OK
1040
1041401 Unauthorized
1042
1043404 Not Found
1044
1045500 Internal Server Error
1046
1047503 Service Unavailable
1048
1049
1050RESPONSE SAMPLES
1051200 OK
1052401 Unauthorized
1053404 Not Found
1054500 Internal Server Error
1055503 Service Unavailable
1056Expand all Collapse all
1057{
1058"links": [
1059{}
1060],
1061"resources": [
1062{}
1063]
1064}
1065Asset Files
1066GET /api/3/assets/{id}/files
1067Server URL
1068
1069https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/files
1070
1071Returns the files discovered on an asset.
1072
1073PARAMETERS
1074Path Parameters
1075 id	
1076integer <int64>
1077The identifier of the asset.
1078
1079RESPONSES
1080200 OK
1081
1082401 Unauthorized
1083
1084404 Not Found
1085
1086500 Internal Server Error
1087
1088503 Service Unavailable
1089
1090
1091RESPONSE SAMPLES
1092200 OK
1093401 Unauthorized
1094404 Not Found
1095500 Internal Server Error
1096503 Service Unavailable
1097Expand all Collapse all
1098{
1099"links": [
1100{}
1101],
1102"resources": [
1103{}
1104]
1105}
1106Asset Services
1107GET /api/3/assets/{id}/services
1108Server URL
1109
1110https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/services
1111
1112Returns the services discovered on an asset.
1113
1114PARAMETERS
1115Path Parameters
1116 id	
1117integer <int64>
1118The identifier of the asset.
1119
1120RESPONSES
1121200 OK
1122
1123401 Unauthorized
1124
1125404 Not Found
1126
1127500 Internal Server Error
1128
1129503 Service Unavailable
1130
1131
1132RESPONSE SAMPLES
1133200 OK
1134401 Unauthorized
1135404 Not Found
1136500 Internal Server Error
1137503 Service Unavailable
1138Expand all Collapse all
1139{
1140"links": [
1141{}
1142],
1143"resources": [
1144{}
1145]
1146}
1147Asset Service
1148GET /api/3/assets/{id}/services/{protocol}/{port}
1149Server URL
1150
1151https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/services/{protocol}/{port}
1152
1153Returns the service running a port and protocol on the asset.
1154
1155PARAMETERS
1156Path Parameters
1157 id	
1158integer <int64>
1159The identifier of the asset.
1160
1161 protocol	
1162string
1163"ip" "icmp" "igmp" "ggp" "tcp" "pup" "udp" "idp" "esp" "nd" "raw"
1164The protocol of the service.
1165
1166 port	
1167integer <int32>
1168The port of the service.
1169
1170RESPONSES
1171200 OK
1172
1173401 Unauthorized
1174
1175404 Not Found
1176
1177500 Internal Server Error
1178
1179503 Service Unavailable
1180
1181
1182RESPONSE SAMPLES
1183200 OK
1184401 Unauthorized
1185404 Not Found
1186500 Internal Server Error
1187503 Service Unavailable
1188Expand all Collapse all
1189{
1190"configurations": [
1191{}
1192],
1193"databases": [
1194{}
1195],
1196"family": "",
1197"links": [
1198{}
1199],
1200"name": "CIFS Name Service",
1201"port": 139,
1202"product": "Samba",
1203"protocol": "tcp",
1204"userGroups": [
1205{}
1206],
1207"users": [
1208{}
1209],
1210"vendor": "",
1211"version": "3.5.11",
1212"webApplications": [
1213{}
1214]
1215}
1216Asset Service Configurations
1217GET /api/3/assets/{id}/services/{protocol}/{port}/configurations
1218Server URL
1219
1220https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/services/{protocol}/{port}/configurations
1221
1222Returns the configuration (properties) of a port and protocol on an asset.
1223
1224PARAMETERS
1225Path Parameters
1226 id	
1227integer <int64>
1228The identifier of the asset.
1229
1230 protocol	
1231string
1232"ip" "icmp" "igmp" "ggp" "tcp" "pup" "udp" "idp" "esp" "nd" "raw"
1233The protocol of the service.
1234
1235 port	
1236integer <int32>
1237The port of the service.
1238
1239RESPONSES
1240200 OK
1241
1242401 Unauthorized
1243
1244404 Not Found
1245
1246500 Internal Server Error
1247
1248503 Service Unavailable
1249
1250
1251RESPONSE SAMPLES
1252200 OK
1253401 Unauthorized
1254404 Not Found
1255500 Internal Server Error
1256503 Service Unavailable
1257Expand all Collapse all
1258{
1259"links": [
1260{}
1261],
1262"resources": [
1263{}
1264]
1265}
1266Asset Service Databases
1267GET /api/3/assets/{id}/services/{protocol}/{port}/databases
1268Server URL
1269
1270https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/services/{protocol}/{port}/databases
1271
1272Returns the databases running on a port and protocol on an asset.
1273
1274PARAMETERS
1275Path Parameters
1276 id	
1277integer <int64>
1278The identifier of the asset.
1279
1280 protocol	
1281string
1282"ip" "icmp" "igmp" "ggp" "tcp" "pup" "udp" "idp" "esp" "nd" "raw"
1283The protocol of the service.
1284
1285 port	
1286integer <int32>
1287The port of the service.
1288
1289RESPONSES
1290200 OK
1291
1292401 Unauthorized
1293
1294404 Not Found
1295
1296500 Internal Server Error
1297
1298503 Service Unavailable
1299
1300
1301RESPONSE SAMPLES
1302200 OK
1303401 Unauthorized
1304404 Not Found
1305500 Internal Server Error
1306503 Service Unavailable
1307Expand all Collapse all
1308{
1309"links": [
1310{}
1311],
1312"resources": [
1313{}
1314]
1315}
1316Asset Service User Groups
1317GET /api/3/assets/{id}/services/{protocol}/{port}/user_groups
1318Server URL
1319
1320https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/services/{protocol}/{port}/user_groups
1321
1322Returns the user groups enumerated on a port and protocol on an asset.
1323
1324PARAMETERS
1325Path Parameters
1326 id	
1327integer <int64>
1328The identifier of the asset.
1329
1330 protocol	
1331string
1332"ip" "icmp" "igmp" "ggp" "tcp" "pup" "udp" "idp" "esp" "nd" "raw"
1333The protocol of the service.
1334
1335 port	
1336integer <int32>
1337The port of the service.
1338
1339RESPONSES
1340200 OK
1341
1342401 Unauthorized
1343
1344404 Not Found
1345
1346500 Internal Server Error
1347
1348503 Service Unavailable
1349
1350
1351RESPONSE SAMPLES
1352200 OK
1353401 Unauthorized
1354404 Not Found
1355500 Internal Server Error
1356503 Service Unavailable
1357Expand all Collapse all
1358{
1359"links": [
1360{}
1361],
1362"resources": [
1363{}
1364]
1365}
1366Asset Service Users
1367GET /api/3/assets/{id}/services/{protocol}/{port}/users
1368Server URL
1369
1370https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/services/{protocol}/{port}/users
1371
1372Returns the users enumerated on a port and protocol on an asset.
1373
1374PARAMETERS
1375Path Parameters
1376 id	
1377integer <int64>
1378The identifier of the asset.
1379
1380 protocol	
1381string
1382"ip" "icmp" "igmp" "ggp" "tcp" "pup" "udp" "idp" "esp" "nd" "raw"
1383The protocol of the service.
1384
1385 port	
1386integer <int32>
1387The port of the service.
1388
1389RESPONSES
1390200 OK
1391
1392401 Unauthorized
1393
1394404 Not Found
1395
1396500 Internal Server Error
1397
1398503 Service Unavailable
1399
1400
1401RESPONSE SAMPLES
1402200 OK
1403401 Unauthorized
1404404 Not Found
1405500 Internal Server Error
1406503 Service Unavailable
1407Expand all Collapse all
1408{
1409"links": [
1410{}
1411],
1412"resources": [
1413{}
1414]
1415}
1416Asset Service Web Applications
1417GET /api/3/assets/{id}/services/{protocol}/{port}/web_applications
1418Server URL
1419
1420https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/services/{protocol}/{port}/web_applications
1421
1422Returns the web applications running on a port and protocol on an asset.
1423
1424PARAMETERS
1425Path Parameters
1426 id	
1427integer <int64>
1428The identifier of the asset.
1429
1430 protocol	
1431string
1432"ip" "icmp" "igmp" "ggp" "tcp" "pup" "udp" "idp" "esp" "nd" "raw"
1433The protocol of the service.
1434
1435 port	
1436integer <int32>
1437The port of the service.
1438
1439RESPONSES
1440200 OK
1441
1442401 Unauthorized
1443
1444404 Not Found
1445
1446500 Internal Server Error
1447
1448503 Service Unavailable
1449
1450
1451RESPONSE SAMPLES
1452200 OK
1453401 Unauthorized
1454404 Not Found
1455500 Internal Server Error
1456503 Service Unavailable
1457Expand all Collapse all
1458{
1459"links": [
1460{}
1461],
1462"resources": [
14630
1464]
1465}
1466Asset Service Web Application
1467GET /api/3/assets/{id}/services/{protocol}/{port}/web_applications/{webApplicationId}
1468Server URL
1469
1470https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/services/{protocol}/{port}/web_applications/{webApplicationId}
1471
1472Returns a web application running on a port and protocol on an asset.
1473
1474PARAMETERS
1475Path Parameters
1476 id	
1477integer <int64>
1478The identifier of the asset.
1479
1480 protocol	
1481string
1482"ip" "icmp" "igmp" "ggp" "tcp" "pup" "udp" "idp" "esp" "nd" "raw"
1483The protocol of the service.
1484
1485 port	
1486integer <int32>
1487The port of the service.
1488
1489 webApplicationId	
1490integer <int64>
1491The identifier of the web application.
1492
1493RESPONSES
1494200 OK
1495
1496401 Unauthorized
1497
1498404 Not Found
1499
1500500 Internal Server Error
1501
1502503 Service Unavailable
1503
1504
1505RESPONSE SAMPLES
1506200 OK
1507401 Unauthorized
1508404 Not Found
1509500 Internal Server Error
1510503 Service Unavailable
1511Expand all Collapse all
1512{
1513"id": 30712,
1514"pages": [
1515{}
1516],
1517"root": "/",
1518"virtualHost": "102.89.22.253"
1519}
1520Asset Software
1521GET /api/3/assets/{id}/software
1522Server URL
1523
1524https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/software
1525
1526Returns the software on an asset.
1527
1528PARAMETERS
1529Path Parameters
1530 id	
1531integer <int64>
1532The identifier of the asset.
1533
1534RESPONSES
1535200 OK
1536
1537401 Unauthorized
1538
1539404 Not Found
1540
1541500 Internal Server Error
1542
1543503 Service Unavailable
1544
1545
1546RESPONSE SAMPLES
1547200 OK
1548401 Unauthorized
1549404 Not Found
1550500 Internal Server Error
1551503 Service Unavailable
1552Expand all Collapse all
1553{
1554"links": [
1555{}
1556],
1557"resources": [
1558{}
1559]
1560}
1561Asset Tags
1562GET /api/3/assets/{id}/tags
1563Server URL
1564
1565https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/tags
1566
1567Returns tags assigned to an asset.
1568
1569PARAMETERS
1570Path Parameters
1571 id	
1572integer <int64>
1573The identifier of the asset.
1574
1575RESPONSES
1576200 OK
1577
1578401 Unauthorized
1579
1580404 Not Found
1581
1582500 Internal Server Error
1583
1584503 Service Unavailable
1585
1586
1587RESPONSE SAMPLES
1588200 OK
1589401 Unauthorized
1590404 Not Found
1591500 Internal Server Error
1592503 Service Unavailable
1593Expand all Collapse all
1594{
1595"links": [
1596{}
1597],
1598"resources": [
1599{}
1600]
1601}
1602Asset Tag
1603PUT /api/3/assets/{id}/tags/{tagId}
1604Server URL
1605
1606https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/tags/{tagId}
1607
1608Assigns the specified tag to the asset.
1609
1610PARAMETERS
1611Path Parameters
1612 id	
1613integer <int64>
1614The identifier of the asset.
1615
1616 tagId	
1617integer <int32>
1618The identifier of the tag.
1619
1620RESPONSES
1621200 OK
1622
1623400 Bad Request
1624
1625401 Unauthorized
1626
1627404 Not Found
1628
1629500 Internal Server Error
1630
1631503 Service Unavailable
1632
1633
1634RESPONSE SAMPLES
1635200 OK
1636400 Bad Request
1637401 Unauthorized
1638404 Not Found
1639500 Internal Server Error
1640503 Service Unavailable
1641Expand all Collapse all
1642{
1643"links": [
1644{}
1645]
1646}
1647Asset Tag
1648DELETE /api/3/assets/{id}/tags/{tagId}
1649Server URL
1650
1651https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/tags/{tagId}
1652
1653Removes the specified tag from the asset's tags.
1654
1655PARAMETERS
1656Path Parameters
1657 id	
1658integer <int64>
1659The identifier of the asset.
1660
1661 tagId	
1662integer <int32>
1663The identifier of the tag.
1664
1665RESPONSES
1666200 OK
1667
1668401 Unauthorized
1669
1670404 Not Found
1671
1672500 Internal Server Error
1673
1674503 Service Unavailable
1675
1676
1677RESPONSE SAMPLES
1678200 OK
1679401 Unauthorized
1680404 Not Found
1681500 Internal Server Error
1682503 Service Unavailable
1683Expand all Collapse all
1684{
1685"links": [
1686{}
1687]
1688}
1689Asset User Groups
1690GET /api/3/assets/{id}/user_groups
1691Server URL
1692
1693https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/user_groups
1694
1695Returns user groups enumerated on an asset.
1696
1697PARAMETERS
1698Path Parameters
1699 id	
1700integer <int64>
1701The identifier of the asset.
1702
1703RESPONSES
1704200 OK
1705
1706401 Unauthorized
1707
1708404 Not Found
1709
1710500 Internal Server Error
1711
1712503 Service Unavailable
1713
1714
1715RESPONSE SAMPLES
1716200 OK
1717401 Unauthorized
1718404 Not Found
1719500 Internal Server Error
1720503 Service Unavailable
1721Expand all Collapse all
1722{
1723"links": [
1724{}
1725],
1726"resources": [
1727{}
1728]
1729}
1730Asset Users
1731GET /api/3/assets/{id}/users
1732Server URL
1733
1734https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/users
1735
1736Returns users enumerated on an asset.
1737
1738PARAMETERS
1739Path Parameters
1740 id	
1741integer <int64>
1742The identifier of the asset.
1743
1744RESPONSES
1745200 OK
1746
1747401 Unauthorized
1748
1749404 Not Found
1750
1751500 Internal Server Error
1752
1753503 Service Unavailable
1754
1755
1756RESPONSE SAMPLES
1757200 OK
1758401 Unauthorized
1759404 Not Found
1760500 Internal Server Error
1761503 Service Unavailable
1762Expand all Collapse all
1763{
1764"links": [
1765{}
1766],
1767"resources": [
1768{}
1769]
1770}
1771Operating Systems
1772GET /api/3/operating_systems
1773Server URL
1774
1775https://help.rapid7.com/insightvm/en-us/api/3/operating_systems
1776
1777Returns all operating systems discovered across all assets.
1778
1779PARAMETERS
1780Query Parameters
1781 page	
1782integer <int32>
17830
1784The index of the page (zero-based) to retrieve.
1785
1786 size	
1787integer <int32>
178810
1789The number of records per page to retrieve.
1790
1791 sort	
1792Multiple query params of string
1793The 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.
1794
1795RESPONSES
1796200 OK
1797
1798401 Unauthorized
1799
1800404 Not Found
1801
1802500 Internal Server Error
1803
1804503 Service Unavailable
1805
1806
1807RESPONSE SAMPLES
1808200 OK
1809401 Unauthorized
1810404 Not Found
1811500 Internal Server Error
1812503 Service Unavailable
1813Expand all Collapse all
1814{
1815"links": [
1816{}
1817],
1818"page": {
1819"number": 6,
1820"size": 10,
1821"totalPages": 13,
1822"totalResources": 123
1823},
1824"resources": [
1825{}
1826]
1827}
1828Operating System
1829GET /api/3/operating_systems/{id}
1830Server URL
1831
1832https://help.rapid7.com/insightvm/en-us/api/3/operating_systems/{id}
1833
1834Returns the details for an operating system.
1835
1836PARAMETERS
1837Path Parameters
1838 id	
1839integer <int64>
1840The identifier of the operating system.
1841
1842RESPONSES
1843200 OK
1844
1845401 Unauthorized
1846
1847404 Not Found
1848
1849500 Internal Server Error
1850
1851503 Service Unavailable
1852
1853
1854RESPONSE SAMPLES
1855200 OK
1856401 Unauthorized
1857404 Not Found
1858500 Internal Server Error
1859503 Service Unavailable
1860Expand all Collapse all
1861{
1862"architecture": "x86",
1863"configurations": [
1864{}
1865],
1866"cpe": {
1867"edition": "enterprise",
1868"language": "",
1869"other": "",
1870"part": "o",
1871"product": "windows_server_2008",
1872"swEdition": "",
1873"targetHW": "",
1874"targetSW": "",
1875"update": "sp1",
1876"v2.2": "cpe:/o:microsoft:windows_server_2008:-:sp1:enterprise",
1877"v2.3": "cpe:2.3:o:microsoft:windows_server_2008:-:sp1:enterprise:*:*:*:*:*",
1878"vendor": "microsoft",
1879"version": "-"
1880},
1881"description": "Microsoft Windows Server 2008 Enterprise Edition SP1",
1882"family": "Windows",
1883"id": 35,
1884"product": "Windows Server 2008 Enterprise Edition",
1885"systemName": "Microsoft Windows",
1886"type": "Workstation",
1887"vendor": "Microsoft",
1888"version": "SP1"
1889}
1890Software
1891GET /api/3/software
1892Server URL
1893
1894https://help.rapid7.com/insightvm/en-us/api/3/software
1895
1896Returns all software enumerated on any asset.
1897
1898PARAMETERS
1899Query Parameters
1900 page	
1901integer <int32>
19020
1903The index of the page (zero-based) to retrieve.
1904
1905 size	
1906integer <int32>
190710
1908The number of records per page to retrieve.
1909
1910 sort	
1911Multiple query params of string
1912The 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.
1913
1914RESPONSES
1915200 OK
1916
1917401 Unauthorized
1918
1919404 Not Found
1920
1921500 Internal Server Error
1922
1923503 Service Unavailable
1924
1925
1926RESPONSE SAMPLES
1927200 OK
1928401 Unauthorized
1929404 Not Found
1930500 Internal Server Error
1931503 Service Unavailable
1932Expand all Collapse all
1933{
1934"links": [
1935{}
1936],
1937"page": {
1938"number": 6,
1939"size": 10,
1940"totalPages": 13,
1941"totalResources": 123
1942},
1943"resources": [
1944{}
1945]
1946}
1947Software
1948GET /api/3/software/{id}
1949Server URL
1950
1951https://help.rapid7.com/insightvm/en-us/api/3/software/{id}
1952
1953Returns the details for software.
1954
1955PARAMETERS
1956Path Parameters
1957 id	
1958integer <int64>
1959The identifier of the software.
1960
1961RESPONSES
1962200 OK
1963
1964401 Unauthorized
1965
1966404 Not Found
1967
1968500 Internal Server Error
1969
1970503 Service Unavailable
1971
1972
1973RESPONSE SAMPLES
1974200 OK
1975401 Unauthorized
1976404 Not Found
1977500 Internal Server Error
1978503 Service Unavailable
1979Expand all Collapse all
1980{
1981"configurations": [
1982{}
1983],
1984"cpe": {
1985"edition": "enterprise",
1986"language": "",
1987"other": "",
1988"part": "o",
1989"product": "windows_server_2008",
1990"swEdition": "",
1991"targetHW": "",
1992"targetSW": "",
1993"update": "sp1",
1994"v2.2": "cpe:/o:microsoft:windows_server_2008:-:sp1:enterprise",
1995"v2.3": "cpe:2.3:o:microsoft:windows_server_2008:-:sp1:enterprise:*:*:*:*:*",
1996"vendor": "microsoft",
1997"version": "-"
1998},
1999"description": "Microsoft Outlook 2013 15.0.4867.1000",
2000"family": "Office 2013",
2001"id": 0,
2002"product": "Outlook 2013",
2003"type": "Productivity",
2004"vendor": "Microsoft",
2005"version": "15.0.4867.1000"
2006}
2007ASSET DISCOVERY
2008
2009Resources for managing and viewing the mechanisms used to automatically discover assets.
2010
2011Discovery Connections
2012GET /api/3/discovery_connections
2013Server URL
2014
2015https://help.rapid7.com/insightvm/en-us/api/3/discovery_connections
2016
2017Returns all discovery connections.
2018
2019PARAMETERS
2020Query Parameters
2021 page	
2022integer <int32>
20230
2024The index of the page (zero-based) to retrieve.
2025
2026 size	
2027integer <int32>
202810
2029The number of records per page to retrieve.
2030
2031 sort	
2032Multiple query params of string
2033The 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.
2034
2035RESPONSES
2036200 OK
2037
2038401 Unauthorized
2039
2040404 Not Found
2041
2042500 Internal Server Error
2043
2044503 Service Unavailable
2045
2046
2047RESPONSE SAMPLES
2048200 OK
2049401 Unauthorized
2050404 Not Found
2051500 Internal Server Error
2052503 Service Unavailable
2053Expand all Collapse all
2054{
2055"links": [
2056{}
2057],
2058"page": {
2059"number": 6,
2060"size": 10,
2061"totalPages": 13,
2062"totalResources": 123
2063},
2064"resources": [
2065{}
2066]
2067}
2068Discovery Connection
2069GET /api/3/discovery_connections/{id}
2070Server URL
2071
2072https://help.rapid7.com/insightvm/en-us/api/3/discovery_connections/{id}
2073
2074Returns a discovery connection.
2075
2076PARAMETERS
2077Path Parameters
2078 id	
2079integer <int64>
2080The identifier of the discovery connection.
2081
2082RESPONSES
2083200 OK
2084
2085401 Unauthorized
2086
2087404 Not Found
2088
2089500 Internal Server Error
2090
2091503 Service Unavailable
2092
2093
2094RESPONSE SAMPLES
2095200 OK
2096401 Unauthorized
2097404 Not Found
2098500 Internal Server Error
2099503 Service Unavailable
2100Expand all Collapse all
2101{
2102"accessKeyId": "",
2103"address": "",
2104"arn": "",
2105"awsSessionName": "",
2106"connectionType": "",
2107"eventSource": "",
2108"exchangeServerHostname": "",
2109"exchangeUser": "",
2110"folderPath": "",
2111"id": "",
2112"ldapServer": "",
2113"links": [
2114{}
2115],
2116"name": "Connection 1",
2117"port": "",
2118"protocol": "",
2119"region": "",
2120"scanEngineIsInsideAWS": false,
2121"secretAccessKey": "",
2122"status": "",
2123"username": "",
2124"winRMServer": ""
2125}
2126Discovery Connection Reconnect
2127POST /api/3/discovery_connections/{id}/connect
2128Server URL
2129
2130https://help.rapid7.com/insightvm/en-us/api/3/discovery_connections/{id}/connect
2131
2132Attempts to reconnect the discovery connection.
2133
2134PARAMETERS
2135Path Parameters
2136 id	
2137integer <int64>
2138The identifier of the discovery connection.
2139
2140RESPONSES
2141200 OK
2142
2143400 Bad Request
2144
2145401 Unauthorized
2146
2147500 Internal Server Error
2148
2149503 Service Unavailable
2150
2151
2152RESPONSE SAMPLES
2153400 Bad Request
2154401 Unauthorized
2155500 Internal Server Error
2156503 Service Unavailable
2157Expand all Collapse all
2158{
2159"links": [
2160{}
2161],
2162"message": "An error has occurred.",
2163"status": "400"
2164}
2165Sonar Queries
2166GET /api/3/sonar_queries
2167Server URL
2168
2169https://help.rapid7.com/insightvm/en-us/api/3/sonar_queries
2170
2171Returns all sonar queries.
2172
2173RESPONSES
2174200 OK
2175
2176401 Unauthorized
2177
2178404 Not Found
2179
2180500 Internal Server Error
2181
2182503 Service Unavailable
2183
2184
2185RESPONSE SAMPLES
2186200 OK
2187401 Unauthorized
2188404 Not Found
2189500 Internal Server Error
2190503 Service Unavailable
2191Expand all Collapse all
2192{
2193"links": [
2194{}
2195],
2196"resources": [
2197{}
2198]
2199}
2200Sonar Queries
2201POST /api/3/sonar_queries
2202Server URL
2203
2204https://help.rapid7.com/insightvm/en-us/api/3/sonar_queries
2205
2206Creates a sonar query.
2207
2208REQUEST BODY
2209param0
2210
2211
2212 criteria 	
2213The search criteria used to search for assets from the Sonar API.
2214
2215 links 	
2216 name	
2217string
2218The name of the Sonar query.
2219
2220RESPONSES
2221200 OK
2222
2223400 Bad Request
2224
2225401 Unauthorized
2226
2227500 Internal Server Error
2228
2229503 Service Unavailable
2230
2231REQUEST SAMPLES
2232JSON
2233Assets in IP Range
2234Recently Scanned Rapid7 Assets
2235Recently Scanned Assets in IP Range
2236Expand all Collapse all
2237{
2238"criteria": {
2239"filters": []
2240},
2241"links": [
2242{}
2243],
2244"name": "Assets in Domain"
2245}
2246
2247RESPONSE SAMPLES
2248200 OK
2249400 Bad Request
2250401 Unauthorized
2251500 Internal Server Error
2252503 Service Unavailable
2253Expand all Collapse all
2254{
2255"id": 1,
2256"links": [
2257{}
2258]
2259}
2260Sonar Query Search
2261POST /api/3/sonar_queries/search
2262Server URL
2263
2264https://help.rapid7.com/insightvm/en-us/api/3/sonar_queries/search
2265
2266Executes a Sonar query to discover assets with the given search criteria.
2267
2268REQUEST BODY
2269param0
2270
2271
2272 filters 	
2273The filters in the Sonar query.
2274
2275 days	
2276integer <int32>
2277If the field is scan-date-within-the-last, the number of days to search against.
2278
2279 lower	
2280string
2281If the field is ip-address-range, the lower limit of the search.
2282
2283 searchDomain	
2284string
2285If the field is domain-contains, the domain to search against.
2286
2287 type	
2288string
2289"domain-contains" "scan-date-within-the-last" "ip-address-range"
2290The type of query to perform.
2291
2292 upper	
2293string
2294If the field is ip-address-range, the upper limit of the search.
2295
2296RESPONSES
2297200 OK
2298
2299400 Bad Request
2300
2301401 Unauthorized
2302
2303500 Internal Server Error
2304
2305503 Service Unavailable
2306
2307REQUEST SAMPLES
2308JSON
2309Assets in IP Range
2310Recently Scanned Rapid7 Assets
2311Recently Scanned Assets in IP Range
2312Expand all Collapse all
2313{
2314"filters": [
2315{}
2316]
2317}
2318
2319RESPONSE SAMPLES
2320200 OK
2321400 Bad Request
2322401 Unauthorized
2323500 Internal Server Error
2324503 Service Unavailable
2325Expand all Collapse all
2326[
2327{
2328"address": "12.83.99.203",
2329"links": [],
2330"name": "desktop-27.acme.com"
2331}
2332]
2333Sonar Query
2334GET /api/3/sonar_queries/{id}
2335Server URL
2336
2337https://help.rapid7.com/insightvm/en-us/api/3/sonar_queries/{id}
2338
2339Returns a sonar query.
2340
2341PARAMETERS
2342Path Parameters
2343 id	
2344integer <int64>
2345The identifier of the Sonar query.
2346
2347RESPONSES
2348200 OK
2349
2350401 Unauthorized
2351
2352404 Not Found
2353
2354500 Internal Server Error
2355
2356503 Service Unavailable
2357
2358
2359RESPONSE SAMPLES
2360200 OK
2361401 Unauthorized
2362404 Not Found
2363500 Internal Server Error
2364503 Service Unavailable
2365Expand all Collapse all
2366{
2367"criteria": {
2368"filters": []
2369},
2370"id": 14,
2371"links": [
2372{}
2373],
2374"name": "Assets in Domain"
2375}
2376Sonar Query
2377PUT /api/3/sonar_queries/{id}
2378Server URL
2379
2380https://help.rapid7.com/insightvm/en-us/api/3/sonar_queries/{id}
2381
2382Updates a sonar query.
2383
2384PARAMETERS
2385Path Parameters
2386 id	
2387integer <int64>
2388The identifier of the Sonar query.
2389
2390REQUEST BODY
2391param1
2392
2393
2394 criteria 	
2395The search criteria used to search for assets from the Sonar API.
2396
2397 links 	
2398 name	
2399string
2400The name of the Sonar query.
2401
2402RESPONSES
2403200 OK
2404
2405400 Bad Request
2406
2407401 Unauthorized
2408
2409404 Not Found
2410
2411500 Internal Server Error
2412
2413503 Service Unavailable
2414
2415REQUEST SAMPLES
2416JSON
2417Assets in IP Range
2418Recently Scanned Rapid7 Assets
2419Recently Scanned Assets in IP Range
2420Expand all Collapse all
2421{
2422"criteria": {
2423"filters": []
2424},
2425"links": [
2426{}
2427],
2428"name": "Assets in Domain"
2429}
2430
2431RESPONSE SAMPLES
2432200 OK
2433400 Bad Request
2434401 Unauthorized
2435404 Not Found
2436500 Internal Server Error
2437503 Service Unavailable
2438Expand all Collapse all
2439{
2440"links": [
2441{}
2442]
2443}
2444Sonar Query
2445DELETE /api/3/sonar_queries/{id}
2446Server URL
2447
2448https://help.rapid7.com/insightvm/en-us/api/3/sonar_queries/{id}
2449
2450Removes a sonar query.
2451
2452PARAMETERS
2453Path Parameters
2454 id	
2455integer <int64>
2456The identifier of the Sonar query.
2457
2458RESPONSES
2459200 OK
2460
2461401 Unauthorized
2462
2463404 Not Found
2464
2465500 Internal Server Error
2466
2467503 Service Unavailable
2468
2469
2470RESPONSE SAMPLES
2471200 OK
2472401 Unauthorized
2473404 Not Found
2474500 Internal Server Error
2475503 Service Unavailable
2476Expand all Collapse all
2477{
2478"links": [
2479{}
2480]
2481}
2482Sonar Query Assets
2483GET /api/3/sonar_queries/{id}/assets
2484Server URL
2485
2486https://help.rapid7.com/insightvm/en-us/api/3/sonar_queries/{id}/assets
2487
2488Returns the assets that are discovered by a Sonar query.
2489
2490PARAMETERS
2491Path Parameters
2492 id	
2493integer <int64>
2494The identifier of the Sonar query.
2495
2496RESPONSES
2497200 OK
2498
2499401 Unauthorized
2500
2501404 Not Found
2502
2503500 Internal Server Error
2504
2505503 Service Unavailable
2506
2507
2508RESPONSE SAMPLES
2509200 OK
2510401 Unauthorized
2511404 Not Found
2512500 Internal Server Error
2513503 Service Unavailable
2514Expand all Collapse all
2515{
2516"links": [
2517{}
2518],
2519"resources": [
2520{}
2521]
2522}
2523ASSET GROUP
2524
2525Asset Group Tag
2526
2527Asset Groups
2528GET /api/3/asset_groups
2529Server URL
2530
2531https://help.rapid7.com/insightvm/en-us/api/3/asset_groups
2532
2533Returns all asset groups.
2534
2535PARAMETERS
2536Query Parameters
2537 type	
2538string
2539The type of asset group.
2540
2541 name	
2542string
2543A search pattern for the name of the asset group. Searches are case-insensitive contains.
2544
2545 page	
2546integer <int32>
25470
2548The index of the page (zero-based) to retrieve.
2549
2550 size	
2551integer <int32>
255210
2553The number of records per page to retrieve.
2554
2555 sort	
2556Multiple query params of string
2557The 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.
2558
2559RESPONSES
2560200 OK
2561
2562401 Unauthorized
2563
2564404 Not Found
2565
2566500 Internal Server Error
2567
2568503 Service Unavailable
2569
2570
2571RESPONSE SAMPLES
2572200 OK
2573401 Unauthorized
2574404 Not Found
2575500 Internal Server Error
2576503 Service Unavailable
2577Expand all Collapse all
2578{
2579"links": [
2580{}
2581],
2582"page": {
2583"number": 6,
2584"size": 10,
2585"totalPages": 13,
2586"totalResources": 123
2587},
2588"resources": [
2589{}
2590]
2591}
2592Asset Groups
2593POST /api/3/asset_groups
2594Server URL
2595
2596https://help.rapid7.com/insightvm/en-us/api/3/asset_groups
2597
2598Creates a new asset group. The searchCriteria field can be passed no matter what the type of the asset group is. The asset group type changes when the assets are refreshed. Dynamic asset groups constantly refreshed their membership as assets are scanned whereas static asset groups do not change membership automatically. See the Search Criteria for more information on using dynamic criteria.
2599
2600REQUEST BODY
2601The details of the asset group.
2602
2603
2604 description	
2605string
2606The description of the asset group.
2607
2608 name	
2609string REQUIRED
2610The name of the asset group.
2611
2612 searchCriteria 	
2613Search criteria used to determine dynamic membership, if type is "dynamic".
2614
2615 type	
2616string REQUIRED
2617"static" "dynamic"
2618The type of the asset group.
2619
2620 vulnerabilities 	
2621Summary information for distinct vulnerabilities found on the assets.
2622
2623RESPONSES
2624201 Created
2625
2626400 Bad Request
2627
2628401 Unauthorized
2629
2630500 Internal Server Error
2631
2632503 Service Unavailable
2633
2634REQUEST SAMPLES
2635JSON
2636An Empty Static Asset Group
2637A static asset group with assets defined by search criteria
2638A dynamic asset group
2639Expand all Collapse all
2640{
2641"description": "Assets with unacceptable high risk required immediate remediation.",
2642"name": "High Risk Assets",
2643"searchCriteria": {
2644"filters": [],
2645"match": "all"
2646},
2647"type": "dynamic",
2648"vulnerabilities": { }
2649}
2650
2651RESPONSE SAMPLES
2652201 Created
2653400 Bad Request
2654401 Unauthorized
2655500 Internal Server Error
2656503 Service Unavailable
2657Expand all Collapse all
2658{
2659"id": 1,
2660"links": [
2661{}
2662]
2663}
2664Asset Group
2665GET /api/3/asset_groups/{id}
2666Server URL
2667
2668https://help.rapid7.com/insightvm/en-us/api/3/asset_groups/{id}
2669
2670Returns an asset group.
2671
2672PARAMETERS
2673Path Parameters
2674 id	
2675integer <int32>
2676The identifier of the asset group.
2677
2678RESPONSES
2679200 OK
2680
2681401 Unauthorized
2682
2683404 Not Found
2684
2685500 Internal Server Error
2686
2687503 Service Unavailable
2688
2689
2690RESPONSE SAMPLES
2691200 OK
2692401 Unauthorized
2693404 Not Found
2694500 Internal Server Error
2695503 Service Unavailable
2696Expand all Collapse all
2697{
2698"assets": 768,
2699"description": "Assets with unacceptable high risk required immediate remediation.",
2700"id": 61,
2701"links": [
2702{}
2703],
2704"name": "High Risk Assets",
2705"riskScore": 4457823.78,
2706"searchCriteria": {
2707"filters": [],
2708"match": "all"
2709},
2710"type": "dynamic",
2711"vulnerabilities": {
2712"critical": 16,
2713"moderate": 3,
2714"severe": 76,
2715"total": 95
2716}
2717}
2718Asset Group
2719PUT /api/3/asset_groups/{id}
2720Server URL
2721
2722https://help.rapid7.com/insightvm/en-us/api/3/asset_groups/{id}
2723
2724Updates the details of an asset group. See the search criteria endpoint (/search_criteria) for more information about building the search criteria and examples.
2725
2726PARAMETERS
2727Path Parameters
2728 id	
2729integer <int32>
2730The identifier of the asset group.
2731
2732REQUEST BODY
2733The details of the asset group.
2734
2735
2736 description	
2737string
2738The description of the asset group.
2739
2740 name	
2741string REQUIRED
2742The name of the asset group.
2743
2744 searchCriteria 	
2745Search criteria used to determine dynamic membership, if type is "dynamic".
2746
2747 type	
2748string REQUIRED
2749"static" "dynamic"
2750The type of the asset group.
2751
2752 vulnerabilities 	
2753Summary information for distinct vulnerabilities found on the assets.
2754
2755RESPONSES
2756200 OK
2757
2758400 Bad Request
2759
2760401 Unauthorized
2761
2762404 Not Found
2763
2764500 Internal Server Error
2765
2766503 Service Unavailable
2767
2768REQUEST SAMPLES
2769Expand all Collapse all
2770{
2771"description": "Assets with unacceptable high risk required immediate remediation.",
2772"name": "High Risk Assets",
2773"searchCriteria": {
2774"filters": [],
2775"match": "all"
2776},
2777"type": "dynamic",
2778"vulnerabilities": { }
2779}
2780
2781RESPONSE SAMPLES
2782200 OK
2783400 Bad Request
2784401 Unauthorized
2785404 Not Found
2786500 Internal Server Error
2787503 Service Unavailable
2788Expand all Collapse all
2789{
2790"links": [
2791{}
2792]
2793}
2794Asset Group
2795DELETE /api/3/asset_groups/{id}
2796Server URL
2797
2798https://help.rapid7.com/insightvm/en-us/api/3/asset_groups/{id}
2799
2800Deletes the asset group.
2801
2802PARAMETERS
2803Path Parameters
2804 id	
2805integer <int32>
2806The identifier of the asset group.
2807
2808RESPONSES
2809200 OK
2810
2811401 Unauthorized
2812
2813404 Not Found
2814
2815500 Internal Server Error
2816
2817503 Service Unavailable
2818
2819
2820RESPONSE SAMPLES
2821200 OK
2822401 Unauthorized
2823404 Not Found
2824500 Internal Server Error
2825503 Service Unavailable
2826Expand all Collapse all
2827{
2828"links": [
2829{}
2830]
2831}
2832Asset Group Assets
2833GET /api/3/asset_groups/{id}/assets
2834Server URL
2835
2836https://help.rapid7.com/insightvm/en-us/api/3/asset_groups/{id}/assets
2837
2838Returns hypermedia links for the assets that belong to an asset group.
2839
2840PARAMETERS
2841Path Parameters
2842 id	
2843integer <int32>
2844The identifier of the asset group.
2845
2846RESPONSES
2847200 OK
2848
2849401 Unauthorized
2850
2851404 Not Found
2852
2853500 Internal Server Error
2854
2855503 Service Unavailable
2856
2857
2858RESPONSE SAMPLES
2859200 OK
2860401 Unauthorized
2861404 Not Found
2862500 Internal Server Error
2863503 Service Unavailable
2864Expand all Collapse all
2865{
2866"links": [
2867{}
2868],
2869"resources": [
28700
2871]
2872}
2873Asset Group Assets
2874PUT /api/3/asset_groups/{id}/assets
2875Server URL
2876
2877https://help.rapid7.com/insightvm/en-us/api/3/asset_groups/{id}/assets
2878
2879Updates all the assets that belong to a static asset group.
2880
2881PARAMETERS
2882Path Parameters
2883 id	
2884integer <int32>
2885The identifier of the asset group.
2886
2887REQUEST BODY
2888The assets to place in the asset group.
2889
2890
2891integer <int64>
2892RESPONSES
2893200 OK
2894
2895400 Bad Request
2896
2897401 Unauthorized
2898
2899404 Not Found
2900
2901500 Internal Server Error
2902
2903503 Service Unavailable
2904
2905REQUEST SAMPLES
2906Expand all Collapse all
2907[
29080
2909]
2910
2911RESPONSE SAMPLES
2912200 OK
2913400 Bad Request
2914401 Unauthorized
2915404 Not Found
2916500 Internal Server Error
2917503 Service Unavailable
2918Expand all Collapse all
2919{
2920"links": [
2921{}
2922]
2923}
2924Asset Group Assets
2925DELETE /api/3/asset_groups/{id}/assets
2926Server URL
2927
2928https://help.rapid7.com/insightvm/en-us/api/3/asset_groups/{id}/assets
2929
2930Removes the assets from the given static asset group.
2931
2932PARAMETERS
2933Path Parameters
2934 id	
2935integer <int32>
2936The identifier of the asset group.
2937
2938RESPONSES
2939200 OK
2940
2941401 Unauthorized
2942
2943404 Not Found
2944
2945500 Internal Server Error
2946
2947503 Service Unavailable
2948
2949
2950RESPONSE SAMPLES
2951200 OK
2952401 Unauthorized
2953404 Not Found
2954500 Internal Server Error
2955503 Service Unavailable
2956Expand all Collapse all
2957{
2958"links": [
2959{}
2960]
2961}
2962Asset Group Asset
2963PUT /api/3/asset_groups/{id}/assets/{assetId}
2964Server URL
2965
2966https://help.rapid7.com/insightvm/en-us/api/3/asset_groups/{id}/assets/{assetId}
2967
2968Adds an asset to a static asset group.
2969
2970PARAMETERS
2971Path Parameters
2972 id	
2973integer <int32>
2974The identifier of the asset group.
2975
2976 assetId	
2977integer <int64>
2978The identifier of the asset.
2979
2980RESPONSES
2981200 OK
2982
2983400 Bad Request
2984
2985401 Unauthorized
2986
2987404 Not Found
2988
2989500 Internal Server Error
2990
2991503 Service Unavailable
2992
2993
2994RESPONSE SAMPLES
2995200 OK
2996400 Bad Request
2997401 Unauthorized
2998404 Not Found
2999500 Internal Server Error
3000503 Service Unavailable
3001Expand all Collapse all
3002{
3003"links": [
3004{}
3005]
3006}
3007Asset Group Asset
3008DELETE /api/3/asset_groups/{id}/assets/{assetId}
3009Server URL
3010
3011https://help.rapid7.com/insightvm/en-us/api/3/asset_groups/{id}/assets/{assetId}
3012
3013Removes an asset from an asset group.
3014
3015PARAMETERS
3016Path Parameters
3017 id	
3018integer <int32>
3019The identifier of the asset group.
3020
3021 assetId	
3022integer <int64>
3023The identifier of the asset.
3024
3025RESPONSES
3026200 OK
3027
3028401 Unauthorized
3029
3030404 Not Found
3031
3032500 Internal Server Error
3033
3034503 Service Unavailable
3035
3036
3037RESPONSE SAMPLES
3038200 OK
3039401 Unauthorized
3040404 Not Found
3041500 Internal Server Error
3042503 Service Unavailable
3043Expand all Collapse all
3044{
3045"links": [
3046{}
3047]
3048}
3049Asset Group Search Criteria
3050GET /api/3/asset_groups/{id}/search_criteria
3051Server URL
3052
3053https://help.rapid7.com/insightvm/en-us/api/3/asset_groups/{id}/search_criteria
3054
3055Returns the search criteria of a dynamic asset group.For a reference of valid search criteria input see the Asset Search resource.
3056
3057PARAMETERS
3058Path Parameters
3059 id	
3060integer <int32>
3061The identifier of the asset group.
3062
3063RESPONSES
3064200 OK
3065
3066401 Unauthorized
3067
3068404 Not Found
3069
3070500 Internal Server Error
3071
3072503 Service Unavailable
3073
3074
3075RESPONSE SAMPLES
3076200 OK
3077401 Unauthorized
3078404 Not Found
3079500 Internal Server Error
3080503 Service Unavailable
3081Expand all Collapse all
3082{
3083"filters": [
3084{}
3085],
3086"match": "all"
3087}
3088Asset Group Search Criteria
3089PUT /api/3/asset_groups/{id}/search_criteria
3090Server URL
3091
3092https://help.rapid7.com/insightvm/en-us/api/3/asset_groups/{id}/search_criteria
3093
3094Updates the search criteria of a dynamic asset group. For a reference of valid search criteria input see the Asset Search resource.
3095
3096PARAMETERS
3097Path Parameters
3098 id	
3099integer <int32>
3100The identifier of the asset group.
3101
3102REQUEST BODY
3103The search criteria specification.
3104
3105
3106 filters 	
3107Filters used to match assets. See Search Criteria for more information on the structure and format.
3108
3109 match	
3110string
3111"any" "all"
3112Operator 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.
3113
3114RESPONSES
3115200 OK
3116
3117400 Bad Request
3118
3119401 Unauthorized
3120
3121404 Not Found
3122
3123500 Internal Server Error
3124
3125503 Service Unavailable
3126
3127REQUEST SAMPLES
3128JSON
3129Unassigned PCI Incompliant Windows Assets
3130Stale Los Angeles Assets (High Risk)
3131Expand all Collapse all
3132{
3133"filters": [
3134{}
3135],
3136"match": "all"
3137}
3138
3139RESPONSE SAMPLES
3140200 OK
3141400 Bad Request
3142401 Unauthorized
3143404 Not Found
3144500 Internal Server Error
3145503 Service Unavailable
3146Expand all Collapse all
3147{
3148"links": [
3149{}
3150]
3151}
3152Asset Group Tags
3153GET /api/3/asset_groups/{id}/tags
3154Server URL
3155
3156https://help.rapid7.com/insightvm/en-us/api/3/asset_groups/{id}/tags
3157
3158Returns the tags assigned to an asset group.
3159
3160PARAMETERS
3161Path Parameters
3162 id	
3163integer <int32>
3164The identifier of the asset group.
3165
3166RESPONSES
3167200 OK
3168
3169401 Unauthorized
3170
3171404 Not Found
3172
3173500 Internal Server Error
3174
3175503 Service Unavailable
3176
3177
3178RESPONSE SAMPLES
3179200 OK
3180401 Unauthorized
3181404 Not Found
3182500 Internal Server Error
3183503 Service Unavailable
3184Expand all Collapse all
3185{
3186"links": [
3187{}
3188],
3189"resources": [
31900
3191]
3192}
3193Asset Group Tags
3194PUT /api/3/asset_groups/{id}/tags
3195Server URL
3196
3197https://help.rapid7.com/insightvm/en-us/api/3/asset_groups/{id}/tags
3198
3199Updates the tags of an asset group.
3200
3201PARAMETERS
3202Path Parameters
3203 id	
3204integer <int32>
3205The identifier of the asset group.
3206
3207REQUEST BODY
3208The tags to associate to the asset group.
3209
3210
3211integer <int32>
3212RESPONSES
3213200 OK
3214
3215400 Bad Request
3216
3217401 Unauthorized
3218
3219404 Not Found
3220
3221500 Internal Server Error
3222
3223503 Service Unavailable
3224
3225REQUEST SAMPLES
3226Expand all Collapse all
3227[
32280
3229]
3230
3231RESPONSE SAMPLES
3232200 OK
3233400 Bad Request
3234401 Unauthorized
3235404 Not Found
3236500 Internal Server Error
3237503 Service Unavailable
3238Expand all Collapse all
3239{
3240"links": [
3241{}
3242]
3243}
3244Asset Group Tags
3245DELETE /api/3/asset_groups/{id}/tags
3246Server URL
3247
3248https://help.rapid7.com/insightvm/en-us/api/3/asset_groups/{id}/tags
3249
3250Removes all tag associations from the asset group.
3251
3252PARAMETERS
3253Path Parameters
3254 id	
3255integer <int32>
3256The identifier of the asset group.
3257
3258RESPONSES
3259200 OK
3260
3261401 Unauthorized
3262
3263404 Not Found
3264
3265500 Internal Server Error
3266
3267503 Service Unavailable
3268
3269
3270RESPONSE SAMPLES
3271200 OK
3272401 Unauthorized
3273404 Not Found
3274500 Internal Server Error
3275503 Service Unavailable
3276Expand all Collapse all
3277{
3278"links": [
3279{}
3280]
3281}
3282Asset Group Tag
3283PUT /api/3/asset_groups/{id}/tags/{tagId}
3284Server URL
3285
3286https://help.rapid7.com/insightvm/en-us/api/3/asset_groups/{id}/tags/{tagId}
3287
3288Adds a tag to an asset group.
3289
3290PARAMETERS
3291Path Parameters
3292 id	
3293integer <int32>
3294The identifier of the asset group.
3295
3296 tagId	
3297integer <int32>
3298The identifier of the tag.
3299
3300RESPONSES
3301200 OK
3302
3303400 Bad Request
3304
3305401 Unauthorized
3306
3307404 Not Found
3308
3309500 Internal Server Error
3310
3311503 Service Unavailable
3312
3313
3314RESPONSE SAMPLES
3315200 OK
3316400 Bad Request
3317401 Unauthorized
3318404 Not Found
3319500 Internal Server Error
3320503 Service Unavailable
3321Expand all Collapse all
3322{
3323"links": [
3324{}
3325]
3326}
3327Asset Group Tag
3328DELETE /api/3/asset_groups/{id}/tags/{tagId}
3329Server URL
3330
3331https://help.rapid7.com/insightvm/en-us/api/3/asset_groups/{id}/tags/{tagId}
3332
3333Removes a tag from an asset group.
3334
3335PARAMETERS
3336Path Parameters
3337 id	
3338integer <int32>
3339The identifier of the asset group.
3340
3341 tagId	
3342integer <int32>
3343The identifier of the tag.
3344
3345RESPONSES
3346200 OK
3347
3348401 Unauthorized
3349
3350404 Not Found
3351
3352500 Internal Server Error
3353
3354503 Service Unavailable
3355
3356
3357RESPONSE SAMPLES
3358200 OK
3359401 Unauthorized
3360404 Not Found
3361500 Internal Server Error
3362503 Service Unavailable
3363Expand all Collapse all
3364{
3365"links": [
3366{}
3367]
3368}
3369Asset Group Users
3370GET /api/3/asset_groups/{id}/users
3371Server URL
3372
3373https://help.rapid7.com/insightvm/en-us/api/3/asset_groups/{id}/users
3374
3375Returns hypermedia links for the users with access to this asset group.
3376
3377PARAMETERS
3378Path Parameters
3379 id	
3380integer <int32>
3381The identifier of the asset group.
3382
3383RESPONSES
3384200 OK
3385
3386401 Unauthorized
3387
3388404 Not Found
3389
3390500 Internal Server Error
3391
3392503 Service Unavailable
3393
3394
3395RESPONSE SAMPLES
3396200 OK
3397401 Unauthorized
3398404 Not Found
3399500 Internal Server Error
3400503 Service Unavailable
3401Expand all Collapse all
3402{
3403"links": [
3404{}
3405],
3406"resources": [
34070
3408]
3409}
3410Asset Group Users
3411PUT /api/3/asset_groups/{id}/users
3412Server URL
3413
3414https://help.rapid7.com/insightvm/en-us/api/3/asset_groups/{id}/users
3415
3416Grants users with sufficient privileges access to an asset group.
3417
3418PARAMETERS
3419Path Parameters
3420 id	
3421integer <int32>
3422The identifier of the asset group.
3423
3424REQUEST BODY
3425The users to grant access to the asset group.
3426
3427
3428integer <int32>
3429RESPONSES
3430200 OK
3431
3432400 Bad Request
3433
3434401 Unauthorized
3435
3436404 Not Found
3437
3438500 Internal Server Error
3439
3440503 Service Unavailable
3441
3442REQUEST SAMPLES
3443Expand all Collapse all
3444[
34450
3446]
3447
3448RESPONSE SAMPLES
3449200 OK
3450400 Bad Request
3451401 Unauthorized
3452404 Not Found
3453500 Internal Server Error
3454503 Service Unavailable
3455Expand all Collapse all
3456{
3457"links": [
3458{}
3459]
3460}
3461Asset Group User
3462PUT /api/3/asset_groups/{id}/users/{userId}
3463Server URL
3464
3465https://help.rapid7.com/insightvm/en-us/api/3/asset_groups/{id}/users/{userId}
3466
3467Grants a user with sufficient privileges access to the asset group.
3468
3469PARAMETERS
3470Path Parameters
3471 id	
3472integer <int32>
3473The identifier of the asset group.
3474
3475 userId	
3476integer <int32>
3477The identifier of the user.
3478
3479RESPONSES
3480200 OK
3481
3482400 Bad Request
3483
3484401 Unauthorized
3485
3486404 Not Found
3487
3488500 Internal Server Error
3489
3490503 Service Unavailable
3491
3492
3493RESPONSE SAMPLES
3494200 OK
3495400 Bad Request
3496401 Unauthorized
3497404 Not Found
3498500 Internal Server Error
3499503 Service Unavailable
3500Expand all Collapse all
3501{
3502"links": [
3503{}
3504]
3505}
3506Asset Group User
3507DELETE /api/3/asset_groups/{id}/users/{userId}
3508Server URL
3509
3510https://help.rapid7.com/insightvm/en-us/api/3/asset_groups/{id}/users/{userId}
3511
3512Removes a user's access from an asset group.
3513
3514PARAMETERS
3515Path Parameters
3516 id	
3517integer <int32>
3518The identifier of the asset group.
3519
3520 userId	
3521integer <int32>
3522The identifier of the user.
3523
3524RESPONSES
3525200 OK
3526
3527401 Unauthorized
3528
3529404 Not Found
3530
3531500 Internal Server Error
3532
3533503 Service Unavailable
3534
3535
3536RESPONSE SAMPLES
3537200 OK
3538401 Unauthorized
3539404 Not Found
3540500 Internal Server Error
3541503 Service Unavailable
3542Expand all Collapse all
3543{
3544"links": [
3545{}
3546]
3547}
3548CREDENTIAL
3549
3550Resources and operations for managing shared credentials.
3551
3552Shared Credentials
3553GET /api/3/shared_credentials
3554Server URL
3555
3556https://help.rapid7.com/insightvm/en-us/api/3/shared_credentials
3557
3558Retrieves all defined shared credential resources.
3559
3560RESPONSES
3561200 OK
3562
3563401 Unauthorized
3564
3565404 Not Found
3566
3567500 Internal Server Error
3568
3569503 Service Unavailable
3570
3571
3572RESPONSE SAMPLES
3573200 OK
3574401 Unauthorized
3575404 Not Found
3576500 Internal Server Error
3577503 Service Unavailable
3578Expand all Collapse all
3579{
3580"links": [
3581{}
3582],
3583"resources": [
3584{}
3585]
3586}
3587Shared Credentials
3588POST /api/3/shared_credentials
3589Server URL
3590
3591https://help.rapid7.com/insightvm/en-us/api/3/shared_credentials
3592
3593Creates a new shared credential.
3594
3595REQUEST BODY
3596The specification of a shared credential.
3597
3598
3599 account 	
3600 REQUIRED
3601Specify the type of service to authenticate as well as all of the information required by that service.
3602
3603service string
3604"as400" "cifs" "cifshash" "cvs" "db2" "ftp" "http" "ms-sql" "mysql" "notes" "oracle" "pop" "postgresql" "remote-exec" "snmp" "snmpv3" "ssh" "ssh-key" "sybase" "telnet"
3605The type of service to authenticate with.
3606The following are the names of the valid values for service:
3607
3608Value	Service
3609as400	IBM AS/400
3610cifs	Microsoft Windows/Samba (SMB/CIFS)
3611cifshash	Microsoft Windows/Samba LM/NTLM Hash (SMB/CIFS)
3612cvs	Concurrent Versioning System (CVS)
3613db2	DB2
3614ftp	File Transfer Protocol (FTP)
3615http	Web Site HTTP Authentication
3616ms-sql	Microsoft SQL Server
3617mysql	MySQL Server
3618notes	Lotus Notes/Domino
3619oracle	Oracle
3620pop	Post Office Protocol (POP)
3621postgresql	PostgreSQL
3622remote-exec	Remote Execution
3623snmp	Simple Network Management Protocol v1/v2c
3624snmpv3	Simple Network Management Protocol v3
3625ssh	Secure Shell (SSH)
3626ssh-key	Secure Shell (SSH) Public Key
3627sybase	Sybase SQL Server
3628telnet	Telnet
3629The following is a specification of supported credential properties for each type of service. These properties are to be specified within the account object.
3630
3631as400 supported properties:
3632
3633domain string
3634The address of the domain.
3635
3636username string REQUIRED
3637The user name for the account that will be used for authenticating.
3638
3639password string REQUIRED
3640The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
3641
3642cifs supported properties:
3643
3644domain string
3645The address of the domain.
3646
3647username string REQUIRED
3648The user name for the account that will be used for authenticating.
3649
3650password string REQUIRED
3651The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
3652
3653cifshash supported properties:
3654
3655domain string
3656The address of the domain.
3657
3658username string REQUIRED
3659The user name for the account that will be used for authenticating.
3660
3661ntlmHash string REQUIRED
3662The NTLM password hash. Note: This property is not returned in responses for security.
3663
3664cvs supported properties:
3665
3666domain string
3667The address of the domain.
3668
3669username string REQUIRED
3670The user name for the account that will be used for authenticating.
3671
3672password string REQUIRED
3673The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
3674
3675db2 supported properties:
3676
3677database string
3678The name of the database.
3679
3680username string REQUIRED
3681The user name for the account that will be used for authenticating.
3682
3683password string REQUIRED
3684The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
3685
3686ftp supported properties:
3687
3688username string REQUIRED
3689The user name for the account that will be used for authenticating.
3690
3691password string REQUIRED
3692The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
3693
3694http supported properties:
3695
3696realm string
3697The realm.
3698
3699username string REQUIRED
3700The user name for the account that will be used for authenticating.
3701
3702password string REQUIRED
3703The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
3704
3705ms-sql supported properties:
3706
3707database string
3708The name of the database. If not specified, a default database name will be used during authentication.
3709
3710useWindowsAuthentication boolean
3711Boolean flag signaling whether to connect to the database using Windows authentication. When set to true, Windows authentication is attempted; when set to false, SQL authentication is attempted.
3712
3713domain string
3714The address of the domain. This property cannot be specified unless property useWindowsAuthentication is set to true.
3715
3716username string REQUIRED
3717The user name for the account that will be used for authenticating.
3718
3719password string REQUIRED
3720The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
3721
3722mysql supported properties:
3723
3724database string
3725The name of the database. If not specified, a default database name will be used during authentication.
3726
3727username string REQUIRED
3728The user name for the account that will be used for authenticating.
3729
3730password string REQUIRED
3731The Notes ID password. Note: This property is not returned in responses for security.
3732
3733notes supported properties:
3734
3735notesIDPassword string REQUIRED
3736The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
3737
3738oracle supported properties:
3739
3740sid string
3741The name of the database. If not specified, a default database name will be used during authentication.
3742
3743username string REQUIRED
3744The user name for the account that will be used for authenticating.
3745
3746password string REQUIRED
3747The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
3748
3749enumerateSids boolean
3750Boolean flag instructing the scan engine to attempt to enumerate SIDs from your environment. If set to true, set the Oracle Net Listener password in property oracleListenerPassword.
3751
3752oracleListenerPassword string
3753The Oracle Net Listener password. Used to enumerate SIDs from your environment.
3754
3755pop supported properties:
3756
3757username string REQUIRED
3758The user name for the account that will be used for authenticating.
3759
3760password string REQUIRED
3761The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
3762
3763postgresql supported properties:
3764
3765database string
3766The name of the database.
3767
3768username string REQUIRED
3769The user name for the account that will be used for authenticating.
3770
3771password string REQUIRED
3772The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
3773
3774remote-exec supported properties:
3775
3776username string REQUIRED
3777The user name for the account that will be used for authenticating.
3778
3779password string REQUIRED
3780The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
3781
3782snmp supported properties:
3783
3784communityName string REQUIRED
3785The community name that will be used for authenticating. Note: This property is not returned in responses for security.
3786
3787snmpv3 supported properties:
3788
3789authenticationType string REQUIRED
3790"no-authentication" "md5" "sha"
3791The authentication protocols available to use in SNMP v3.
3792
3793username string REQUIRED
3794The user name for the account that will be used for authenticating.
3795
3796password string
3797The password for the account that will be used for authenticating. Is required when the property authenticationType is set to valid value other than "no-authentication". Note: This property is not returned in responses for security.
3798
3799privacyType string
3800"no-privacy" "des" "aes-128" "aes-192" "aes-192-with-3-des-key-extension" "aes-256" "aes-265-with-3-des-key-extension"
3801The privacy protocols available to use in SNMP v3.
3802
3803privacyPassword string
3804The privacy password for the account that will be used for authenticating. Is required when the property authenticationType is set to valid value other than "no-authentication" and when the privacyType is set to a valid value other than code>"no-privacy". Note: This property is not returned in responses for security.
3805
3806ssh supported properties:
3807
3808username string REQUIRED
3809The user name for the account that will be used for authenticating.
3810
3811password string REQUIRED
3812The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
3813
3814permissionElevation string
3815"none" "sudo" "sudosu" "su" "pbrun" "privileged-exec"
3816Elevate scan engine permissions to administrative or root access, which is necessary to obtain certain data during the scan. Defaults to "none" if not specified.
3817
3818permissionElevationUsername string
3819The user name for the account with elevated permissions. This property must not be specified when the property permissionElevation is set to either "none" or "pbrun"; otherwise the property is required.
3820
3821password string
3822The password for the account with elevated permissions. This property must not be specified when the property permissionElevation is set to either "none" or "pbrun"; otherwise the property is required.Note: This property is not returned in responses for security.
3823
3824ssh-key supported properties:
3825
3826username string REQUIRED
3827The user name for the account that will be used for authenticating.
3828
3829privateKeyPassword string REQUIRED
3830The password for private key. Note: This property is not returned in responses for security.
3831
3832pemKey string REQUIRED
3833The PEM-format private key. Note: This property is not returned in responses for security.
3834
3835permissionElevation string
3836"none" "sudo" "sudosu" "su" "pbrun" "privileged-exec"
3837Elevate scan engine permissions to administrative or root access, which is necessary to obtain certain data during the scan. Defaults to "none" if not specified.
3838
3839permissionElevationUsername string
3840The user name for the account with elevated permissions. This property must not be specified when the property permissionElevation is set to either "none" or "pbrun"; otherwise the property is required.
3841
3842password string
3843The password for the account with elevated permissions. This property must not be specified when the property permissionElevation is set to either "none" or "pbrun"; otherwise the property is required.Note: This property is not returned in responses for security.
3844
3845sybase supported properties:
3846
3847database string
3848The name of the database. If not specified, a default database name will be used during authentication.
3849
3850useWindowsAuthentication boolean
3851Boolean flag signaling whether to connect to the database using Windows authentication. When set to true, Windows authentication is attempted; when set to false, SQL authentication is attempted.
3852
3853domain string
3854The address of the domain. This property cannot be specified unless property useWindowsAuthentication is set to true.
3855
3856username string REQUIRED
3857The user name for the account that will be used for authenticating.
3858
3859password string REQUIRED
3860The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
3861
3862telnet supported properties:
3863
3864username string REQUIRED
3865The user name for the account that will be used for authenticating.
3866
3867password string REQUIRED
3868The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
3869
3870 description	
3871string
3872The description of the credential.
3873
3874 hostRestriction	
3875string
3876The host name or IP address that you want to restrict the credentials to.
3877
3878 id	
3879integer <int32>
3880The identifier of the credential.
3881
3882 name	
3883string REQUIRED
3884The name of the credential.
3885
3886 portRestriction	
3887integer <int32> [ 1 .. 65535 ]
3888Further restricts the credential to attempt to authenticate on a specific port. The port can only be restricted if the property hostRestriction is specified.
3889
3890 siteAssignment	
3891string REQUIRED
3892Assigns the shared scan credential either to be available to all sites or to a specific list of sites. The following table describes each supported value:
3893
3894Value	Description
3895"all-sites"	The shared scan credential is assigned to all current and future sites.
3896"specific-sites"	The shared scan credential is assigned to zero sites by default. Administrators must explicitly assign sites to the shared credential.
3897Shared scan credentials assigned to a site can disabled within the site configuration, if needed.
3898
3899 sites	
3900 integer <int32> 
3901List of site identifiers. These sites are explicitly assigned access to the shared scan credential, allowing the site to use the credential for authentication during a scan. This property can only be set if the value of property siteAssignment is set to "specific-sites". When the property siteAssignment is set to "all-sites", this property will be null.
3902
3903RESPONSES
3904200 OK
3905
3906400 Bad Request
3907
3908401 Unauthorized
3909
3910500 Internal Server Error
3911
3912503 Service Unavailable
3913
3914REQUEST SAMPLES
3915JSON
3916A CIFS credential
3917A Microsoft SQL Server credential
3918An Oracle database credential
3919An SNMPv3 credential
3920An SSH credential
3921An SSH credential using sudo+su permission elevation
3922An SSH public key credential
3923Expand all Collapse all
3924{
3925"account": {
3926"authenticationType": "string",
3927"communityName": "string",
3928"database": "string",
3929"domain": "string",
3930"enumerateSids": true,
3931"notesIDPassword": "string",
3932"ntlmHash": "string",
3933"oracleListenerPassword": "string",
3934"password": "string",
3935"pemKey": "string",
3936"permissionElevation": "string",
3937"permissionElevationPassword": "string",
3938"permissionElevationUserName": "string",
3939"privacyPassword": "string",
3940"privacyType": "string",
3941"privateKeyPassword": "string",
3942"realm": "string",
3943"service": "string",
3944"sid": "string",
3945"useWindowsAuthentication": true,
3946"username": "string"
3947},
3948"description": "",
3949"hostRestriction": "",
3950"id": "",
3951"name": "",
3952"portRestriction": "",
3953"siteAssignment": "",
3954"sites": [
39550
3956]
3957}
3958
3959RESPONSE SAMPLES
3960200 OK
3961400 Bad Request
3962401 Unauthorized
3963500 Internal Server Error
3964503 Service Unavailable
3965Expand all Collapse all
3966{
3967"id": 1,
3968"links": [
3969{}
3970]
3971}
3972Shared Credentials
3973DELETE /api/3/shared_credentials
3974Server URL
3975
3976https://help.rapid7.com/insightvm/en-us/api/3/shared_credentials
3977
3978Deletes all shared credentials.
3979
3980RESPONSES
3981200 OK
3982
3983401 Unauthorized
3984
3985404 Not Found
3986
3987500 Internal Server Error
3988
3989503 Service Unavailable
3990
3991
3992RESPONSE SAMPLES
3993200 OK
3994401 Unauthorized
3995404 Not Found
3996500 Internal Server Error
3997503 Service Unavailable
3998Expand all Collapse all
3999{
4000"links": [
4001{}
4002]
4003}
4004Shared Credential
4005GET /api/3/shared_credentials/{id}
4006Server URL
4007
4008https://help.rapid7.com/insightvm/en-us/api/3/shared_credentials/{id}
4009
4010Retrieves the specified shared credential.
4011
4012PARAMETERS
4013Path Parameters
4014 id	
4015integer <int32>
4016The identifier of the credential.
4017
4018RESPONSES
4019200 OK
4020
4021401 Unauthorized
4022
4023404 Not Found
4024
4025500 Internal Server Error
4026
4027503 Service Unavailable
4028
4029
4030RESPONSE SAMPLES
4031200 OK
4032401 Unauthorized
4033404 Not Found
4034500 Internal Server Error
4035503 Service Unavailable
4036Expand all Collapse all
4037{
4038"account": {
4039"authenticationType": "string",
4040"communityName": "string",
4041"database": "string",
4042"domain": "string",
4043"enumerateSids": true,
4044"notesIDPassword": "string",
4045"ntlmHash": "string",
4046"oracleListenerPassword": "string",
4047"password": "string",
4048"pemKey": "string",
4049"permissionElevation": "string",
4050"permissionElevationPassword": "string",
4051"permissionElevationUserName": "string",
4052"privacyPassword": "string",
4053"privacyType": "string",
4054"privateKeyPassword": "string",
4055"realm": "string",
4056"service": "string",
4057"sid": "string",
4058"useWindowsAuthentication": true,
4059"username": "string"
4060},
4061"description": "",
4062"hostRestriction": "",
4063"id": "",
4064"name": "",
4065"portRestriction": "",
4066"siteAssignment": "",
4067"sites": [
40680
4069]
4070}
4071Shared Credential
4072PUT /api/3/shared_credentials/{id}
4073Server URL
4074
4075https://help.rapid7.com/insightvm/en-us/api/3/shared_credentials/{id}
4076
4077Updates the specified shared credential.
4078
4079PARAMETERS
4080Path Parameters
4081 id	
4082integer <int32>
4083The identifier of the credential.
4084
4085REQUEST BODY
4086The specification of the shared credential to update.
4087
4088
4089 account 	
4090 REQUIRED
4091Specify the type of service to authenticate as well as all of the information required by that service.
4092
4093service string
4094"as400" "cifs" "cifshash" "cvs" "db2" "ftp" "http" "ms-sql" "mysql" "notes" "oracle" "pop" "postgresql" "remote-exec" "snmp" "snmpv3" "ssh" "ssh-key" "sybase" "telnet"
4095The type of service to authenticate with.
4096The following are the names of the valid values for service:
4097
4098Value	Service
4099as400	IBM AS/400
4100cifs	Microsoft Windows/Samba (SMB/CIFS)
4101cifshash	Microsoft Windows/Samba LM/NTLM Hash (SMB/CIFS)
4102cvs	Concurrent Versioning System (CVS)
4103db2	DB2
4104ftp	File Transfer Protocol (FTP)
4105http	Web Site HTTP Authentication
4106ms-sql	Microsoft SQL Server
4107mysql	MySQL Server
4108notes	Lotus Notes/Domino
4109oracle	Oracle
4110pop	Post Office Protocol (POP)
4111postgresql	PostgreSQL
4112remote-exec	Remote Execution
4113snmp	Simple Network Management Protocol v1/v2c
4114snmpv3	Simple Network Management Protocol v3
4115ssh	Secure Shell (SSH)
4116ssh-key	Secure Shell (SSH) Public Key
4117sybase	Sybase SQL Server
4118telnet	Telnet
4119The following is a specification of supported credential properties for each type of service. These properties are to be specified within the account object.
4120
4121as400 supported properties:
4122
4123domain string
4124The address of the domain.
4125
4126username string REQUIRED
4127The user name for the account that will be used for authenticating.
4128
4129password string REQUIRED
4130The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
4131
4132cifs supported properties:
4133
4134domain string
4135The address of the domain.
4136
4137username string REQUIRED
4138The user name for the account that will be used for authenticating.
4139
4140password string REQUIRED
4141The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
4142
4143cifshash supported properties:
4144
4145domain string
4146The address of the domain.
4147
4148username string REQUIRED
4149The user name for the account that will be used for authenticating.
4150
4151ntlmHash string REQUIRED
4152The NTLM password hash. Note: This property is not returned in responses for security.
4153
4154cvs supported properties:
4155
4156domain string
4157The address of the domain.
4158
4159username string REQUIRED
4160The user name for the account that will be used for authenticating.
4161
4162password string REQUIRED
4163The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
4164
4165db2 supported properties:
4166
4167database string
4168The name of the database.
4169
4170username string REQUIRED
4171The user name for the account that will be used for authenticating.
4172
4173password string REQUIRED
4174The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
4175
4176ftp supported properties:
4177
4178username string REQUIRED
4179The user name for the account that will be used for authenticating.
4180
4181password string REQUIRED
4182The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
4183
4184http supported properties:
4185
4186realm string
4187The realm.
4188
4189username string REQUIRED
4190The user name for the account that will be used for authenticating.
4191
4192password string REQUIRED
4193The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
4194
4195ms-sql supported properties:
4196
4197database string
4198The name of the database. If not specified, a default database name will be used during authentication.
4199
4200useWindowsAuthentication boolean
4201Boolean flag signaling whether to connect to the database using Windows authentication. When set to true, Windows authentication is attempted; when set to false, SQL authentication is attempted.
4202
4203domain string
4204The address of the domain. This property cannot be specified unless property useWindowsAuthentication is set to true.
4205
4206username string REQUIRED
4207The user name for the account that will be used for authenticating.
4208
4209password string REQUIRED
4210The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
4211
4212mysql supported properties:
4213
4214database string
4215The name of the database. If not specified, a default database name will be used during authentication.
4216
4217username string REQUIRED
4218The user name for the account that will be used for authenticating.
4219
4220password string REQUIRED
4221The Notes ID password. Note: This property is not returned in responses for security.
4222
4223notes supported properties:
4224
4225notesIDPassword string REQUIRED
4226The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
4227
4228oracle supported properties:
4229
4230sid string
4231The name of the database. If not specified, a default database name will be used during authentication.
4232
4233username string REQUIRED
4234The user name for the account that will be used for authenticating.
4235
4236password string REQUIRED
4237The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
4238
4239enumerateSids boolean
4240Boolean flag instructing the scan engine to attempt to enumerate SIDs from your environment. If set to true, set the Oracle Net Listener password in property oracleListenerPassword.
4241
4242oracleListenerPassword string
4243The Oracle Net Listener password. Used to enumerate SIDs from your environment.
4244
4245pop supported properties:
4246
4247username string REQUIRED
4248The user name for the account that will be used for authenticating.
4249
4250password string REQUIRED
4251The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
4252
4253postgresql supported properties:
4254
4255database string
4256The name of the database.
4257
4258username string REQUIRED
4259The user name for the account that will be used for authenticating.
4260
4261password string REQUIRED
4262The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
4263
4264remote-exec supported properties:
4265
4266username string REQUIRED
4267The user name for the account that will be used for authenticating.
4268
4269password string REQUIRED
4270The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
4271
4272snmp supported properties:
4273
4274communityName string REQUIRED
4275The community name that will be used for authenticating. Note: This property is not returned in responses for security.
4276
4277snmpv3 supported properties:
4278
4279authenticationType string REQUIRED
4280"no-authentication" "md5" "sha"
4281The authentication protocols available to use in SNMP v3.
4282
4283username string REQUIRED
4284The user name for the account that will be used for authenticating.
4285
4286password string
4287The password for the account that will be used for authenticating. Is required when the property authenticationType is set to valid value other than "no-authentication". Note: This property is not returned in responses for security.
4288
4289privacyType string
4290"no-privacy" "des" "aes-128" "aes-192" "aes-192-with-3-des-key-extension" "aes-256" "aes-265-with-3-des-key-extension"
4291The privacy protocols available to use in SNMP v3.
4292
4293privacyPassword string
4294The privacy password for the account that will be used for authenticating. Is required when the property authenticationType is set to valid value other than "no-authentication" and when the privacyType is set to a valid value other than code>"no-privacy". Note: This property is not returned in responses for security.
4295
4296ssh supported properties:
4297
4298username string REQUIRED
4299The user name for the account that will be used for authenticating.
4300
4301password string REQUIRED
4302The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
4303
4304permissionElevation string
4305"none" "sudo" "sudosu" "su" "pbrun" "privileged-exec"
4306Elevate scan engine permissions to administrative or root access, which is necessary to obtain certain data during the scan. Defaults to "none" if not specified.
4307
4308permissionElevationUsername string
4309The user name for the account with elevated permissions. This property must not be specified when the property permissionElevation is set to either "none" or "pbrun"; otherwise the property is required.
4310
4311password string
4312The password for the account with elevated permissions. This property must not be specified when the property permissionElevation is set to either "none" or "pbrun"; otherwise the property is required.Note: This property is not returned in responses for security.
4313
4314ssh-key supported properties:
4315
4316username string REQUIRED
4317The user name for the account that will be used for authenticating.
4318
4319privateKeyPassword string REQUIRED
4320The password for private key. Note: This property is not returned in responses for security.
4321
4322pemKey string REQUIRED
4323The PEM-format private key. Note: This property is not returned in responses for security.
4324
4325permissionElevation string
4326"none" "sudo" "sudosu" "su" "pbrun" "privileged-exec"
4327Elevate scan engine permissions to administrative or root access, which is necessary to obtain certain data during the scan. Defaults to "none" if not specified.
4328
4329permissionElevationUsername string
4330The user name for the account with elevated permissions. This property must not be specified when the property permissionElevation is set to either "none" or "pbrun"; otherwise the property is required.
4331
4332password string
4333The password for the account with elevated permissions. This property must not be specified when the property permissionElevation is set to either "none" or "pbrun"; otherwise the property is required.Note: This property is not returned in responses for security.
4334
4335sybase supported properties:
4336
4337database string
4338The name of the database. If not specified, a default database name will be used during authentication.
4339
4340useWindowsAuthentication boolean
4341Boolean flag signaling whether to connect to the database using Windows authentication. When set to true, Windows authentication is attempted; when set to false, SQL authentication is attempted.
4342
4343domain string
4344The address of the domain. This property cannot be specified unless property useWindowsAuthentication is set to true.
4345
4346username string REQUIRED
4347The user name for the account that will be used for authenticating.
4348
4349password string REQUIRED
4350The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
4351
4352telnet supported properties:
4353
4354username string REQUIRED
4355The user name for the account that will be used for authenticating.
4356
4357password string REQUIRED
4358The password for the account that will be used for authenticating. Note: This property is not returned in responses for security.
4359
4360 description	
4361string
4362The description of the credential.
4363
4364 hostRestriction	
4365string
4366The host name or IP address that you want to restrict the credentials to.
4367
4368 id	
4369integer <int32>
4370The identifier of the credential.
4371
4372 name	
4373string REQUIRED
4374The name of the credential.
4375
4376 portRestriction	
4377integer <int32> [ 1 .. 65535 ]
4378Further restricts the credential to attempt to authenticate on a specific port. The port can only be restricted if the property hostRestriction is specified.
4379
4380 siteAssignment	
4381string REQUIRED
4382Assigns the shared scan credential either to be available to all sites or to a specific list of sites. The following table describes each supported value:
4383
4384Value	Description
4385"all-sites"	The shared scan credential is assigned to all current and future sites.
4386"specific-sites"	The shared scan credential is assigned to zero sites by default. Administrators must explicitly assign sites to the shared credential.
4387Shared scan credentials assigned to a site can disabled within the site configuration, if needed.
4388
4389 sites	
4390 integer <int32> 
4391List of site identifiers. These sites are explicitly assigned access to the shared scan credential, allowing the site to use the credential for authentication during a scan. This property can only be set if the value of property siteAssignment is set to "specific-sites". When the property siteAssignment is set to "all-sites", this property will be null.
4392
4393RESPONSES
4394200 OK
4395
4396400 Bad Request
4397
4398401 Unauthorized
4399
4400404 Not Found
4401
4402500 Internal Server Error
4403
4404503 Service Unavailable
4405
4406REQUEST SAMPLES
4407Expand all Collapse all
4408{
4409"account": {
4410"authenticationType": "string",
4411"communityName": "string",
4412"database": "string",
4413"domain": "string",
4414"enumerateSids": true,
4415"notesIDPassword": "string",
4416"ntlmHash": "string",
4417"oracleListenerPassword": "string",
4418"password": "string",
4419"pemKey": "string",
4420"permissionElevation": "string",
4421"permissionElevationPassword": "string",
4422"permissionElevationUserName": "string",
4423"privacyPassword": "string",
4424"privacyType": "string",
4425"privateKeyPassword": "string",
4426"realm": "string",
4427"service": "string",
4428"sid": "string",
4429"useWindowsAuthentication": true,
4430"username": "string"
4431},
4432"description": "",
4433"hostRestriction": "",
4434"id": "",
4435"name": "",
4436"portRestriction": "",
4437"siteAssignment": "",
4438"sites": [
44390
4440]
4441}
4442
4443RESPONSE SAMPLES
4444200 OK
4445400 Bad Request
4446401 Unauthorized
4447404 Not Found
4448500 Internal Server Error
4449503 Service Unavailable
4450Expand all Collapse all
4451{
4452"links": [
4453{}
4454]
4455}
4456Shared Credential
4457DELETE /api/3/shared_credentials/{id}
4458Server URL
4459
4460https://help.rapid7.com/insightvm/en-us/api/3/shared_credentials/{id}
4461
4462Deletes the specified shared scan credential.
4463
4464PARAMETERS
4465Path Parameters
4466 id	
4467integer <int32>
4468The identifier of the credential.
4469
4470RESPONSES
4471200 OK
4472
4473401 Unauthorized
4474
4475404 Not Found
4476
4477500 Internal Server Error
4478
4479503 Service Unavailable
4480
4481
4482RESPONSE SAMPLES
4483200 OK
4484401 Unauthorized
4485404 Not Found
4486500 Internal Server Error
4487503 Service Unavailable
4488Expand all Collapse all
4489{
4490"links": [
4491{}
4492]
4493}
4494POLICY
4495
4496Resources and operations for managing policies.
4497
4498Policies For Asset
4499GET /api/3/assets/{assetId}/policies
4500Server URL
4501
4502https://help.rapid7.com/insightvm/en-us/api/3/assets/{assetId}/policies
4503
4504Retrieves the list of policies with compliance results for the specified asset.
4505
4506PARAMETERS
4507Path Parameters
4508 assetId	
4509integer <int64>
4510The identifier of the asset.
4511
4512Query Parameters
4513 applicableOnly	
4514boolean
4515An optional boolean parameter indicating the policies retrieved should only include those with a policy compliance status of either a PASS of FAIL result. Default value is false, which will also include policies with a compliance status of NOT_APPLICABLE.
4516
4517 page	
4518integer <int32>
45190
4520The index of the page (zero-based) to retrieve.
4521
4522 size	
4523integer <int32>
452410
4525The number of records per page to retrieve.
4526
4527 sort	
4528Multiple query params of string
4529The 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.
4530
4531RESPONSES
4532200 OK
4533
4534401 Unauthorized
4535
4536404 Not Found
4537
4538500 Internal Server Error
4539
4540503 Service Unavailable
4541
4542
4543RESPONSE SAMPLES
4544200 OK
4545401 Unauthorized
4546404 Not Found
4547500 Internal Server Error
4548503 Service Unavailable
4549Expand all Collapse all
4550{
4551"links": [
4552{}
4553],
4554"page": {
4555"number": 6,
4556"size": 10,
4557"totalPages": 13,
4558"totalResources": 123
4559},
4560"resources": [
4561{}
4562]
4563}
4564Policy Rules or Groups Directly Under Policy For Asset
4565GET /api/3/assets/{assetId}/policies/{policyId}/children
4566Server URL
4567
4568https://help.rapid7.com/insightvm/en-us/api/3/assets/{assetId}/policies/{policyId}/children
4569
4570Retrieves a paged resource of either policy rules, or groups, that are defined directly underneath the specified policy with rule compliance results for the specified asset.
4571
4572PARAMETERS
4573Path Parameters
4574 assetId	
4575integer <int64>
4576The identifier of the asset.
4577
4578 policyId	
4579integer <int64>
4580The identifier of the policy
4581
4582RESPONSES
4583200 OK
4584
4585401 Unauthorized
4586
4587404 Not Found
4588
4589500 Internal Server Error
4590
4591503 Service Unavailable
4592
4593
4594RESPONSE SAMPLES
4595200 OK
4596401 Unauthorized
4597404 Not Found
4598500 Internal Server Error
4599503 Service Unavailable
4600Expand all Collapse all
4601{
4602"links": [
4603{}
4604],
4605"page": {
4606"number": 6,
4607"size": 10,
4608"totalPages": 13,
4609"totalResources": 123
4610},
4611"resources": [
4612{}
4613]
4614}
4615Policy Rules or Groups Directly Under Policy Group For Asset
4616GET /api/3/assets/{assetId}/policies/{policyId}/groups/{groupId}/children
4617Server URL
4618
4619https://help.rapid7.com/insightvm/en-us/api/3/assets/{assetId}/policies/{policyId}/groups/{groupId}/children
4620
4621Retrieves a paged resource of either policy rules, or groups, that are defined directly underneath the specified policy group with rule compliance results for the specified asset.
4622
4623PARAMETERS
4624Path Parameters
4625 assetId	
4626integer <int64>
4627The identifier of the asset.
4628
4629 policyId	
4630integer <int64>
4631The identifier of the policy
4632
4633 groupId	
4634integer <int64>
4635The identifier of the policy group.
4636
4637RESPONSES
4638200 OK
4639
4640401 Unauthorized
4641
4642404 Not Found
4643
4644500 Internal Server Error
4645
4646503 Service Unavailable
4647
4648
4649RESPONSE SAMPLES
4650200 OK
4651401 Unauthorized
4652404 Not Found
4653500 Internal Server Error
4654503 Service Unavailable
4655Expand all Collapse all
4656{
4657"links": [
4658{}
4659],
4660"page": {
4661"number": 6,
4662"size": 10,
4663"totalPages": 13,
4664"totalResources": 123
4665},
4666"resources": [
4667{}
4668]
4669}
4670Policy Rules Under Policy Group For Asset
4671GET /api/3/assets/{assetId}/policies/{policyId}/groups/{groupId}/rules
4672Server URL
4673
4674https://help.rapid7.com/insightvm/en-us/api/3/assets/{assetId}/policies/{policyId}/groups/{groupId}/rules
4675
4676Retrieves the list of policy rules defined directly, or indirectly, underneath the specified policy group and the compliance results for the specified asset.
4677
4678PARAMETERS
4679Path Parameters
4680 assetId	
4681integer <int64>
4682The identifier of the asset.
4683
4684 policyId	
4685integer <int64>
4686The identifier of the policy
4687
4688 groupId	
4689integer <int64>
4690The identifier of the policy group.
4691
4692Query Parameters
4693 page	
4694integer <int32>
46950
4696The index of the page (zero-based) to retrieve.
4697
4698 size	
4699integer <int32>
470010
4701The number of records per page to retrieve.
4702
4703 sort	
4704Multiple query params of string
4705The 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.
4706
4707RESPONSES
4708200 OK
4709
4710401 Unauthorized
4711
4712404 Not Found
4713
4714500 Internal Server Error
4715
4716503 Service Unavailable
4717
4718
4719RESPONSE SAMPLES
4720200 OK
4721401 Unauthorized
4722404 Not Found
4723500 Internal Server Error
4724503 Service Unavailable
4725Expand all Collapse all
4726{
4727"links": [
4728{}
4729],
4730"page": {
4731"number": 6,
4732"size": 10,
4733"totalPages": 13,
4734"totalResources": 123
4735},
4736"resources": [
4737{}
4738]
4739}
4740Policy Rules For Asset
4741GET /api/3/assets/{assetId}/policies/{policyId}/rules
4742Server URL
4743
4744https://help.rapid7.com/insightvm/en-us/api/3/assets/{assetId}/policies/{policyId}/rules
4745
4746Retrieves the list of policy rules with compliance results for the specified asset and policy.
4747
4748PARAMETERS
4749Path Parameters
4750 assetId	
4751integer <int64>
4752The identifier of the asset.
4753
4754 policyId	
4755integer <int64>
4756The identifier of the policy
4757
4758Query Parameters
4759 page	
4760integer <int32>
47610
4762The index of the page (zero-based) to retrieve.
4763
4764 size	
4765integer <int32>
476610
4767The number of records per page to retrieve.
4768
4769 sort	
4770Multiple query params of string
4771The 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.
4772
4773RESPONSES
4774200 OK
4775
4776401 Unauthorized
4777
4778404 Not Found
4779
4780500 Internal Server Error
4781
4782503 Service Unavailable
4783
4784
4785RESPONSE SAMPLES
4786200 OK
4787401 Unauthorized
4788404 Not Found
4789500 Internal Server Error
4790503 Service Unavailable
4791Expand all Collapse all
4792{
4793"links": [
4794{}
4795],
4796"page": {
4797"number": 6,
4798"size": 10,
4799"totalPages": 13,
4800"totalResources": 123
4801},
4802"resources": [
4803{}
4804]
4805}
4806Policies
4807GET /api/3/policies
4808Server URL
4809
4810https://help.rapid7.com/insightvm/en-us/api/3/policies
4811
4812Retrieves a paged resource of policies.
4813
4814PARAMETERS
4815Query Parameters
4816 filter	
4817string
4818Filters the retrieved policies with those whose titles that match the parameter.
4819
4820 scannedOnly	
4821boolean
4822Flag indicating the policies retrieved should only include those with Pass or Fail compliance results. The list of scanned policies is based on the user's list of accessible assets.
4823
4824 page	
4825integer <int32>
48260
4827The index of the page (zero-based) to retrieve.
4828
4829 size	
4830integer <int32>
483110
4832The number of records per page to retrieve.
4833
4834 sort	
4835Multiple query params of string
4836The 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.
4837
4838RESPONSES
4839200 OK
4840
4841401 Unauthorized
4842
4843404 Not Found
4844
4845500 Internal Server Error
4846
4847503 Service Unavailable
4848
4849
4850RESPONSE SAMPLES
4851200 OK
4852401 Unauthorized
4853404 Not Found
4854500 Internal Server Error
4855503 Service Unavailable
4856Expand all Collapse all
4857{
4858"links": [
4859{}
4860],
4861"page": {
4862"number": 6,
4863"size": 10,
4864"totalPages": 13,
4865"totalResources": 123
4866},
4867"resources": [
4868{}
4869]
4870}
4871Policy Rules or Groups Directly Under Policy
4872GET /api/3/policies/{id}/children
4873Server URL
4874
4875https://help.rapid7.com/insightvm/en-us/api/3/policies/{id}/children
4876
4877Retrieves a paged resource of either policy rules, or groups, that are defined directly underneath the specified policy.
4878
4879PARAMETERS
4880Path Parameters
4881 id	
4882integer <int64>
4883The identifier of the policy
4884
4885RESPONSES
4886200 OK
4887
4888401 Unauthorized
4889
4890404 Not Found
4891
4892500 Internal Server Error
4893
4894503 Service Unavailable
4895
4896
4897RESPONSE SAMPLES
4898200 OK
4899401 Unauthorized
4900404 Not Found
4901500 Internal Server Error
4902503 Service Unavailable
4903Expand all Collapse all
4904{
4905"links": [
4906{}
4907],
4908"page": {
4909"number": 6,
4910"size": 10,
4911"totalPages": 13,
4912"totalResources": 123
4913},
4914"resources": [
4915{}
4916]
4917}
4918Policy
4919GET /api/3/policies/{policyId}
4920Server URL
4921
4922https://help.rapid7.com/insightvm/en-us/api/3/policies/{policyId}
4923
4924Retrieves the specified policy.
4925
4926PARAMETERS
4927Path Parameters
4928 policyId	
4929integer <int64>
4930The identifier of the policy
4931
4932RESPONSES
4933200 OK
4934
4935401 Unauthorized
4936
4937404 Not Found
4938
4939500 Internal Server Error
4940
4941503 Service Unavailable
4942
4943
4944RESPONSE SAMPLES
4945200 OK
4946401 Unauthorized
4947404 Not Found
4948500 Internal Server Error
4949503 Service Unavailable
4950Expand all Collapse all
4951{
4952"enabled": [
49530
4954],
4955"links": [
4956{}
4957],
4958"recursiveWindowsFSSearch": false,
4959"storeSCAP": false
4960}
4961Policy Asset Results
4962GET /api/3/policies/{policyId}/assets
4963Server URL
4964
4965https://help.rapid7.com/insightvm/en-us/api/3/policies/{policyId}/assets
4966
4967Retrieves asset resources with rule compliance results for the specified policy.
4968
4969PARAMETERS
4970Path Parameters
4971 policyId	
4972integer <int64>
4973The identifier of the policy
4974
4975Query Parameters
4976 applicableOnly	
4977boolean
4978An optional boolean parameter indicating the assets retrieved should only include those with rule results of either PASS or FAIL. Default value is false, which will also include assets with a compliance status of NOT_APPLICABLE.
4979
4980 page	
4981integer <int32>
49820
4983The index of the page (zero-based) to retrieve.
4984
4985 size	
4986integer <int32>
498710
4988The number of records per page to retrieve.
4989
4990 sort	
4991Multiple query params of string
4992The 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.
4993
4994RESPONSES
4995200 OK
4996
4997401 Unauthorized
4998
4999404 Not Found
5000
5001500 Internal Server Error
5002
5003503 Service Unavailable
5004
5005
5006RESPONSE SAMPLES
5007200 OK
5008401 Unauthorized
5009404 Not Found
5010500 Internal Server Error
5011503 Service Unavailable
5012Expand all Collapse all
5013{
5014"links": [
5015{}
5016],
5017"page": {
5018"number": 6,
5019"size": 10,
5020"totalPages": 13,
5021"totalResources": 123
5022},
5023"resources": [
5024{}
5025]
5026}
5027Policy Asset Result
5028GET /api/3/policies/{policyId}/assets/{assetId}
5029Server URL
5030
5031https://help.rapid7.com/insightvm/en-us/api/3/policies/{policyId}/assets/{assetId}
5032
5033Retrieves an asset resource with rule compliance results for the specified asset and policy.
5034
5035PARAMETERS
5036Path Parameters
5037 policyId	
5038integer <int64>
5039The identifier of the policy
5040
5041 assetId	
5042integer <int64>
5043The identifier of the asset.
5044
5045RESPONSES
5046200 OK
5047
5048401 Unauthorized
5049
5050404 Not Found
5051
5052500 Internal Server Error
5053
5054503 Service Unavailable
5055
5056
5057RESPONSE SAMPLES
5058200 OK
5059401 Unauthorized
5060404 Not Found
5061500 Internal Server Error
5062503 Service Unavailable
5063Expand all Collapse all
5064{
5065"hostname": "",
5066"id": "",
5067"ip": "",
5068"links": [
5069{}
5070],
5071"os": {
5072"architecture": "x86",
5073"configurations": [],
5074"cpe": {},
5075"description": "Microsoft Windows Server 2008 Enterprise Edition SP1",
5076"family": "Windows",
5077"id": 35,
5078"product": "Windows Server 2008 Enterprise Edition",
5079"systemName": "Microsoft Windows",
5080"type": "Workstation",
5081"vendor": "Microsoft",
5082"version": "SP1"
5083},
5084"status": ""
5085}
5086Policy Groups
5087GET /api/3/policies/{policyId}/groups
5088Server URL
5089
5090https://help.rapid7.com/insightvm/en-us/api/3/policies/{policyId}/groups
5091
5092Retrieves a paged resource of policy groups for the specified policy.
5093
5094PARAMETERS
5095Path Parameters
5096 policyId	
5097integer <int64>
5098The identifier of the policy
5099
5100Query Parameters
5101 page	
5102integer <int32>
51030
5104The index of the page (zero-based) to retrieve.
5105
5106 size	
5107integer <int32>
510810
5109The number of records per page to retrieve.
5110
5111 sort	
5112Multiple query params of string
5113The 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.
5114
5115RESPONSES
5116200 OK
5117
5118401 Unauthorized
5119
5120404 Not Found
5121
5122500 Internal Server Error
5123
5124503 Service Unavailable
5125
5126
5127RESPONSE SAMPLES
5128200 OK
5129401 Unauthorized
5130404 Not Found
5131500 Internal Server Error
5132503 Service Unavailable
5133Expand all Collapse all
5134{
5135"links": [
5136{}
5137],
5138"page": {
5139"number": 6,
5140"size": 10,
5141"totalPages": 13,
5142"totalResources": 123
5143},
5144"resources": [
5145{}
5146]
5147}
5148Policy Group
5149GET /api/3/policies/{policyId}/groups/{groupId}
5150Server URL
5151
5152https://help.rapid7.com/insightvm/en-us/api/3/policies/{policyId}/groups/{groupId}
5153
5154Retrieves the specified policy group.
5155
5156PARAMETERS
5157Path Parameters
5158 policyId	
5159integer <int64>
5160The identifier of the policy
5161
5162 groupId	
5163integer <int64>
5164The identifier of the policy group.
5165
5166RESPONSES
5167200 OK
5168
5169401 Unauthorized
5170
5171404 Not Found
5172
5173500 Internal Server Error
5174
5175503 Service Unavailable
5176
5177
5178RESPONSE SAMPLES
5179200 OK
5180401 Unauthorized
5181404 Not Found
5182500 Internal Server Error
5183503 Service Unavailable
5184Expand all Collapse all
5185{
5186"assets": {
5187"links": [],
5188"total": "",
5189"totalFailed": "",
5190"totalNotApplicable": "",
5191"totalPassed": 0
5192},
5193"benchmark": {
5194"links": [],
5195"name": "",
5196"title": "",
5197"version": ""
5198},
5199"description": "",
5200"id": "",
5201"links": [
5202{}
5203],
5204"name": "",
5205"policy": {
5206"links": [],
5207"name": "",
5208"title": "",
5209"version": ""
5210},
5211"scope": "",
5212"status": "",
5213"surrogateId": "",
5214"title": ""
5215}
5216Assets Compliance For Policy Rules Under Policy Group
5217GET /api/3/policies/{policyId}/groups/{groupId}/assets
5218Server URL
5219
5220https://help.rapid7.com/insightvm/en-us/api/3/policies/{policyId}/groups/{groupId}/assets
5221
5222Retrieves asset resources with rule compliance status against all rules under the specified policy group.
5223
5224PARAMETERS
5225Path Parameters
5226 policyId	
5227integer <int64>
5228The identifier of the policy
5229
5230 groupId	
5231integer <int64>
5232The identifier of the policy group.
5233
5234Query Parameters
5235 applicableOnly	
5236boolean
5237An optional boolean parameter indicating the assets retrieved should only include those with rule results of either PASS or FAIL. Default value is false, which will also include assets with a compliance status of NOT_APPLICABLE.
5238
5239 page	
5240integer <int32>
52410
5242The index of the page (zero-based) to retrieve.
5243
5244 size	
5245integer <int32>
524610
5247The number of records per page to retrieve.
5248
5249 sort	
5250Multiple query params of string
5251The 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.
5252
5253RESPONSES
5254200 OK
5255
5256401 Unauthorized
5257
5258404 Not Found
5259
5260500 Internal Server Error
5261
5262503 Service Unavailable
5263
5264
5265RESPONSE SAMPLES
5266200 OK
5267401 Unauthorized
5268404 Not Found
5269500 Internal Server Error
5270503 Service Unavailable
5271Expand all Collapse all
5272{
5273"links": [
5274{}
5275],
5276"page": {
5277"number": 6,
5278"size": 10,
5279"totalPages": 13,
5280"totalResources": 123
5281},
5282"resources": [
5283{}
5284]
5285}
5286Asset Compliance For Policy Rules Under Policy Group
5287GET /api/3/policies/{policyId}/groups/{groupId}/assets/{assetId}
5288Server URL
5289
5290https://help.rapid7.com/insightvm/en-us/api/3/policies/{policyId}/groups/{groupId}/assets/{assetId}
5291
5292Retrieves an asset resource with rule compliance status against all rules under the specified policy group.
5293
5294PARAMETERS
5295Path Parameters
5296 policyId	
5297integer <int64>
5298The identifier of the policy
5299
5300 groupId	
5301integer <int64>
5302The identifier of the policy group.
5303
5304 assetId	
5305integer <int64>
5306The identifier of the asset.
5307
5308RESPONSES
5309200 OK
5310
5311401 Unauthorized
5312
5313404 Not Found
5314
5315500 Internal Server Error
5316
5317503 Service Unavailable
5318
5319
5320RESPONSE SAMPLES
5321200 OK
5322401 Unauthorized
5323404 Not Found
5324500 Internal Server Error
5325503 Service Unavailable
5326Expand all Collapse all
5327{
5328"hostname": "",
5329"id": "",
5330"ip": "",
5331"links": [
5332{}
5333],
5334"os": {
5335"architecture": "x86",
5336"configurations": [],
5337"cpe": {},
5338"description": "Microsoft Windows Server 2008 Enterprise Edition SP1",
5339"family": "Windows",
5340"id": 35,
5341"product": "Windows Server 2008 Enterprise Edition",
5342"systemName": "Microsoft Windows",
5343"type": "Workstation",
5344"vendor": "Microsoft",
5345"version": "SP1"
5346},
5347"status": ""
5348}
5349Policy Rules or Groups Directly Under Policy Group
5350GET /api/3/policies/{policyId}/groups/{groupId}/children
5351Server URL
5352
5353https://help.rapid7.com/insightvm/en-us/api/3/policies/{policyId}/groups/{groupId}/children
5354
5355Retrieves a paged resource of either policy rules, or groups, that are defined directly underneath the specified policy group.
5356
5357PARAMETERS
5358Path Parameters
5359 policyId	
5360integer <int64>
5361The identifier of the policy
5362
5363 groupId	
5364integer <int64>
5365The identifier of the policy group.
5366
5367RESPONSES
5368200 OK
5369
5370401 Unauthorized
5371
5372404 Not Found
5373
5374500 Internal Server Error
5375
5376503 Service Unavailable
5377
5378
5379RESPONSE SAMPLES
5380200 OK
5381401 Unauthorized
5382404 Not Found
5383500 Internal Server Error
5384503 Service Unavailable
5385Expand all Collapse all
5386{
5387"links": [
5388{}
5389],
5390"page": {
5391"number": 6,
5392"size": 10,
5393"totalPages": 13,
5394"totalResources": 123
5395},
5396"resources": [
5397{}
5398]
5399}
5400Policy Rules Under Policy Group
5401GET /api/3/policies/{policyId}/groups/{groupId}/rules
5402Server URL
5403
5404https://help.rapid7.com/insightvm/en-us/api/3/policies/{policyId}/groups/{groupId}/rules
5405
5406Retrieves the list of policy rules defined directly, or indirectly, underneath the specified policy group.
5407
5408PARAMETERS
5409Path Parameters
5410 policyId	
5411integer <int64>
5412The identifier of the policy
5413
5414 groupId	
5415integer <int64>
5416The identifier of the policy group.
5417
5418Query Parameters
5419 page	
5420integer <int32>
54210
5422The index of the page (zero-based) to retrieve.
5423
5424 size	
5425integer <int32>
542610
5427The number of records per page to retrieve.
5428
5429 sort	
5430Multiple query params of string
5431The 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.
5432
5433RESPONSES
5434200 OK
5435
5436401 Unauthorized
5437
5438404 Not Found
5439
5440500 Internal Server Error
5441
5442503 Service Unavailable
5443
5444
5445RESPONSE SAMPLES
5446200 OK
5447401 Unauthorized
5448404 Not Found
5449500 Internal Server Error
5450503 Service Unavailable
5451Expand all Collapse all
5452{
5453"links": [
5454{}
5455],
5456"page": {
5457"number": 6,
5458"size": 10,
5459"totalPages": 13,
5460"totalResources": 123
5461},
5462"resources": [
5463{}
5464]
5465}
5466Policy Rules
5467GET /api/3/policies/{policyId}/rules
5468Server URL
5469
5470https://help.rapid7.com/insightvm/en-us/api/3/policies/{policyId}/rules
5471
5472Retrieves a paged resource of policy rules for the specified policy.
5473
5474PARAMETERS
5475Path Parameters
5476 policyId	
5477integer <int64>
5478The identifier of the policy
5479
5480Query Parameters
5481 page	
5482integer <int32>
54830
5484The index of the page (zero-based) to retrieve.
5485
5486 size	
5487integer <int32>
548810
5489The number of records per page to retrieve.
5490
5491 sort	
5492Multiple query params of string
5493The 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.
5494
5495RESPONSES
5496200 OK
5497
5498401 Unauthorized
5499
5500404 Not Found
5501
5502500 Internal Server Error
5503
5504503 Service Unavailable
5505
5506
5507RESPONSE SAMPLES
5508200 OK
5509401 Unauthorized
5510404 Not Found
5511500 Internal Server Error
5512503 Service Unavailable
5513Expand all Collapse all
5514{
5515"links": [
5516{}
5517],
5518"page": {
5519"number": 6,
5520"size": 10,
5521"totalPages": 13,
5522"totalResources": 123
5523},
5524"resources": [
5525{}
5526]
5527}
5528Disabled Policy Rules
5529GET /api/3/policies/{policyId}/rules/disabled
5530Server URL
5531
5532https://help.rapid7.com/insightvm/en-us/api/3/policies/{policyId}/rules/disabled
5533
5534Retrieves a paged resource of disabled policy rules for the specified policy.
5535
5536PARAMETERS
5537Path Parameters
5538 policyId	
5539integer <int64>
5540The identifier of the policy
5541
5542Query Parameters
5543 page	
5544integer <int32>
55450
5546The index of the page (zero-based) to retrieve.
5547
5548 size	
5549integer <int32>
555010
5551The number of records per page to retrieve.
5552
5553 sort	
5554Multiple query params of string
5555The 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.
5556
5557RESPONSES
5558200 OK
5559
5560401 Unauthorized
5561
5562404 Not Found
5563
5564500 Internal Server Error
5565
5566503 Service Unavailable
5567
5568
5569RESPONSE SAMPLES
5570200 OK
5571401 Unauthorized
5572404 Not Found
5573500 Internal Server Error
5574503 Service Unavailable
5575Expand all Collapse all
5576{
5577"links": [
5578{}
5579],
5580"page": {
5581"number": 6,
5582"size": 10,
5583"totalPages": 13,
5584"totalResources": 123
5585},
5586"resources": [
5587{}
5588]
5589}
5590Policy Rule
5591GET /api/3/policies/{policyId}/rules/{ruleId}
5592Server URL
5593
5594https://help.rapid7.com/insightvm/en-us/api/3/policies/{policyId}/rules/{ruleId}
5595
5596Retrieves the specified policy rule.
5597
5598PARAMETERS
5599Path Parameters
5600 policyId	
5601integer <int64>
5602The identifier of the policy
5603
5604 ruleId	
5605integer <int64>
5606The identifier of the policy rule.
5607
5608RESPONSES
5609200 OK
5610
5611401 Unauthorized
5612
5613404 Not Found
5614
5615500 Internal Server Error
5616
5617503 Service Unavailable
5618
5619
5620RESPONSE SAMPLES
5621200 OK
5622401 Unauthorized
5623404 Not Found
5624500 Internal Server Error
5625503 Service Unavailable
5626Expand all Collapse all
5627{
5628"assets": {
5629"links": [],
5630"total": "",
5631"totalFailed": "",
5632"totalNotApplicable": "",
5633"totalPassed": 0
5634},
5635"benchmark": {
5636"links": [],
5637"name": "",
5638"title": "",
5639"version": ""
5640},
5641"description": "",
5642"id": "",
5643"isCustom": false,
5644"links": [
5645{}
5646],
5647"name": "",
5648"role": "",
5649"scope": "",
5650"status": "",
5651"surrogateId": "",
5652"title": ""
5653}
5654Assets Compliance For Policy Rule
5655GET /api/3/policies/{policyId}/rules/{ruleId}/assets
5656Server URL
5657
5658https://help.rapid7.com/insightvm/en-us/api/3/policies/{policyId}/rules/{ruleId}/assets
5659
5660Retrieves asset resources with rule compliance results for the specified policy policy rule.
5661
5662PARAMETERS
5663Path Parameters
5664 policyId	
5665integer <int64>
5666The identifier of the policy
5667
5668 ruleId	
5669integer <int64>
5670The identifier of the policy rule.
5671
5672Query Parameters
5673 applicableOnly	
5674boolean
5675An optional boolean parameter indicating the assets retrieved should only include those with rule results of either PASS or FAIL. Default value is false, which will also include assets with a compliance status of NOT_APPLICABLE.
5676
5677 page	
5678integer <int32>
56790
5680The index of the page (zero-based) to retrieve.
5681
5682 size	
5683integer <int32>
568410
5685The number of records per page to retrieve.
5686
5687 sort	
5688Multiple query params of string
5689The 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.
5690
5691RESPONSES
5692200 OK
5693
5694401 Unauthorized
5695
5696404 Not Found
5697
5698500 Internal Server Error
5699
5700503 Service Unavailable
5701
5702
5703RESPONSE SAMPLES
5704200 OK
5705401 Unauthorized
5706404 Not Found
5707500 Internal Server Error
5708503 Service Unavailable
5709Expand all Collapse all
5710{
5711"links": [
5712{}
5713],
5714"page": {
5715"number": 6,
5716"size": 10,
5717"totalPages": 13,
5718"totalResources": 123
5719},
5720"resources": [
5721{}
5722]
5723}
5724Asset Compliance For Policy Rule
5725GET /api/3/policies/{policyId}/rules/{ruleId}/assets/{assetId}
5726Server URL
5727
5728https://help.rapid7.com/insightvm/en-us/api/3/policies/{policyId}/rules/{ruleId}/assets/{assetId}
5729
5730Retrieves an asset resource with rule compliance results for the specified policy policy rule.
5731
5732PARAMETERS
5733Path Parameters
5734 policyId	
5735integer <int64>
5736The identifier of the policy
5737
5738 ruleId	
5739integer <int64>
5740The identifier of the policy rule.
5741
5742 assetId	
5743integer <int64>
5744The identifier of the asset.
5745
5746RESPONSES
5747200 OK
5748
5749401 Unauthorized
5750
5751404 Not Found
5752
5753500 Internal Server Error
5754
5755503 Service Unavailable
5756
5757
5758RESPONSE SAMPLES
5759200 OK
5760401 Unauthorized
5761404 Not Found
5762500 Internal Server Error
5763503 Service Unavailable
5764Expand all Collapse all
5765{
5766"hostname": "",
5767"id": "",
5768"ip": "",
5769"links": [
5770{}
5771],
5772"os": {
5773"architecture": "x86",
5774"configurations": [],
5775"cpe": {},
5776"description": "Microsoft Windows Server 2008 Enterprise Edition SP1",
5777"family": "Windows",
5778"id": 35,
5779"product": "Windows Server 2008 Enterprise Edition",
5780"systemName": "Microsoft Windows",
5781"type": "Workstation",
5782"vendor": "Microsoft",
5783"version": "SP1"
5784},
5785"status": ""
5786}
5787Policy Rule Proof For Asset
5788GET /api/3/policies/{policyId}/rules/{ruleId}/assets/{assetId}/proof
5789Server URL
5790
5791https://help.rapid7.com/insightvm/en-us/api/3/policies/{policyId}/rules/{ruleId}/assets/{assetId}/proof
5792
5793Retrieves the policy rule proof captured during evaluation against the specified asset.
5794
5795PARAMETERS
5796Path Parameters
5797 policyId	
5798integer <int64>
5799The identifier of the policy
5800
5801 ruleId	
5802integer <int64>
5803The identifier of the policy rule.
5804
5805 assetId	
5806integer <int64>
5807The identifier of the asset.
5808
5809RESPONSES
5810200 OK
5811
5812401 Unauthorized
5813
5814404 Not Found
5815
5816500 Internal Server Error
5817
5818503 Service Unavailable
5819
5820
5821RESPONSE SAMPLES
5822200 OK
5823401 Unauthorized
5824404 Not Found
5825500 Internal Server Error
5826503 Service Unavailable
5827 "string"
5828Policy Rule Controls
5829GET /api/3/policies/{policyId}/rules/{ruleId}/controls
5830Server URL
5831
5832https://help.rapid7.com/insightvm/en-us/api/3/policies/{policyId}/rules/{ruleId}/controls
5833
5834Retrieves all NIST SP 800-53 controls mappings for each CCE within the specified policy rule.
5835
5836PARAMETERS
5837Path Parameters
5838 policyId	
5839integer <int64>
5840The identifier of the policy
5841
5842 ruleId	
5843integer <int64>
5844The identifier of the policy rule.
5845
5846Query Parameters
5847 page	
5848integer <int32>
58490
5850The index of the page (zero-based) to retrieve.
5851
5852 size	
5853integer <int32>
585410
5855The number of records per page to retrieve.
5856
5857 sort	
5858Multiple query params of string
5859The 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.
5860
5861RESPONSES
5862200 OK
5863
5864401 Unauthorized
5865
5866404 Not Found
5867
5868500 Internal Server Error
5869
5870503 Service Unavailable
5871
5872
5873RESPONSE SAMPLES
5874200 OK
5875401 Unauthorized
5876404 Not Found
5877500 Internal Server Error
5878503 Service Unavailable
5879Expand all Collapse all
5880{
5881"links": [
5882{}
5883],
5884"page": {
5885"number": 6,
5886"size": 10,
5887"totalPages": 13,
5888"totalResources": 123
5889},
5890"resources": [
5891{}
5892]
5893}
5894Policy Rule Rationale
5895GET /api/3/policies/{policyId}/rules/{ruleId}/rationale
5896Server URL
5897
5898https://help.rapid7.com/insightvm/en-us/api/3/policies/{policyId}/rules/{ruleId}/rationale
5899
5900Retrieves the policy rule rationale for the specified policy.
5901
5902PARAMETERS
5903Path Parameters
5904 policyId	
5905integer <int64>
5906The identifier of the policy
5907
5908 ruleId	
5909integer <int64>
5910The identifier of the policy rule.
5911
5912RESPONSES
5913200 OK
5914
5915401 Unauthorized
5916
5917404 Not Found
5918
5919500 Internal Server Error
5920
5921503 Service Unavailable
5922
5923
5924RESPONSE SAMPLES
5925200 OK
5926401 Unauthorized
5927404 Not Found
5928500 Internal Server Error
5929503 Service Unavailable
5930 "string"
5931Policy Rule Remediation
5932GET /api/3/policies/{policyId}/rules/{ruleId}/remediation
5933Server URL
5934
5935https://help.rapid7.com/insightvm/en-us/api/3/policies/{policyId}/rules/{ruleId}/remediation
5936
5937Retrieves the policy rule remediation for the specified policy.
5938
5939PARAMETERS
5940Path Parameters
5941 policyId	
5942integer <int64>
5943The identifier of the policy
5944
5945 ruleId	
5946integer <int64>
5947The identifier of the policy rule.
5948
5949RESPONSES
5950200 OK
5951
5952401 Unauthorized
5953
5954404 Not Found
5955
5956500 Internal Server Error
5957
5958503 Service Unavailable
5959
5960
5961RESPONSE SAMPLES
5962200 OK
5963401 Unauthorized
5964404 Not Found
5965500 Internal Server Error
5966503 Service Unavailable
5967 "string"
5968Policy Compliance Summaries
5969GET /api/3/policy/summary
5970Server URL
5971
5972https://help.rapid7.com/insightvm/en-us/api/3/policy/summary
5973
5974Retrieves a compliance summary of all policies.
5975
5976RESPONSES
5977200 OK
5978
5979401 Unauthorized
5980
5981404 Not Found
5982
5983500 Internal Server Error
5984
5985503 Service Unavailable
5986
5987
5988RESPONSE SAMPLES
5989200 OK
5990401 Unauthorized
5991404 Not Found
5992500 Internal Server Error
5993503 Service Unavailable
5994Expand all Collapse all
5995{
5996"decreasedCompliance": "",
5997"increasedCompliance": "",
5998"links": [
5999{}
6000],
6001"numberOfPolicies": "",
6002"overallCompliance": "",
6003"scannedPolicies": ""
6004}
6005POLICY OVERRIDE
6006
6007Policy Override Resource Controller
6008
6009Asset Policy Overrides
6010GET /api/3/assets/{id}/policy_overrides
6011Server URL
6012
6013https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/policy_overrides
6014
6015Retrieves policy overrides defined on policy rules for the specified asset.
6016
6017PARAMETERS
6018Path Parameters
6019 id	
6020integer <int64>
6021The identifier of the asset.
6022
6023RESPONSES
6024200 OK
6025
6026401 Unauthorized
6027
6028404 Not Found
6029
6030500 Internal Server Error
6031
6032503 Service Unavailable
6033
6034
6035RESPONSE SAMPLES
6036200 OK
6037401 Unauthorized
6038404 Not Found
6039500 Internal Server Error
6040503 Service Unavailable
6041Expand all Collapse all
6042{
6043"links": [
6044{}
6045],
6046"resources": [
6047{}
6048]
6049}
6050Policy Overrides
6051GET /api/3/policy_overrides
6052Server URL
6053
6054https://help.rapid7.com/insightvm/en-us/api/3/policy_overrides
6055
6056Retrieves policy overrides defined on policy rules.
6057
6058PARAMETERS
6059Query Parameters
6060 page	
6061integer <int32>
60620
6063The index of the page (zero-based) to retrieve.
6064
6065 size	
6066integer <int32>
606710
6068The number of records per page to retrieve.
6069
6070 sort	
6071Multiple query params of string
6072The 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.
6073
6074RESPONSES
6075200 OK
6076
6077401 Unauthorized
6078
6079404 Not Found
6080
6081500 Internal Server Error
6082
6083503 Service Unavailable
6084
6085
6086RESPONSE SAMPLES
6087200 OK
6088401 Unauthorized
6089404 Not Found
6090500 Internal Server Error
6091503 Service Unavailable
6092Expand all Collapse all
6093{
6094"links": [
6095{}
6096],
6097"page": {
6098"number": 6,
6099"size": 10,
6100"totalPages": 13,
6101"totalResources": 123
6102},
6103"resources": [
6104{}
6105]
6106}
6107Policy Overrides
6108POST /api/3/policy_overrides
6109Server URL
6110
6111https://help.rapid7.com/insightvm/en-us/api/3/policy_overrides
6112
6113Submit a policy override. The policy override can be submitted or it can be submitted and approved in a single request.
6114
6115REQUEST BODY
6116The specification of a policy override. Allows users to override the compliance result of a policy rule.
6117
6118
6119 expires	
6120string
6121The date the policy override is set to expire. Date is represented in ISO 8601 format.
6122
6123 links 	
6124 review 	
6125Details regarding the review and/or approval of the policy override.
6126
6127 scope 	
6128 REQUIRED
6129The scope of the policy override. Indicates which assets' policy compliance results are to be affected by the override.
6130
6131 state	
6132string REQUIRED
6133The state of the policy override. Can be one of the following values:
6134
6135Value	Description	Affects Compliance Results
6136"deleted"	The policy override has been deleted.	
6137"expired"	The policy override had an expiration date and it has expired.	
6138"approved"	The policy override was submitted and approved.	✓
6139"rejected"	The policy override was rejected by the reviewer.	
6140"under-review"	The policy override was submitted but not yet approved or rejected by the reviewer.	
6141 submit 	
6142 REQUIRED
6143Details regarding the submission of the policy override.
6144
6145RESPONSES
6146200 OK
6147
6148400 Bad Request
6149
6150401 Unauthorized
6151
6152500 Internal Server Error
6153
6154503 Service Unavailable
6155
6156REQUEST SAMPLES
6157Expand all Collapse all
6158{
6159"expires": "",
6160"links": [
6161{}
6162],
6163"review": {
6164"links": []
6165},
6166"scope": {
6167"asset": "",
6168"links": [],
6169"newResult": "",
6170"rule": "",
6171"type": ""
6172},
6173"state": "",
6174"submit": {
6175"comment": "",
6176"links": []
6177}
6178}
6179
6180RESPONSE SAMPLES
6181200 OK
6182400 Bad Request
6183401 Unauthorized
6184500 Internal Server Error
6185503 Service Unavailable
6186Expand all Collapse all
6187{
6188"id": 1,
6189"links": [
6190{}
6191]
6192}
6193Policy Override
6194GET /api/3/policy_overrides/{id}
6195Server URL
6196
6197https://help.rapid7.com/insightvm/en-us/api/3/policy_overrides/{id}
6198
6199Retrieve the specified policy override.
6200
6201PARAMETERS
6202Path Parameters
6203 id	
6204integer <int64>
6205The identifier of the policy override.
6206
6207RESPONSES
6208200 OK
6209
6210401 Unauthorized
6211
6212404 Not Found
6213
6214500 Internal Server Error
6215
6216503 Service Unavailable
6217
6218
6219RESPONSE SAMPLES
6220200 OK
6221401 Unauthorized
6222404 Not Found
6223500 Internal Server Error
6224503 Service Unavailable
6225Expand all Collapse all
6226{
6227"expires": "",
6228"id": "",
6229"links": [
6230{}
6231],
6232"review": {
6233"comment": "",
6234"date": "",
6235"links": [],
6236"name": "",
6237"user": ""
6238},
6239"scope": {
6240"asset": "",
6241"links": [],
6242"newResult": "",
6243"originalResult": "",
6244"rule": "",
6245"type": ""
6246},
6247"state": "",
6248"submit": {
6249"comment": "",
6250"date": "",
6251"links": [],
6252"name": "",
6253"user": ""
6254}
6255}
6256Policy Override
6257DELETE /api/3/policy_overrides/{id}
6258Server URL
6259
6260https://help.rapid7.com/insightvm/en-us/api/3/policy_overrides/{id}
6261
6262Removes a policy override created for a policy rule.
6263
6264PARAMETERS
6265Path Parameters
6266 id	
6267integer <int64>
6268The identifier of the policy override.
6269
6270RESPONSES
6271200 OK
6272
6273401 Unauthorized
6274
6275404 Not Found
6276
6277500 Internal Server Error
6278
6279503 Service Unavailable
6280
6281
6282RESPONSE SAMPLES
6283200 OK
6284401 Unauthorized
6285404 Not Found
6286500 Internal Server Error
6287503 Service Unavailable
6288Expand all Collapse all
6289{
6290"links": [
6291{}
6292]
6293}
6294Policy Override Expiration
6295GET /api/3/policy_overrides/{id}/expires
6296Server URL
6297
6298https://help.rapid7.com/insightvm/en-us/api/3/policy_overrides/{id}/expires
6299
6300Get the expiration date for a policy override.
6301
6302PARAMETERS
6303Path Parameters
6304 id	
6305integer <int64>
6306The identifier of the policy override.
6307
6308RESPONSES
6309200 OK
6310
6311401 Unauthorized
6312
6313404 Not Found
6314
6315500 Internal Server Error
6316
6317503 Service Unavailable
6318
6319
6320RESPONSE SAMPLES
6321200 OK
6322401 Unauthorized
6323404 Not Found
6324500 Internal Server Error
6325503 Service Unavailable
6326 "string"
6327Policy Override Expiration
6328PUT /api/3/policy_overrides/{id}/expires
6329Server URL
6330
6331https://help.rapid7.com/insightvm/en-us/api/3/policy_overrides/{id}/expires
6332
6333Set the expiration date for a policy override. This must be a valid date in the future.
6334
6335PARAMETERS
6336Path Parameters
6337 id	
6338integer <int64>
6339The identifier of the policy override.
6340
6341REQUEST BODY
6342The date the policy override is set to expire. Date is represented in ISO 8601 format.
6343
6344
6345string
6346RESPONSES
6347200 OK
6348
6349400 Bad Request
6350
6351401 Unauthorized
6352
6353404 Not Found
6354
6355500 Internal Server Error
6356
6357503 Service Unavailable
6358
6359REQUEST SAMPLES
6360 "string"
6361
6362RESPONSE SAMPLES
6363200 OK
6364400 Bad Request
6365401 Unauthorized
6366404 Not Found
6367500 Internal Server Error
6368503 Service Unavailable
6369Expand all Collapse all
6370{
6371"links": [
6372{}
6373]
6374}
6375Policy Override Status
6376POST /api/3/policy_overrides/{id}/{status}
6377Server URL
6378
6379https://help.rapid7.com/insightvm/en-us/api/3/policy_overrides/{id}/{status}
6380
6381Update the status of the specified policy override. The status can be one of the following: "recall", "approve", or "reject".
6382
6383PARAMETERS
6384Path Parameters
6385 id	
6386integer <int64>
6387The identifier of the policy override.
6388
6389 status	
6390string
6391"recall" "approve" "reject"
6392Policy Override Status
6393
6394REQUEST BODY
6395A comment describing the change of the policy override status.
6396
6397
6398string
6399RESPONSES
6400200 OK
6401
6402400 Bad Request
6403
6404401 Unauthorized
6405
6406500 Internal Server Error
6407
6408503 Service Unavailable
6409
6410REQUEST SAMPLES
6411 "string"
6412
6413RESPONSE SAMPLES
6414400 Bad Request
6415401 Unauthorized
6416500 Internal Server Error
6417503 Service Unavailable
6418Expand all Collapse all
6419{
6420"links": [
6421{}
6422],
6423"message": "An error has occurred.",
6424"status": "400"
6425}
6426REMEDIATION
6427
6428Resources for determining the details required to remediate vulnerabilities.
6429
6430Asset Vulnerability Solution
6431GET /api/3/assets/{id}/vulnerabilities/{vulnerabilityId}/solution
6432Server URL
6433
6434https://help.rapid7.com/insightvm/en-us/api/3/assets/{id}/vulnerabilities/{vulnerabilityId}/solution
6435
6436Returns the highest-superceding rollup solutions for a vulnerability on an asset. The solution(s) selected will be the most recent and cost-effective means by which the vulnerability can be remediated.
6437
6438PARAMETERS
6439Path Parameters
6440 id	
6441integer <int64>
6442The identifier of the asset.
6443
6444 vulnerabilityId	
6445string
6446The identifier of the vulnerability.
6447
6448RESPONSES
6449200 OK
6450
6451401 Unauthorized
6452
6453404 Not Found
6454
6455500 Internal Server Error
6456
6457503 Service Unavailable
6458
6459
6460RESPONSE SAMPLES
6461200 OK
6462401 Unauthorized
6463404 Not Found
6464500 Internal Server Error
6465503 Service Unavailable
6466Expand all Collapse all
6467{
6468"links": [
6469{}
6470],
6471"resources": [
6472{}
6473]
6474}
6475REPORT
6476
6477Resources and operations for managing and generating reports. Reports are broadly categorized into document, export, and file types. document reports use section-based report templates to control the output and can be generated in several formats. export reports are designed to output their contents into a specific file format. file reports are templatized reports that output based on the format of a template file. Reports can be configured to generate on a schedule and be distributed via email to specific recipients.
6478
6479Report Formats
6480GET /api/3/report_formats
6481Server URL
6482
6483https://help.rapid7.com/insightvm/en-us/api/3/report_formats
6484
6485Returns all available report formats. A report format indicates an output file format specification (e.g. PDF, XML, etc). Some printable formats may be templated, and others may not. The supported templates for each formated are provided.
6486
6487RESPONSES
6488200 OK
6489
6490401 Unauthorized
6491
6492404 Not Found
6493
6494500 Internal Server Error
6495
6496503 Service Unavailable
6497
6498
6499RESPONSE SAMPLES
6500200 OK
6501401 Unauthorized
6502404 Not Found
6503500 Internal Server Error
6504503 Service Unavailable
6505Expand all Collapse all
6506{
6507"links": [
6508{}
6509],
6510"resources": [
6511{}
6512]
6513}
6514Report Templates
6515GET /api/3/report_templates
6516Server URL
6517
6518https://help.rapid7.com/insightvm/en-us/api/3/report_templates
6519
6520Returns all available report templates.
6521
6522RESPONSES
6523200 OK
6524
6525401 Unauthorized
6526
6527404 Not Found
6528
6529500 Internal Server Error
6530
6531503 Service Unavailable
6532
6533
6534RESPONSE SAMPLES
6535200 OK
6536401 Unauthorized
6537404 Not Found
6538500 Internal Server Error
6539503 Service Unavailable
6540Expand all Collapse all
6541{
6542"links": [
6543{}
6544],
6545"resources": [
6546{}
6547]
6548}
6549Report Template
6550GET /api/3/report_templates/{id}
6551Server URL
6552
6553https://help.rapid7.com/insightvm/en-us/api/3/report_templates/{id}
6554
6555Returns the details of a report template. Report templates govern the contents generated within a report.
6556
6557PARAMETERS
6558Path Parameters
6559 id	
6560string
6561The identifier of the report template;
6562
6563RESPONSES
6564200 OK
6565
6566401 Unauthorized
6567
6568404 Not Found
6569
6570500 Internal Server Error
6571
6572503 Service Unavailable
6573
6574
6575RESPONSE SAMPLES
6576200 OK
6577401 Unauthorized
6578404 Not Found
6579500 Internal Server Error
6580503 Service Unavailable
6581Expand all Collapse all
6582{
6583"builtin": true,
6584"description": "Provides comprehensive details about discovered assets, vulnerabilities, and users.",
6585"id": "audit-report",
6586"links": [
6587{}
6588],
6589"name": "Audit Report",
6590"sections": [
6591"string"
6592],
6593"type": "document"
6594}
6595Reports
6596GET /api/3/reports
6597Server URL
6598
6599https://help.rapid7.com/insightvm/en-us/api/3/reports
6600
6601Returns all defined report configurations.
6602
6603PARAMETERS
6604Query Parameters
6605 page	
6606integer <int32>
66070
6608The index of the page (zero-based) to retrieve.
6609
6610 size	
6611integer <int32>
661210
6613The number of records per page to retrieve.
6614
6615 sort	
6616Multiple query params of string
6617The 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.
6618
6619RESPONSES
6620200 OK
6621
6622401 Unauthorized
6623
6624404 Not Found
6625
6626500 Internal Server Error
6627
6628503 Service Unavailable
6629
6630
6631RESPONSE SAMPLES
6632200 OK
6633401 Unauthorized
6634404 Not Found
6635500 Internal Server Error
6636503 Service Unavailable
6637Expand all Collapse all
6638{
6639"links": [
6640{}
6641],
6642"page": {
6643"number": 6,
6644"size": 10,
6645"totalPages": 13,
6646"totalResources": 123
6647},
6648"resources": [
6649{}
6650]
6651}
6652Reports
6653POST /api/3/reports
6654Server URL
6655
6656https://help.rapid7.com/insightvm/en-us/api/3/reports
6657
6658Configures a new report for generation. Report types are controlled through either or both a format and template. Non-templatized (export) report formats do not require a template and have their output format preset. Templatized (document and file) report formats support a report template that governs the content of the output and the output format can be chosen from a list of supported formats.
6659
6660REQUEST BODY
6661The specification of a report configuration.
6662
6663
6664 bureau	
6665string
6666The name of the bureau for a CyberScope report. Only used when the format is "cyberscope-xml".
6667
6668 component	
6669string
6670The name of the component for a CyberScope report. Only used when the format is "cyberscope-xml".
6671
6672 database 	
6673Configuration for database export. Only used when the format is "database-export".
6674
6675 email 	
6676Email distribution settings for the report.
6677
6678 enclave	
6679string
6680The name of the enclave for a CyberScope report. Only used when the format is "cyberscope-xml".
6681
6682 filters 	
6683Filters applied to the contents of the report. The supported filters for a report vary by format and template.
6684
6685categories Object
6686The vulnerability categories to include or exclude in the report. Only included or excluded may be specified, not both.
6687included Array[string]
6688The identifiers of the vulnerability categories to included in the report.
6689excluded Array[string]
6690The identifiers of the vulnerability categories to exclude in the report.
6691severity string
6692"all" "critical" "critical-and-severe"
6693The vulnerability severities to include in the report.
6694statuses Array[string]
6695"vulnerable" "vulnerable-version" "potentially-vulnerable" "vulnerable-and-validated"
6696The vulnerability statuses to include in the report. If "vulnerable-and-validated" is selected no other values can be specified.
6697The following filter elements may be defined for non-templatized report formats:
6698
6699Format	Categories	Severity	Statuses
6700arf-xml			
6701csv-export	✓	✓	✓
6702cyberscope-xml			
6703database-export			
6704nexpose-simple-xml	✓	✓	
6705oval-xml			
6706qualys-xml	✓	✓	
6707scap-xml	✓	✓	
6708sql-query	✓	✓	✓
6709xccdf-csv			
6710xccdf-xml	✓	✓	
6711xml-export	✓	✓	✓
6712xml-export-v2	✓	✓	✓
6713The following filter elements may be defined for templatized report formats:
6714
6715Template	Categories	Severity	Statuses
6716audit-report	✓	✓	
6717baseline-comparison			
6718basic-vulnerability-check-results	✓	✓	✓
6719executive-overview			
6720highest-risk-vulns			
6721pci-attestation-v12			
6722pci-executive-summary-v12			
6723pci-vuln-details-v12			
6724policy-details	✓	✓	✓
6725policy-eval			
6726policy-summary	✓	✓	✓
6727prioritized-remediations	✓	✓	✓
6728prioritized-remediations-with-details	✓	✓	✓
6729r7-discovered-assets	✓	✓	✓
6730r7-vulnerability-exceptions	✓	✓	✓
6731remediation-plan	✓	✓	
6732report-card	✓	✓	
6733risk-scorecard	✓	✓	✓
6734rule-breakdown-summary	✓	✓	✓
6735top-policy-remediations	✓	✓	✓
6736top-policy-remediations-with-details	✓	✓	✓
6737top-riskiest-assets	✓	✓	✓
6738top-vulnerable-assets	✓	✓	✓
6739vulnerability-trends	✓	✓	✓
6740 format	
6741string
6742The output format of the report. The format will restrict the available templates and parameters that can be specified.
6743
6744 frequency 	
6745The recurring frequency with which to generate the report.
6746
6747 language	
6748string
6749The locale (language) in which the report is generated
6750
6751 name	
6752string
6753The name of the report.
6754
6755 organization	
6756string
6757The organization used for a XCCDF XML report. Only used when the format is "xccdf-xml".
6758
6759 owner	
6760integer <int32>
6761The identifier of the report owner.
6762
6763 policy	
6764integer <int64>
6765The policy to report on. Only used when the format is "oval-xml", ""xccdf-csv", or "xccdf-xml".
6766
6767 query	
6768string
6769SQL query to run against the Reporting Data Model. Only used when the format is "sql-query".
6770
6771 scope 	
6772The scope of the report. Scope is an object that has the following properties that vary by format and template:
6773
6774assets Array[integer <int32>]
6775The identifiers of the assets to report on.
6776sites Array[integer <int32>]
6777The identifiers of the sites to report on.
6778assetGroups Array[integer <int32>]
6779The identifiers of the asset to report on.
6780tags Array[integer <int32>]
6781The identifiers of the tag to report on.
6782scan integer <int32>
6783The identifier of the scan to report on.
6784The following scope elements may be defined for non-templatized report formats:
6785
6786Format	Assets	Sites	Asset Groups	Tags	Scan
6787arf-xml	✓	✓	✓	✓	
6788csv-export	✓	✓	✓	✓	✓
6789cyberscope-xml	✓	✓	✓	✓	✓
6790database-export		✓			
6791nexpose-simple-xml	✓	✓	✓	✓	✓
6792oval-xml	✓	✓	✓	✓	
6793qualys-xml	✓	✓	✓	✓	✓
6794scap-xml	✓	✓	✓	✓	✓
6795sql-query	✓	✓	✓	✓	✓
6796xccdf-csv	✓				
6797xccdf-xml	✓	✓	✓	✓	✓
6798xml-export	✓	✓	✓	✓	✓
6799xml-export-v2	✓	✓	✓	✓	✓
6800The following scope elements may be defined for templatized report formats:
6801
6802Template	Assets	Sites	Asset Groups	Tags	Scan
6803audit-report	✓	✓	✓	✓	✓
6804baseline-comparison	✓	✓	✓	✓	
6805basic-vulnerability-check-results	✓	✓	✓	✓	✓
6806executive-overview	✓	✓	✓	✓	
6807highest-risk-vulns	✓	✓	✓	✓	
6808pci-attestation-v12	✓	✓	✓	✓	✓
6809pci-executive-summary-v12	✓	✓	✓	✓	✓
6810pci-vuln-details-v12	✓	✓	✓	✓	✓
6811policy-details	✓	✓	✓	✓	
6812policy-eval	✓	✓	✓	✓	
6813policy-summary	✓	✓	✓	✓	✓
6814prioritized-remediations	✓	✓	✓	✓	✓
6815prioritized-remediations-with-details	✓	✓	✓	✓	✓
6816r7-discovered-assets	✓	✓	✓	✓	✓
6817r7-vulnerability-exceptions	✓	✓	✓	✓	✓
6818remediation-plan	✓	✓	✓	✓	✓
6819report-card	✓	✓	✓	✓	✓
6820risk-scorecard	✓	✓	✓	✓	
6821rule-breakdown-summary	✓	✓	✓	✓	
6822top-policy-remediations	✓	✓	✓	✓	
6823top-policy-remediations-with-details	✓	✓	✓	✓	
6824top-riskiest-assets	✓	✓	✓	✓	✓
6825top-vulnerable-assets	✓	✓	✓	✓	✓
6826vulnerability-trends	✓	✓	✓	✓	
6827If a report supports specifying a scan as the scope and a scan is specified, no other scope elements may be defined. In all other cases as many different types of supported scope elements can be specified in any combination. All reports except the sql-query format require at least one element to be specified as the scope.
6828
6829 storage 	
6830The additional storage location and path.
6831
6832 template	
6833string
6834The template for the report (only required if the format is templatized).
6835
6836 timezone	
6837string
6838The timezone the report generates in, such as "America/Los_Angeles".
6839
6840 users	
6841 integer <int32> 
6842The identifiers of the users granted explicit access to the report.
6843
6844 version	
6845string
6846The version of the report Data Model to report against. Only used when the format is "sql-query".
6847
6848RESPONSES
6849200 OK
6850
6851400 Bad Request
6852
6853401 Unauthorized
6854
6855500 Internal Server Error
6856
6857503 Service Unavailable
6858
6859REQUEST SAMPLES
6860JSON
6861Nexposeâ„¢ Simple XML
6862Qualys XML
6863OVAL XML
6864XCCDF CSV
6865XCCDF XML
6866Expand all Collapse all
6867{
6868"bureau": "Bureau",
6869"component": "Component",
6870"database": {
6871"credentials": {},
6872"host": "database.acme.com",
6873"name": "database",
6874"port": 3306,
6875"vendor": "mysql"
6876},
6877"email": {
6878"access": "zip",
6879"additional": "file",
6880"additionalRecipients": [],
6881"assetAccess": true,
6882"owner": "file",
6883"smtp": {}
6884},
6885"enclave": "Enclave",
6886"filters": {
6887"categories": {},
6888"severity": "",
6889"statuses": []
6890},
6891"format": "pdf",
6892"frequency": {
6893"repeat": {},
6894"start": "2018-03-01T04:31:56Z"
6895},
6896"language": "en-US",
6897"name": "Monthly Corporate Site Summary",
6898"organization": "Acme, Inc.",
6899"owner": 1,
6900"policy": 789,
6901"query": "SELECT * FROM dim_asset ORDER BY ip_address ASC",
6902"scope": {
6903"assetGroups": [],
6904"assets": [],
6905"scan": 68,
6906"sites": [],
6907"tags": []
6908},
6909"storage": {
6910"location": "monthly_reports/site/corporate"
6911},
6912"template": "executive-overview",
6913"timezone": "America/Los_Angeles",
6914"users": "7",
6915"version": "2.3.0"
6916}
6917
6918RESPONSE SAMPLES
6919200 OK
6920400 Bad Request
6921401 Unauthorized
6922500 Internal Server Error
6923503 Service Unavailable
6924Expand all Collapse all
6925{
6926"id": 1,
6927"links": [
6928{}
6929]
6930}
6931Report
6932GET /api/3/reports/{id}
6933Server URL
6934
6935https://help.rapid7.com/insightvm/en-us/api/3/reports/{id}
6936
6937Returns the configuration details of a report.
6938
6939PARAMETERS
6940Path Parameters
6941 id	
6942integer <int32>
6943The identifier of the report.
6944
6945RESPONSES
6946200 OK
6947
6948401 Unauthorized
6949
6950404 Not Found
6951
6952500 Internal Server Error
6953
6954503 Service Unavailable
6955
6956
6957RESPONSE SAMPLES
6958200 OK
6959401 Unauthorized
6960404 Not Found
6961500 Internal Server Error
6962503 Service Unavailable
6963Expand all Collapse all
6964{
6965"bureau": "Bureau",
6966"component": "Component",
6967"database": {
6968"credentials": {},
6969"host": "database.acme.com",
6970"name": "database",
6971"port": 3306,
6972"vendor": "mysql"
6973},
6974"email": {
6975"access": "zip",
6976"additional": "file",
6977"additionalRecipients": [],
6978"assetAccess": true,
6979"owner": "file",
6980"smtp": {}
6981},
6982"enclave": "Enclave",
6983"filters": {
6984"categories": {},
6985"severity": "",
6986"statuses": []
6987},
6988"format": "pdf",
6989"frequency": {
6990"nextRuntimes": [],
6991"repeat": {},
6992"start": "2018-03-01T04:31:56Z"
6993},
6994"id": 17,
6995"language": "en-US",
6996"links": [
6997{}
6998],
6999"name": "Monthly Corporate Site Summary",
7000"organization": "Acme, Inc.",
7001"owner": 1,
7002"policy": 789,
7003"query": "SELECT * FROM dim_asset ORDER BY ip_address ASC",
7004"scope": {
7005"assetGroups": [],
7006"assets": [],
7007"scan": 68,
7008"sites": [],
7009"tags": []
7010},
7011"storage": {
7012"location": "monthly_reports/site/corporate",
7013"path": "$(install_dir)/nsc/reports/$(user)/monthly_reports/site/corporate"
7014},
7015"template": "executive-overview",
7016"timezone": "America/Los_Angeles",
7017"users": "7",
7018"version": "2.3.0"
7019}
7020Report
7021PUT /api/3/reports/{id}