Rapid7 Investigations API

openapi: 3.1.0
info:
  title: InsightAppSec Accounts Investigations API
  description: '<p>Welcome to the reference documentation for the public APIs available for InsightAppSec.</p><p>Here are a few resources to help you learn how to start using our APIs:</p><ul><li><a href=''https://insight.help.rapid7.com/docs/api-overview''>Learn about basic concepts and capabilities</a></li><li><a href=''https://insight.help.rapid7.com/docs/managing-platform-api-keys''>Get an Insight platform API key to set up authentication</a></li><li><a href=''https://insight.help.rapid7.com/docs/product-apis''>See available Insight product APIs</a></li><li><a href=''https://insightappsec.help.rapid7.com/docs''>Learn more about InsightAppSec</a></li></ul><p>After you''ve got the basics down, you can use this API guide to find examples of requests and responses.</p></p><h2>Permissions</h2><p>This API uses the platform role of a user''s API key to inherit a set of permissions.</p><p><b>Notes</b>:<li>Platform Admins do not require explicit access to an App in order to see it, or anything associated with it</li><li>Organization keys will inherit Product Admin permissions.</li></p><table><thead><tr><th>Role</th><th>Permissions</th></tr></thead><tbody><tr><td>Product Admin</td><td><li><code>Manage Apps</code></li><li><code>Read Attack Templates</code></li><li><code>Manage Targets</code><li><code>Manage Scan Configs</code><li><code>Manage Scans</code></li><li><code>Manage Vulnerabilities</code></li><li><code>Administer Vulnerability Comments</code></li><li><code>Manage Engines</code></li><li><code>Manage Engine Groups</code></li><li><code>Manage Schedules</code></li><li><code>Manage Blackouts</code></li><li><code>Manage Global Blackouts</code></li><li><code>Manage Files</code></li><li><code>Manage Tags</code></li><li><code>Manage PDF Report</code></li></td></tr><tr><td>Read Write</td><td><li><code>Manage Apps</code></li><li><code>Read Attack Templates</code></li><li><code>Read Targets</code><li><code>Manage Scan Configs</code><li><code>Manage Scans</code></li><li><code>Manage Vulnerabilities</code></li><li><code>Manage Vulnerability Comments</code></li><li><code>Read Engines</code></li><li><code>Read Engine Groups</code></li><li><code>Manage Schedules</code></li><li><code>Manage Blackouts</code></li><li><code>Manage Files</code></li><li><code>Manage Tags</code></li><li><code>Manage PDF Report</code></li></td></tr><tr><td>Read Only</td><td><li><code>Read Apps</code></li><li><code>Read Attack Templates</code></li><li><code>Read Targets</code><li><code>Read Scan Configs</code><li><code>Read Scans</code></li><li><code>Read Vulnerabilities</code></li><li><code>Read Vulnerability Comments</code></li><li><code>Read Engines</code></li><li><code>Read Engine Groups</code></li><li><code>Read Schedules</code></li><li><code>Read Blackouts</code></li><li><code>Read Files</code></li><li><code>Read Tags</code></li><li><code>Read PDF Report</code></li></td></tr></tbody><table><a href="#pagination"><h2 id="pagination">Pagination Parameters</h2></a><p>The following query parameters can be used to control the order, offset and size of the returned data</p><table><thead><tr><th>Parameter</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><code>index</code></td><td><p>The 0-based index of the page of data desired (default: 0)<p></td><td><code>?index=2</code></td></tr><tr><td><code>size</code></td><td><p>The size of the page of data desired (min: 1, max: 1000, default: 50)<p></td><td><code>?size=10</code></td></tr><tr><td><code>sort</code></td><td><p>The sort terms and (optional) directions for the desired ordering of data (default: specific to each resource)<p></td><td><code>?sort=scan.submit_time,DESC,scan.status</code></td></tr><tr><td><code>page-token</code></td><td><p>The page token, used as an alternative to <code>index</code> (default: Not provided)<p></td><td><code>?page-token=NDM0NTk0NTIyOjo6X1M6OjpiYW5hbmFz</code></td></tr></tbody></table><h3>Paging using a page token</h3><p>When intending to page beyond the 10,000th result, or as an alternative to using the <code>index</code> query parameter, the <code>page-token</code> option may be used instead. After retrieving the first page, the <code>page_token</code> will be present in the <code>metadata</code> section of the response.<br />For example, with <code>size=99</code>, <code>index=0</code> to <code>index=99</code> may be used. To load the next page, use the <code>page_token</code> value used in the response e.g. <code>?page-token=NDM0NTk0NTIyO</code> </p><h2>Creating resources</h2><p>As is generally the accepted practice with REST-ful APIs, creating a resource can be performed by sending an appropriately formatted POST request. Any ID provided for a new resource in a POST request <i>body</i> will simply be ignored (and a new one generated internally and returned as part of the resource in subsequent GET requests), and POST requests to URLs following a format similar to <code>.../resource/<ID></code> are unsupported and should respond with <code>415 Method Not Allowed</code>. All requests which successfully create a resource and respond with <code>201 Created</code> will contain a <code>Location</code> header the value of which is an absolute URI for the resource (the ID of which can be determined as the last section of the path in the given URI). For example:<br /><code>Location: https://us.api.insight.rapid7.com/ias/v1/scans/12345678-1234-5678-90AB-1234567890AB</code></p><h2>Date, Time and Timezone Support</h2><p>The value of date and date-time type properties are fixed to the common ISO-8601 format. Unless otherwise specified, all date or date-time data in response bodies are expressed in UTC, and it is also expected that data provided in request bodies are also expressed in UTC.</p><h3>Schedules and Blackouts</h3><p>The <code>first_start</code> and <code>first_end</code> properties of both Blackouts and Schedules, and the <code>last_start</code> property of Blackouts may be specified with a timezone. If the timezone is not specified, it is assumed to be UTC. For example:<br /><code>2019-08-12T14:00:00.000000Z[Asia/Tokyo]</code><br />It is also possible to specify the timezone as an offset of either <code>GMT</code> or <code>UTC</code>. For example:<br /><code>2019-09-04T15:00:00.000000Z[GMT+03:00]</code></p><table><thead><tr><th>Value</th><th>Format</th><th>Notes</th></tr></thead><tbody><tr><td>Date</td><td>YYYY-MM-DD</td><td>Defaults to 12 am UTC (if used for a date &amp; time)</td></tr><tr><td>Date &amp; time only</td><td>YYYY-MM-DD''T''hh:mm:ss[.nnn]</td><td>Defaults to UTC</td></tr><tr><td>Date &amp; time in UTC</td><td>YYYY-MM-DD''T''hh:mm:ss[.nnn]Z</td><td></td></tr><tr><td>Date &amp; time with specific timezone</td><td>YYYY-MM-DD''T''hh:mm:ss[.nnn]Z[TimeZoneId]</td><td></td></tr></tbody></table><h2>Searching and Filtering</h2><p>One characteristic of a powerful API is support for complex search and filtering of resources using a flexible query language. It is entirely possible to provide basic search and filtering functionality on standard GET resource collection operations using HTTP query parameters, but this becomes restrictive when attempting to encode boolean logic. Other solutions are also possible but come with equally restrictive compromises. The most effective way to facilitate this complex search and filtering is to provide it as a top-level API with a robust Domain-Specific Language (DSL).</p><p>For simple data retrieval that supports paging and sorting functionality, use the traditional resource-specific GET collection operations; for more complex data retrieval that supports a user-crafted query DSL, use the global Search operation.</p><h2>Errors</h2><p>Any response from the API with an HTTP Status Code in the 4xx or 5xx range indicates an error. If in the 4xx range it indicates a client-side error, where in the 5xx range it indicates a server-side error. All responses indicating an error should be JSON formatted, and contain both a "status" and a "message" property indicating the cause of the error, a "r7-correlation-id" header should also always be returned in the format of a UUID, which uniquely identifies the HTTP exchange that took place and caused the error (this header is present on <i>every</i> request). On some occasions, an "error_code" property will be included in the response body, which can provide the support team further context into the cause of the error in cases where the message is not explicitly clear.</p><p>When contacting support about error responses received from the API, please attempt to include, at minimum:<ul><li>A description of the requests intent</li><li>The request URL</li><li>The request body</li><li>The error response body</li><li>The error response "r7-correlation-id" header</li></ul></p><h3>Validation Errors</h3><p>Specifically, when a response with an HTTP Status Code of 422 is returned, this indicates a validation error, almost always received in a response from a non-idempotent request (normally PUT, POST or DELETE). In this case, there should be an additional "errors" property included in the JSON response body that should describe the cause of the validation exception; this will almost always require a modification to the request body to resolve. </p>'
  version: v1
