This article explains how to scan a standalone API target with Probely.
How does the API scanning work?
To scan an API, we need its specification, the schema. You can define it with an URL pointing to the schema or uploading it to Probely. The former has the advantage of us fetching the schema before every scan, ensuring we always get the most up-to-date version.
Probely supports APIs with different authentication methods. You can set a fixed API key in a custom header or configure a login endpoint from which you obtain an authentication token.
You can also define custom parameter values that replace those found in the schema. This allows you to override example values or to ensure domain-specific values are properly filled.
How do I scan an API?
Scanning an API is a simple three-step process:
Add an API target
Configure the API target
Start the scan
This article describes these steps in detail, covering multiple authentication scenarios.
Step 1: Adding an API target
To add a target, do the following:
Go to the Probely app.
Select the TARGETS tab and click on ADD.
Fill out the Add target form.
Fill out the following fields:
Select whether you want to Scan occasionally with credits or Scan frequently without limits. Learn more about it in Unlimited Scans vs. Scans with Credits.
Type in a meaningful Name for the target.
Set the URL field to the API base URL, i.e., the domain from which your API is actually serving clients.
Select API and, in API Type, choose between an "OpenAPI" and a "Postman Collection". If you choose the latter, make sure the Postman collection is already configured before adding the API target. Learn more about it in How to configure an API target (Postman Collection).
Choose between entering your API schema URL or uploading it. We support both JSON and YAML schemas. However, setting the schema URL has the advantage of Probely fetching it before a scan, so we always scan the API's latest version.
Click on ADD to create the new target.
If the server defined in the schema is not within the scope of the target, a warning will appear. You can opt to ignore the server from the OpenAPI schema file and use the target URL instead.
Step 2: Configure an API target
After adding (and verifying, if needed) the API target, go to its settings where there are some differences when compared with a non-API target, namely:
The Target Authentication section is replaced with API Target Authentication.
There's a new API Scanning Settings section, where the schema and custom values are set.
There's no Seeds List section, as we only crawl and scan endpoints defined in the schema.
There's no Extra Hosts section, as this only makes sense for web apps.
Configure the API Authentication
If the API requires authentication, the configuration depends on whether the API target was configured as OpenAPI or Postman Collection:
OpenAPI: the authentication configuration is made in the API target settings. Learn more about it in How to authenticate to scan an API target (OpenAPI).
Postman Collection: there's no need to configure the API target since the authentication is configured in the Postman Collection itself. Learn more about it in How to configure an API target (Postman Collection).
Configure the API Scanning Settings
In the API Scanning Settings section, you can override or set values for the endpoint parameters described in the schema.
Our scanning engine has a set of predetermined values for the most common parameters, such as email, address, and dates.
If we cannot infer the adequate value for a parameter, we use a default value. You can override that behavior by setting specific values, such as email and the product_id, as shown in the example below:
Step 3: Start the scan
Just press Scan Now, and the scan will start in a few seconds. You can follow the scan progress on the scan page.
Afterward, you can download a coverage report in CSV format that lists the endpoints parsed from the schema and the respective HTTP response code. The coverage report is a great tool for determining whether there were failed endpoints.
You can learn more about the coverage report in What is the meaning of the .CSV coverage report?