Set Up and Deploy the InsightAppSec API

Using the API

Once you have the API key, you can start to use the API to send, post, get, and delete data from InsightAppSec.

First, decide which tool you want to use in order to interact with the API, such as Postman. Learn more about Postman here: https://www.getpostman.com/

Perform Basic Operations using the API

The following sections contain examples of basic InsightAppSec operations that you can perform using the API. The URL for a Rapid7 Insight API endpoint follows the structure: {{base url}}/{{api}}/{{version}}/{{endpoint}}

The base url depends on the region for your account. You can refer to the Supported Regions article for a specific base URL based on your location. For our examples, we will assume that your account is in the US region and you are using version 1 of the API. The URL for an endpoint will then be: https://us.api.insight.rapid7.com/ias/v1/{{endpoint}}.

Rapid7 Insight platform APIs use the X-Api-Key header for authentication and authorization. Before you perform any API call with Postman, make sure you add a header X-Api-Key with the value as your Insight API Key. Postman considers header values as strings by default, so you do not need to add quotes around the API key.

These examples contain all the information necessary to perform the API operation, such as the URL, operation, and the POST body. Placeholder text will be surrounded by curly braces (for example: {{Provide domain name here}}) so you can customize your API requests. Insert the information in the appropriate sections in Postman and click Send.

The “Expected Response” section in each example will explain what response status and response contents you should expect for a successful operation. Some processes are interconnected, so the response of one will become a request parameter for the other.

Add a Target

Prerequisites

• Domain URL or IP address of a web application that you’d like to scan.

Operation

POST URLhttps://us.api.insight.rapid7.com/ias/v1/targetsHeaders

 
1
X-Api-Key : {{Insight API Key}}
2
Content-Type : application/json

Body

 
1
{
2
  "domain": "{{Your domain URL or IP address}}",
3
  "enabled": true
4
}

Expected ResponseStatus 201 Created HeaderLocation : https://us.api.insight.rapid7.com:443/ias/v1/targets/{{Target ID}}

Create an App

Operation POST URLhttps://us.api.insight.rapid7.com/ias/v1/apps/Headers

 
1
X-Api-Key : {{Insight API Key}}
2
Content-Type : application/json

Body

 
1
{
2
  "name": "API-test-app",
3
  "description": "Creating an app to test the API"
4
}

excerpt: "This article covers how to integrate the Jenkins CI/CD software with InsightAppSec." Status 201 Created HeaderLocation : https://us.api.insight.rapid7.com:443/ias/v1/apps/{{App ID}}

Create a Scan Config

Prerequisites

• App ID from Create an App
• The unique ID of the attack template that you’d like to use for your scan config. You can obtain the IDs of all attack templates by running GET https://us.api.insight.rapid7.com/ias/v1/attack-templates/.

Operation POST URLhttps://us.api.insight.rapid7.com/ias/v1/scan-configs/Headers

 
1
X-Api-Key : {{Insight API Key}}
2
Content-Type : application/json

Body

 
1
{
2
  "name" : "api-test-scan-config",
3
  "description" : "Webscantest scan using the API",
4
  "app" : {
5
    "id" : "{{App ID}}"
6
  },
7
  "attack_template" : {
8
    "id" : "{{Attack template ID}}"
9
  }
10
}

Expected ResponseStatus 201 Created HeaderLocation : https://us.api.insight.rapid7.com:443/ias/v1/scan-configs/{{Scan Config ID}}

Add a Domain to a Scan Config

Prerequisites

• Domain URL or IP address from Add a Target
• Scan config ID from Create a Scan Config

Operation PUT URLhttps://us.api.insight.rapid7.com/ias/v1/scan-configs/{{Scan Config ID}}/optionsHeaders

 
1
X-Api-Key : {{Insight API Key}}
2
Content-Type : application/json

Body

 
1
{
2
  "crawl_config": {
3
	"seed_url_list": [
4
      {
5
        "value": "{{Your domain URL or IP address}}"
6
      }
7
    ],
8
    "max_crawl_results": 101,
9
    "scope_constraint_list": [
10
      {
11
        "URL": "{{Your domain URL or IP address}}/*",
12
        "method": "ALL",
13
        "exclusion": "INCLUDE",
14
        "match_criteria": "WILDCARD",
15
        "http_parameter_list": []
16
      }
17
    ]
18
  },
19
  "attacker_config": {
20
    "scope_constraint_list": [
21
      {
22
        "URL": "{{Your domain URL or IP address}}/*",
23
        "method": "ALL",
24
        "exclusion": "INCLUDE",
25
        "match_criteria": "WILDCARD",
26
        "http_parameter_list": []
27
      }
28
    ]
29
  }
30
}

Expected ResponseStatus 200 OK