servers:
- url: https://[region].api.insight.rapid7.com/ias/v1
tags:
- name: Investigations
paths:
  /idr/v1/investigations/{id}/status/{status}:
    put:
      tags:
      - Investigations
      summary: Set the status of an investigation
      description: An API that sets the status of the investigation with the given ID or RRN. This API returns the investigation with its status updated to the new state. If the investigation already has the given status, no change is made, but the investigation will still be returned.
      operationId: setStatus
      parameters:
      - name: id
        in: path
        description: The ID or RRN of the investigation to change the status of.
        required: true
        schema:
          type: string
        examples:
          investigationId:
            description: investigationId
            value: 174e4f99-2ac7-4481-9301-4d24c34baf06
          rrn:
            description: rrn
            value: rrn:investigation:us1:a2c78570-5346-4d76-b57a-230da72c5e58:investigation:ABSJB123U3O9
      - name: status
        in: path
        description: The new status for the investigation (case-insensitive).
        required: true
        schema:
          type: string
          enum:
          - OPEN
          - CLOSED
          - INVESTIGATING
          example: OPEN
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Investigation'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '403':
          description: Insufficient Permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '404':
          description: Entity Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
  /idr/v1/investigations/{id}/assignee:
    put:
      tags:
      - Investigations
      summary: Assign user to investigation
      description: An API that assigns a user to the specified investigation. The user must be a platform administrator, product administrator, or read/write user with access to either InsightIDR or InsightUBA.
      operationId: assignUserToInvestigation
      parameters:
      - name: id
        in: path
        description: The ID or RRN of the investigation to assign the user to.
        required: true
        schema:
          type: string
        example: 174e4f99-2ac7-4481-9301-4d24c34baf06
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignUserToInvestigationRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Investigation'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '403':
          description: Insufficient Permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '404':
          description: Entity Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
  /idr/v1/investigations/bulk_close:
    post:
      tags:
      - Investigations
      summary: Close investigations in bulk
      description: An API to close all investigations that match the parameters provided in the request body. This API returns the number of investigations that were closed and a list of their IDs.
      operationId: bulkCloseInvestigations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkCloseInvestigationsRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClosedInvestigations'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '403':
          description: Insufficient Permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '404':
          description: Entity Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
  /idr/v1/investigations:
    get:
      tags:
      - Investigations
      summary: List investigations
      description: An API to list all investigations. This API retrieves a page of investigations matching the given request parameters. The investigations will always be sorted by investigation created_time in descending order.
      operationId: listInvestigations
      parameters:
      - name: index
        in: query
        description: The optional, 0 based index of the page to retrieve.  Must be an integer greater than or equal to 0.
        required: false
        schema:
          type: integer
          default: 0
          minimum: 0
        example: 0
      - name: size
        in: query
        description: The optional size of the page to retrieve. Must be an integer greater than 0 or less then or equal to 1000.
        required: false
        schema:
          type: integer
          default: 20
          maximum: 1000
          minimum: 1
        example: 20
      - name: statuses
        in: query
        description: An optional, comma-separated set of investigation statuses. Only investigations whose status matches one of the entries in the list will be returned.  If this parameter, is omitted investigations with any status may be returned.
        required: false
        schema:
          type: string
        example: OPEN, CLOSED, INVESTIGATING
      - name: start_time
        in: query
        description: An optional, ISO-formatted timestamp. Only investigations whose createTime is after this date will be returned by the API. If this parameter is omitted, investigations with any create_time may be returned.
        required: false
        schema:
          type: string
        example: '2018-07-01T00:00:00Z'
      - name: end_time
        in: query
        description: An optional, ISO-formatted timestamp. Only investigations whose createTime is before this date will be returned by the API. If this parameter is omitted, investigations with any create_time may be returned.
        required: false
        schema:
          type: string
        example: '2018-07-04T00:00:00Z'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageInvestigation'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '403':
          description: Insufficient Permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '404':
          description: Entity Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse3'
