Scan API Preferences

Scan jobs can be configured with the optional "preferences" object. If no "preferences" object is passed to a scanning job the default parameters are used.

scan_type

Parameter type: string

To perform the explorer scan, send the scan type parameter with the value api . Check the checks performed here: Features

Allowed parameters
full
default
lite
api

The API scan is designed to perform vulnerability checks and collect relevant information through the API specification itself. In other words, to perform the API scan you need to provide the specification of your API.

{
    "url": "https://api.example.com",
    "preferences": {
        "scan_type" : "api",
        "api_definition": "https://api.example.com/api/schema",
    }
}

Example of expected response in cases of successful request:

{
    "enqueued_scan_id": "1f7dffb6-28fb-11f0-80c4-e6cba48c97bd"
}

Authentication

API Scan with Customizable Authentication

We provide authentication for API cans by providing a request field for HTTP headers. This means that you can provide the request header expected by your API.

With this feature, you can send an internal JSON request detailing exactly how your API receives, authenticates and validates the requests that will be sent.

{
    "url": "https://api.example.com",
    "preferences": {
        "scan_type" : "api",
        "api_definition": "https://api.example.com/api/schema",
        "api_header":{"x-apikey_example": "d1ue09-uecquq-q2iv-q2i-0q20qv-q0oq2"}
    }
}

Note that the key x-apikey_example was used in the example but is not limited to. In other words, you can use any names from your API regardless of which or how many keys/values ​​you need.

API Definition

We accept API definition files in:

• JSON

• YML/YAML

• XML

The API types we are able to scan are:

• OpenAPI

• SOAP

Some common validations

When the required API definition field is missing, we currently return this message:

{
    "detail": "Something went wrong when starting your scan"
}

When the API definition does not match as expected, for ease we return the original error like this:

{
    "detail": "The type and/or format values of the api definition field 'api_definition' are invalid. Please submit a correct api definition."
}