Feature/docs 2986 new api discovery #1580
Conversation
✅ Deploy Preview for pensive-dubinsky-5f7a00 ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
| * Required and optional parameters and headers of requests and responses including: | ||
|
|
||
| * [Type/format](./exploring.md#format-and-data-type) of data sent in each parameter | ||
| * Date and time when parameter information was last updated |
There was a problem hiding this comment.
@MaximBashurov Why don't we mention things like sensitive data type, risk score, number of requests, application and sensitive business flow? Not sure we need to add them: just want to understand why there are not listed along with other attributes of API entries and parameters.
There was a problem hiding this comment.
This part lists major objects: hosts, endpoints, and parameters of requests and responses. The remaining things are mentioned further on the same page.
|
|
||
| * Have a full visibility into the whole API estate. | ||
| * See what data ([REST](exploring.md#rest-endpoint-details), [GraphQL](exploring.md#graphql-operation-details)) is going into and out of the APIs. | ||
| * Get a list of endpoints with the open vulnerabilities. |
There was a problem hiding this comment.
@MaximBashurov List remove "vulnerabilities" for now. Yes, API Discovery will display any vuln related to a specific API endpoint (there are few of them) in the expanded "Risk score" section, but no specific filter or column for vulns. We are going to introduce more vulns and integrate API D with new product - Security issues (AASM) within https://wallarm.atlassian.net/browse/PROD-2798 and https://wallarm.atlassian.net/browse/DISC-10
|
|
||
| ### Noise detection | ||
|
|
||
| The API Discovery module bases noise detection on the two major traffic parameters: |
There was a problem hiding this comment.
@MaximBashurov We are not sure what will be the default stability threshold values (probably same - 5 requests with 200 response over 300 seconds), but we'll choose them within the task: https://wallarm.atlassian.net/browse/IO-2612
No edits here for now, just FYI
There was a problem hiding this comment.
Got it, thanks.
| * Only those requests to which the server responded in the 2xx range are processed. | ||
| * Requests that do not conform to the design principles of the REST or GraphQL API are not processed. | ||
|
|
||
| For REST, this is done by controlling the `Content-Type` header of responses: if it does not contain `application/json` (like `Content-Type: application/json;charset=utf-8`), the request is considered to be a non-REST API and is not analyzed. If the header does not exist, API Discovery analyzes the request. |
There was a problem hiding this comment.
@MaximBashurov let's modify it:
An entry should NOT be classified as a valid API call and not displayed in API Discovery if both following conditions is met:
- The request path contains a file extension (i.e., the last path segment does not match the pattern .*.[a-zA-Z0-9]+).
- The response Content-Type header
- is not present or
- is present and it is not starting with application/ and does not contain json after slash (case-insensitive match, without charset suffix).
|
|
||
| ### Sensitive data detection | ||
|
|
||
| API Discovery [detects and highlights](sensitive-data.md) sensitive data consumed and carried by your APIs: |
There was a problem hiding this comment.
@MaximBashurov Let's add AI prompts as a separate sensitive data group as well
There was a problem hiding this comment.
Added, but cannot actually see them in Sensitive data filter, let's discuss.
|
|
||
| In addition to automatic identification, you can manually adjust the assigned sensitive business flow tags and manually set tags for the endpoints of your choice. | ||
|
|
||
| Once endpoints are assigned with the sensitive business flow tags, it becomes possible to filter all discovered endpoint by a specific business flow which makes it easier on protecting the most critical business capabilities. |
There was a problem hiding this comment.
@MaximBashurov in new API Discovery users will operate with smth further than endpoints - API entries. We call them this way since for non-REST protocols one API endpoint represents multiple API entries with different schema, parameters and behaviour.
Since one record in API Discovery correlates with one API entry rather with endpoint, I suggest that we replace API endpoints with this new term or smth similar.
There was a problem hiding this comment.
Let's discuss.
There was a problem hiding this comment.
Discussed and decided to leave as it is for now.
docs/latest/api-discovery-2.0/sbf.md
Outdated
| @@ -0,0 +1,48 @@ | |||
| # Sensitive Business Flows <a href="../../about-wallarm/subscription-plans/#waap-and-advanced-api-security"><img src="../../images/api-security-tag.svg" style="border: none;"></a> | |||
|
|
|||
| With the sensitive business flow capability, Wallarm's [API Discovery](overview.md) can automatically identify endpoints that are critical to specific business flows and functions, such as authentication, account management, billing, and similar critical capabilities. Learn from this article how to use the sensitive business flow functionality. | |||
There was a problem hiding this comment.
@MaximBashurov I believe adding AI agents to the list would be nice in terms of our market positioning
docs/latest/api-discovery-2.0/sbf.md
Outdated
|
|
||
|  | ||
|
|
||
| You can do the same in the endpoint details. |
There was a problem hiding this comment.
@MaximBashurov for now, you cannot. We decided not to implement this capability since it is duplicating the same button in the list (which is visible even when the API entry is expanded). Let's skip this part.
|
|
||
| In the **Status** column for endpoints and parameters, API Discovery provides data about changes in your API for the last week: | ||
|
|
||
| * **New** for the endpoints discovered within a week. |
There was a problem hiding this comment.
@MaximBashurov I recommend replacing endpoint term with smth like API entry or route within the whole section.
|
|
||
|  | ||
|
|
||
| To change the time period, redefine dates in the **Changes since** filter. |
There was a problem hiding this comment.
@MaximBashurov Not relevant here. Changes since doesn't affect status column (opposed to old API Discovery). We believe it improves clarity of the user flow.
There was a problem hiding this comment.
Fixed. Suggest to rename filter from Changes since to Changed since, let's discuss along with other filters and UI changes ("endpoint" in UI).
|
|
||
|  | ||
|
|
||
| By default, endpoints and operations are sorted by host/endpoint or operation name. Also, **Group by host** is on. With grouping by host disabled, you can sort endpoints by risk. |
There was a problem hiding this comment.
@MaximBashurov we improved UI for sorting by risk score. Even when the grouping is on, user is able to apply sorting and disable the grouping at the same time.
There was a problem hiding this comment.
With that in mind, text is still correct: sorting is only possible with grouping off.
No description provided.