Making a Request

🚧

API Rate Limiting

To ensure service stability and to prevent abuse, rate limits have been implemented on all WhiteHat Dynamic APIs. These limits allow 3000 requests originated from single source IP address identified by x-forwarded-for header over a ten second period. If you exceed a rate limit when using any of our APIs, WhiteHat Dynamic will return a slow response with error HTTP 500 Internal Server Error. This continues until the evaluation window has passed.

By using Query, Display, and Page parameters, you can control or limit the amount of information retrieved from requests to WhiteHat Dynamic API resources.

The following sections summarize the parameters you can set.

Query Parameters

Query parameters control what information is retrieved from a GET request. The individual parameters are described in the reference documentation for each resource, but in general you can limit your queries based on:

• A category or type, such as a user name or asset type
• A date range
• A quality (status, or a boolean value such as "does / does not have credentials", etc.)

Display Parameters

Whereas Query parameters control the information that is retrieved, Display parameters control the information that is reported. For example, if you used a GET to retrieve information about the applications that are using a particular scan schedule, you probably don’t need to see that scan schedule for every application. So, you might use query_scan_schedule_name_like, but set the display_schedule to false (0).

On version 2.0 API resources, display parameters are implemented in a single Fields parameter. Specifying comma-separated properties in this parameter that do not appear in the default response, allows each additional property and its associated data to appear in the response.

Page Parameters

Page parameters can be used to limit, offset, or order the results of your query. Page:limit will limit the results returned; page:offset will start showing results beginning from the value provided; and page:order_by will order the results by the given value.

For version 2.0 API resources, Page parameters work similarly but are specified using sort, limit, and offset parameters.

📘

Availability of page parameters

Page parameters may not be available for all operations that produce collections of data.

Request Examples

Version 1.0 API

GET https://sentinel.whitehatsec.com/api/site/{site_id}/user

This request will return a list of users authorized for the site with the specified site ID. Because no query parameters or display parameters are specified, all users with permissions for that site will be included in the response, and all available information will be given.

GET https://sentinel.whitehatsec.com/api/site?query_scan_schedule_name_like=Nights

This request will return a list of sites with an assigned schedule that includes "Nights" in the name (for instance, "Nights & Weekends").

GET https://sentinel.whitehatsec.com/api/site?query_scan_schedule_name_like=Nights&display_all=0&display_organization=1

This request will return a list of sites with an assigned schedule that includes "Nights" in the name (for instance, "Nights & Weekends"), but instead of displaying all the information for those sites it will include only basic information (site id, for instance) and the organization the site is associated to.

Version 2.0 API

GET https://sentinel.whitehatsec.com/api/findings

The above request will return an unfiltered list of all findings (vulnerabilities) available to the current user. Since no additional parameters are specified, the response will include all the default information for each vulnerability.

GET https://sentinel.whitehatsec.com/api/findings?risk=5

This request will return all vulnerabilities available to the current user that have a critical (5) risk rating. The risk parameter is a query parameter that filters the results to only the subset you want to see.

GET https://sentinel.whitehatsec.com/api/findings?risk=5&fields=cvssScore,cvssV3

This request will return all vulnerabilities available to the current user that have a critical risk rating, but the response will also include:

• The CVSS v2 score
• The CVSS v3 score and vector data
• Any CVSS v3 customizations added by the customer for each vulnerability