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."
}

Example return (with fake/made-up values) to merely visualize the return pattern.

{
   "scan":{
      "started_at":"2025-05-13T15:12:57.856904Z",
      "scan_id":"c0a9a2db-301a-11f2-a912-0aa58c11015e",
      "preferences":{
         "services_brute_force":0,
         "xss":false,
         "cms_brute_force":0,
         "web_brute_force":0,
         "scan_type":"api",
         "csrf":true,
         "scan_deep":3,
         "scan_speed":"moderate",
         "api_definition":"https://api.example.com/swagger.json",
         "leak_data_usage":0,
         "scheduled":false,
         "dork":false,
         "crawler_options":{
            "open_directory":false,
            "exposed_information":false,
            "backdoor_detection":false,
            "exposed_emails":true,
            "search_url_malware":false,
            "open_redirect":true,
            "exposed_apikeys":true
         },
         "ratelimit_req_sec":10,
         "search_in_web_cache":false,
         "sqli":false,
         "bucket_s3":false
      },
      "percentage":"100.0",
      "ended_at":"2025-05-13T15:26:07.220361Z",
      "last_updater_heartbeat":"2025-05-13T16:57:54.756151Z",
      "information":{
         "services":[],
         "emails":[],
         "components":{},
         "database":{},
         "web_server":{},
         "os":{},
         "cdn":null,
         "cms":null,
         "certificate":null,
         "waf":[],
         "ips":[],
         "isp":"unknown",
         "api_reference":{
            "type":"openapi",
            "format":"json",
            "api_definition":"https://api.example.com/swagger/.json",
            "is_api_header":false
         },
         "total_checked":2
      },
      "issues":{
         "scan_api":{
            "issues":[
               {
                  "group":"unprotected_api",
                  "name":"Cross-Domain Misconfiguration ",
                  "severity":"medium",
                  "cve":[
                     
                  ],
                  "cwe":[
                     264
                  ],
                  "cvss":{
                     "score":0,
                     "detail":""
                  },
                  "remediation":"Ensure that sensitive data is not available in an unauthenticated manner (using IP address white-listing, for instance).Configure the \"Access-Control-Allow-Origin\" HTTP header to a more restrictive set of domains, or remove all CORS headers entirely, to allow the web browser to enforce the Same Origin Policy (SOP) in a more restrictive manner. ",
                  "references":"https://vulncat.fortify.com/en/detail?id=desc.config.dotnet.html5_overly_permissive_cors_policy",
                  "description":"Web browser data loading may be possible, due to a Cross Origin Resource Sharing (CORS) misconfiguration on the web server. Uri: https://api.example.com/swagger.json Method: GET Evidence: access-control-allow-origin: * Otherinfo: The CORS misconfiguration on the web server permits cross-domain read requests from arbitrary third party domains, using unauthenticated APIs on this domain. Web browser implementations do not permit arbitrary third parties to read the response from authenticated APIs, however. This reduces the risk somewhat. This misconfiguration could be used by an attacker to access data that is available in an unauthenticated manner, but which uses some other form of security, such as IP address white-listing.. ",
                  "raw":{
                     
                  }
               }
            ]
         }
      }
   }
}