API Discovery ¶
The API Discovery section of Wallarm Console enables you to manage your API inventory, as well as to fine-tune its discovery. This guide instructs you on using this section.
The section is only available to the users of the following roles:
Administrator and Analyst can view and manage the data discovered by the API Discovery module, and access the API Discovery configuration part.
Global Administrator and Global Analyst in the accounts with the multitenancy feature have the same rights.
API Developer can view and download the data discovered by the API Discovery module. This role allows distinguishing users whose tasks only require using Wallarm to get actual data on company APIs. These users do not have access to any Wallarm Console sections except for API Discovery and Settings → Profile.
Default view: time period, sorting and grouping
Each time you open the API Discovery section:
- You see actual inventory of your APIs (all discovered endpoints)
The Changes since filter goes to the
Lask weekstate, which means:
- From the presented endpoints, the
Changedwithin this period will obtain corresponding marks
- Additionally, endpoints
Deletedwithin this period will be displayed
- From the presented endpoints, the
See this example to understand what API Discovery displays by default.
You can manually select other time periods to be covered.
Sorting and grouping
By default, endpoints are sorted by host/endpoint names (and grouped by hosts). If you sort by Hits or Risk, grouping goes away - to get back to the default, click hosts/endpoint column again.
Among a wide range of API endpoint filters, you can choose the ones corresponding to your analysis purpose, e.g.:
Only attacked endpoints that you can sort by the number of hits.
Find the endpoints that have been changed or newly discovered in the last week and that process PII data. This kind of request can help you to stay up to date with critical changes in your APIs.
Find the endpoints being used to upload data to your server by the PUT or POST calls. Since such endpoints are a frequent attack target, they should be well secured. Using this kind of request you can check that endpoints are known to the team and are well secured from attacks.
Find the endpoints processing customers' bank card data. With this request, you can check that sensitive data is processed only by secured endpoints.
Find the endpoints of a deprecated API version (e.g. by searching
/v1) and make sure that they are not used by clients.
Find the most vulnerable endpoints characterized by processing sensitive data and active vulnerabilities of the high risk level. Exploiting vulnerabilities of a high risk level allows attackers to perform many malicious actions with the system including stealing sensitive data that the endpoint processes/stores.
All filtered data can be exported in the OpenAPI v3 for additional analysis.
Viewing endpoint parameters¶
By clicking the endpoint, you can also find the endpoint details, including required and optional parameters with the relevant data types:
Each parameter information includes:
Parameter name and the part of request this parameter belongs to
Information about parameter changes (new, removed)
Presence and type of sensitive data (PII) transmitted by this parameter, including:
- Technical data like IP and MAC addresses
- Login credentials like secret keys and passwords
- Financial data like bank card numbers
- Medical data like medical license number
- Personally identifiable information (PII) like full name, passport number or SSN
Type/format of data sent in this parameter
Date and time when parameter information was last updated
Tracking changes in API¶
You can check what changes occurred in the API within the specified period of time. To do that, from the Changes since filter, select the appropriate period or date. The following marks will be displayed in the endpoint list:
New for the endpoints added to the list within the period.
Changed for the endpoints that have new or removed parameters. In the details of the endpoint such parameters will have a corresponding mark.
Removed for the endpoints that did not receive any traffic within the period. For each endpoint this period will be different - calculated based on the statistics of accessing each of the endpoints. If later the "removed" endpoint is discovered as having some traffic again it will be marked as "new".
Note that whatever period is selected, if nothing is highlighted with the New, Changed or Removed mark, this means there are no changes in API for that period.
Each time you open the API Discovery section, the Changes since filter goes to the
Last week state, which means only the changes occurred within the last week are highlighted.
Using the Changes since filter only highlights the endpoints changed within the selected period, but does not filter out endpoints without changes.
The Changes in API filter works differently and shows only endpoints changed within the selected period and filters out all the rest.
Let us consider the example: say your API today has 10 endpoints (there were 12, but 3 of them were removed 10 days ago). 1 of this 10 was added yesterday, 2 have changes in their parameters occurred 5 days ago for one and 10 days ago for another:
Each time you open the API Discovery section today, the Changes since filter will go to the
Last weekstate; page will display 10 endpoints, in the Changes column 1 of them will have the New mark, and 1 - the Changed mark.
Switch Changes since to
Last 2 weeks- 13 endpoints will be displayed, in the Changes column 1 of them will have the New mark, 2 - the Changed mark, and 3 - the Removed mark.
Set Changes in API to
Removed endpoints- 3 endpoints will be displayed, all with the Removed mark.
Change Changes in API to
New endpoints + Removed endpoints- 4 endpoints will be displayed, 3 with the Removed mark, and 1 with the New mark.
Switch Changes since back to
Last week- 1 endpoint will be displayed, it will have the New mark.
Working with risk score¶
The risk score allows you to understand which endpoints are most likely to be an attack target and therefore should be the focus of your security efforts.
Risk score may be from
1 (lowest) to
|1 to 3||Low||Gray|
|4 to 7||Medium||Orange|
|8 to 10||High||Red|
1means no risk factors for this endpoint.
Risk score is not displayed (
N/A) for the removed endpoints.
Sort by risk score in the Risk column.
Lowusing the Risk score filter.
Configuring risk score calculation
By default, the API Discovery module automatically calculates a risk score for each endpoint based on the well-proven risk factor weights. To adapt risk score estimation under your understanding of importance of factors, you can configure the weight of each factor and a risk score calculation method.
To understand what caused the risk score for the endpoint and how to reduce the risk, go to the endpoint details:
Monitoring attacks on API endpoints¶
Number of attacks on API endpoints for the last 7 days are displayed in the Hits column.
Request displaying only attacked endpoints by selecting in filters: Others → Attacked endpoints.
Sort by the Hits column.
To see attacks to some endpoint, click number in the Hits column:
The Events section will be displayed with the filter applied:
attacks last 7 days endpoint_id:<YOUR_ENDPOINT_ID>
You can also copy some endpoint URL to the clipboard and use it to search for the events. To do this, in this endpoint menu select Copy URL.
API inventory and rules¶
You can quickly create a new custom rule from any endpoint of API inventory:
In this endpoint menu select Create rule. The create rule window is displayed. The endpoint address is parsed into the window automatically.
In the create rule window, specify rule information and then click Create.
Download OpenAPI specification (OAS) of your API inventory¶
Click Download OAS to get a
swagger.json file with the API inventory discovered by Wallarm. The description will be in the OpenAPI v3 format.
When downloading the API inventory, applied filters are taken into account. Only filtered data is downloaded.
API host information in downloaded Swagger file
If a discovered API inventory contains several API hosts, endpoints from all API hosts will be included in the downloaded Swagger file. Currently, the API host information is not included in the file.
Using the downloaded data, you can discover:
The list of endpoints discovered by Wallarm, but absent in your specification (missing endpoints, also known as "Shadow API").
The list of endpoints presented in your specification but not discovered by Wallarm (endpoints that are not in use, also known as "Zombie API").
Automatic BOLA protection¶
Wallarm can automatically discover and protect endpoints that are vulnerable to the BOLA attacks among the ones explored by the API Discovery module. If the option is enabled, protected endpoints are highlighted with the corresponding icon in the API inventory, e.g.:
You can filter API endpoints by the BOLA auto protection state. The corresponding parameter is available under the Others filter.
Configuring API Discovery¶
By clicking the Configure API Discovery button in the API Discovery section, you proceed to the API discovery fine-tuning options, such as choosing applications for API discovery and customizing the risk score calculation.
Choosing applications for API Discovery¶
If the API Discovery subscription is purchased for your company account, you can enable/disable traffic analysis with API Discovery in Wallarm Console → API Discovery → Configure API Discovery.
You may enable/disable API Discovery for all applications or only the selected ones.
When you add a new application in Settings → Applications, it is automatically added to the list of applications for API discovery in the disabled state.
Customizing risk score calculation¶
You can configure the weight of each factor in risk score calculation and calculation method.
Use the highest weight from all criteria as endpoint risk score.
Default factor weights:
Factor Weight Active vulnerabilities 9 Potentially vulnerable to BOLA 6 Parameters with sensitive data 8 Number of query and body parameters 6 Accepts XML / JSON objects 6 Allows uploading files to the server 6
To change how risk score is calculated:
Click the Configure API Discovery button in the API Discovery section.
Select calculation method: highest or average weight.
If necessary, disable factors you do not want to affect a risk score.
Set weight for the remaining.
Save changes. Wallarm will re-calculate the risk score for your endpoints in accordance with the new settings in several minutes.