Making a Request

🚧

API Rate Limiting

To ensure service stability and to prevent abuse, rate limits have been implemented on all Sentinel platform API’s. 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, Sentinel will return slow response with error HTTP 500 Internal Server Error. This continues until the evaluation window has passed.

The ability to GET, PUT, POST, or DELETE information via the API resources is not particularly useful without the ability to limit or control the information retrieved. When you make a request to the API, you can use the various parameters to control what you see and how you see it. Please refer to the parameter summaries that follow:

Query Parameters

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

• A category or type (e.g. a user name, or an 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 have 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 each application. You might use query_scan_schedule_name_like, but set 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; page:order_by will order the results by the value given.

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

📘

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

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. Since 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 wish 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, and the CVSS v3 score and vector data, as well as any CVSS v3 customizations added by the customer for each vulnerability.