components:
  schemas:
    PageMetadata3:
      type: object
      properties:
        index:
          type: integer
          format: int32
          description: 'The 0 based index of the page retrieved. '
          example: 0
        size:
          type: integer
          format: int32
          description: 'The size of the page requested. '
          example: 20
        total_pages:
          type: integer
          format: int32
          description: 'The total number of pages available with the given filter parameters. '
          example: 1
        total_data:
          type: integer
          format: int64
          description: 'The total number of results available with the given filter parameters. '
          example: 15
      required:
      - index
      - size
      - total_data
      - total_pages
    ClosedInvestigations:
      type: object
      properties:
        ids:
          type: array
          description: The IDs of the investigations that were closed by the request.
          example:
          - 581134c9-2510-4010-865c-7ae81761315b
          - 114c706d-e64a-4731-997b-9115beef3026
          items:
            type: string
          uniqueItems: true
        num_closed:
          type: integer
          format: int32
          description: The number of investigations closed by the request.
          example: 2
      required:
      - ids
      - num_closed
    AlertInfo:
      type: object
      properties:
        type:
          type: string
          description: The alert's type.
          example: Account Created
        type_description:
          type: string
          description: An optional description of this type of alert.
          example: A new account has been created.
        first_event_time:
          type: string
          description: The time the first event involved in this alert occurred.
          example: '2018-06-06T16:56:42Z'
      required:
      - type
    Assignee:
      type: object
      properties:
        name:
          type: string
          description: The name of the assigned user.
          example: Ellen Example
        email:
          type: string
          description: The email of the assigned user.
          example: example@test.com
      required:
      - email
      - name
    Investigation:
      type: object
      properties:
        id:
          type: string
          description: The ID of the investigation.
          example: 174e4f99-2ac7-4481-9301-4d24c34baf06
        rrn:
          type: string
          description: The RRN of the investigation.
          example: rrn:investigation:us1:174e4f99-2ac7-4481-9301-4d24c34baf06:investigation:6A74T2A4
        title:
          type: string
          description: The investigation's title.
          example: Joe enabled account Joebob
        status:
          type: string
          description: The status of the investigations.
          enum:
          - OPEN,INVESTIGATING,CLOSED
          example: OPEN
        source:
          type: string
          description: The source of this investigation.
          example: ALERT
        disposition:
          type: string
          description: This disposition of this investigation.
          enum:
          - BENIGN,MALICIOUS,NOT_APPLICABLE,UNSPECIFIED
          example: BENIGN
        assignee:
          $ref: '#/components/schemas/Assignee'
          description: The user assigned to this investigation, if any.
        alerts:
          type: array
          description: The alerts involved in this investigation, if any.
          items:
            $ref: '#/components/schemas/AlertInfo'
        created_time:
          type: string
          description: The time the investigation was created, as an ISO formatted timestamp.
          example: '2018-06-06T16:56:42Z'
      required:
      - created_time
      - id
      - rrn
      - source
      - status
      - title
    BulkCloseInvestigationsRequest:
      type: object
      description: The criteria for what investigations to close.
      properties:
        source:
          type: string
          description: The name of an investigation source. Only investigations from this source will be closed. If the source is ALERT, an alert type must be specified as well.
          enum:
          - ALERT,MANUAL,HUNT
          example: ALERT
        alert_type:
          type: string
          description: The category of alerts that should be closed. This parameter is required if the source is ALERT and ignored for other sources. This value must exactly match the alert type returned by the List Investigations response.
          example: Attacker Behavior Detected
        detection_rule_rrn:
          type: string
          description: The RRN of the detection rule. Investigations will only be closed that are associated with this detection rule. If a detection rule RRN is given, the alert_type is required to be 'Attacker Behavior Detected'.
          example: rrn:cba:us1:a2c78570-5346-4d76-b57a-230da72c5e58:detection-rule:ABSJB123U3O9
        from:
          type: string
          description: An ISO formatted timestamp. Only investigations whose createTime is after this date will be closed.
          example: '2018-07-01T00:00:00Z'
        to:
          type: string
          description: An ISO formatted timestamp. Only investigations whose createTime is before this date will be closed.
          example: '2018-07-08T00:00:00Z'
        max_investigations_to_close:
          type: integer
          format: int32
          description: An optional, maximum number of alerts to close with this request. If this parameter is not specified, then there is no maximum. If this limit is exceeded, then a 400 error response is returned. The minimum value is 0.
          example: 10
      required:
      - from
      - source
      - to
    AssignUserToInvestigationRequest:
      type: object
      description: Details about which user to assign.
      properties:
        user_email_address:
          type: string
          description: The email address of the user to assign to this investigation, used to log into the Insight Platform.
          example: example@test.com
          minLength: 1
      required:
      - user_email_address
    ErrorResponse3:
      type: object
      properties:
        message:
          type: string
          description: A human-readable message describing the error that occurred.
          example: A human-readable message describing the error that occurred.
        correlation_id:
          type: string
          description: An identifier that uniquely identifies the failed request.
          example: An identifier that uniquely identifies the failed request.
      required:
      - message
    PageInvestigation:
      type: object
      properties:
        data:
          type: array
          description: The list of data that matches the pagination parameters. If no results match, this will be an empty list.
          items:
            $ref: '#/components/schemas/Investigation'
        metadata:
          $ref: '#/components/schemas/PageMetadata3'
          description: 'The pagination parameters used to generate this page result. '
      required:
      - data
      - metadata