diff --git a/docs/5.0/api-discovery/bola-protection.md b/docs/5.0/api-discovery/bola-protection.md index cf4f86bf8c..535224c9ed 100644 --- a/docs/5.0/api-discovery/bola-protection.md +++ b/docs/5.0/api-discovery/bola-protection.md @@ -1 +1,15 @@ ---8<-- "latest/api-discovery/bola-protection.md" \ No newline at end of file +# Automatic Protection Against BOLA Attacks + +Behavioral attacks such as [Broken Object Level Authorization (BOLA)](../attacks-vulns-list.md#broken-object-level-authorization-bola) exploit the vulnerability of the same name. This vulnerability allows an attacker to access an object by its identifier via an API request and either read or modify its data bypassing an authorization mechanism. + +Potential targets of the BOLA attacks are endpoints with variability. Wallarm can automatically discover and protect such endpoints among the ones explored by the [API Discovery](overview.md) module. + +To enable automatic BOLA protection, proceed to Wallarm Console → [**BOLA protection**](../admin-en/configuration-guides/protecting-against-bola.md) and turn the switch to the enabled state: + +![BOLA trigger](../images/user-guides/bola-protection/trigger-enabled-state.png) + +Each protected API endpoint will be highlighted with the corresponding icon in the API inventory, e.g.: + +![BOLA trigger](../images/about-wallarm-waf/api-discovery/endpoints-protected-against-bola.png) + +You can filter API endpoints by the BOLA auto protection state. The corresponding parameter is available under the **Others** filter. diff --git a/docs/5.0/api-discovery/dashboard.md b/docs/5.0/api-discovery/dashboard.md index dba169a6fb..c4469b6cd3 100644 --- a/docs/5.0/api-discovery/dashboard.md +++ b/docs/5.0/api-discovery/dashboard.md @@ -3,4 +3,13 @@ search: exclude: true --- ---8<-- "latest/api-discovery/dashboard.md" \ No newline at end of file +[apid-overview]: overview.md +[apid-risk-score]: risk-score.md +[apid-track-changes]: track-changes.md +[apid-rogue]: rogue-api.md +[check-attack]: ../user-guides/events/check-attack.md +[img-api-discovery-widget]: ../images/user-guides/dashboard/api-discovery-widget.png + +# API Discovery Dashboard + +--8<-- "../include/api-discovery/dashboard-5.0.md" \ No newline at end of file diff --git a/docs/5.0/api-discovery/exploring.md b/docs/5.0/api-discovery/exploring.md index fffa6da9eb..e3355035cb 100644 --- a/docs/5.0/api-discovery/exploring.md +++ b/docs/5.0/api-discovery/exploring.md @@ -1 +1,143 @@ ---8<-- "latest/api-discovery/exploring.md" \ No newline at end of file +# Exploring API Inventory + +As soon as the [API Discovery](overview.md) module has built the catalog of your endpoints (your API inventory), you can explore it in the **API Discovery** section of Wallarm Console. Learn from this article how to go through the discovered data. + +## Endpoints + +Explore your discovered API inventory using the **API Discovery** section in the [US](https://us1.my.wallarm.com/api-discovery) or [EU](https://my.wallarm.com/api-discovery) Cloud. + +![Endpoints discovered by API Discovery](../images/about-wallarm-waf/api-discovery/discovered-api-endpoints.png) + +Each time you open the **API Discovery** section, you see all discovered endpoints and their [changes](track-changes.md) for the last week. With **Changes since** filter, you can change `Last week` to any other period. + +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. + +### External vs. internal + +The endpoints accessible from the external network are the main attack directions. Thus, it is important to see what is available from the outside and pay attention to these endpoints in the first place. + +Wallarm automatically splits discovered APIs to external and internal. The host with all its endpoints is considered to be internal if it is located on: + +* A private IP or local IP address +* A generic top-level domain (for example: localhost, dashboard, etc.) + +In the remaining cases the hosts are considered to be external. + +By default, a list with all API hosts (external and internal) is displayed. In the built API inventory, you can view your internal and external APIs separately. To do this, click **External** or **Internal**. + +### Filtering + +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 most vulnerable endpoints characterized by processing sensitive data and active vulnerabilities of the high [risk level](risk-score.md). 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. +* Find [rogue endpoints](rogue-api.md): shadow, orphan and zombie. +* 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](track-changes.md). +* 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. + +All filtered data can be exported in the OpenAPI v3 for additional analysis. + +## Endpoint details + +By clicking the endpoint, you can also find the endpoint details, including request statistics, headers and parameters of requests and responses with the relevant data types: + +![Request parameters discovered by API Discovery](../images/about-wallarm-waf/api-discovery/discovered-request-params-4.10.png) + +Each request/response parameter information includes: + +* Parameter name and the part of request/response this parameter belongs to +* Information about parameter changes (new, unused) +* Presence and type of sensitive data 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](#format-and-data-type) of data sent in this parameter +* Date and time when parameter information was last updated + +!!! info "Availability of response parameters" + Response parameters are only available when using node 4.10.1 or higher. + +### Format and data type + +In the **Type** column, Wallarm indicates the data format identified through traffic analysis or, if not specific, a general data type. + +Wallarm attempts to detect various data formats such as `Int32`, `Int64`, `Float`, `Double`, `Datetime`, `IPv4`/`IPv6`, among others. If a value does not conform to any recognized data format, Wallarm classifies it under a general data type, such as `Integer`, `Number`, `String`, or `Boolean`. + +This data allows checking that values of the expected format are passed in each parameter. Inconsistencies can be the result of an attack or a scan of your API, for example: + +* The `String` values ​​are passed to the field with `IP` +* The `Double` values are passed to the field where there should be a value no more than `Int32` + +### Variability + +URLs can include diverse elements, such as ID of user, like: + +* `/api/articles/author/author-a-0001` +* `/api/articles/author/author-a-1401` +* `/api/articles/author/author-b-1401` + +The **API Discovery** module unifies such elements into the `{parameter_X}` format in the endpoint paths, so for the example above you will not have 3 endpoints, but instead there will be one: + +* `/api/articles/author/{parameter_1}` + +Click the endpoint to expand its parameters and view which type was automatically detected for the diverse parameter. + +![API Discovery - Variability in path](../images/about-wallarm-waf/api-discovery/api-discovery-variability-in-path-4.10.png) + +Note that the algorithm analyzes the new traffic. If at some moment you see addresses, that should be unified but this did not happen yet, give it a time. As soon as more data arrives, the system will unify endpoints matching the newly found pattern with the appropriate amount of matching addresses. + +## Endpoint activities + +### Attacks + +Number of attacks on API endpoints for the last 7 days are displayed in the **Hits** column. You can request displaying only attacked endpoints by selecting in filters: **Others** → **Attacked endpoints**. + +To see attacks to some endpoint, click number in the **Hits** column: + +![API endpoint - open events](../images/about-wallarm-waf/api-discovery/endpoint-open-events.png) + +The **Attacks** section will be displayed with the [filter applied](../user-guides/search-and-filters/use-search.md): + +``` +attacks last 7 days 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**. + +### All activities + +The number of all requests related to the endpoint is displayed in the **Requests** column. Click this number to open the [**API Sessions**](../api-sessions/overview.md) section with the list of user sessions for the last week with these requests. + +Within each found session, only requests to your endpoint will be initially displayed - in session, remove filter by endpoint to see all requests for context. + +A structured view of session activity helps in understanding your endpoint place in malicious and legitimate activities, its relation to sensitive business flows and required protection measures. + +## Creating rules for API endpoints + +You can quickly create a new [custom rule](../user-guides/rules/rules.md) from any endpoint of API inventory: + +1. In this endpoint menu select **Create rule**. The create rule window is displayed. The endpoint address is parsed into the window automatically. +1. In the create rule window, specify rule information and then click **Create**. + +![Create rule from endpoint](../images/about-wallarm-waf/api-discovery/endpoint-create-rule.png) + +## Exporting API inventory data + +The API Discovery UI provides you with an option to export the current filtered list of endpoints as the [OpenAPI v3](https://spec.openapis.org/oas/v3.0.0) specification or CSV file. + +To export, in Wallarm Console → **API Discovery**, use the **OAS/CSV** option. Consider the following: + +* For **OAS**, Wallarm returns the `swagger.json` with filtered endpoints. You can also use the **Download OAS** button in an individual endpoint menu + + By utilizing the downloaded specification with other applications like Postman, you can conduct endpoints' vulnerability and other tests. In addition, it allows for a closer examination of the endpoints' capabilities to uncover the processing of sensitive data and the presence of undocumented parameters. + +* For **CSV**, Wallarm returns filtered endpoints data in a simple text comma-separated format, making it easy to export it into other programs. + +!!! warning "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 file. Currently, the API host information is not included in the file. diff --git a/docs/5.0/api-discovery/overview.md b/docs/5.0/api-discovery/overview.md index fbdcf07c49..d2d5758083 100644 --- a/docs/5.0/api-discovery/overview.md +++ b/docs/5.0/api-discovery/overview.md @@ -1 +1,122 @@ ---8<-- "latest/api-discovery/overview.md" \ No newline at end of file +# API Discovery Overview + +The **API Discovery** module of the Wallarm platform builds your application REST API inventory based on the actual API usage. The module continuously analyzes the real traffic requests and builds the API inventory based on the analysis results. + +The API built inventory includes the following elements: + +* API endpoints +* Request methods (GET, POST, and others) +* Required and optional GET, POST, and header parameters 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 + +!!! info "Availability of response parameters" + Response parameters are only available when using node 4.10.1 or higher. + +
+ +
+ +
+
+ +## Issues addressed by API Discovery + +**Building an actual and complete API inventory** is the main issue the API Discovery module is addressing. + +Keeping API inventory up-to-date is a difficult task. There are multiple teams that use different APIs and it is a common case that different tools and processes are used to produce the API documentation. As a result, companies struggle in both understanding what APIs they have, what data they expose and having up-to-date API documentation. + +Since the API Discovery module uses the real traffic as a data source, it helps to get up-to-date and complete API documentation by including to the API inventory all endpoints that are actually processing the requests. + +**As you have your API inventory discovered by Wallarm, you can**: + +* Have a full visibility into the whole API estate including the list of [external and internal](exploring.md#external-vs-internal) APIs. +* See [what data](exploring.md#endpoint-details) is going into and out of the APIs. +* Get a list of endpoints with the open vulnerabilities. +* Get a list of the threats that occurred over the past 7 days per any given API endpoint. +* Filter out only attacked APIs, sort them by number of hits. +* Filter APIs that consume and carry [sensitive data](#sensitive-data-detection). +* View visualized summary on your API inventory structure and problems on a handy [dashboard](dashboard.md). +* Understand which endpoints are [most likely](risk-score.md) to be an attack target. +* Find [shadow, orphan and zombie APIs](rogue-api.md). +* [Track changes](track-changes.md) in API that took place within the selected period of time. +* Filter API endpoints by the [BOLA auto protection state](bola-protection.md). +* Provide your developers with [access](../user-guides/settings/users.md#user-roles) to the built API inventory reviewing and downloading. + +## How does API Discovery work? + +API Discovery relies on request statistics and uses sophisticated algorithms to generate up-to-date API specs based on the actual API usage. + +### Traffic processing + +API Discovery uses a hybrid approach to conduct analysis locally and in the Cloud. This approach enables a [privacy-first process](#security-of-data-uploaded-to-the-wallarm-cloud) where request data and sensitive data are kept locally while using the power of the Cloud for the statistics analysis: + +1. API Discovery analyzes legitimate traffic locally. Wallarm analyzes the endpoints to which requests are made and what parameters are passed and returned. +1. According to this data, statistics are made and sent to the Cloud. +1. Wallarm Cloud aggregates the received statistics and builds an [API description](exploring.md) on its basis. + + !!! info "Noise detection" + Rare or single requests are [determined as noise](#noise-detection) and not included in the API inventory. + +### Noise detection + +The API Discovery module bases noise detection on the two major traffic parameters: + +* Endpoint stability - at least 5 requests must be recorded within 5 minutes from the moment of the first request to the endpoint. +* Parameter stability - the occurrence of the parameter in requests to the endpoint must be more than 1 percent. + +The API inventory will display the endpoints and parameters that exceeded these limits. The time required to build the complete API inventory depends on the traffic diversity and intensity. + +Also, the API Discovery performs filtering of requests relying on the other criteria: + +* 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 API are not processed. + + 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. + +* Standard fields such as `Accept` and alike are discarded. + +### Sensitive data detection + +API Discovery [detects and highlights](sensitive-data.md) sensitive data consumed and carried by your APIs: + +* 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 + +API Discovery provides the ability to configure the detection process and add your own sensitive data patterns (requires NGINX Node 5.0.3 or Native Node 0.7.0 or higher). + +### Security of data uploaded to the Wallarm Cloud + +API Discovery analyzes most of the traffic locally. The module sends to the Wallarm Cloud only the discovered endpoints, parameter names and various statistical data (time of arrival, their number, etc.) All data is transmitted via a secure channel: before uploading the statistics to the Wallarm Cloud, the API Discovery module hashes the values of request parameters using the [SHA-256](https://en.wikipedia.org/wiki/SHA-2) algorithm. + +On the Cloud side, hashed data is used for statistical analysis (for example, when quantifying requests with identical parameters). + +Other data (endpoint values, request methods, and parameter names) is not hashed before being uploaded to the Wallarm Cloud, because hashes cannot be restored to their original state which would make building API inventory impossible. + +!!! warning "Important" + Wallarm does not send the values that are specified in the parameters to the Cloud. Only the endpoint, parameter names and statistics on them are sent. + +## API Discovery demo video + +Watch API Discovery demo video: + +
+ +
+ +## Checking API Discovery in playground + +To try the module even before signing up and deploying the node to your environment, explore [API Discovery in Wallarm Playground](https://playground.wallarm.com/api-discovery/?utm_source=wallarm_docs_apid). + +In Playground, you can access the API Discovery view like it is filled with real data and thus learn and try out how the module works, and get some useful examples of its usage in the read-only mode. + +![API Discovery – Sample Data](../images/about-wallarm-waf/api-discovery/api-discovery-sample-data.png) + +## Enabling and configuring API Discovery + +To start using API Discovery, enable and configure it as described in [API Discovery Setup](setup.md). diff --git a/docs/5.0/api-discovery/risk-score.md b/docs/5.0/api-discovery/risk-score.md index 1c1aa13915..5c28b234ec 100644 --- a/docs/5.0/api-discovery/risk-score.md +++ b/docs/5.0/api-discovery/risk-score.md @@ -1 +1,55 @@ ---8<-- "latest/api-discovery/risk-score.md" \ No newline at end of file +# Endpoint Risk Score + +[API Discovery](overview.md) automatically calculates a **risk score** for each endpoint in your API inventory. 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 factors + +The risk score is made up of various factors, each having its own weight when calculating the final risk score. By default, the highest weight from all factors is used as endpoint risk score. + +| Factor | Description | Default weight | +| --- | --- | --- | +| Active vulnerabilities | [Active vulnerabilities](../about-wallarm/detecting-vulnerabilities.md) may result in unauthorized data access or corruption. | 9 | +| Potentially vulnerable to BOLA | Presence of the [variable path parts](exploring.md#variability), such as user IDs, e.g. `/api/articles/author/{parameter_X}`. Attackers can manipulate object IDs and, in case of insufficient request authentication, either read or modify the object sensitive data ([BOLA attacks](../admin-en/configuration-guides/protecting-against-bola.md)). | 6 | +| Parameters with sensitive data | Rather than directly attacking APIs, attackers can steal [sensitive data](overview.md#sensitive-data-detection) and use it to seamlessly reach your resources. | 8 | +| Number of query and body parameters | A large number of parameters increases the number of attack directions. | 6 | +| Accepts XML / JSON objects | XML or JSON objects passed in requests may be used by attackers to transfer malicious XML external entities and injections to the server. | 6 | +| Allows uploading files to the server | Endpoints are frequently targeted by [Remote Code Execution (RCE)](../attacks-vulns-list.md#remote-code-execution-rce) attacks, where files with malicious code are uploaded to a server. To secure these endpoints, uploaded file extensions and contents should be properly validated as recommended by the [OWASP Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html). | 6 | + +To adapt risk score estimation under your understanding of importance of factors, you can [configure](#customizing-risk-score-calculation) the weight of each factor in risk score calculation and calculation method. + +## Risk score levels + +Risk score may be from `1` (lowest) to `10` (highest): + +| Value | Risk level | Color | +| --------- | ----------- | --------- | +| 1 to 3 | Low | Gray | +| 4 to 7 | Medium | Orange | +| 8 to 10 | High | Red | + +* `1` means no risk factors for this endpoint. +* Risk score is not displayed (`N/A`) for the unused endpoints. +* Sort by risk score in the **Risk** column. +* Filter `High`, `Medium` or `Low` using the **Risk score** filter. + +To understand what caused the risk score for the endpoint and how to reduce the risk, go to the endpoint details: + +![API Discovery - Risk score](../images/about-wallarm-waf/api-discovery/api-discovery-risk-score.png) + +You can also get summary on APIs by their risk score levels in **Dashboards** → **API Discovery** in the [US](https://us1.my.wallarm.com/dashboard-api-discovery) or [EU](https://my.wallarm.com/dashboard-api-discovery) Cloud. + +## Customizing risk score calculation + +You can configure the weight of each factor in risk score calculation and calculation method. + +To change how risk score is calculated: + +1. Click the **Configure API Discovery** button in the **API Discovery** section. +1. Switch to the **Risk scoring** tab. +1. Select calculation method: highest or average weight. +1. If necessary, disable factors you do not want to affect a risk score. +1. Set weights for the remaining. + + ![API Discovery - Risk score setup](../images/about-wallarm-waf/api-discovery/api-discovery-risk-score-setup.png) + +1. Save changes. Wallarm will re-calculate the risk score for your endpoints in accordance with the new settings in several minutes. diff --git a/docs/5.0/api-discovery/sbf.md b/docs/5.0/api-discovery/sbf.md index 911f6a578c..5590d8e097 100644 --- a/docs/5.0/api-discovery/sbf.md +++ b/docs/5.0/api-discovery/sbf.md @@ -1 +1,50 @@ ---8<-- "latest/api-discovery/sbf.md" \ No newline at end of file +# Sensitive Business Flows + +With the sensitive business flow capability, Wallarm's [API Discovery](overview.md) can automatically identifies 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. + +Requires NGINX Node 5.2.11 or Native Node 0.10.1 or higher. + +## Addressed issues + +The abuse of the sensitive business flows ranks sixth ([API6](https://owasp.org/API-Security/editions/2023/en/0xa6-unrestricted-access-to-sensitive-business-flows/)) among OWASP API Top 10 risks. Protecting these sensitive business flows ensures business continuity, prevents leaking of sensitive data, reputation risks, and financial damage. + +WIth the sensitive business flows capability, Wallarm highlights health of the business-critical functions and helps to: + +* Regularly monitor and audit endpoints related to sensitive business flows for vulnerabilities or breaches. +* Prioritize them for development, maintenance, and security efforts. +* Implement stronger security measures (e.g., encryption, authentication, access controls, and rate limits). +* Easily produce audit trails and evidence of data protection measures. + +## Automatic tagging + +For your convenience, API Discovery tags endpoints as belonging to sensitive business flows automatically - on discovering a new endpoint, it checks whether this endpoint potentially belongs to one or more sensitive business flows: + +--8<-- "../include/default-sbf.md" + +Automatic checks are conducted using keywords from the endpoint URL. For example, keywords like `payment`, `subscription`, or `purchase` automatically associate the endpoint with the **Billing** flow, while keywords such as `auth`, `token`, or `login` link it to the **Authentication** flow. If matches are detected, the endpoint is automatically assigned to the appropriate flow. + +The automatic tagging discovers most of the sensitive business flows. However, it is also possible to manually adjust the list of assigned business flows as described in the section below. + +## Tagging endpoints manually + +To adjust the results of [automatic tagging](#automatic-tagging), you can manually edit the list of sensitive business flow the endpoint belongs to. You can also manually tag endpoints that do not directly fall under the keyword list. + +To edit the list of flows the endpoint belongs to, in Wallarm Console, go to API Discovery, then for your endpoint, in the **Business flow & sensitive data**, select one or several flows from the list. + +![API Discovery - Sensitive business flows](../images/about-wallarm-waf/api-discovery/api-discovery-sbf.png) + +You can do the same in the endpoint details. + +## Business flows in Sessions + +Wallarm's [API Sessions](../api-sessions/overview.md) are used to provide you with the full sequence of user activities and thus give more visibility into the logic of malicious actors. If session's requests affect the endpoints that in API Discovery were tagged as important for some sensitive business flows, such session will be automatically [tagged](../api-sessions/exploring.md#sensitive-business-flows) as affecting this business flow as well. + +Once sessions are assigned with the sensitive business flow tags, it becomes possible to filter them by a specific business flow which makes it easier to select the sessions that are most important to analyze. + +![!API Sessions - sensitive business flows](../images/api-sessions/api-sessions-sbf-no-select.png) + +## Filtering by business flow + +Once endpoints are assigned with the sensitive business flow tags, it becomes possible to filter all discovered endpoint by a specific business flow (the **Business flow** filter) which makes it easier on protecting the most critical business capabilities. + +![API Discovery - Filtering by sensitive business flows](../images/about-wallarm-waf/api-discovery/api-discovery-sbf-filter.png) diff --git a/docs/5.0/api-discovery/sensitive-data.md b/docs/5.0/api-discovery/sensitive-data.md index 9e95720c08..6061f91639 100644 --- a/docs/5.0/api-discovery/sensitive-data.md +++ b/docs/5.0/api-discovery/sensitive-data.md @@ -1 +1,74 @@ ---8<-- "latest/api-discovery/sensitive-data.md" \ No newline at end of file +# Sensitive Data Detection + +API Discovery detects and highlights sensitive data consumed and carried by your APIs, which allows applying encryption, tokenization, or other security controls to protect it and prevent data breaches and transmitting sensitive data across insecure channels or to unauthorized systems. This article describes how to use and configure the feature. + +You get Wallarm's sensitive data detection ready-to-use with the comprehensive default configuration. It is also highly customizable: you can fine-tune the existing detection process and extend it with your own data types to detect. + +## Detection by default + +By default, API Discovery detects the following types of sensitive data: + +* 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 + +In Wallarm Console, go to **API Discovery** → **Configure API Discovery** → **Sensitive data** to check the list of default [sensitive data patterns](#customizing-sensitive-data-detection) provided for each of listed types. + +## Customizing sensitive data detection + +To make sensitive data detection fully comply with your company's specific needs and industry-specific regulations such as GDPR, HIPAA, PCI DSS, etc., API Discovery provides the ability to fine-tune the detection process (requires NGINX Node 5.0.3 or Native Node 0.7.0 or higher). + +Customization empowers you to meet your company's unique data protection obligations. Additionally, if any proprietary or specialized sensitive data elements are presented in your data flows, you will benefit from the ability to define custom regular expressions for their precise identification. + +Sensitive data detection is configured with the set **sensitive data patterns** - each pattern defines specific sensitive data and settings for its search. API Discovery goes with the set of default patterns. You can modify default patterns and add your own in Wallarm Console → **API Discovery** → **Configure API Discovery** → **Sensitive data**. + +You can modify or disable the default (out-of-box) patterns and quickly restore them to initial settings if necessary. Your own patterns can be created, modified, disabled and deleted at any moment. + +**Confidence scores** + +You can use patterns and context words to configure your sensitive data detection. Choose the confidence scores from `0.1` to `1.0` for your patterns and context words to specify how confident you are that matching this expression or the presence of the string or word next to the sensitive data means the presence of sensitive data. Use appropriate scores to detect more real entities and produce fewer false positives. + +The sensitive data is detected if score threshold of `0.3` is reached or exceeded: the context word scores are summed up, from the patterns the biggest is taken. See examples below for better understanding. + +You should adjust confidence scores after trying them on actual traffic data. + +**Pattern-based detection** + +Use a regular expression in [PCRE](https://www.pcre.org/) format to match the expected sensitive data value. When you use a regular expression, detection becomes much more precise. You can use several patterns with different scores. If any is matched, the sensitive data is detected. + +Patterns are suitable for fixed-length tokens, IDs, and URIs. + +**Context words** + +Wallarm looks at the words around the suspected sensitive data that match the pattern. If any of the context words is found, it boosts the resulting confidence score. The context can come from URL path, query parameter name, JSON keys, and other parameters next to it. + +![API Discovery – Settings - Sensitive data](../images/about-wallarm-waf/api-discovery/api-discovery-settings-sd.png) + +For example, on the picture above, the sensitive data will be detected: + +* Immediately if the match to `JWT` or `AWS access key ID` pattern is found. +* If the match to `AWS key (weak)` is found, by itself it will not result "yes" (score of `0.1` is below threshold of `0.3`). +* But with the context words `access` (`0.1`) and `api` (`0.1`) the sum becomes `0.3` and sensitive data is detected. +* If we mark `auth` as mandatory, the situation changes: in absence of `auth`, scores of presented `access` and `api` will be ignored and cannot boost the pattern's score. + +**Context word only-based detection** + +If you specify context words without patterns, Wallarm decides on sensitive data presence based on the presence of the words. The more the confidence scores sum, the more likely the parameter will be marked as having your described sensitive data. + +For some context-only searches, it is necessary to declare some words as **mandatory**: if the mandatory word is not presented in the value's context, the parameter does not contain sensitive data. + +Example: personal_name + +Context words: + +* name +* first +* middle + +We must match `middle_name,` but not `name` or `middle`. So, we set a score for `name` to `0.1` so we will not match `name`. But we must give `middle` a big score of `0.5` because "middle_name" is a strong combination. + +To prevent us from detecting "middle" without `name,` we mark `name` as mandatory for an entity. If `name` is not found, no sensitive data is detected. + +![API Discovery – Settings - Sensitive data - Creating custom pattern](../images/about-wallarm-waf/api-discovery/api-discovery-settings-sd-own-pattern.png) diff --git a/docs/5.0/api-discovery/track-changes.md b/docs/5.0/api-discovery/track-changes.md index f2bb9eb5a5..84b8eba797 100644 --- a/docs/5.0/api-discovery/track-changes.md +++ b/docs/5.0/api-discovery/track-changes.md @@ -1 +1,94 @@ ---8<-- "latest/api-discovery/track-changes.md" \ No newline at end of file +# Tracking changes in API + +If changes occur in your API, [API Discovery](overview.md) updates the built API inventory, highlights the changes and gives you information on when and what has changed. Additionally, you can set up notifications on all or some of the changes. + +![API Discovery - track changes](../images/about-wallarm-waf/api-discovery/api-discovery-track-changes.png) + +The company may have several teams, disparate programming languages, and a variety of language frameworks. Thus changes can come to API at any time from different sources which make them difficult to control. For security officers it is important to detect changes as soon as possible and analyze them. If missed, such changes may hold some risks, for example: + +* The development team can start using a third-party library with a separate API and they do not notify the security specialists about that. This way the company gets endpoints that are not monitored and not checked for vulnerabilities. They can be potential attack directions. +* The PII data begin to be transferred to the endpoint. An unplanned transfer of PII can lead to a violation of compliance with the requirements of regulators, as well as lead to reputational risks. +* Important for the business logic endpoint (for example, `/login`, `/order/{order_id}/payment/`) is no longer called. +* Other parameters that should not be transferred, for example `is_admin` (someone accesses the endpoint and tries to do it with administrator rights) begin to be transferred to the endpoint. + +## Highlighting changes in API + +Each time you open the **API Discovery** section, the **Changes since** filter goes to the `Last week` state, which means the changes occurred within the last week are highlighted. To change the time period, redefine dates in the **Changes since** filter. + +In the endpoint list, the following marks highlight the changes in API: + +* **New** for the endpoints added to the list within the period. +* **Changed** for the endpoints that have newly discovered parameters or parameters that obtained the `Unused` status within the period. In the details of the endpoint such parameters will have a corresponding mark. + + * A parameter gets the `New` status if is is discovered within the period. + * A parameter gets the `Unused` status if it does not pass any data for 7 days. + * If later the parameter in the `Unused` status passes data again it will lose the `Unused` status. + +* **Unused** for the endpoints that obtained the `Unused` status within the period. + + * An endpoint gets the `Unused` status if it is not requested (with the code 200 in response) for 7 days. + * If later the endpoint in the `Unused` status is requested (with the code 200 in response) again it will lose the `Unused` status. + +Note that whatever period is selected, if nothing is highlighted with the **New**, **Changed** or **Unused** mark, this means there are no changes in API for that period. + +![API Discovery - track changes](../images/about-wallarm-waf/api-discovery/api-discovery-track-changes.png) + +Quick tips for endpoints marked as rogue: + +* Mouse over the **New**, **Changed** or **Unused** labels to see when the change happened +* Go to **Changed** endpoint details to see reason of this status: **New** parameters and parameters that got **Unused** status - mouse over labels to see when the parameter change occurred +* Counters for all types of changes for the last 7 days are displayed at the [API Discovery Dashboard](dashboard.md). + + +## Filtering changes in API + +In the **API Discovery** section, 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 marked unused 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 week` state; 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 **Unused** mark. +* Set **Changes in API** to `Unused endpoints` - 3 endpoints will be displayed, all with the **Unused** mark. +* Change **Changes in API** to `New endpoints + Unused endpoints` - 4 endpoints will be displayed, 3 with the **Unused** 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. + +## Getting notified + +To get immediate notifications about changes in API to your messenger, SIEM or log management system, configure [triggers](../user-guides/triggers/triggers.md) with the **Changes in API** condition. + +You can get messages about new, changed or unused endpoints or about all of these changes. You can also narrow notifications by application or host that you want to monitor and by the type of presented sensitive data. + +**Trigger example: notification about new endpoints in Slack** + +In this example, if new endpoints for the `example.com` API host are discovered by the API Discovery module, the notification about this will be sent to your configured Slack channel. + +![Changes in API trigger](../images/user-guides/triggers/trigger-example-changes-in-api.png) + +**To test the trigger:** + +1. Go to Wallarm Console → **Integrations** in the [US](https://us1.my.wallarm.com/integrations/) or [EU](https://my.wallarm.com/integrations/) cloud, and configure [integration with Slack](../user-guides/settings/integrations/slack.md). +1. In the **Triggers** section, create a trigger as shown above. +1. Send several requests to the `example.com/users` endpoint to get the `200` (`OK`) response. +1. In the **API Discovery** section, check that your endpoint was added with the **New** mark. +1. Check messages in your Slack channel like: + ``` + [wallarm] A new endpoint has been discovered in your API + + Notification type: api_structure_changed + + The new GET example.com/users endpoint has been discovered in your API. + + Client: Client 001 + Cloud: US + + Details: + + application: Application 1802 + domain: example.com + endpoint_path: /users + http_method: GET + change_type: added + link: https://my.wallarm.com/api-discovery?instance=1802&method=GET&q=example.com%2Fusers + ``` diff --git a/docs/latest/about-wallarm/protecting-against-attacks.md b/docs/latest/about-wallarm/protecting-against-attacks.md index ea7e6d8c61..ebc9ae4093 100644 --- a/docs/latest/about-wallarm/protecting-against-attacks.md +++ b/docs/latest/about-wallarm/protecting-against-attacks.md @@ -1,6 +1,6 @@ [rule-creation-options]: ../user-guides/events/check-attack.md#attack-analysis_1 [request-processing]: ../user-guides/rules/request-processing.md -[api-discovery-enable-link]: ../api-discovery/setup.md#enable +[api-discovery-enable-link]: ../api-discovery/setup.md#enabled-by-default [ip-lists-link]: ../user-guides/ip-lists/overview.md [ip-sessions-link]: ../api-sessions/blocking.md#blocking-sessions [parsing-requests-link]: ../user-guides/rules/request-processing.md diff --git a/docs/latest/about-wallarm/subscription-plans.md b/docs/latest/about-wallarm/subscription-plans.md index 2274b43535..195cf658a1 100644 --- a/docs/latest/about-wallarm/subscription-plans.md +++ b/docs/latest/about-wallarm/subscription-plans.md @@ -6,7 +6,7 @@ Wallarm is the only solution that unifies API discovery, risk management, real-t **Cloud Native WAAP** - WAAP (Web Application & API Protection) subscription provides web applications and APIs with protection against common threats such as SQLi, XSS, brute force, etc. It supports all API protocols but does not cover some specific API threats. -**WAAP + Advanced API Security**. This bundle enhances general WAAP capabilities with comprehensive API Security tools to cover all OWASP API Top-10 threats. +**WAAP + Advanced API Security** . This bundle enhances general WAAP capabilities with comprehensive API Security tools to cover all OWASP API Top-10 threats. **Security Testing**. This bundle helps you proactively uncover security vulnerabilities in your applications and APIs before attackers do. diff --git a/docs/latest/admin-en/configure-wallarm-mode.md b/docs/latest/admin-en/configure-wallarm-mode.md index 93751e6e39..b6f5e09380 100644 --- a/docs/latest/admin-en/configure-wallarm-mode.md +++ b/docs/latest/admin-en/configure-wallarm-mode.md @@ -1,4 +1,4 @@ -[api-discovery-enable-link]: ../api-discovery/setup.md#enable +[api-discovery-enable-link]: ../api-discovery/setup.md [link-wallarm-mode-override]: ../admin-en/configure-parameters-en.md#wallarm_mode_allow_override [rule-creation-options]: ../user-guides/events/check-attack.md#attack-analysis_1 [acl-access-phase]: ../admin-en/configure-parameters-en.md#wallarm_acl_access_phase diff --git a/docs/latest/api-abuse-prevention/exceptions.md b/docs/latest/api-abuse-prevention/exceptions.md index a5fa37eff0..d9203811c8 100644 --- a/docs/latest/api-abuse-prevention/exceptions.md +++ b/docs/latest/api-abuse-prevention/exceptions.md @@ -1,4 +1,4 @@ -[api-discovery-enable-link]: ../api-discovery/setup.md#enable +[api-discovery-enable-link]: ../api-discovery/setup.md # API Abuse Prevention Exceptions diff --git a/docs/latest/api-attack-surface/setup.md b/docs/latest/api-attack-surface/setup.md index 85903aa54b..c7f96d7b39 100644 --- a/docs/latest/api-attack-surface/setup.md +++ b/docs/latest/api-attack-surface/setup.md @@ -191,7 +191,7 @@ Navigate back from configuration dialog to the main **API Attack Surface** scree You automatically receive notifications to your personal email (the one you use to log in) about discovered hosts and security issues in a **Weekly AASM statistics** - information about hosts, APIs, and statistics for security issues discovered for your configured domains within last week. -The notifications are enabled by default. You can unsubscribe at any moment and configure any additional emails to get all or some of these notifications in Wallarm Console → **Configuration** → **Integrations** → **Email and messengers** → **Personal email** (you email) or **Email report** (extra emails) as described [here][link-integrations-email]. +The notifications are enabled by default. You can unsubscribe at any moment and configure any additional emails to get all or some of these notifications in Wallarm Console → **Configuration** → **Integrations** → **Email and messengers** → **Personal email** (your email) or **Email report** (extra emails) as described [here][link-integrations-email]. Additionally, the notifications about security issues detected by [all methods](../about-wallarm/detecting-vulnerabilities.md#detection-methods), including AASM, can be received. This includes: diff --git a/docs/latest/api-discovery/bola-protection.md b/docs/latest/api-discovery/bola-protection.md index 5cf1e05f70..da3465a304 100644 --- a/docs/latest/api-discovery/bola-protection.md +++ b/docs/latest/api-discovery/bola-protection.md @@ -1,5 +1,8 @@ # Automatic Protection Against BOLA Attacks +!!! warning "Feature availability" + In the latest versions of API Discovery, this feature is under reconstruction and may be temporarily unavailable. + Behavioral attacks such as [Broken Object Level Authorization (BOLA)](../attacks-vulns-list.md#broken-object-level-authorization-bola) exploit the vulnerability of the same name. This vulnerability allows an attacker to access an object by its identifier via an API request and either read or modify its data bypassing an authorization mechanism. Potential targets of the BOLA attacks are endpoints with variability. Wallarm can automatically discover and protect such endpoints among the ones explored by the [API Discovery](overview.md) module. diff --git a/docs/latest/api-discovery/dashboard.md b/docs/latest/api-discovery/dashboard.md index 88b89566ea..6039b509d3 100644 --- a/docs/latest/api-discovery/dashboard.md +++ b/docs/latest/api-discovery/dashboard.md @@ -3,7 +3,7 @@ [apid-track-changes]: track-changes.md [apid-rogue]: rogue-api.md [check-attack]: ../user-guides/events/check-attack.md -[img-api-discovery-widget]: ../images/user-guides/dashboard/api-discovery-widget.png +[img-api-discovery-dashboard]: ../images/about-wallarm-waf/api-discovery-2.0/api-discovery-dashboard.png # API Discovery Dashboard diff --git a/docs/latest/api-discovery/exploring.md b/docs/latest/api-discovery/exploring.md index e443617208..b01a45fd2b 100644 --- a/docs/latest/api-discovery/exploring.md +++ b/docs/latest/api-discovery/exploring.md @@ -1,4 +1,4 @@ -# Exploring API Inventory +# Exploring API Inventory As soon as the [API Discovery](overview.md) module has built the catalog of your endpoints (your API inventory), you can explore it in the **API Discovery** section of Wallarm Console. Learn from this article how to go through the discovered data. @@ -6,119 +6,174 @@ As soon as the [API Discovery](overview.md) module has built the catalog of your Explore your discovered API inventory using the **API Discovery** section in the [US](https://us1.my.wallarm.com/api-discovery) or [EU](https://my.wallarm.com/api-discovery) Cloud. -![Endpoints discovered by API Discovery](../images/about-wallarm-waf/api-discovery/discovered-api-endpoints.png) +![API Discovery - built API inventory](../images/about-wallarm-waf/api-discovery-2.0/api-discovery-built-inventory.png) -Each time you open the **API Discovery** section, you see all discovered endpoints and their [changes](track-changes.md) for the last week. With **Changes since** filter, you can change `Last week` to any other period. - -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. - -### External vs. internal - -The endpoints accessible from the external network are the main attack directions. Thus, it is important to see what is available from the outside and pay attention to these endpoints in the first place. - -Wallarm automatically splits discovered APIs to external and internal. The host with all its endpoints is considered to be internal if it is located on: - -* A private IP or local IP address -* A generic top-level domain (for example: localhost, dashboard, etc.) - -In the remaining cases the hosts are considered to be external. - -By default, a list with all API hosts (external and internal) is displayed. In the built API inventory, you can view your internal and external APIs separately. To do this, click **External** or **Internal**. +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. ### Filtering 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 most vulnerable endpoints characterized by processing sensitive data and active vulnerabilities of the high [risk level](risk-score.md). 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. -* Find [rogue endpoints](rogue-api.md): shadow, orphan and zombie. +* Find the endpoints characterized with the highest [risk level](risk-score.md) to analyze and mitigate the risks. +* Find endpoints related to specific [application](../user-guides/settings/applications.md). * 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](track-changes.md). -* 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 being used to upload data to your server by the PUT or POST calls (REST) or mutations (GraphQL) (**API protocols** filter with methods for REST and operation types for Graph QL). 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 sensitive data to ensure they are properly secured. * Find the endpoints of a deprecated API version (e.g. by searching `/v1`) and make sure that they are not used by clients. -All filtered data can be exported in the OpenAPI v3 for additional analysis. +### Labeling + +You can create labels (e.g., `P90`, `HighTraffic`, `Legacy`, etc.) and assign them to endpoints to manage them more effectively. Once labels are assigned, use the **Label** filter to quickly search and isolate endpoints based on these custom labels. + +![API Discovery - labels](../images/about-wallarm-waf/api-discovery-2.0/api-discovery-labels.png) -## Endpoint details +Note that several labels can be assigned to the same endpoint. -By clicking the endpoint, you can also find the endpoint details, including request statistics, headers and parameters of requests and responses with the relevant data types: +## REST endpoint details -![Request parameters discovered by API Discovery](../images/about-wallarm-waf/api-discovery/discovered-request-params-4.10.png) +By clicking the REST endpoint, you can find its details, including transferred sensitive data, risk score and what contributes to it, headers and parameters of requests and responses: + +![API Discovery - REST endpoint details](../images/about-wallarm-waf/api-discovery-2.0/api-discovery-endpoint-details-REST.png) Each request/response parameter information includes: * Parameter name and the part of request/response this parameter belongs to +* Path: the hierarchical location of a parameter within a REST query structure (not displayed, if all parameters are stored in the same root location) * Information about parameter changes (new, unused) * Presence and type of sensitive data transmitted by this parameter, including: - * Technical data like IP and MAC addresses + * Personally identifiable information (PII) like full name, passport number or SSN * 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](#format-and-data-type) of data sent in this parameter -* Date and time when parameter information was last updated + * Technical data like IP and MAC addresses -!!! info "Availability of response parameters" - Response parameters are only available when using node 4.10.1 or higher. +* [Type/format](#data_format_rest) of data sent in this parameter +* Date and time when parameter value was last transferred by requests -### Format and data type +**REST format and data type** -In the **Type** column, Wallarm indicates the data format identified through traffic analysis or, if not specific, a general data type. +In REST endpoint details, in the **Type** column for parameters of request and responses, Wallarm indicates the data format identified through traffic analysis or, if not specific, a general data type. -Wallarm attempts to detect various data formats such as `Int32`, `Int64`, `Float`, `Double`, `Datetime`, `IPv4`/`IPv6`, among others. If a value does not conform to any recognized data format, Wallarm classifies it under a general data type, such as `Integer`, `Number`, `String`, or `Boolean`. +For REST endpoints, Wallarm attempts to detect various data formats such as `Int32`, `Int64`, `Float`, `Double`, `Datetime`, `IPv4`/`IPv6`, among others. If a value does not conform to any recognized data format, Wallarm classifies it under a general data type, such as `Integer`, `Number`, `String`, or `Boolean`. This data allows checking that values of the expected format are passed in each parameter. Inconsistencies can be the result of an attack or a scan of your API, for example: * The `String` values ​​are passed to the field with `IP` * The `Double` values are passed to the field where there should be a value no more than `Int32` -### Variability +## GraphQL operation details -URLs can include diverse elements, such as ID of user, like: +By clicking the GraphQL operation, you can find its details, including transferred sensitive data, risk score and what contributes to it, schema, parameters and headers of requests and responses: -* `/api/articles/author/author-a-0001` -* `/api/articles/author/author-a-1401` -* `/api/articles/author/author-b-1401` +![API Discovery - GraphQL operation details](../images/about-wallarm-waf/api-discovery-2.0/api-discovery-endpoint-details-GQL.png) -The **API Discovery** module unifies such elements into the `{parameter_X}` format in the endpoint paths, so for the example above you will not have 3 endpoints, but instead there will be one: +Each request/response parameter information includes: -* `/api/articles/author/{parameter_1}` +* Parameter name and the part of request/response this parameter belongs to +* Path: the hierarchical location of a parameter within a GraphQL query structure (not displayed, if all parameters are stored in the same root location) +* Information about parameter changes (new, unused) +* Presence and type of sensitive data transmitted by this parameter, including: +* Date and time when parameter value was last transferred by requests -Click the endpoint to expand its parameters and view which type was automatically detected for the diverse parameter. +**Format and data type** -![API Discovery - Variability in path](../images/about-wallarm-waf/api-discovery/api-discovery-variability-in-path-4.10.png) +In GraphQL operation details, in the **Type** column for parameters and headers, Wallarm indicates the data format identified through traffic analysis. -Note that the algorithm analyzes the new traffic. If at some moment you see addresses, that should be unified but this did not happen yet, give it a time. As soon as more data arrives, the system will unify endpoints matching the newly found pattern with the appropriate amount of matching addresses. +For GraphQL operations, data formats are detected in accordance with the [scalar types](https://graphql.org/learn/schema/#scalar-types) specification: -## Endpoint activities +* `Int`: A signed 32‐bit integer. +* `Float`: A signed double-precision floating-point value. +* `String`: A UTF‐8 character sequence. +* `Boolean`: true or false. + +## SOAP operation details -### Attacks +By clicking the SOAP operation, you can find its details, including transferred sensitive data, risk score and what contributes to it, XML body parameters, HTTPS and XML headers of requests and responses: -Number of attacks on API endpoints for the last 7 days are displayed in the **Hits** column. You can request displaying only attacked endpoints by selecting in filters: **Others** → **Attacked endpoints**. +![API Discovery - SOAP operation details](../images/about-wallarm-waf/api-discovery-2.0/api-discovery-endpoint-details-SOAP.png) -To see attacks to some endpoint, click number in the **Hits** column: +Each request/response XML parameter information includes: + +* Parameter name (**Key**) +* Path: the hierarchical location of a parameter within an XML structure (not displayed, if all parameters are stored in the same root location) +* Parameter type +* Namespaces for path elements (from more general to more specific) +* Presence and type of sensitive data transmitted by this parameter +* Information about parameter changes (new, unused) +* Date and time when parameter value was last transferred by requests -![API endpoint - open events](../images/about-wallarm-waf/api-discovery/endpoint-open-events.png) +**Format and data type** -The **Attacks** section will be displayed with the [filter applied](../user-guides/search-and-filters/use-search.md): +In SOAP operation details, in the **Type** column for parameters and headers, Wallarm indicates the data format identified through traffic analysis. -``` -attacks last 7 days endpoint_id: -``` +For SOAP operations, it is a limited set from the [built-in primitive XML data types](https://www.w3.org/TR/xmlschema-2/#built-in-primitive-datatypes): -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**. +* soapTypeString = `String` +* soapTypeBoolean = `Boolean` +* soapTypeFloat = `Float` +* soapTypeDecimal = `Decimal` +* soapTypeDuration = `Duration` +* soapTypeURI = `URI` -### All activities +## Endpoint activities -The number of all requests related to the endpoint is displayed in the **Requests** column. Click this number to open the [**API Sessions**](../api-sessions/overview.md) section with the list of user sessions for the last week with these requests. +The number of requests related to the endpoint is displayed in the **Requests** column. Click this number to open the [**API Sessions**](../api-sessions/overview.md) section with the list of user sessions for the last week with these requests. Within each found session, only requests to your endpoint will be initially displayed - in session, remove filter by endpoint to see all requests for context. A structured view of session activity helps in understanding your endpoint place in malicious and legitimate activities, its relation to sensitive business flows and required protection measures. -## Creating rules for API endpoints +## Variability + +### Path variability + +Without unifying variable path segments, the same logical endpoint would appear many times in your inventory—once per distinct value (e.g., one entry per user ID). That would inflate the catalog, make it hard to see your real API surface, and complicate risk analysis and change tracking. API Discovery normalizes these varying segments so you get one endpoint per unique path pattern and can manage and secure your APIs effectively. + +These varying segments are diverse elements in URLs, such as user IDs. API Discovery **automatically** detects them for UUID, INTEGER, FLOAT and HEX path segment types. In some specific cases, automatic variability can work on a wider scope of parameter types. + +* `/api/users/profile/a1b2c3d4-e5f6-7890-1234-567890abcdef12` +* `/api/users/profile/f0e9d8c7-b6a5-4321-fedc-ba9876543210` +* `/api/users/profile/1a2b3c4d-5e6f-7080-9102-34567890fedc` + +The module unifies such elements into the `{parameter_X}` format in the endpoint path. For the example above you therefore get one endpoint instead of three: + +* `/api/users/profile/{parameter_1}` + +Click the endpoint to expand its parameters and see which type (UUID, INTEGER, FLOAT or HEX) was automatically detected for each unified parameter. + +In endpoint path string, click the `{parameter_1}` unified path element to review its info. Note that automatically detected variability cannot be disabled or modified. + +![API Discovery - variability in path](../images/about-wallarm-waf/api-discovery-2.0/api-discovery-variability-in-path.png) + +Besides automatic one, API Discovery provides [custom manual variability](setup.md#custom-manual-variability). + +### Host variability + +Besides path variability, API Discovery provides automatic **host variability** as well. + +## CSV reports + +You can download the report on your API inventory in CSV format: + +1. Optionally, apply filters. Only data remaining after filter apply will go to report. +1. Click **Download CSV**. + + This will instantly generate a CSV file with list of your APIs, including all key attributes, including risk score, sensitive data types and more. + + !!! info "No parameter information" + The report does not include the information on API endpoint parameters. + +## Notifications + +You can [setup](setup.md#notifications) API Discovery notifications to be sent to your personal email (the one you use to log in) and to any additional emails: + +* Daily endpoint changes +* Hourly endpoint changes + +The notification will include both [changed and new](track-changes.md) endpoints. By default, the notification is disabled. + + \ No newline at end of file diff --git a/docs/latest/api-discovery/overview.md b/docs/latest/api-discovery/overview.md index 919a45b614..fb60170414 100644 --- a/docs/latest/api-discovery/overview.md +++ b/docs/latest/api-discovery/overview.md @@ -1,47 +1,51 @@ # API Discovery Overview -The **API Discovery** module of the Wallarm platform builds your application REST API inventory based on the actual API usage. The module continuously analyzes the real traffic requests and builds the API inventory based on the analysis results. +Wallarm's multi-protocol API Discovery continuously analyzes the real traffic requests and builds the API inventory (full picture of your active APIs) based on the analysis results. -The API built inventory includes the following elements: +## Supported protocols -* API endpoints -* Request methods (GET, POST, and others) -* Required and optional GET, POST, and header parameters of requests and responses including: - * [Type/format](./exploring.md#format-and-data-type) of data sent in each parameter +API Discovery is capable of finding and representing hosts and endpoints utilizing different protocols. The following protocols are supported: + +| Protocol | Core entity | Required [NGINX Node](../installation/nginx-native-node-internals.md#nginx-node) version | Required [Native Node](../installation/nginx-native-node-internals.md#native-node) version | +| --- | --- | --- | --- | +| **REST** | Endpoint | Any | Any | +| **GraphQL** | Operation (query, mutation, subscription) | 6.1.0 | NA | +| **SOAP** | Operation | 6.3.0 | NA | + +## Your API inventory + +API inventory is a picture of your active APIs automatically built by Wallarm's API Discovery based on traffic going through Wallarm nodes. It includes: + +* API hosts and their endpoints +* Required and optional parameters and headers of requests and responses including: + + * Type and format of data sent in each parameter * Date and time when parameter information was last updated -!!! info "Availability of response parameters" - Response parameters are only available when using node 4.10.1 or higher. +* Request methods (GET, POST, and others) for REST +* GraphQL operations (queries, mutations, subscriptions) +* GraphQL schema +* SOAP operations -
- -
- -
-
+![API Discovery - built API inventory](../images/about-wallarm-waf/api-discovery-2.0/api-discovery-built-inventory.png) ## Issues addressed by API Discovery **Building an actual and complete API inventory** is the main issue the API Discovery module is addressing. -Keeping API inventory up-to-date is a difficult task. There are multiple teams that use different APIs and it is a common case that different tools and processes are used to produce the API documentation. As a result, companies struggle in both understanding what APIs they have, what data they expose and having up-to-date API documentation. +Keeping API inventory up-to-date is a difficult task. There is a high chance that one API is used by multiple teams and clients and it is a common case that different tools and processes are used to produce the API documentation. As a result, companies struggle in both understanding what APIs they have, what data they expose and having up-to-date API documentation. Since the API Discovery module uses the real traffic as a data source, it helps to get up-to-date and complete API documentation by including to the API inventory all endpoints that are actually processing the requests. **As you have your API inventory discovered by Wallarm, you can**: -* Have a full visibility into the whole API estate including the list of [external and internal](exploring.md#external-vs-internal) APIs. -* See [what data](exploring.md#endpoint-details) is going into and out of the APIs. -* Get a list of endpoints with the open vulnerabilities. -* Get a list of the threats that occurred over the past 7 days per any given API endpoint. -* Filter out only attacked APIs, sort them by number of hits. +* Have a full visibility into the whole API estate. +* See what data ([REST](exploring.md#rest-endpoint-details), [GraphQL](exploring.md#graphql-operation-details), [SOAP](exploring.md#soap-operation-details)) is going into and out of the APIs. * Filter APIs that consume and carry [sensitive data](#sensitive-data-detection). -* View visualized summary on your API inventory structure and problems on a handy [dashboard](dashboard.md). * Understand which endpoints are [most likely](risk-score.md) to be an attack target. -* Find [shadow, orphan and zombie APIs](rogue-api.md). * [Track changes](track-changes.md) in API that took place within the selected period of time. -* Filter API endpoints by the [BOLA auto protection state](bola-protection.md). * Provide your developers with [access](../user-guides/settings/users.md#user-roles) to the built API inventory reviewing and downloading. + ## How does API Discovery work? @@ -70,31 +74,78 @@ The API Discovery module bases noise detection on the two major traffic paramete * **Parameter stability** - the occurrence of the parameter in requests to the endpoint must be more than 1 percent. -The API inventory will display the endpoints and parameters that exceeded these limits. The time required to build the complete API inventory depends on the traffic diversity and intensity. +Also, the API Discovery performs filtering of requests relying on the other criteria, described in the sections below. Note that the time required to build the complete API inventory depends on the traffic diversity and intensity. + +#### Core filtering criteria + +1. **HTTP status code validation** - only requests with server responses in the `2xx` range (`200`-`299`) are processed. +1. **HTTP method validation** - requests must use valid HTTP methods. The following is not processed: empty method, `OPTIONS`, `HEAD`. +1. **Host validation** - requests must not target localhost or loopback addresses. The following is not processed: `localhost`, `127.0.0.1`, IPv6 loopback addresses (`::1`, `0:0:0:0:0:0:0:1`, etc.) +1. **Path validation** - request paths must conform to valid patterns: `^[\w{}\s\-]+(?:[.@][\w{}\s\-]+)*$`. The following is not processed: paths containing CJK characters (Unicode range 0x3000-0x303F). +1. **File extension filtering** - requests with file extensions are filtered based on content type validation: when a path has an extension, the `Content-type` header validation becomes mandatory. +1. **Content-type header validation** - the `Content-type` header of response must be valid: + + * `text/xml` + * `application/*json` (any JSON variant) + * `application/octet-stream` + * `application/*xml` (any XML variant) + + This type of validation is only performed if enabled (see [how to check](setup.md#general-api-discovery-settings)) by the Wallarm support team, except cases when presence of file extension in the path makes it mandatory. The necessity of this validation in noise reduction depends on the peculiarities of your traffic. + +1. **Security filtering** - the following is not processed: + + * Requests with [attack types](../attacks-vulns-list.md) + * Requests from DirBuster and similar scanners + +#### Protocol-specific criteria + +##### GraphQL + +**Detection method**: analyzes request payload structure for GraphQL-specific patterns. +**Key indicators**: + +* GraphQL structure in any HTTP valid request type (`GET`, `POST`) +* Operation types: `query`, `mutation`, `subscription` + +**Response pattern**: only JSON object with structure `{"data":{}}`. -Also, the API Discovery performs filtering of requests relying on the other criteria: +##### SOAP -* 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 API are not processed. - - 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. +**Detection method**: analyzes XML structure for SOAP envelope patterns. +**Key indicators**: -* Standard fields such as `Accept` and alike are discarded. -* Requests targeting `localhost` or loopback addresses are not processed. +* XML structure with SOAP envelope +* Must contain proper SOAP namespace structure + +**Requirements**: + +* Must have SOAP envelope with proper namespace +* Must contain SOAP Body element +* Must have a method name as the final element + +##### REST + +**Detection method**: default fallback for requests that don't match other patterns. +**Key indicators**: + +* Does not match GraphQL, SOAP +* Uses standard HTTP methods (`GET`, `POST`, `PUT`, `DELETE`, etc.) + +#### Additional filtering criteria + +1. **Multipart request filtering** - multipart requests with header parts are not processed. +1. **Base64 content filtering** - request points ending with "base64" are excluded. +1. **Empty value filtering** - request points with empty values are excluded in most contexts. ### Sensitive data detection API Discovery [detects and highlights](sensitive-data.md) sensitive data consumed and carried by your APIs: -* Technical data like IP and MAC addresses +* Personally identifiable information (PII) like full name, passport number or SSN * 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 - -API Discovery provides the ability to configure the detection process and add your own sensitive data patterns (requires NGINX Node 5.0.3 or Native Node 0.7.0 or higher). +* Technical data like IP and MAC addresses ### Sensitive business flows @@ -104,7 +155,7 @@ In addition to automatic identification, you can manually adjust the assigned se 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. -![API Discovery - Filtering by sensitive business flows](../images/about-wallarm-waf/api-discovery/api-discovery-sbf-filter.png) +![API Discovery - Filtering by sensitive business flows](../images/about-wallarm-waf/api-discovery-2.0/api-discovery-sbf-filter.png) ### Security of data uploaded to the Wallarm Cloud @@ -115,15 +166,7 @@ On the Cloud side, hashed data is used for statistical analysis (for example, wh Other data (endpoint values, request methods, and parameter names) is not hashed before being uploaded to the Wallarm Cloud, because hashes cannot be restored to their original state which would make building API inventory impossible. !!! warning "Important" - Wallarm does not send the values that are specified in the parameters to the Cloud. Only the endpoint, parameter names and statistics on them are sent. - -## API Discovery demo video - -Watch API Discovery demo video: - -
- -
+ API Discovery does not send the parameter values to the Cloud. Only the endpoint, parameter names and statistics on them are sent. ## Checking API Discovery in playground @@ -133,6 +176,6 @@ In Playground, you can access the API Discovery view like it is filled with real ![API Discovery – Sample Data](../images/about-wallarm-waf/api-discovery/api-discovery-sample-data.png) -## Enabling and configuring API Discovery +## Enabling API Discovery -To start using API Discovery, enable and configure it as described in [API Discovery Setup](setup.md). +To start using API Discovery, enable it as described in [API Discovery Setup](setup.md). diff --git a/docs/latest/api-discovery/risk-score.md b/docs/latest/api-discovery/risk-score.md index d256c66144..8d547c70e8 100644 --- a/docs/latest/api-discovery/risk-score.md +++ b/docs/latest/api-discovery/risk-score.md @@ -1,4 +1,4 @@ -# Endpoint Risk Score +# Endpoint Risk Score [API Discovery](overview.md) automatically calculates a **risk score** for each endpoint in your API inventory. 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. @@ -9,13 +9,12 @@ The risk score is made up of various factors, each having its own weight when ca | Factor | Description | Default weight | | --- | --- | --- | | Active vulnerabilities | [Active vulnerabilities](../about-wallarm/detecting-vulnerabilities.md) may result in unauthorized data access or corruption. | 9 | -| Potentially vulnerable to BOLA | Presence of the [variable path parts](exploring.md#variability), such as user IDs, e.g. `/api/articles/author/{parameter_X}`. Attackers can manipulate object IDs and, in case of insufficient request authentication, either read or modify the object sensitive data ([BOLA attacks](../admin-en/configuration-guides/protecting-against-bola.md)). | 6 | | Parameters with sensitive data | Rather than directly attacking APIs, attackers can steal [sensitive data](overview.md#sensitive-data-detection) and use it to seamlessly reach your resources. | 8 | | Number of query and body parameters | A large number of parameters increases the number of attack directions. | 6 | -| Accepts XML / JSON objects | XML or JSON objects passed in requests may be used by attackers to transfer malicious XML external entities and injections to the server. | 6 | +| Accepts XML / JSON objects* | XML or JSON objects passed in requests may be used by attackers to transfer malicious XML external entities and injections to the server. | 6 | | Allows uploading files to the server | Endpoints are frequently targeted by [Remote Code Execution (RCE)](../attacks-vulns-list.md#remote-code-execution-rce) attacks, where files with malicious code are uploaded to a server. To secure these endpoints, uploaded file extensions and contents should be properly validated as recommended by the [OWASP Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html). | 6 | -To adapt risk score estimation under your understanding of importance of factors, you can [configure](#customizing-risk-score-calculation) the weight of each factor in risk score calculation and calculation method. +* This risk factor is not accounted for GraphQL and SOAP since any API request of this type accepts XML / JSON object. ## Risk score levels @@ -28,28 +27,9 @@ Risk score may be from `1` (lowest) to `10` (highest): | 8 to 10 | High | Red | * `1` means no risk factors for this endpoint. -* Risk score is not displayed (`N/A`) for the unused endpoints. * Sort by risk score in the **Risk** column. * Filter `High`, `Medium` or `Low` using the **Risk score** filter. To understand what caused the risk score for the endpoint and how to reduce the risk, go to the endpoint details: -![API Discovery - Risk score](../images/about-wallarm-waf/api-discovery/api-discovery-risk-score.png) - -You can also get summary on APIs by their risk score levels in **Dashboards** → **API Discovery** in the [US](https://us1.my.wallarm.com/dashboard-api-discovery) or [EU](https://my.wallarm.com/dashboard-api-discovery) Cloud. - -## Customizing risk score calculation - -You can configure the weight of each factor in risk score calculation and calculation method. - -To change how risk score is calculated: - -1. Click the **Configure API Discovery** button in the **API Discovery** section. -1. Switch to the **Risk scoring** tab. -1. Select calculation method: highest or average weight. -1. If necessary, disable factors you do not want to affect a risk score. -1. Set weights for the remaining. - - ![API Discovery - Risk score setup](../images/about-wallarm-waf/api-discovery/api-discovery-risk-score-setup.png) - -1. Save changes. Wallarm will re-calculate the risk score for your endpoints in accordance with the new settings in several minutes. +![API Discovery - Risk score](../images/about-wallarm-waf/api-discovery-2.0/api-discovery-risk-score-details.png) diff --git a/docs/latest/api-discovery/rogue-api.md b/docs/latest/api-discovery/rogue-api.md index 465b788028..98c1f341af 100644 --- a/docs/latest/api-discovery/rogue-api.md +++ b/docs/latest/api-discovery/rogue-api.md @@ -1,5 +1,8 @@ # Shadow, Orphan, Zombie API +!!! warning "Feature availability" + In the latest versions of API Discovery, this feature is under reconstruction and may be temporarily unavailable. + The [API Discovery](overview.md) module automatically identifies shadow, orphan and zombie APIs by comparing your uploaded specification to the live traffic. |Rogue API type | What is it? | diff --git a/docs/latest/api-discovery/sbf.md b/docs/latest/api-discovery/sbf.md index 72fa3a40dd..0777325ead 100644 --- a/docs/latest/api-discovery/sbf.md +++ b/docs/latest/api-discovery/sbf.md @@ -1,8 +1,6 @@ # Sensitive Business Flows -With the sensitive business flow capability, Wallarm's [API Discovery](overview.md) can automatically identifies 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. - -Requires NGINX Node 5.2.11 or Native Node 0.10.1 or higher. +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, utilizing AI, and similar critical capabilities. Learn from this article how to use the sensitive business flow functionality. ## Addressed issues @@ -21,7 +19,7 @@ For your convenience, API Discovery tags endpoints as belonging to sensitive bus --8<-- "../include/default-sbf.md" -Automatic checks are conducted using keywords from the endpoint URL. For example, keywords like `payment`, `subscription`, or `purchase` automatically associate the endpoint with the **Billing** flow, while keywords such as `auth`, `token`, or `login` link it to the **Authentication** flow. If matches are detected, the endpoint is automatically assigned to the appropriate flow. +Automatic checks are conducted using keywords from the endpoint URL (REST) or operation name (GraphQL, SOAP). For example, keywords like `payment`, `subscription`, or `purchase` automatically associate the endpoint with the **Billing** flow, while keywords such as `auth`, `token`, or `login` link it to the **Authentication** flow. If matches are detected, the endpoint is automatically assigned to the appropriate flow. The automatic tagging discovers most of the sensitive business flows. However, it is also possible to manually adjust the list of assigned business flows as described in the section below. @@ -29,22 +27,20 @@ The automatic tagging discovers most of the sensitive business flows. However, i To adjust the results of [automatic tagging](#automatic-tagging), you can manually edit the list of sensitive business flow the endpoint belongs to. You can also manually tag endpoints that do not directly fall under the keyword list. -To edit the list of flows the endpoint belongs to, in Wallarm Console, go to API Discovery, then for your endpoint, in the **Business flow & sensitive data**, select one or several flows from the list. - -![API Discovery - Sensitive business flows](../images/about-wallarm-waf/api-discovery/api-discovery-sbf.png) +To edit the list of flows the endpoint belongs to, in Wallarm Console, go to API Discovery, then for your endpoint, in the **Business flow**, select one or several flows from the list. -You can do the same in the endpoint details. +![API Discovery - Sensitive business flows](../images/about-wallarm-waf/api-discovery-2.0/api-discovery-sbf.png) -## Business flows in Sessions + ## Filtering by business flow Once endpoints are assigned with the sensitive business flow tags, it becomes possible to filter all discovered endpoint by a specific business flow (the **Business flow** filter) which makes it easier on protecting the most critical business capabilities. -![API Discovery - Filtering by sensitive business flows](../images/about-wallarm-waf/api-discovery/api-discovery-sbf-filter.png) +![API Discovery - Filtering by sensitive business flows](../images/about-wallarm-waf/api-discovery-2.0/api-discovery-sbf-filter.png) diff --git a/docs/latest/api-discovery/sensitive-data.md b/docs/latest/api-discovery/sensitive-data.md index 15479623aa..60013ae62c 100644 --- a/docs/latest/api-discovery/sensitive-data.md +++ b/docs/latest/api-discovery/sensitive-data.md @@ -1,24 +1,26 @@ # Sensitive Data Detection -API Discovery detects and highlights sensitive data consumed and carried by your APIs, which allows applying encryption, tokenization, or other security controls to protect it and prevent data breaches and transmitting sensitive data across insecure channels or to unauthorized systems. This article describes how to use and configure the feature. +API Discovery detects and highlights sensitive data consumed and carried by your APIs, which allows applying encryption, tokenization, or other security controls to protect it and prevent data breaches and transmitting sensitive data across insecure channels or to unauthorized systems. -You get Wallarm's sensitive data detection ready-to-use with the comprehensive default configuration. It is also highly customizable: you can fine-tune the existing detection process and extend it with your own data types to detect. +![API Discovery - sensitive data](../images/about-wallarm-waf/api-discovery-2.0/api-discovery-sensitive-data.png) + +API Discovery detects the following types of sensitive data: -* Technical data like IP and MAC addresses +* Personally identifiable information (PII) like full name, passport number or SSN * 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 +* Technical data like IP and MAC addresses -In Wallarm Console, go to **API Discovery** → **Configure API Discovery** → **Sensitive data** to check the list of default [sensitive data patterns](#customizing-sensitive-data-detection) provided for each of listed types. +In Wallarm Console, go to **API Discovery** → **Configure** → **Sensitive data** to check the list of default [sensitive data patterns](#customizing-sensitive-data-detection) provided for each of listed types. ## Customizing sensitive data detection -To make sensitive data detection fully comply with your company's specific needs and industry-specific regulations such as GDPR, HIPAA, PCI DSS, etc., API Discovery provides the ability to fine-tune the detection process (requires NGINX Node 5.0.3 or Native Node 0.7.0 or higher). +To make sensitive data detection fully comply with your company's specific needs and industry-specific regulations such as GDPR, HIPAA, PCI DSS, etc., API Discovery provides the ability to fine-tune the detection process. Customization empowers you to meet your company's unique data protection obligations. Additionally, if any proprietary or specialized sensitive data elements are presented in your data flows, you will benefit from the ability to define custom regular expressions for their precise identification. @@ -71,4 +73,4 @@ We must match `middle_name,` but not `name` or `middle`. So, we set a score for To prevent us from detecting "middle" without `name,` we mark `name` as mandatory for an entity. If `name` is not found, no sensitive data is detected. -![API Discovery – Settings - Sensitive data - Creating custom pattern](../images/about-wallarm-waf/api-discovery/api-discovery-settings-sd-own-pattern.png) +![API Discovery – Settings - Sensitive data - Creating custom pattern](../images/about-wallarm-waf/api-discovery/api-discovery-settings-sd-own-pattern.png)--> diff --git a/docs/latest/api-discovery/setup.md b/docs/latest/api-discovery/setup.md index e0de13da36..bcb47a0392 100644 --- a/docs/latest/api-discovery/setup.md +++ b/docs/latest/api-discovery/setup.md @@ -1,48 +1,91 @@ # API Discovery Setup -This article describes how to enable, configure and debug the [API Discovery](overview.md) module. +This article describes how to enable and configure Wallarm's [API Discovery](overview.md). -## Enable +## Requirements -API Discovery is included in all [self-hosted](../installation/supported-deployment-options.md), [Security Edge](../installation/security-edge/overview.md) and [Connector](../installation/connectors/overview.md) forms of the Wallarm node installation. During node deployment, it installs the API Discovery module but keeps it disabled by default. +* Advanced API Security [subscription plan](../about-wallarm/subscription-plans.md#waap-and-advanced-api-security) +* For **GraphQL** - [NGINX Node](../installation/nginx-native-node-internals.md#nginx-node) 6.1.0 or higher (not supported by [Native Node](../installation/nginx-native-node-internals.md#native-node) so far) +* For **SOAP** - [NGINX Node](../installation/nginx-native-node-internals.md#nginx-node) 6.3.0 or higher (not supported by [Native Node](../installation/nginx-native-node-internals.md#native-node) so far) -To enable and run API Discovery correctly: +## Enabled by default -1. Make sure your [subscription plan](../about-wallarm/subscription-plans.md#core-subscription-plans) includes **API Discovery**. To change the subscription plan, please send a request to [sales@wallarm.com](mailto:sales@wallarm.com). -1. In Wallarm Console → **API Discovery** → **Configure API Discovery**, enable traffic analysis with API Discovery. - -Once the API Discovery module is enabled, it will start the traffic analysis and API inventory building. The API inventory will be displayed in the **API Discovery** section of Wallarm Console. +API Discovery is included in all [forms](../installation/supported-deployment-options.md) of the Wallarm node installation and is enabled by default, analyzing all traffic going through Wallarm nodes. ## Configure -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. +By clicking the **Configure** button in the **API Discovery** section, you proceed to the API discovery fine-tuning options, including selection of protocols to be handled, general settings for how API Discovery processes traffic, displayed applications, and customizing the sensitive data detection. + +### General API Discovery settings + +You can get define general API Discovery settings in Wallarm Console → **API Discovery** → **Configure** → **Settings**. -### Choosing applications for API Discovery +!!! info "Parameter availability" + Some of the parameters may be unavailable if they are managed by a **global administrator** of [multi-tenant](../installation/multi-tenant/overview.md) Wallarm installation. -You may enable/disable API Discovery for all applications or only the selected ones: +![API Discovery - general settings](../images/about-wallarm-waf/api-discovery-2.0/api-discovery-configure-settings-read-only.png) -1. Ensure that the applications are added as described in the [Setting up applications](../user-guides/settings/applications.md) article. +They are: - If the applications are not configured, structures of all APIs are grouped in one tree. +* Protocols to discover: note that if you already have discovered data for some of the protocols and then deselect this protocol in settings, its data will remain and will still by displayed, but the new endpoints for the corresponding protocol will stop appearing, those already found will stop being updated. +* Parameters defining how API Discovery [detects noise](overview.md#noise-detection) to show only relevant APIs. This is important as API Discovery bases its findings on the real traffic: -1. Enable API Discovery for the required applications in Wallarm Console → **API Discovery** → **Configure API Discovery**. + * **Filter endpoints by response content type** turns on/off validation of traffic by the `Content-type` header of response. The necessity of this validation in noise reduction depends on the peculiarities of your traffic. - ![API Discovery – Settings](../images/about-wallarm-waf/api-discovery/api-discovery-settings.png) + * Endpoint stability thresholds: at least specific **number of requests** should be registered for the endpoint for it to be displayed by API Discovery AND and at least one of them must be outside the **timeframe**. -When you add a new application in **Settings** → **[Applications](../user-guides/settings/applications.md)**, it is automatically added to the list of applications for API discovery in the **disabled** state. + This settings aim to avoid showing API entries, that had no traffic or had a traffic for a short timeframe only - they are considered unstable. Even if the specific endpoint was requested huge amount of times, but just within a short timeframe, there’s no need to consider this one-time spike as stable API endpoint. -### Customizing risk score calculation + ![API Discovery - general settings - endpoint stability](../images/about-wallarm-waf/api-discovery-2.0/api-discovery-endpoint-stability.png) -You can configure the weight of each factor in [risk score](risk-score.md) calculation and calculation method. +* Percentage of requests used to: **determine parameter types** (50% by default) and **detect sensitive data** (10% by default). Non-100% values are used to lower CPU usage. Increased numbers are good for environments with less requests. +* Applications to be displayed: only data for the selected applications will be displayed by API Discovery. Note that this is about displaying: data is discovered for all applications, you just decide whether to show it. ### Customizing sensitive data detection API Discovery [detects and highlights](sensitive-data.md) sensitive data consumed and carried by your APIs. You can fine-tune the existing detection process and extend it with your own data types to detect. -To view the current configuration and perform changes, in Wallarm Console, go to **API Discovery** → **Configure API Discovery** → **Sensitive data**. Here, you can overview and modify the existing sensitive data patterns and add your own. +To view the current configuration and perform changes, in Wallarm Console, go to **API Discovery** → **Configure** → **Sensitive data**. Here, you can overview and modify the existing sensitive data patterns and add your own. [See details here →](sensitive-data.md#customizing-sensitive-data-detection) +### Custom manual variability + +In addition to [automatic variability](exploring.md#path-variability) (unifying path segments such as UUIDs or numeric IDs into `{parameter_X}`), you can define **custom manual variability**—your own **path patterns** so that API Discovery treats certain URL segments as **variable** and merges them into **one endpoint** in the inventory. + +* **What it does**: You define path patterns; API Discovery treats matching URL segments as variable and merges them into a single endpoint. +* **When to use it**: When your APIs contain path elements where it is not immediately obvious they should be treated as variable (e.g., language codes or region-specific values, like `/website/lang/en_US`, `/website/lang/de_DE`, `/website/lang/fr_FR`) and you want to explicitly control how these are grouped in your inventory. Where variable segments are "obvious" (e.g., UUIDs, numeric IDs), automatic variability will handle them without any manual intervention. +* **Why**: The catalog stays **concise** and reflects the **real structure** of your API. + +How to configure: + +* **To merge endpoints:** In **API Discovery**, go to the details of an endpoint with an unmerged (variable) path segment. Mouse over the segment and click **Merge similar endpoints** to create a pattern that unifies them. +* **To review or split a merged pattern:** In the details of an endpoint with a merged segment, mouse over the merged segment and click **Review similar endpoints**. In the review window, you’ll see all endpoints currently grouped by this pattern; if needed, you can break the group apart by clicking **Split to individual endpoints**. + + ![API Discovery - manual variability review](../images/about-wallarm-waf/api-discovery-2.0/api-discovery-manual-variability-review.png) + +* **Disabling vs. deletion**: Disabling a pattern (either by turning it off in the list or using **Split to individual endpoints**) only makes the pattern inactive—endpoints will be shown separately again, but the pattern itself remains available and can be re-enabled at any time. However, if you choose to **Delete** a pattern, it is permanently removed and cannot be restored or used again in the future. + +* Full list of your custom patterns is always available in **API Discovery** → **Configure** → **Variability**. + + !!! info "Applying changes" + Both merge and split take time—changes are reflected in the list within **5 minutes**. + +## Notifications + +You can setup API Discovery notifications to be sent to your personal email (the one you use to log in) and to any additional emails: + +1. Access Wallarm Console → **Configuration** → **Integrations** → **Email and messengers**: + + * → **Personal email**, to setup notifications to your email + * → **Email report**, to setup notifications to additional emails + + Learn more about working with [email integrations](../user-guides/settings/integrations/email.md). + +1. In the **API Discovery notifications** section select notifications you want to get (hourly or daily notifications on [new and changed](track-changes.md#highlighting-changes-in-api) endpoints). + + ![API Discovery - email notification settings](../images/about-wallarm-waf/api-discovery-2.0/api-discovery-notifications.png) + ## Debug -To get and analyze the API Discovery logs, you can read the log file `/opt/wallarm/var/log/wallarm/appstructure-out.log` on the Linux machine where the node is running. +To get and analyze the API Discovery logs, you can read the log file `/opt/wallarm/var/log/wallarm/appstructure-out.log` on the Linux machine where the node is running.--> diff --git a/docs/latest/api-discovery/track-changes.md b/docs/latest/api-discovery/track-changes.md index f4f4ae014b..332000bfe1 100644 --- a/docs/latest/api-discovery/track-changes.md +++ b/docs/latest/api-discovery/track-changes.md @@ -1,8 +1,10 @@ # Tracking changes in API -If changes occur in your API, [API Discovery](overview.md) updates the built API inventory, highlights the changes and gives you information on when and what has changed. Additionally, you can set up notifications on all or some of the changes. +If changes occur in your API, [API Discovery](overview.md) updates the built API inventory, highlights the changes and gives you information on when and what has changed. -![API Discovery - track changes](../images/about-wallarm-waf/api-discovery/api-discovery-track-changes.png) +![API Discovery - track changes](../images/about-wallarm-waf/api-discovery-2.0/api-discovery-changes.png) + +## Overview The company may have several teams, disparate programming languages, and a variety of language frameworks. Thus changes can come to API at any time from different sources which make them difficult to control. For security officers it is important to detect changes as soon as possible and analyze them. If missed, such changes may hold some risks, for example: @@ -13,48 +15,33 @@ The company may have several teams, disparate programming languages, and a varie ## Highlighting changes in API -Each time you open the **API Discovery** section, the **Changes since** filter goes to the `Last week` state, which means the changes occurred within the last week are highlighted. To change the time period, redefine dates in the **Changes since** filter. - -In the endpoint list, the following marks highlight the changes in API: +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 added to the list within the period. +* **New** for the endpoints discovered within a week. * **Changed** for the endpoints that have newly discovered parameters or parameters that obtained the `Unused` status within the period. In the details of the endpoint such parameters will have a corresponding mark. - * A parameter gets the `New` status if is is discovered within the period. - * A parameter gets the `Unused` status if it does not pass any data for 7 days. + * A parameter gets the `New` status if it is discovered within the last week. + * A parameter gets the `Unused` status if it does not pass any data for a week. * If later the parameter in the `Unused` status passes data again it will lose the `Unused` status. -* **Unused** for the endpoints that obtained the `Unused` status within the period. +* **Unused** for the endpoints not requested (with the code 200 in response) within the last week or longer. - * An endpoint gets the `Unused` status if it is not requested (with the code 200 in response) for 7 days. * If later the endpoint in the `Unused` status is requested (with the code 200 in response) again it will lose the `Unused` status. -Note that whatever period is selected, if nothing is highlighted with the **New**, **Changed** or **Unused** mark, this means there are no changes in API for that period. - -![API Discovery - track changes](../images/about-wallarm-waf/api-discovery/api-discovery-track-changes.png) - -Quick tips for endpoints marked as rogue: +![API Discovery - track changes](../images/about-wallarm-waf/api-discovery-2.0/api-discovery-changes.png) -* Mouse over the **New**, **Changed** or **Unused** labels to see when the change happened -* Go to **Changed** endpoint details to see reason of this status: **New** parameters and parameters that got **Unused** status - mouse over labels to see when the parameter change occurred -* Counters for all types of changes for the last 7 days are displayed at the [API Discovery Dashboard](dashboard.md). +Use **Changed since** filter to only see endpoints changed in specific time period, for example, today. +## Notifications -## Filtering changes in API +You can [setup](setup.md#notifications) API Discovery notifications to be sent to your personal email (the one you use to log in) and to any additional emails: -In the **API Discovery** section, using the **Changes since** filter only highlights the endpoints changed within the selected period, but does not filter out endpoints without changes. +* Daily endpoint changes +* Hourly endpoint changes -The **Changes in API** filter works differently and shows **only** endpoints changed within the selected period and filters out all the rest. +The notification will include both changed and new endpoints. By default, the notification is disabled. -Let us consider the example: say your API today has 10 endpoints (there were 12, but 3 of them were marked unused 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 week` state; 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 **Unused** mark. -* Set **Changes in API** to `Unused endpoints` - 3 endpoints will be displayed, all with the **Unused** mark. -* Change **Changes in API** to `New endpoints + Unused endpoints` - 4 endpoints will be displayed, 3 with the **Unused** 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. - -## Getting notified + diff --git a/docs/latest/api-protection/file-upload-restriction.md b/docs/latest/api-protection/file-upload-restriction.md index 2c743d8b13..503d1aaf7d 100644 --- a/docs/latest/api-protection/file-upload-restriction.md +++ b/docs/latest/api-protection/file-upload-restriction.md @@ -1,4 +1,4 @@ -[api-discovery-enable-link]: ../api-discovery/setup.md#enable +[api-discovery-enable-link]: ../api-discovery/setup.md#enabled-by-default # File Upload Restriction Policy diff --git a/docs/latest/api-protection/graphql-rule.md b/docs/latest/api-protection/graphql-rule.md index 1a718fe5b9..5389d27f3e 100644 --- a/docs/latest/api-protection/graphql-rule.md +++ b/docs/latest/api-protection/graphql-rule.md @@ -1,4 +1,4 @@ -[api-discovery-enable-link]: ../api-discovery/setup.md#enable +[api-discovery-enable-link]: ../api-discovery/setup.md # GraphQL API Protection diff --git a/docs/latest/installation/oob/ebpf/deployment.md b/docs/latest/installation/oob/ebpf/deployment.md index 3448ab4e10..84d79caa54 100644 --- a/docs/latest/installation/oob/ebpf/deployment.md +++ b/docs/latest/installation/oob/ebpf/deployment.md @@ -200,6 +200,6 @@ To test that the Wallarm eBPF operates correctly: * As server response bodies are not mirrored: * Vulnerability detection based on [passive detection](../../../about-wallarm/detecting-vulnerabilities.md#passive-detection) is not supported. - * Displaying API endpoint [response structure in API Discovery](../../../api-discovery/exploring.md#endpoint-details) is not supported. + * Displaying API endpoint response structure in API Discovery is not supported. * While the solution is in beta, not all Kubernetes resources can be mirrored effectively. Therefore, we recommend enabling traffic mirroring specifically for NGINX Ingress controllers, Kong Ingress controllers, or regular NGINX servers in Kubernetes. diff --git a/docs/latest/updating-migrating/node-artifact-versions.md b/docs/latest/updating-migrating/node-artifact-versions.md index 5345d638e5..c8dbac6f81 100644 --- a/docs/latest/updating-migrating/node-artifact-versions.md +++ b/docs/latest/updating-migrating/node-artifact-versions.md @@ -154,6 +154,7 @@ new attack types in logging variables and search bars? ### 6.1.0 (2025-05-09) +* Added support for GraphQL protocol in [API Discovery](../api-discovery/overview.md) * Added support for [**enumeration**](../api-protection/enumeration-attack-protection.md) mitigation controls * Added support for [**DoS protection**](../api-protection/dos-protection.md) mitigation control * Bugfix: Attacks originated from allowlisted sources are no longer shown in the **Attacks** section @@ -341,6 +342,7 @@ new attack types in logging variables and search bars? ### 6.1.0 (2025-05-09) +* Added support for GraphQL protocol in [API Discovery](../api-discovery/overview.md) * Bugfix: Attacks originated from allowlisted sources are no longer shown in the **Attacks** section * wstore logs now include `"component": "wstore"` for easier identification @@ -487,6 +489,7 @@ new attack types in logging variables and search bars? ### 6.1.0 (2025-05-09) +* Added support for GraphQL protocol in [API Discovery](../api-discovery/overview.md) * Bugfix: Attacks originated from allowlisted sources are no longer shown in the **Attacks** section * wstore logs now include `"component": "wstore"` for easier identification @@ -651,6 +654,7 @@ new attack types in logging variables and search bars? ### 6.1.0 (2025-05-09) +* Added support for GraphQL protocol in [API Discovery](../api-discovery/overview.md) * Bugfix: Attacks originated from allowlisted sources are no longer shown in the **Attacks** section * wstore logs now include `"component": "wstore"` for easier identification @@ -778,6 +782,7 @@ new attack types in logging variables and search bars? ### 6.1.0 (2025-05-09) +* Added support for GraphQL protocol in [API Discovery](../api-discovery/overview.md) * Bugfix: Attacks originated from allowlisted sources are no longer shown in the **Attacks** section * wstore logs now include `"component": "wstore"` for easier identification diff --git a/docs/latest/updating-migrating/older-versions/what-is-new.md b/docs/latest/updating-migrating/older-versions/what-is-new.md index 4a668e67e4..088355fb12 100644 --- a/docs/latest/updating-migrating/older-versions/what-is-new.md +++ b/docs/latest/updating-migrating/older-versions/what-is-new.md @@ -150,6 +150,51 @@ To start using the functionality, you need to create at least one [**Detect Grap ![GraphQL thresholds](../../images/user-guides/rules/graphql-rule.png) +## New API Discovery + +Wallarm's New [API Discovery](../../api-discovery/overview.md) is now **multi-protocol**: the REST protocol is extended with the support of GraphQL and SOAP. Also, improved user interface and performance make work with the API Discovery more comfortable and effective than before. + +### GraphQL protocol support + +!!! tip "" + [NGINX Node 6.1.0 and higher](../node-artifact-versions.md) and not supported by Native Node so far + +If some of your APIs utilize the GraphQL protocol and are requested in the real traffic, API Discovery will now detect them. In the built API inventory, you will see data about: + +* GraphQL operations (queries, mutations, subscriptions) +* GraphQL schema + +Within each GraphQL operation, you will find its details, including transferred sensitive data, risk score and what contributes to it, schema, parameters and headers of requests and responses: + +![API Discovery - GraphQL operation details](../../images/about-wallarm-waf/api-discovery-2.0/api-discovery-endpoint-details-GQL.png) + +Each request/response parameter information includes: + +* Parameter name and the part of request/response this parameter belongs to +* Path: the hierarchical location of a parameter within a GraphQL query structure +* Information about parameter changes (new, unused) +* Presence and type of sensitive data transmitted by this parameter, including: +* Date and time when parameter value was last transferred by requests + +### SOAP protocol support + +!!! tip "" + [NGINX Node 6.2.0 and higher](../node-artifact-versions.md) and not supported by Native Node so far + +If some of your APIs utilize the SOAP protocol and are requested in the real traffic, API Discovery will now detect them. In the built API inventory, you will see data about SOAP operations, including such data as transferred sensitive data, risk score and what contributes to it, XML body parameters, HTTPS and XML headers of requests and responses: + +![API Discovery - SOAP operation details](../../images/about-wallarm-waf/api-discovery-2.0/api-discovery-endpoint-details-SOAP.png) + +Each request/response XML parameter information includes: + +* Parameter name (**Key**) +* Path: the hierarchical location of a parameter within an XML structure +* Parameter type +* Namespaces for path elements (from more general to more specific) +* Presence and type of sensitive data transmitted by this parameter +* Information about parameter changes (new, unused) +* Date and time when parameter value was last transferred by requests + ## Mitigation Controls We introduce a unified management center for all Wallarm attack mitigation settings - [**Mitigation Controls**](../../about-wallarm/mitigation-controls-overview.md). With mitigation controls you can: diff --git a/docs/latest/updating-migrating/what-is-new.md b/docs/latest/updating-migrating/what-is-new.md index 94962976a4..f59b014d0c 100644 --- a/docs/latest/updating-migrating/what-is-new.md +++ b/docs/latest/updating-migrating/what-is-new.md @@ -74,6 +74,51 @@ As a result of this change, also the following changed in the configuration rule you should now switch to scraping `/wallarm-status` via Prometheus. +## New API Discovery + +Wallarm's New [API Discovery](../api-discovery/overview.md) is now **multi-protocol**: the REST protocol is extended with the support of GraphQL and SOAP. Also, improved user interface and performance make work with the API Discovery more comfortable and effective than before. + +### GraphQL protocol support + +!!! tip "" + [NGINX Node 6.1.0 and higher](node-artifact-versions.md) and not supported by Native Node so far + +If some of your APIs utilize the GraphQL protocol and are requested in the real traffic, API Discovery will now detect them. In the built API inventory, you will see data about: + +* GraphQL operations (queries, mutations, subscriptions) +* GraphQL schema + +Within each GraphQL operation, you will find its details, including transferred sensitive data, risk score and what contributes to it, schema, parameters and headers of requests and responses: + +![API Discovery - GraphQL operation details](../images/about-wallarm-waf/api-discovery-2.0/api-discovery-endpoint-details-GQL.png) + +Each request/response parameter information includes: + +* Parameter name and the part of request/response this parameter belongs to +* Path: the hierarchical location of a parameter within a GraphQL query structure +* Information about parameter changes (new, unused) +* Presence and type of sensitive data transmitted by this parameter, including: +* Date and time when parameter value was last transferred by requests + +### SOAP protocol support + +!!! tip "" + [NGINX Node 6.2.0 and higher](node-artifact-versions.md) and not supported by Native Node so far + +If some of your APIs utilize the SOAP protocol and are requested in the real traffic, API Discovery will now detect them. In the built API inventory, you will see data about SOAP operations, including such data as transferred sensitive data, risk score and what contributes to it, XML body parameters, HTTPS and XML headers of requests and responses: + +![API Discovery - SOAP operation details](../images/about-wallarm-waf/api-discovery-2.0/api-discovery-endpoint-details-SOAP.png) + +Each request/response XML parameter information includes: + +* Parameter name (**Key**) +* Path: the hierarchical location of a parameter within an XML structure +* Parameter type +* Namespaces for path elements (from more general to more specific) +* Presence and type of sensitive data transmitted by this parameter +* Information about parameter changes (new, unused) +* Date and time when parameter value was last transferred by requests + ## Mitigation Controls We introduce a unified management center for all Wallarm attack mitigation settings - [**Mitigation Controls**](../about-wallarm/mitigation-controls-overview.md). With mitigation controls you can: diff --git a/docs/latest/user-guides/dashboards/api-discovery.md b/docs/latest/user-guides/dashboards/api-discovery.md index ea032b1c9b..6b9fc89247 100644 --- a/docs/latest/user-guides/dashboards/api-discovery.md +++ b/docs/latest/user-guides/dashboards/api-discovery.md @@ -3,7 +3,7 @@ [apid-track-changes]: ../../api-discovery/track-changes.md [apid-rogue]: ../../api-discovery/rogue-api.md [check-attack]: ../../user-guides/events/check-attack.md -[img-api-discovery-widget]: ../../images/user-guides/dashboard/api-discovery-widget.png +[img-api-discovery-dashboard]: ../../images/about-wallarm-waf/api-discovery-2.0/api-discovery-dashboard.png # API Discovery Dashboard diff --git a/docs/latest/user-guides/rules/add-replace-response-header.md b/docs/latest/user-guides/rules/add-replace-response-header.md index d95254356a..bb832e58a4 100644 --- a/docs/latest/user-guides/rules/add-replace-response-header.md +++ b/docs/latest/user-guides/rules/add-replace-response-header.md @@ -1,4 +1,4 @@ -[api-discovery-enable-link]: ../../api-discovery/setup.md#enable +[api-discovery-enable-link]: ../../api-discovery/setup.md # Changing Server Response Headers diff --git a/docs/latest/user-guides/rules/configure-overlimit-res-detection.md b/docs/latest/user-guides/rules/configure-overlimit-res-detection.md index b0443f7527..75fbc1825f 100644 --- a/docs/latest/user-guides/rules/configure-overlimit-res-detection.md +++ b/docs/latest/user-guides/rules/configure-overlimit-res-detection.md @@ -1,4 +1,4 @@ -[api-discovery-enable-link]: ../../api-discovery/setup.md#enable +[api-discovery-enable-link]: ../../api-discovery/setup.md # Limiting Request Processing Time diff --git a/docs/latest/user-guides/rules/rate-limiting.md b/docs/latest/user-guides/rules/rate-limiting.md index 05808a2fba..51df6626b9 100644 --- a/docs/latest/user-guides/rules/rate-limiting.md +++ b/docs/latest/user-guides/rules/rate-limiting.md @@ -1,4 +1,4 @@ -[api-discovery-enable-link]: ../../api-discovery/setup.md#enable +[api-discovery-enable-link]: ../../api-discovery/setup.md # Rate Limiting diff --git a/docs/latest/user-guides/rules/regex-rule.md b/docs/latest/user-guides/rules/regex-rule.md index d6e5df4d75..b1413ad703 100644 --- a/docs/latest/user-guides/rules/regex-rule.md +++ b/docs/latest/user-guides/rules/regex-rule.md @@ -3,7 +3,7 @@ [img-regex-example2]: ../../images/user-guides/rules/regex-rule-2.png [img-regex-id]: ../../images/user-guides/rules/regex-id.png [request-processing]: ../../user-guides/rules/request-processing.md -[api-discovery-enable-link]: ../../api-discovery/setup.md#enable +[api-discovery-enable-link]: ../../api-discovery/setup.md # Custom Attack Detectors diff --git a/docs/latest/user-guides/rules/request-processing.md b/docs/latest/user-guides/rules/request-processing.md index 025eed10c6..633d6bda05 100644 --- a/docs/latest/user-guides/rules/request-processing.md +++ b/docs/latest/user-guides/rules/request-processing.md @@ -1,6 +1,6 @@ [rule-creation-options]: ../../user-guides/events/check-attack.md#attack-analysis_1 [request-processing]: ../../user-guides/rules/request-processing.md -[api-discovery-enable-link]: ../../api-discovery/setup.md#enable +[api-discovery-enable-link]: ../../api-discovery/setup.md # Parsing Requests diff --git a/docs/latest/user-guides/rules/sensitive-data-rule.md b/docs/latest/user-guides/rules/sensitive-data-rule.md index 8f90673155..65e0cee811 100644 --- a/docs/latest/user-guides/rules/sensitive-data-rule.md +++ b/docs/latest/user-guides/rules/sensitive-data-rule.md @@ -1,7 +1,7 @@ [img-masking]: ../../images/user-guides/rules/sensitive-data-rule.png [rule-creation-options]: ../../user-guides/events/check-attack.md#attack-analysis_1 [request-processing]: ../../user-guides/rules/request-processing.md -[api-discovery-enable-link]: ../../api-discovery/setup.md#enable +[api-discovery-enable-link]: ../../api-discovery/setup.md # Masking Sensitive Data diff --git a/docs/latest/user-guides/rules/vpatch-rule.md b/docs/latest/user-guides/rules/vpatch-rule.md index a5145c0199..67537c3857 100644 --- a/docs/latest/user-guides/rules/vpatch-rule.md +++ b/docs/latest/user-guides/rules/vpatch-rule.md @@ -3,7 +3,7 @@ [img-regex-example1]: ../../images/user-guides/rules/regex-rule-1.png [rule-creation-options]: ../../user-guides/events/check-attack.md#attack-analysis_1 [request-processing]: ../../user-guides/rules/request-processing.md -[api-discovery-enable-link]: ../../api-discovery/setup.md#enable +[api-discovery-enable-link]: ../../api-discovery/setup.md # Virtual Patching diff --git a/docs/latest/user-guides/vulnerabilities.md b/docs/latest/user-guides/vulnerabilities.md index 099ac01386..aa16506084 100644 --- a/docs/latest/user-guides/vulnerabilities.md +++ b/docs/latest/user-guides/vulnerabilities.md @@ -139,7 +139,7 @@ Additionally, information about security issues found specifically by [API Attac * **Weekly AASM statistics** - information about hosts, APIs, and statistics for security issues discovered for your configured domains within last week. -The notifications are enabled by default. You can unsubscribe at any moment and configure any additional emails to get all or some of these notifications in Wallarm Console → **Configuration** → **Integrations** → **Email and messengers** → **Personal email** (you email) or **Email report** (extra emails) as described [here][link-integrations-email]. +The notifications are enabled by default. You can unsubscribe at any moment and configure any additional emails to get all or some of these notifications in Wallarm Console → **Configuration** → **Integrations** → **Email and messengers** → **Personal email** (your email) or **Email report** (extra emails) as described [here][link-integrations-email]. ### Instant notification diff --git a/docs/pt-BR/api-discovery/bola-protection.md b/docs/pt-BR/api-discovery/bola-protection.md index cf4f86bf8c..271492134c 100644 --- a/docs/pt-BR/api-discovery/bola-protection.md +++ b/docs/pt-BR/api-discovery/bola-protection.md @@ -1 +1 @@ ---8<-- "latest/api-discovery/bola-protection.md" \ No newline at end of file +--8<-- "5.0/api-discovery/bola-protection.md" \ No newline at end of file diff --git a/docs/pt-BR/api-discovery/dashboard.md b/docs/pt-BR/api-discovery/dashboard.md index e952652c63..05825e5b85 100644 --- a/docs/pt-BR/api-discovery/dashboard.md +++ b/docs/pt-BR/api-discovery/dashboard.md @@ -1 +1 @@ ---8<-- "latest/api-discovery/dashboard.md" \ No newline at end of file +--8<-- "5.0/api-discovery/dashboard.md" \ No newline at end of file diff --git a/docs/pt-BR/api-discovery/risk-score.md b/docs/pt-BR/api-discovery/risk-score.md index 1c1aa13915..6d03226c13 100644 --- a/docs/pt-BR/api-discovery/risk-score.md +++ b/docs/pt-BR/api-discovery/risk-score.md @@ -1 +1 @@ ---8<-- "latest/api-discovery/risk-score.md" \ No newline at end of file +--8<-- "5.0/api-discovery/risk-score.md" \ No newline at end of file diff --git a/docs/pt-BR/api-discovery/rogue-api.md b/docs/pt-BR/api-discovery/rogue-api.md index 77d709c6cb..5a9f506984 100644 --- a/docs/pt-BR/api-discovery/rogue-api.md +++ b/docs/pt-BR/api-discovery/rogue-api.md @@ -1 +1 @@ ---8<-- "latest/api-discovery/rogue-api.md" \ No newline at end of file +--8<-- "5.0/api-discovery/rogue-api.md" \ No newline at end of file diff --git a/docs/pt-BR/api-discovery/track-changes.md b/docs/pt-BR/api-discovery/track-changes.md index f2bb9eb5a5..b2a25a4dc4 100644 --- a/docs/pt-BR/api-discovery/track-changes.md +++ b/docs/pt-BR/api-discovery/track-changes.md @@ -1 +1 @@ ---8<-- "latest/api-discovery/track-changes.md" \ No newline at end of file +--8<-- "5.0/api-discovery/track-changes.md" \ No newline at end of file diff --git a/images/about-wallarm-waf/api-discovery-2.0/api-discovery-built-inventory (old).png b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-built-inventory (old).png new file mode 100644 index 0000000000..2ea03baa58 Binary files /dev/null and b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-built-inventory (old).png differ diff --git a/images/about-wallarm-waf/api-discovery-2.0/api-discovery-built-inventory.png b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-built-inventory.png new file mode 100644 index 0000000000..06dcf2f054 Binary files /dev/null and b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-built-inventory.png differ diff --git a/images/about-wallarm-waf/api-discovery-2.0/api-discovery-changes.png b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-changes.png new file mode 100644 index 0000000000..80b4ccad5f Binary files /dev/null and b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-changes.png differ diff --git a/images/about-wallarm-waf/api-discovery-2.0/api-discovery-configure-settings-read-only.png b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-configure-settings-read-only.png new file mode 100644 index 0000000000..c533b75298 Binary files /dev/null and b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-configure-settings-read-only.png differ diff --git a/images/about-wallarm-waf/api-discovery-2.0/api-discovery-dashboard.png b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-dashboard.png new file mode 100644 index 0000000000..bf267a34ba Binary files /dev/null and b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-dashboard.png differ diff --git a/images/about-wallarm-waf/api-discovery-2.0/api-discovery-endpoint-details-GQL.png b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-endpoint-details-GQL.png new file mode 100644 index 0000000000..b1bb6e146d Binary files /dev/null and b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-endpoint-details-GQL.png differ diff --git a/images/about-wallarm-waf/api-discovery-2.0/api-discovery-endpoint-details-REST.png b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-endpoint-details-REST.png new file mode 100644 index 0000000000..a5647bda3e Binary files /dev/null and b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-endpoint-details-REST.png differ diff --git a/images/about-wallarm-waf/api-discovery-2.0/api-discovery-endpoint-details-SOAP.png b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-endpoint-details-SOAP.png new file mode 100644 index 0000000000..56439015e0 Binary files /dev/null and b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-endpoint-details-SOAP.png differ diff --git a/images/about-wallarm-waf/api-discovery-2.0/api-discovery-endpoint-stability.png b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-endpoint-stability.png new file mode 100644 index 0000000000..d7fa5966f3 Binary files /dev/null and b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-endpoint-stability.png differ diff --git a/images/about-wallarm-waf/api-discovery-2.0/api-discovery-labels.png b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-labels.png new file mode 100644 index 0000000000..d93e639281 Binary files /dev/null and b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-labels.png differ diff --git a/images/about-wallarm-waf/api-discovery-2.0/api-discovery-manual-variability-review.png b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-manual-variability-review.png new file mode 100644 index 0000000000..a4fe80754e Binary files /dev/null and b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-manual-variability-review.png differ diff --git a/images/about-wallarm-waf/api-discovery-2.0/api-discovery-notifications.png b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-notifications.png new file mode 100644 index 0000000000..27fca12b72 Binary files /dev/null and b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-notifications.png differ diff --git a/images/about-wallarm-waf/api-discovery-2.0/api-discovery-risk-score-details.png b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-risk-score-details.png new file mode 100644 index 0000000000..5b59803679 Binary files /dev/null and b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-risk-score-details.png differ diff --git a/images/about-wallarm-waf/api-discovery-2.0/api-discovery-sbf-filter.png b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-sbf-filter.png new file mode 100644 index 0000000000..435da4b2eb Binary files /dev/null and b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-sbf-filter.png differ diff --git a/images/about-wallarm-waf/api-discovery-2.0/api-discovery-sbf.png b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-sbf.png new file mode 100644 index 0000000000..88efffc51c Binary files /dev/null and b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-sbf.png differ diff --git a/images/about-wallarm-waf/api-discovery-2.0/api-discovery-sensitive-data.png b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-sensitive-data.png new file mode 100644 index 0000000000..71d2e498d9 Binary files /dev/null and b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-sensitive-data.png differ diff --git a/images/about-wallarm-waf/api-discovery-2.0/api-discovery-variability-in-path.png b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-variability-in-path.png new file mode 100644 index 0000000000..0449b9dfcc Binary files /dev/null and b/images/about-wallarm-waf/api-discovery-2.0/api-discovery-variability-in-path.png differ diff --git a/images/about-wallarm-waf/api-discovery/api-discovery-sample-data.png b/images/about-wallarm-waf/api-discovery/api-discovery-sample-data.png index d7410db941..13e22d3c37 100644 Binary files a/images/about-wallarm-waf/api-discovery/api-discovery-sample-data.png and b/images/about-wallarm-waf/api-discovery/api-discovery-sample-data.png differ diff --git a/images/about-wallarm-waf/api-discovery/api-discovery-settings-sd-own-pattern.png b/images/about-wallarm-waf/api-discovery/api-discovery-settings-sd-own-pattern.png index 9ba0980feb..01bf76da8b 100644 Binary files a/images/about-wallarm-waf/api-discovery/api-discovery-settings-sd-own-pattern.png and b/images/about-wallarm-waf/api-discovery/api-discovery-settings-sd-own-pattern.png differ diff --git a/images/about-wallarm-waf/api-discovery/api-discovery-settings-sd.png b/images/about-wallarm-waf/api-discovery/api-discovery-settings-sd.png index b58cf17567..3539a0ec6b 100644 Binary files a/images/about-wallarm-waf/api-discovery/api-discovery-settings-sd.png and b/images/about-wallarm-waf/api-discovery/api-discovery-settings-sd.png differ diff --git a/images/user-guides/settings/integrations/add-email-report-integration.png b/images/user-guides/settings/integrations/add-email-report-integration.png index fcc4cf729d..cd50f8ee95 100644 Binary files a/images/user-guides/settings/integrations/add-email-report-integration.png and b/images/user-guides/settings/integrations/add-email-report-integration.png differ diff --git a/include/api-attack-surface/aasm-notifications.md b/include/api-attack-surface/aasm-notifications.md index 7218b97bbc..c3dbfdea48 100644 --- a/include/api-attack-surface/aasm-notifications.md +++ b/include/api-attack-surface/aasm-notifications.md @@ -6,7 +6,7 @@ You automatically receive notifications to your personal email (the one you use * **Daily security issues (new only)** - statistics for security issues opened for the day, sent once a day with information on how many issues of every [risk level][link-aasm-security-issue-risk-level] were found and general action items for mitigation. * **Weekly AASM statistics** - information about hosts, APIs, and statistics for security issues discovered for your configured domains within last week. -The notifications are enabled by default. You can unsubscribe at any moment and configure any additional emails to get all or some of these notifications in Wallarm Console → **Configuration** → **Integrations** → **Email and messengers** → **Personal email** (you email) or **Email report** (extra emails) as described [here][link-integrations-email]. +The notifications are enabled by default. You can unsubscribe at any moment and configure any additional emails to get all or some of these notifications in Wallarm Console → **Configuration** → **Integrations** → **Email and messengers** → **Personal email** (your email) or **Email report** (extra emails) as described [here][link-integrations-email]. ### Instant notification diff --git a/include/api-discovery/dashboard-5.0.md b/include/api-discovery/dashboard-5.0.md new file mode 100644 index 0000000000..5528d79e0e --- /dev/null +++ b/include/api-discovery/dashboard-5.0.md @@ -0,0 +1,18 @@ +Review data about your API collected by the Wallarm's [**API Discovery**][apid-overview] with the **API Discovery** dashboard. + +The dashboard provides the full landscape of your API endpoints, including shadow, orphan, and zombie APIs. It visualizes the **risk score assessment** results helping prioritize security efforts by identifying the most vulnerable or high-risk APIs. + +APIs evolve over time, with new endpoints being added and old ones deprecated. The dashboard provides visibility into these changes which ensures that deprecated APIs are properly retired and that new or modified APIs are compliant with security policies and standards. + +
+ +
+ +
+
+ +Consider the following: + +* How much your API endpoints are under risk is marked with the [risk score][apid-risk-score] +* Pay attention to [changes][apid-track-changes] in your API (displayed for the last 7 days) +* [Rogue API][apid-rogue] is a serious risk factor - upload your specification to compare with real traffic diff --git a/include/api-discovery/dashboard.md b/include/api-discovery/dashboard.md index 5528d79e0e..5070869b9d 100644 --- a/include/api-discovery/dashboard.md +++ b/include/api-discovery/dashboard.md @@ -1,18 +1,16 @@ Review data about your API collected by the Wallarm's [**API Discovery**][apid-overview] with the **API Discovery** dashboard. -The dashboard provides the full landscape of your API endpoints, including shadow, orphan, and zombie APIs. It visualizes the **risk score assessment** results helping prioritize security efforts by identifying the most vulnerable or high-risk APIs. +The dashboard provides the full landscape of your API endpoints, including total APIs, APIs by discovered sensitive data, host and application. It visualizes the **risk score assessment** results helping prioritize security efforts by identifying the most vulnerable or high-risk APIs. APIs evolve over time, with new endpoints being added and old ones deprecated. The dashboard provides visibility into these changes which ensures that deprecated APIs are properly retired and that new or modified APIs are compliant with security policies and standards. -
- -
- -
-
+![API Discovery - Dashboard][img-api-discovery-dashboard] Consider the following: * How much your API endpoints are under risk is marked with the [risk score][apid-risk-score] * Pay attention to [changes][apid-track-changes] in your API (displayed for the last 7 days) -* [Rogue API][apid-rogue] is a serious risk factor - upload your specification to compare with real traffic +* How many parameters hold the sensitive data and what types of data exactly is a valuable information +* You can analyze the number of found APIs by host and application + +The elements of the dashboard are all interactive which means you can click the element to be redirected to API Discovery with corresponding filters: for example, click Medium Risk APIs and the API Discovery section will be opened displaying all APIs with this risk level. diff --git a/include/integrations/events-for-integrations-mail.md b/include/integrations/events-for-integrations-mail.md index 7ea2b8b0cd..59f55499ce 100644 --- a/include/integrations/events-for-integrations-mail.md +++ b/include/integrations/events-for-integrations-mail.md @@ -6,4 +6,7 @@ * [Security issue](../../../user-guides/vulnerabilities.md) notifications: * Daily critical security issues (new only) found by [all methods](../../../about-wallarm/detecting-vulnerabilities.md#detection-methods) * Daily security issues (new only) found by [all methods](../../../about-wallarm/detecting-vulnerabilities.md#detection-methods) - * Weekly [AASM](../../../api-attack-surface/overview.md) statistics including security issues [found for the discovered hosts](../../../api-attack-surface/security-issues.md) (available with API Attack Surface [subscription plan](../../../../about-wallarm/subscription-plans/#api-attack-surface) only) \ No newline at end of file + * Weekly [AASM](../../../api-attack-surface/overview.md) statistics including security issues [found for the discovered hosts](../../../api-attack-surface/security-issues.md) (available with API Attack Surface [subscription plan](../../../../about-wallarm/subscription-plans/#api-attack-surface) only) +* [API Discovery](../../../api-discovery/overview.md) notifications: + * Daily endpoint changes + * Hourly endpoint changes \ No newline at end of file diff --git a/mkdocs-base.yml b/mkdocs-base.yml index f0176b3b10..48ed9b36c7 100644 --- a/mkdocs-base.yml +++ b/mkdocs-base.yml @@ -15,7 +15,7 @@ plugins: minify_css: true js_files: - extra.js - - feedback.js + # - feedback.js - supported-platforms.js - inkeep-widget.js css_files: @@ -125,7 +125,7 @@ extra_css: extra_javascript: - 'extra.js' - - 'feedback.js' + # - 'feedback.js' - 'inkeep-widget.js' markdown_extensions: diff --git a/stylesheets/partials/nav-item.html b/stylesheets/partials/nav-item.html index 5f41e4604e..c6cc3a6cd7 100644 --- a/stylesheets/partials/nav-item.html +++ b/stylesheets/partials/nav-item.html @@ -8,6 +8,7 @@ "api attack surface": ".icons/material/vulnerability.svg", "assets & vulnerabilities": ".icons/material/vulnerability.svg", "api discovery": ".icons/material/api.svg", + "api discovery new": ".icons/material/api.svg", "api protection": ".icons/material/api-threat.svg", "agentic ai": ".icons/material/ai-prompt-attack.svg", "ai security": ".icons/material/ai-prompt-attack.svg",