Skip to main content

How to create a target to scan an API (OpenAPI)

To scan an API for vulnerabilities, you have to create a target that will define the scope and the behavior of the scan. To specify the API you can use an OpenAPI schema (either in JSON or YAML formats) in one of two ways:

  • OpenAPI schema URL - Provide a URL to the OpenAPI schema, and Probely fetches it to scan the API endpoints. This means that when the API changes, Probely will use the latest changes.
  • OpenAPI schema file - Upload a file with the OpenAPI schema, and Probely uses it to scan the API endpoints. This means that when the API changes, a file with the latest changes should be uploaded.

As an alternative to an OpenAPI schema, you can use a Postman Collection schema. Learn more in this tutorial about how to create a target to scan an API (Postman Collection).

Prerequisites​

Before creating a target, ensure you have created and verified the target domain. Learn more in this tutorial about how to create and verify a target domain.

Step 1: Create the Target​​

Create the target using an OpenAPI schema URL or an OpenAPI schema file.

If you are using an OpenAPI schema URL, create the target with the following information:

  • A recognizable name for the target.
  • The URL of the API to scan.
  • The type of target ("type": "api").
  • The type of API schema ("api_schema_type": "openapi").
  • The URL of the OpenAPI schema (in "api_schema_url").

In this request, we use the target name as My target (API), the API URL as https://api.example.com, and the OpenAPI schema URL as https://developers.example.com/openapi.yaml.

Request
curl https://api.probely.com/targets/ \
  -X POST \
  -H 'Authorization: JWT <YOUR_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "site": {
        "name": "My target (API)",
        "url": "https://api.example.com",
        "api_scan_settings": {
            "api_schema_type": "openapi",
            "api_schema_url": "https://developers.example.com/openapi.yaml"
        }
    },
    "type": "api"
}
caution

Ensure that in the payload, the server you specify in the url is the same that is specified in the servers: property of the OpenAPI schema or, otherwise, you will get an error like: "Target didn't match server URL from API schema."

The response will return the newly created target with the identifier (id), and the information provided (name, url, api_schema_type, and api_schema_url).
You will find other information such as:

  • host - It must have the domain corresponding to the URL you provided. In this tutorial, it is api.example.com because the URL is https://api.example.com.
  • verified - If you followed the prerequisites, it must be true. If not, the target scans can be interpreted as malicious attacks. Learn more about how to create and verify a target domain.
Response
{
  "id": "ZjvNQa2shD17",
  "site": {
    "id": "HPVA4pT6Epa3",
    "name": "My target (API)",
    "desc": "",
    "url": "https://api.example.com",
    "host": "api.example.com",
    "has_form_login": false,
    ...
    "stack": [],
    "verified": true,
    "verification_token": "5041700e-e954-4905-95d3-20324666134c",
    ...
    "api_scan_settings": {
      "api_schema_type": "openapi",
      "api_schema_url": "https://developers.example.com/openapi.yaml",
      "api_schema_file": "",
      "custom_api_parameters": [],
      ...
    }
  },
  ...
}

Now that your target has been created, you can start a scan. Learn more in how to start a scan.