diff --git a/src/content/docs/api-shield/get-started.mdx b/src/content/docs/api-shield/get-started.mdx index fe8ab961ed4..b99df9fb9df 100644 --- a/src/content/docs/api-shield/get-started.mdx +++ b/src/content/docs/api-shield/get-started.mdx @@ -9,14 +9,10 @@ sidebar: label: Get started --- -import { GlossaryTooltip, Render, Steps } from "~/components"; +import { GlossaryTooltip, Render } from "~/components"; API Shield protects your APIs by discovering endpoints, validating request schemas, and detecting abuse patterns. This guide walks through the initial setup from configuring session identifiers to enabling advanced protections. -:::note -Enabling API Shield features will have no impact on your traffic until you choose to move a setting from `log` to `block` mode. -::: - ## Session identifiers @@ -27,17 +23,17 @@ Enabling API Shield features will have no impact on your traffic until you choos -## Upload a schema using Schema validation (optional) +## Create a Schema Profile -Schema validation protects your APIs by checking incoming requests against your API schema. Depending on your configured action, requests that do not match the schema are logged or blocked. +[Application Profiles](/waf/detections/application-profiles/) provides one Schema Profile with two sources. Schema Learning derives a profile from traffic, while Schema Validation uses an uploaded OpenAPI schema. -When you upload a schema via the Cloudflare dashboard, its endpoints are automatically added to Endpoint Management. If you already have an OpenAPI specification, upload it to [Schema validation](/api-shield/security/schema-validation/). +Both sources provide an **always-on detection** after their profile becomes available. Mitigation requires a separate WAF Custom Rule. :::note -It is recommended to start with Schema validation rules set to `log` to review logged requests in [Security Events](/waf/analytics/security-events/). When you are confident that only the correct requests are logged, you should switch the rule to `block`. +Customers with API Security already have access to Schema Profiles through Schema Learning and Schema Validation. Cloudflare is opening a closed beta to invited Enterprise customers without API Security. Interested customers can contact their account team to express interest. Closed-beta access does not imply future plan availability or pricing. ::: -If you do not have a schema to upload, continue reading this guide to learn how to generate a schema with API Shield. +If you maintain an OpenAPI schema, follow the [Schema Validation upload procedure](/api-shield/security/schema-validation/#upload-a-schema). API Shield remains the reference for OpenAPI compatibility, schema governance, and automation. ## Enable the Sensitive Data Detection ruleset and accompanying rules @@ -49,29 +45,15 @@ Sensitive Data Detection requires a separate subscription. Contact your account You can identify endpoints returning sensitive data by selecting the icon next to the path in a row. Expand the endpoint to see details on which rules were triggered and view more information by exploring events in **Firewall Events**. -## Add your discovered endpoints to Endpoint Management - -Cloudflare automatically discovers API endpoints by inspecting your traffic. Adding these discovered endpoints to [Endpoint Management](/api-shield/management-and-monitoring/endpoint-management/) unlocks additional security and monitoring features. - -Endpoint Management tracks request counts, error rates, and latency for each saved endpoint. - -:::note -Schema validation, schema learning, JWT validation rules, sequence mitigation rules, and rate limit recommendations use operations in the `full` state. Sequence Analytics runs on operations in the `full` or `candidate` state that API Shield can match at the edge. For more information, refer to [Operation states](/security/web-assets/manage-operations/#operation-states). -::: - -You can save your endpoints directly from [API Discovery](/api-shield/management-and-monitoring/endpoint-management/#add-endpoints-from-api-discovery), [Schema validation](/api-shield/management-and-monitoring/endpoint-management/#add-endpoints-from-schema-validation), or [manually](/api-shield/management-and-monitoring/endpoint-management/#add-endpoints-manually) by method, path, and host. - -You can view your list of saved endpoints in the **Endpoint Management** page. Cloudflare will aggregate [performance data](/api-shield/management-and-monitoring/endpoint-management/#endpoint-analysis) and security data on your endpoint once it is saved. +## Manage operations -### Allow the system to learn your traffic patterns +Web Assets continuously discovers operations from traffic. An operation represents an endpoint by HTTP method, hostname pattern, and path pattern. -After you add an endpoint, Cloudflare begins learning schema parameters from your API traffic. Endpoints must be saved for at least 24 hours before schema learning begins. Schema learning is a continuous process that inspects the most recent 72 hours of traffic. Endpoints with higher traffic volumes produce more accurate schemas. +You can also add operations manually under **Web Assets** > **Operations**. Discovery and manual creation only add inventory entries. -Cloudflare also uses your configured session identifiers to generate rate limit recommendations for each endpoint. +To start Schema Learning, select **Learn profile** from the operation overflow menu. Review the learned schema through **View details** > **Security overview**. -Allow at least 24 hours after adding endpoints before proceeding to the schema and rate limit steps below. - -While the system learns your traffic patterns, you can continue with [additional configurations](/api-shield/get-started/#additional-configuration) such as JWT validation or mTLS. +For the complete workflow and traffic thresholds, refer to [Get started with Application Profiles](/waf/detections/application-profiles/get-started/). ## Add rate limits to your most sensitive endpoints @@ -81,20 +63,14 @@ API Shield generates rate limit recommendations for each endpoint based on your Per-session rate limits track traffic from individual visitors during their session to a specific endpoint. This reduces false positives from broadly scoped rules while still limiting abusive traffic. -## Import a learned schema to Schema validation - -Cloudflare learns schema parameters by inspecting request traffic for all endpoints saved to Endpoint Management. You can export the learned schema as an OpenAPI v3.0.0 specification by hostname. - -Import the learned schema into Schema validation to protect endpoints that Cloudflare discovered through traffic inspection — including endpoints you may not have had a schema for previously. - -You can import the learned schema of an entire hostname using the [Cloudflare dashboard](/api-shield/security/schema-validation/#add-validation-by-applying-a-learned-schema-to-an-entire-hostname). Alternatively, you can [apply learned schemas to individual endpoints](/api-shield/security/schema-validation/#add-validation-by-applying-a-learned-schema-to-a-single-endpoint). Before applying a learned schema, export and review it to verify the schema accurately represents your expected traffic patterns. - -## Export a learned schema from Endpoint Management +## Export a learned schema Learned schemas include the hostname, all endpoints by host, method, and path, and detected path variables (for example, `/users/{id}`). They can also include detected query parameters and their format. You can optionally include rate limit threshold recommendations. You can export your learned schemas in the [Cloudflare dashboard](/api-shield/management-and-monitoring/endpoint-management/schema-learning/#export-a-schema) or via the [API](/api/resources/api_gateway/subresources/schemas/methods/list/). +Exporting creates an OpenAPI `v3.0.0` file. To use a fixed profile, upload that file through [Schema Validation](/api-shield/security/schema-validation/). + ## View and configure Sequence Analytics [Sequence Analytics](/api-shield/security/sequence-analytics/) identifies common patterns of API requests — for example, a user checking their account balance before initiating a funds transfer. diff --git a/src/content/docs/api-shield/index.mdx b/src/content/docs/api-shield/index.mdx index 17d43790109..7a38e26efe0 100644 --- a/src/content/docs/api-shield/index.mdx +++ b/src/content/docs/api-shield/index.mdx @@ -11,7 +11,7 @@ head: content: Overview --- -import { Description, Feature, Plan, RelatedProduct, Render } from "~/components" +import { Description, Feature, Plan, RelatedProduct, Render } from "~/components"; Identify and address your API vulnerabilities. @@ -29,7 +29,7 @@ As APIs have become more prevalent, however, so have their problems: - Many companies have [thousands of APIs](/api-shield/security/api-discovery/), including ones they do not even know about. - To support a large base of users, many APIs are protected by a negative security model that makes them vulnerable to credential-stuffing attacks and automated scanning tools. -- With so many endpoints and users, it’s difficult to recognize brute-force attacks against [specific endpoints](/api-shield/security/volumetric-abuse-detection/). +- With so many endpoints and users, it is difficult to recognize brute-force attacks against [specific endpoints](/api-shield/security/volumetric-abuse-detection/). - Sophisticated attacks are even harder to recognize, often because even development teams are unaware of common and uncommon [usage patterns](/api-shield/security/sequence-analytics/). Refer to the [Get started](/api-shield/get-started/) guide to set up API Shield. @@ -44,11 +44,21 @@ Secure your APIs using API Shield's security features. Monitor the health of your API endpoints. +## Use Schema Profiles + +[Application Profiles](/waf/detections/application-profiles/) provides a shared detection, analytics, and mitigation model. Schema Profile is its only current profile type. + +API Shield provides two Schema Profile sources. [Schema Learning](/api-shield/management-and-monitoring/endpoint-management/schema-learning/) learns from traffic, while [Schema Validation](/api-shield/security/schema-validation/) uses uploaded OpenAPI schemas. + +Use API Shield for API inventory, OpenAPI governance, profile export, automation, and higher-scale API workflows. Use the WAF Application Profiles pages for Profile Analysis and Custom Rule enforcement. + ## Availability -Cloudflare API Security products are available to Enterprise customers only, though anyone can set up [Mutual TLS](/api-shield/security/mtls/) with a Cloudflare-managed certificate authority. +Cloudflare API Security products are available to Enterprise customers only. Anyone can set up [Mutual TLS](/api-shield/security/mtls/) with a Cloudflare-managed certificate authority. + +The full API Shield security suite is available as an Enterprise paid add-on. Refer to [API Shield plans](/api-shield/plans/) for feature-specific availability. -The full API Shield security suite is available as an Enterprise-only paid add-on, but all customers can access [Endpoint Management](/api-shield/management-and-monitoring/) and [Schema validation](/api-shield/security/schema-validation/) functionalities. +Customers with API Security already have access to Schema Profiles through Schema Learning and Schema Validation. Cloudflare is opening a closed beta to invited Enterprise customers without API Security. Interested customers can contact their account team to express interest. Closed-beta access does not imply future plan availability or pricing. :::note API Shield currently does not work for JDCloud customers. diff --git a/src/content/docs/api-shield/management-and-monitoring/endpoint-labels.mdx b/src/content/docs/api-shield/management-and-monitoring/endpoint-labels.mdx index 540da8bb39a..b24b5938b1c 100644 --- a/src/content/docs/api-shield/management-and-monitoring/endpoint-labels.mdx +++ b/src/content/docs/api-shield/management-and-monitoring/endpoint-labels.mdx @@ -71,9 +71,7 @@ Cloudflare automatically runs risk scans every 24 hours on your saved endpoints. `cf-risk-mixed-auth`: Automatically added when some successful requests contain a session identifier and some successful requests lack a session identifier. Refer to [Authentication Posture](/api-shield/security/authentication-posture/#process) for more information. -`cf-risk-sensitive`: Automatically added to endpoints when HTTP responses match the WAF's [Sensitive Data Detection](/api-shield/management-and-monitoring/#sensitive-data-detection) ruleset. - -`cf-risk-missing-schema`: Automatically added when a learned schema is available for an endpoint that has no active schema. +`cf-risk-sensitive`: Automatically added to endpoints when HTTP responses match the WAF's [Sensitive Data Detection](/api-shield/management-and-monitoring/endpoint-management/#sensitive-data-detection) ruleset. `cf-risk-error-anomaly`: Automatically added when an endpoint experiences a recent increase in response errors over the last 24 hours. diff --git a/src/content/docs/api-shield/management-and-monitoring/endpoint-management/index.mdx b/src/content/docs/api-shield/management-and-monitoring/endpoint-management/index.mdx index 752d964d494..bca5657afcd 100644 --- a/src/content/docs/api-shield/management-and-monitoring/endpoint-management/index.mdx +++ b/src/content/docs/api-shield/management-and-monitoring/endpoint-management/index.mdx @@ -1,6 +1,6 @@ --- pcx_content_type: concept -description: Promote, learn, and monitor API endpoints with API Shield and Web Assets. +description: Manage API operations through the Web Assets dashboard. products: - api-shield title: Endpoint Management @@ -12,9 +12,15 @@ import { GlossaryTooltip, Plan, Steps, DashButton } from "~/components"; -Web Assets provides a unified inventory for managing API endpoints. In Web Assets, an **operation** represents an endpoint by its HTTP method, hostname pattern, and path pattern. +Endpoint Management content uses the current [Web Assets](/security/web-assets/) dashboard. Go to **Web Assets** > **Operations** to manage API endpoints. -Promote an API endpoint to move its operation into the `full` state. Promotion starts collecting data for profile learning and [performance analysis](#endpoint-analysis). +An operation is Cloudflare's term for an endpoint identified by HTTP method, hostname pattern, and path pattern. Web Assets continuously discovers operations, and you can add them manually. + +Discovery and manual creation only add operations to inventory. To start profiling, select **Learn profile** for the intended operation. + +:::note[Schema Profile availability] +Customers with API Security already have access to Schema Profiles through Schema Learning and Schema Validation. Cloudflare is opening a closed beta to invited Enterprise customers without API Security. Interested customers can contact their account team to express interest. Closed-beta access does not imply future plan availability or pricing. +::: :::note When an endpoint uses [Cloudflare Workers](/workers/), some metrics are not populated. @@ -29,22 +35,15 @@ When an endpoint uses [Cloudflare Workers](/workers/), some metrics are not popu 2. Go to the **Operations** tab. -### Add endpoints from API Discovery - -The **Learn profile** action is available to API Shield customers using unified operation discovery and other customers with access to profile learning. - -This workflow promotes an existing discovered operation. +### Review discovered operations - -1. From **Web Assets** > **Operations**, open the row actions for a candidate or shadow operation. -2. Select **Learn profile**. - +Web Assets continuously adds discovered operations to the inventory. Discovery does not start profile learning. -Cloudflare promotes the operation to the `full` state. The row action then changes to **Profile learned**. For more information, refer to [Promote an operation](/security/web-assets/manage-operations/#promote-an-operation). +Candidate operations can provide context for matching, edge security detections, and [Sequence Analytics](/api-shield/security/sequence-analytics/). You do not need to change every discovered operation. -You do not need to promote every discovered operation. Candidate operations can provide context for matching, edge security detections, and [Sequence Analytics](/api-shield/security/sequence-analytics/) without promotion. Persisted API profiles and [risk findings](/api-shield/management-and-monitoring/endpoint-labels/#risk-labels) require operations in the `full` state. + -### Add endpoints from Schema validation +### Add operations from Schema validation 1. From **Web Assets** > **Operations**, select **Add operation**. @@ -55,7 +54,9 @@ You do not need to promote every discovered operation. Candidate operations can API Shield looks for duplicate operations with the same hostname, method, and path. Duplicate operations are not added. -### Add endpoints manually + + +### Add operations manually 1. From **Web Assets** > **Operations**, select **Add operation**. @@ -64,6 +65,8 @@ API Shield looks for duplicate operations with the same hostname, method, and pa 4. Select **Add operation**. +Manual operation creation does not start profile learning. + When adding an operation manually, you can specify variable fields in the path or hostname. Enclose variables in braces, such as `/api/user/{var1}/details` or `{hostVar1}.example.com`. Cloudflare supports hostname variables in the following formats: @@ -101,13 +104,28 @@ You can edit the identity of an operation. -Editing a candidate or shadow operation promotes it to the `full` state with the edited values. +Editing an operation updates its inventory identity. It does not start profile learning. :::caution[Editing this operation will change its ID] -Cloudflare computes operation IDs from the HTTP method, hostname, and path. Cloudflare relearns labels, schemas, and rate limiting recommendations for an operation with a new ID. +Cloudflare computes operation IDs from the HTTP method, hostname, and path. Changing these values creates a different operation ID. ::: -### Delete endpoints manually +### Start profile learning + +Start profiling only after reviewing the operation identity. + + + +1. From **Web Assets** > **Operations**, open the operation overflow menu. +2. Select **Learn profile**. +3. After the profile becomes available, open the overflow menu again. +4. Select **View details** and review **Security overview**. + + + +For learning requirements, analytics, and enforcement, refer to [Application Profiles](/waf/detections/application-profiles/). + +### Delete operations manually You can delete endpoints one at a time or in bulk. @@ -120,7 +138,9 @@ You can delete endpoints one at a time or in bulk. When you delete a full operation, Cloudflare stops tracking its associated performance and analytics data. Its previous historical metrics cannot be restored. If the operation returns to the `full` state, metric tracking restarts from that point. ::: -## Endpoint analysis + + +## Operation analysis For each operation in the `full` state, you can view: diff --git a/src/content/docs/api-shield/management-and-monitoring/endpoint-management/schema-learning.mdx b/src/content/docs/api-shield/management-and-monitoring/endpoint-management/schema-learning.mdx index e74fec84c1e..d97f2044f2e 100644 --- a/src/content/docs/api-shield/management-and-monitoring/endpoint-management/schema-learning.mdx +++ b/src/content/docs/api-shield/management-and-monitoring/endpoint-management/schema-learning.mdx @@ -1,6 +1,6 @@ --- pcx_content_type: concept -description: Automatically learn API schema parameters from traffic and export in OpenAPI format. +description: Learn Schema Profiles from qualifying operation traffic. products: - api-shield title: Schema learning @@ -8,17 +8,56 @@ sidebar: order: 2 --- -import { Steps, DashButton } from "~/components"; +import { DashButton, Steps } from "~/components"; -Schema learning observes live API traffic for operations in the `full` state. It discovers the parameters, headers, and body formats that your API endpoints accept. You can export learned schemas in OpenAPI `v3.0.0` format by hostname. +:::note +Schema Learning is the learned source for a Schema Profile. For the shared detection and mitigation model, refer to [Application Profiles](/waf/detections/application-profiles/). +::: + +Schema Learning observes qualifying traffic for selected operations. It learns expected request fields and constraints for a Schema Profile. + +An operation is Cloudflare's term for an endpoint identified by HTTP method, hostname pattern, and path pattern. [Web Assets](/security/web-assets/) continuously discovers operations, and you can add operations manually. + +Discovery and manual creation only add operations to your inventory. They do not start profiling. + +## Availability + +Customers with API Security already have access to Schema Profiles through Schema Learning and Schema Validation. Cloudflare is opening a closed beta to invited Enterprise customers without API Security. Interested customers can contact their account team to express interest. Closed-beta access does not imply future plan availability or pricing. + +## Start profile learning -For API Shield customers using unified operation discovery, select **Learn profile** from a discovered operation's row actions. This promotes the operation to the `full` state and starts collecting data for schema learning. The action then changes to **Profile learned**. For more information, refer to [Promote an operation](/security/web-assets/manage-operations/#promote-an-operation). + + +1. In the Cloudflare dashboard, go to **Web Assets** > **Operations**. + + + +2. Open the operation overflow menu and select **Learn profile**. +3. After the profile becomes available, select **View details**. +4. Review the learned schema under **Security overview**. + + -To protect your API with a learned schema, refer to [Schema validation](/api-shield/security/schema-validation/#add-validation-by-applying-a-learned-schema-to-an-entire-hostname). +Cloudflare runs an **always-on detection** after the learned profile becomes available. The detection does not mitigate requests by itself. + +To investigate results, refer to [Analyze profile detections](/waf/detections/application-profiles/analyze-profile-detections/). To mitigate violations, refer to [Enforce profiles with Custom Rules](/waf/detections/application-profiles/enforce-profiles-with-custom-rules/). + +## Meet learning requirements + +Learning runs weekly using qualifying traffic from the previous seven days. Only requests that received a `2xx` response contribute. + +The field-learning threshold requires 1,000 qualifying requests. The boundary-learning threshold requires 10,000 qualifying requests. + +The first profile appears after the next weekly learning run. This can take up to seven days after meeting the relevant threshold. + +For supported request components, constraints, and limitations, refer to [Schema Profiles](/waf/detections/application-profiles/schema-profiles/). ## Export a schema +Export creates a separate OpenAPI file from the current learned profile. It does not change the profile or its detection. + + 1. In the Cloudflare dashboard, go to the **Web Assets** page. @@ -26,6 +65,7 @@ To protect your API with a learned schema, refer to [Schema validation](/api-shi 3. Select **Export schema** and choose a hostname to export. 4. Select whether to include learned parameters and rate limit recommendations. 5. Select **Export schema** and choose a location to save the file. + :::note @@ -34,25 +74,14 @@ The schema is saved as a JSON file in OpenAPI `v3.0.0` format. ## Learned schema contents -Learned schemas always include: +Exported schemas include the listed hostname in the servers section. They also include operations by hostname, method, and path. -- The listed hostname in the servers section -- All full operations by hostname, method, and path - -For operations that receive sufficient traffic, learned schemas will also include: +For operations that receive sufficient traffic, exported schemas also include: - Detected path variables and formats - Detected query parameters and formats - Detected `POST`, `PUT`, and `PATCH` body variable names and formats for `application/json` content types -Learned schemas can optionally include: - -- API Shield's rate limit threshold recommendations - -## Limitations - -An operation must remain in the `full` state for at least 24 hours before schema learning begins. Schema learning continuously inspects the last 72 hours of traffic to the operation. - -Schema learning only learns from requests with `2xx` response codes. +Exported schemas can optionally include API Shield rate limit recommendations. -Schema learning works best with high traffic volumes. Learned schemas may have lower confidence for operations with fewer than 10,000 requests in the last 72 hours. +For a fixed Schema Profile, upload the exported file through [Schema validation](/api-shield/security/schema-validation/). diff --git a/src/content/docs/api-shield/plans.mdx b/src/content/docs/api-shield/plans.mdx index 7cba5403983..40d0c176a54 100644 --- a/src/content/docs/api-shield/plans.mdx +++ b/src/content/docs/api-shield/plans.mdx @@ -9,16 +9,16 @@ sidebar: --- -Free, Pro, Business, and Enterprise customers without an API Shield subscription can access [Endpoint Management](/api-shield/management-and-monitoring/) and [Schema validation](/api-shield/security/schema-validation/), but no other [API Shield](/api-shield/) features. +Customers with API Security already have access to Schema Profiles through Schema Learning and Schema Validation. Cloudflare is opening a closed beta to invited Enterprise customers without API Security. Interested customers can contact their account team to express interest. Closed-beta access does not imply future plan availability or pricing. To subscribe to API Shield, upgrade to an Enterprise plan and contact your account team. -Limits to endpoints apply to Endpoint Management and Schema validation. Refer to the table below for limits based on your zone plan. +Existing operation and uploaded schema limits remain based on your zone plan. These limits do not determine Application Profiles availability. -| Plan type | Saved endpoints | Uploaded schemas | Total uploaded schema size | Rule action | -| --- | --- | --- | --- | --- | -| **Free** | 100 | 5 | 200 kB | `Block` only | -| **Pro** | 250 | 5 | 500 kB | `Block` only | -| **Business** | 500 | 10 | 2 MB | `Block` only | -| **Enterprise without API Shield** | 500 | 10 | 5 MB | `Log` or `Block` | -| **Enterprise with API Shield** | 10,000 | 10+ | 10+ MB | `Log` or `Block` | \ No newline at end of file +| Plan type | Saved operations | Uploaded schemas | Total uploaded schema size | +| --- | --- | --- | --- | +| **Free** | 100 | 5 | 200 kB | +| **Pro** | 250 | 5 | 500 kB | +| **Business** | 500 | 10 | 2 MB | +| **Enterprise without API Shield** | 500 | 10 | 5 MB | +| **Enterprise with API Shield** | 10,000 | 10+ | 10+ MB | diff --git a/src/content/docs/api-shield/reference/terraform.mdx b/src/content/docs/api-shield/reference/terraform.mdx index ef295c6661b..39a06542aad 100644 --- a/src/content/docs/api-shield/reference/terraform.mdx +++ b/src/content/docs/api-shield/reference/terraform.mdx @@ -1,7 +1,7 @@ --- pcx_content_type: how-to title: Terraform -description: Configure API Shield resources with Terraform, including endpoints and schemas. +description: Configure API Shield operations and uploaded schemas. products: - api-shield tags: @@ -9,7 +9,7 @@ tags: --- -import { GlossaryTooltip } from "~/components" +import { GlossaryTooltip } from "~/components"; Get started with API Shield using Terraform from the examples below. For more information on how to use Terraform with Cloudflare, refer to the [Terraform documentation](/terraform/). @@ -19,18 +19,14 @@ The following resources are available to configure through Terraform: - [`api_shield`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/api_shield) for configuring session identifiers in API Shield. -**Endpoint Management** +**Web Assets operations** -- [`api_shield_operation`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/api_shield_operation) for configuring endpoints in Endpoint Management. +- [`api_shield_operation`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/api_shield_operation) for configuring endpoints as operations. **Schema validation** - [`cloudflare_schema_validation_schemas`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/schema_validation_schemas) for configuring a schema in [Schema validation](/api-shield/security/schema-validation/). ~~[`api_shield_schema`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/api_shield_schema)~~ has been deprecated and will be removed in a future version of the terraform provider. -- [`cloudflare_schema_validation_settings`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/schema_validation_settings) for configuring zone-level Schema validation settings. - ~~[`api_shield_schema_validation_settings`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/api_shield_schema_validation_settings)~~ has been deprecated and will be removed in a future version of the terraform provider. -- [`cloudflare_schema_validation_operation_settings`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/schema_validation_operation_settings) for configuring operation-level Schema validation settings. - ~~[`api_shield_operation_schema_validation_settings`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/api_shield_operation_schema_validation_settings)~~ has been deprecated and will be removed in a future version of the terraform provider. **JWT Validation** @@ -51,9 +47,9 @@ resource "cloudflare_api_shield" "session_identifiers" { } ``` -## Manage API Shield Endpoint Management +## Manage Web Assets operations -Refer to the example configuration below to [manage endpoints](/api-shield/management-and-monitoring/) on your zone. +Use operation resources to manage endpoints by method, hostname, and path. These operations appear in the Web Assets inventory. ```tf title="Example configuration" resource "cloudflare_api_shield_operation" "get_image" { @@ -74,14 +70,13 @@ resource "cloudflare_api_shield_operation" "post_image" { ## Manage Schema validation :::note - -It is required to configure Endpoint Management if you want to set up Schema validation using Terraform. +Configure Web Assets operations before activating uploaded schema evaluation with Terraform. ::: -Refer to the example configuration below to manage [Schema validation](/api-shield/security/schema-validation/api/) on your zone. +The schema resource uploads an OpenAPI schema. Setting `validation_enabled` to `true` makes uploaded profile evaluation available. ```tf title="Example configuration" -# Schema that should be used for Schema validation +# Upload an OpenAPI schema for Schema Validation resource "cloudflare_schema_validation_schemas" "example_schema" { zone_id = var.zone_id kind = "openapi_v3" @@ -90,21 +85,10 @@ resource "cloudflare_schema_validation_schemas" "example_schema" { source = file("./schemas/example-schema.yaml") validation_enabled = true } - -# Block all requests that violate schema by default -resource "cloudflare_schema_validation_settings" "zone_level_settings" { - zone_id = var.zone_id - validation_default_mitigation_action = "block" -} - -# For endpoint post_image - only log requests that violate schema -resource "cloudflare_schema_validation_operation_settings" "post_image_log_only" { - zone_id = var.zone_id - operation_id = cloudflare_api_shield_operation.post_image.id - mitigation_action = "log" -} ``` +Activation does not configure mitigation. Use `cf.schema_validation.uploaded.violated` in [WAF Custom Rules](/waf/detections/application-profiles/enforce-profiles-with-custom-rules/). + ## Validate JWTs Refer to the example configuration below to perform [JWT Validation](/api-shield/security/jwt-validation/) on your zone. diff --git a/src/content/docs/api-shield/security/index.mdx b/src/content/docs/api-shield/security/index.mdx index 36a3a3e4120..deeb4103e0f 100644 --- a/src/content/docs/api-shield/security/index.mdx +++ b/src/content/docs/api-shield/security/index.mdx @@ -9,10 +9,11 @@ sidebar: --- -import { DirectoryListing } from "~/components" +[Application Profiles](/waf/detections/application-profiles/) provides the shared profile detection, analytics, and mitigation model. Schema Profile is its only current profile type. +[Schema Learning](/api-shield/management-and-monitoring/endpoint-management/schema-learning/) learns a Schema Profile from traffic. [Schema Validation](/api-shield/security/schema-validation/) supplies the same profile type through uploaded OpenAPI schemas. -Cloudflare offers the following features to help secure your APIs: +API Shield provides API inventory, schema governance, OpenAPI export, and automation. Cloudflare also offers these API security features: | Discovery & management | Posture management | Runtime protection | | --- | --- | --- | @@ -22,7 +23,6 @@ Cloudflare offers the following features to help secure your APIs: | | [Risk labels](/api-shield/management-and-monitoring/endpoint-labels/#risk-labels) | [Mutual TLS (mTLS)](/api-shield/security/mtls/) | | | [Vulnerability Scanner](/api-shield/security/vulnerability-scanner/) | [GraphQL query protection](/api-shield/security/graphql-protection/) | - ## Example Cloudflare solutions Cloudflare API Shield, together with other Cloudflare products, helps protect your API from the [OWASP API Security Top 10](https://owasp.org/www-project-api-security/). These are the most common API security risks, ranging from unauthorized data access to denial of service. @@ -39,7 +39,7 @@ The following table maps each OWASP vulnerability to the Cloudflare features tha | Unrestricted Access to Sensitive Business Flows | [Sequence mitigation], [Bot Management], [GraphQL Query Protection] | | Server Side Request Forgery | [Schema validation], [WAF managed rules], [WAF custom rules](/waf/custom-rules/) | | Security Misconfiguration | [Sequence mitigation], [Schema validation], [WAF managed rules], [GraphQL Query Protection] | -| Improper Inventory Management | [Discovery](/api-shield/security/api-discovery/), [Schema learning](/api-shield/management-and-monitoring/#endpoint-schema-learning) | +| Improper Inventory Management | [Discovery](/api-shield/security/api-discovery/), [Schema learning](/api-shield/management-and-monitoring/endpoint-management/schema-learning/) | | Unsafe Consumption of APIs | [JWT validation], [WAF managed rules] | [Schema validation]: /api-shield/security/schema-validation/ diff --git a/src/content/docs/api-shield/security/schema-validation/api.mdx b/src/content/docs/api-shield/security/schema-validation/api.mdx index fd4ae36d9eb..6e79e325c0d 100644 --- a/src/content/docs/api-shield/security/schema-validation/api.mdx +++ b/src/content/docs/api-shield/security/schema-validation/api.mdx @@ -1,123 +1,112 @@ --- -title: Configure Schema validation via the API +title: API configuration pcx_content_type: how-to -description: Configure per-endpoint schema validation and mitigation actions using the API. +description: Manage uploaded OpenAPI schemas with the Cloudflare API. products: - api-shield sidebar: - label: API + label: API head: - tag: title content: Configure Schema validation --- -import { GlossaryTooltip, Steps, APIRequest } from "~/components" +import { APIRequest, Steps } from "~/components"; -Schema validation 2.0 allows all corresponding configuration calls to be made via API. This validation centers more around individual endpoints and lets you set mitigation actions for each endpoint individually. Additionally, you can use Cloudflare-provided learned schemas that we [learn automatically](/api-shield/management-and-monitoring/#endpoint-schema-learning) from your traffic for individual endpoints. +Use the API to upload, activate, list, and delete OpenAPI schemas. An uploaded schema supplies a Schema Profile for its operations. :::note [Classic Schema validation documentation](/api-shield/reference/classic-schema-validation/) is available for reference only. ::: -## Upload schemas via the API to Schema validation +## Configure an uploaded schema + 1. Upload a schema. -2. Ensure that your endpoints are added in Endpoint Management. -3. Set the schema to `active` if it is not already done. -4. Set the Schema validation zone-wide action from `none` to `log`. -5. Send test traffic that violates the schema. -6. View test traffic in Security Events by filtering for **Service** > **API Shield - Schema validation**. -7. Optional: - - Set a single endpoint to `block`. - - Set the Schema validation zone-wide to `block`. - - Temporarily override all schemas zone-wide to `none`. - - Remove the temporary override. - +2. Add the schema operations to the Web Assets inventory. +3. Activate the schema to make uploaded profile evaluation available. +4. Send representative traffic through the configured operations. +5. Analyze `cf.schema_validation.uploaded.violated` in [Profile Analysis](/waf/detections/application-profiles/analyze-profile-detections/). +6. Configure mitigation with [WAF Custom Rules](/waf/detections/application-profiles/enforce-profiles-with-custom-rules/). -Cloudflare recommends you to rerun test traffic and monitor the HTTP response codes after changing any settings to ensure Schema validation is operating as expected. + Settings changes may take a few minutes to implement. :::note - -Endpoints must be listed in Endpoint Management for Schema validation to match requests. +Operations must exist in Web Assets for Schema Validation matching. ::: ## Configuration ### Upload and activate a schema -Upload a schema via the v4 API using `POST`. This example requires a `example_schema.yaml` schema file in the current folder. +Upload a schema with `POST`. This example uses `example_schema.yaml` from the current directory. ", - validation_enabled: true - }} + path="/zones/{zone_id}/schema_validation/schemas" + method="POST" + json={{ + kind: "openapi_v3", + name: "example_schema", + source: "", + validation_enabled: true, + }} /> ```json output { - "result": - { - "schema": - { - "schema_id": "af632e95-c986-4738-a67d-2ac09995017a", - "name": "example_schema", - "kind": "openapi_v3", - "source": "", - "created_at": "2023-04-03T15:10:08.902309Z" - } - }, - "success": true, - "errors": - [], - "messages": - [] + "result": { + "schema": { + "schema_id": "af632e95-c986-4738-a67d-2ac09995017a", + "name": "example_schema", + "kind": "openapi_v3", + "source": "", + "created_at": "2023-04-03T15:10:08.902309Z" + } + }, + "success": true, + "errors": [], + "messages": [] } ``` -By default, Schema validation is disabled for an uploaded schema so that you can inspect it first. You can upload a schema and enable it immediately by setting the form parameter `validation_enabled=true`. +By default, uploaded schema evaluation is inactive. Set `validation_enabled=true` to make evaluation available during upload. -Use a `PATCH` request to activate a schema after inspection. +Use `PATCH` to activate evaluation after inspecting the schema. ```json output { - "result": - { - "schema_id": "0bf58160-5da3-48ac-80a9-069f9642c1a0", - "name": "api_schema.json", - "kind": "openapi_v3", - "validation_enabled": true, - "created_at": "0001-01-01T00:00:00Z" - }, - "success": true, - "errors": - [], - "messages": - [] + "result": { + "schema_id": "0bf58160-5da3-48ac-80a9-069f9642c1a0", + "name": "api_schema.json", + "kind": "openapi_v3", + "validation_enabled": true, + "created_at": "0001-01-01T00:00:00Z" + }, + "success": true, + "errors": [], + "messages": [] } ``` -When a schema is active, it executes the mitigation action specified for each operation. Refer to [change the default and operation-specific mitigation action](#change-the-default-and-operation-specific-mitigation-action). +Activation makes uploaded profile evaluation available for configured operations. It does not configure mitigation. -### Add new operations to Endpoint Management +### Add schema operations -Schemas contain a set of servers, paths, and methods, which together define an operation. Schema validation only acts on the requests to operations which have been added to the API Shield Endpoint Management. If a schema contains operations which have not been added to Endpoint Management, they can be retrieved together with the configuration information about added operations. +Schemas contain servers, paths, and methods that define operations. An operation represents an endpoint by HTTP method, hostname pattern, and path pattern. + +Schema Validation evaluates requests only for operations added to Web Assets. Retrieve schema operations and their configuration with `GET`. ```bash title="cURL command" curl --request GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/user_schemas/{schema_id}/operations?feature=schema_info&operation_status=new&page=1&per_page=5000" \ @@ -127,29 +116,28 @@ curl --request GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gat ```json output { - "result": - [ - { - "method": "GET", - "host": "example.com", - "endpoint": "/pets" - } - ], - "success": true, - "errors": [], - "messages": [], - "result_info": { - "page": 1, - "per_page": 30, - "count": 1, - "total_count": 1 - } + "result": [ + { + "method": "GET", + "host": "example.com", + "endpoint": "/pets" + } + ], + "success": true, + "errors": [], + "messages": [], + "result_info": { + "page": 1, + "per_page": 30, + "count": 1, + "total_count": 1 + } } ``` To receive information about the configuration of existing operations, Cloudflare recommends passing the `?feature=schema_info` parameter. -You can add new operations in a schema to Endpoint Management using `POST`. +Add schema operations to Web Assets with `POST`. ```bash title="cURL command" curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/operations" \ @@ -166,24 +154,22 @@ curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/operation ```json output { - "result": [ - { - "operation_id": "6c734fcd-455d-4040-9eaa-dbb3830526ae", - "method": "GET", - "host": "example.com", - "endpoint": "/pets", - "last_updated": "2023-04-04T16:07:37.575971Z" - } - ], - "success": true, - "errors": - [], - "messages": - [] + "result": [ + { + "operation_id": "6c734fcd-455d-4040-9eaa-dbb3830526ae", + "method": "GET", + "host": "example.com", + "endpoint": "/pets", + "last_updated": "2023-04-04T16:07:37.575971Z" + } + ], + "success": true, + "errors": [], + "messages": [] } ``` -You can add all operations in a schema that do not already exist in Endpoint Management by combining two commands as one. There is a maximum of 20 operations for this API call. The example requires the `jq` tool. +You can add schema operations that do not exist in Web Assets. This API call supports up to 20 operations and requires `jq`. ```bash title="cURL command" curl --silent "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/operations" \ @@ -194,117 +180,16 @@ curl --silent "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/ :::note -If you run this command again immediately, it will result in an error as all `new_operations` are now `existing_operations`. +Running this command again immediately returns an error. All `new_operations` are already `existing_operations`. ::: -### Change the default and operation-specific mitigation action - -If a schema is uploaded and active for a set of operations, it validates incoming requests to each operation and decides whether a mitigation action should be taken. This mitigation action is defined per operation and can take the values **none**, **log**, and **block**, which correspond to no action, logging the requests, or blocking them before they reach the origin. - -New operations will not have a mitigation action set and will use the zone-wide default mitigation action. The current default mitigation action can be retrieved using `GET`. - -```bash title="cURL command" -curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/settings/schema_validation" \ ---header "Authorization: Bearer " -``` - -```json output -{ - "result": { - "validation_default_mitigation_action": "none", - "validation_override_mitigation_action": null - } - "success": true, - "errors": - [], - "messages": - [] -} -``` - -A new value out of `none`, `log`, and `block` can be set using `PUT`. - -```bash title="cURL command" -curl --request PUT "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/settings/schema_validation" \ ---header "Authorization: Bearer " \ ---header "Content-Type: application/json" \ ---data '{ - "validation_default_mitigation_action": "block" -}' -``` - -```json output -{ - "result": { - "validation_default_mitigation_action": "block", - "validation_override_mitigation_action": null - } - "success": true, - "errors": - [], - "messages": - [] -} - -``` - -If the mitigation action for an individual operation is of interest, the current value can be retrieved with `GET` using the operation ID. - -```bash title="cURL command" -curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/operations/{operation_id}/schema_validation" \ ---header "Authorization: Bearer " -``` - -```json output -{ - "result": { - "mitigation_action": "null" - } - "success": true, - "errors": - [], - "messages": - [] -} - -``` - -If the value is `null`, it means that no mitigation action has been specified for this operation and the default mitigation action is being used. - -You can set the mitigation action to a value out of `none`, `block`, `log`, and `null` by using `PUT`. - -```bash title="cURL command" -curl --request PUT "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/operations/{operation_id}/schema_validation" \ ---header "Authorization: Bearer " \ ---header "Content-Type: application/json" \ ---data '{ - "mitigation_action": "block" -}' -``` - -```json output -{ - "result": { - "mitigation_action": "block" - } - "success": true, - "errors": - [], - "messages": - [] -} -``` - ### List all schemas -You can get an overview of the schemas currently active on a zone using `GET`. +List uploaded schemas on a zone with `GET`. `validation_enabled=true` is an optional parameter. - + ```json output { @@ -328,7 +213,7 @@ You can get an overview of the schemas currently active on a zone using `GET`. :::note -We recommend using the query parameter `omit_source=true` to only display active schemas and not retrieve the source for every schema to get less output. +Use `omit_source=true` to exclude each schema source from the response. ::: ### Delete a schema @@ -336,120 +221,15 @@ We recommend using the query parameter `omit_source=true` to only display active You can delete a schema using `DELETE`. ```json output { - "result": null, - "success": true, - "errors": - [], - "messages": - [] -} -``` - -### Activate a learned schema for an operation - -Cloudflare provides automatically learned parameter schemas for all operations in Endpoint Management with a sufficient amount of requests. A learned schema can be inspected using `GET`. - -```bash title="cURL command" -curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/operations/{operation_id}?feature=parameter_schemas" \ ---header "Authorization: Bearer " -``` - -```json output -{ - "result": - { - "operation_id": "5c734fcd-455d-4040-9eaa-dbb3830526ae", - "method": "PATCH", - "host": "example.com", - "endpoint": "/pets", - "last_updated": "2023-04-04T16:07:37.575971Z", - "features": - { - "parameter_schemas": - { - "last_updated": "2023-04-03T20:11:55.879006Z", - "parameter_schemas": - { - "responses": null, - "parameters": - [ - { - "in": "query", - "name": "var1", - "schema": - { - "type": "string" - }, - "required": true, - "description": "Sufficient requests have been observed for this parameter to provide high confidence in this parameter schema." - } - ], - "x-cf-parameter-schemas": "operation schema with automatically learned path and query parameters" - } - } - } - }, - "success": true, - "errors": - [], - "messages": - [] -} -``` - -If you are satisfied with the inspected parameter schema, you can add and activate it using `PUT`. - -```bash title="cURL command" -curl --request PUT "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/operations/{operation_id}/cloudflare_learned_schema?timestamp=2023-04-03T20:11:55.879006Z" \ ---header "Authorization: Bearer " -``` - -```json output -{ - "result": null, - "success": true, - "errors": - [], - "messages": - [] -} - -``` - -:::note - -Parameter schemas are updated between every 24 hours up to one week. To ensure that a parameter schema has not been updated during the inspection, Cloudflare recommends that you pass the `last_updated` timestamp of the parameter-schema feature (not the `last_updated` of the whole operation) as an identifier in the timestamp query parameter. -::: - -### Disable Schema validation - -To quickly disable Schema validation for a whole zone, use `PATCH`. This operation will override all operation-mitigation actions. - -```bash title="cURL command" -curl --request PATCH "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/settings/schema_validation" \ ---header "Authorization: Bearer " \ ---header 'Content-Type: application/json' \ ---data '{ - "validation_override_mitigation_action": "none" -}' -``` - -```json output -{ - "result": { - "validation_default_mitigation_action": "block", - "validation_override_mitigation_action": "none" - } - "success": true, - "errors": - [], - "messages": - [] + "result": null, + "success": true, + "errors": [], + "messages": [] } ``` diff --git a/src/content/docs/api-shield/security/schema-validation/index.mdx b/src/content/docs/api-shield/security/schema-validation/index.mdx index 41fca1f2581..ee50f2ca3e9 100644 --- a/src/content/docs/api-shield/security/schema-validation/index.mdx +++ b/src/content/docs/api-shield/security/schema-validation/index.mdx @@ -1,7 +1,7 @@ --- pcx_content_type: concept title: Schema validation -description: Validate API requests against OpenAPI schemas to block malformed or unexpected traffic. +description: Supply Schema Profiles through uploaded OpenAPI schemas. products: - api-shield sidebar: @@ -11,212 +11,92 @@ sidebar: import { GlossaryDefinition, GlossaryTooltip, - Plan, Steps, DashButton, } from "~/components"; - +:::note +Schema Validation is the uploaded source for a Schema Profile. For the shared detection and mitigation model, refer to [Application Profiles](/waf/detections/application-profiles/). +::: -Schema validation allows you to check if incoming traffic complies with a previously supplied API schema. When you provide an API schema or select from a list of learned schema, API Shield creates rules for incoming traffic from the schema definitions. These rules define which traffic is allowed and which traffic gets logged or blocked. - -Schema validation 2.0 is the current version. For help configuring the previous version for one or more hosts using the dashboard, refer to [Configure Classic Schema validation](/api-shield/reference/classic-schema-validation/). You can make changes to your Classic Schema validation settings but you cannot add any new schemas. +Schema Validation compares incoming requests with an uploaded OpenAPI schema. The uploaded schema supplies expected request structure for a Schema Profile. -You can migrate to Schema validation 2.0 manually by uploading your schemas to the new system. +After the uploaded profile becomes available, Cloudflare generates an **always-on detection**. Use `cf.schema_validation.uploaded.violated` to analyze and mitigate violations. ---- - -## Process +The detection does not mitigate traffic by itself. Review results in [Profile Analysis](/waf/detections/application-profiles/analyze-profile-detections/) before [enforcing the profile with Custom Rules](/waf/detections/application-profiles/enforce-profiles-with-custom-rules/). -Endpoints must be added to [Endpoint Management](/api-shield/management-and-monitoring/endpoint-management/) for Schema validation to protect them. Uploading a schema via the Cloudflare dashboard will automatically add endpoints, or you can manually add them from [API Discovery](/api-shield/security/api-discovery/). +Schema Validation 2.0 is the current version. For previous-version reference, refer to [Configure Classic Schema Validation](/api-shield/reference/classic-schema-validation/). -If you are uploading a schema via the API or Terraform, you must parse the schema and add your endpoints manually. +## Configure an uploaded schema - +Endpoints must exist as operations in **Web Assets** > **Operations**. Uploading through the dashboard adds schema operations automatically. -:::note -To view the contents in your learned schema, refer to [Export a schema](/api-shield/management-and-monitoring/endpoint-management/schema-learning/#export-a-schema) in Endpoint Management. -::: +When using the API or Terraform, add schema operations separately. For automation details, refer to [API configuration](/api-shield/security/schema-validation/api/) or [Terraform](/api-shield/reference/terraform/#manage-schema-validation). ---- + -### Add validation by uploading a schema +### Upload a schema -1. In the Cloudflare dashboard, go to the **Web Assets** page. - - -2. Go to the **Schema validation** tab. -3. Select **Add validation**. -4. Upload a schema file. -5. Select **Add schema and endpoints**. - - -:::note -Changes may take a few minutes to process depending on the number of added endpoints. -::: -### Add validation by applying a learned schema to a single endpoint - - 1. In the Cloudflare dashboard, go to the **Web Assets** page. -2. Go to the **Schema validation** tab. -3. Select **Add validation**. -4. Select **Apply learned schema**. -5. Choose an action and select **Apply schema**. - - -### Add validation by applying a learned schema to an entire hostname -At this time, learned schemas will not overwrite customer-uploaded schemas. If an endpoint is covered by a customer-uploaded schema and also appears in a learned schema, the **Changes** field is set to `Unaffected`. - - -1. In the Cloudflare dashboard, go to the **Web Assets** page. - - 2. Go to the **Schema validation** tab. 3. Select **Add validation**. -4. Select **Apply learned schema**. -5. Choose a hostname and review the endpoints that will be protected by the learned schema. -6. (Optional) Change the action if a request does not match the schema. -7. Select **Apply schema**. - - -:::note -If an endpoint is currently protected by a learned schema, the date of the last applied learned schema will be shown in the current schema field. -::: - -### Add validation by adding a fallthrough rule - -A fallthrough rule acts as a catch-all for requests that do not match endpoints in [Endpoint Management](/api-shield/management-and-monitoring/endpoint-management/). - -By ensuring that all your endpoints in a schema are added to Endpoint Management, the fallthrough action can protect you against legacy or zombie endpoints that your team may be unaware of. - -To set up a fallthrough action: - - -1. In the Cloudflare dashboard, go to the **Security rules** page. - - -2. Select **Templates**. -3. Search for the template named `Mitigate API requests to unidentified endpoints` and select **Preview template**. -4. Give your rule a descriptive name. -5. Choose one or more hostnames from the dropdown menu and select your action. -6. Select **Save as draft** to deploy later, or **Deploy** to deploy now. - - -Your current fallthrough rules can be viewed in the security rules list. - -:::note -You can use the `cf.api_gateway.fallthrough_detected` field in your own custom rule for a more customized logic check. This field evaluates as `true` when a request does not match an endpoint in Endpoint Management. Check against your API hostname or root path to ensure that you are not blocking non-API traffic on your zone. -::: - -### Change the action of an entire schema - - -1. In the Cloudflare dashboard, go to the **Web Assets** page. +4. Upload an OpenAPI schema file. +5. Select **Add schema and endpoints**. - -2. Go to the **Schema validation** tab. -3. Check the multi-select box to select all endpoints associated with the schema. -4. Select **Change action**. -5. Choose an action from the dropdown menu. -6. Select **Set action**. -### Change the global default action of Schema validation - -Schema validation’s default action is visible on the main Schema validation page. This action applies to any endpoint with its action set to `Default`. +Changes may take several minutes, depending on the operation count. -- `Log` action: logs events to [Firewall Events](/firewall/). -- `Block` action: blocks requests that fail the schema for an endpoint and logs events to [Firewall Events](/firewall/). -- `None` action: non-compliant requests are neither logged nor blocked. + + -To change the default action: +### Manage uploaded schemas -1. In the Cloudflare dashboard, go to the **Security Settings** page. - - -2. Filter by **API abuse**. -3. Under **Schema validation** > **Configurations**, select the edit icon next to **Default action**. -4. Choose a new action from the dropdown menu. -5. Select **Save**. - - -### Change the action of a single endpoint - -You can change individual endpoint actions separately from the default action in Schema validation. -This allows you to be stricter on blocking non-compliant requests on certain endpoints when the default action is `Log`. It can also be used to relax constraints on non-compliant requests on certain endpoints when the default action is set to `Block`. You may want to silence known false positives on an endpoint by setting the action to `None`. - -To change the action on an individual endpoint: - - 1. In the Cloudflare dashboard, go to the **Web Assets** page. -2. Go to the **Schema validation** tab. -3. Search for the endpoint to change. -4. Select the three dots on the endpoint's row > **Change action**. -5. Choose a new action from the dropdown menu and select **Set action**. - - -### Disable Schema validation without changing actions -You can disable Schema validation entirely for temporary troubleshooting. You can override all actions at once, preventing Schema validation from taking any action while you complete your troubleshooting. - -To disable Schema validation without changing actions: - - -1. In the Cloudflare dashboard, go to the **Web Assets** page. - - 2. Go to the **Schema validation** tab. 3. Select **Schema settings**. 4. Filter by **API abuse**. -5. Turn **Schema validation** off. - +5. Under **Schema validation** > **Active schemas**, review uploaded schemas. +6. From the schema overflow menu, download or delete the schema. -Your per-endpoint configurations will be saved when modifying the setting, so that you do not lose your configuration. To re-enable your configurations after troubleshooting, navigate back to the settings and select **Enable**. + -### View active schemas +Deleting an uploaded schema stops its profile evaluation. Associated operations remain in the Web Assets inventory. - -1. In the Cloudflare dashboard, go to the **Web Assets** page. + - -2. Go to the **Schema validation** tab. -3. Select **Schema settings**. -4. Filter by **API abuse**. -5. View your schemas on **Schema validation** > **Active schemas**. - +### Add a fallthrough rule -:::note -To export a schema, refer to [Export a schema](/api-shield/management-and-monitoring/endpoint-management/schema-learning/#export-a-schema). -::: +A fallthrough rule matches requests that do not match known operations. Use this WAF Custom Rule to protect against unidentified endpoints. -### Delete active schemas + -Deleting the schema will remove validation from the currently associated endpoints, but it will not delete the endpoints from Endpoint Management. +1. In the Cloudflare dashboard, go to the **Security rules** page. -To delete currently uploaded or learned schemas: + - -1. In the Cloudflare dashboard, go to the **Web Assets** page. +2. Select **Templates**. +3. Find `Mitigate API requests to unidentified endpoints` and select **Preview template**. +4. Enter a descriptive rule name. +5. Choose the intended hostnames and rule action. +6. Select **Save as draft** or **Deploy**. - -2. Go to the **Schema validation** tab. -3. Select **Schema settings**. -4. Filter by **API abuse**. -5. View your schemas on **Schema validation** > **Active schemas**. -6. Select the ellipses to access the menu and download or delete the listed schema. +For custom logic, use `cf.api_gateway.fallthrough_detected`. Scope the rule to your API hostname or root path. + --- ## Specifications @@ -243,7 +123,7 @@ There is a limit of 10,000 total operations for enabled schemas for Enterprise c ### Body size for validation -Schema validation inspects request bodies up to a maximum size that depends on your zone plan. Request bodies that exceed this limit are not validated against your schema, and the configured [Schema validation action](/api-shield/security/schema-validation/#change-the-global-default-action-of-schema-validation) will not apply to those requests. +Schema Validation inspects request bodies up to a plan-specific maximum size. Requests exceeding this limit are not evaluated against the uploaded schema. The default body size limits are: @@ -260,7 +140,7 @@ This limit is separate from the [WAF maximum body inspection size](/waf/managed- #### Identify requests exceeding the body size limit -If Schema validation is blocking or logging requests due to the body size limit, you will see events in **Security** > **Analytics** > **Events** with the Schema validation rule as the source. +Use request logs to compare body sizes with your plan limit. For limits on Free, Pro, Business, or Enterprise customers not subscribed to API Shield, refer to [Plans](/api-shield/plans/). @@ -379,21 +259,19 @@ Media-ranges can also be configured to enforce a `charset` parameter. For this, This section addresses common issues you may encounter when using schema validation. -### `OneOf` constraint error schema violation in the Security Events +### Resolve a `OneOf` constraint violation -A `OneOf` constraint error means an API request failed schema validation because its body did not match exactly one of the options defined in a [`oneOf`](https://swagger.io/docs/specification/v3_0/data-models/oneof-anyof-allof-not/) list within your uploaded schema. +A `OneOf` constraint error means a request violated its uploaded profile. Its body did not match exactly one [`oneOf`](https://swagger.io/docs/specification/v3_0/data-models/oneof-anyof-allof-not/) option. The request was invalid for one of two reasons: - **Matches Zero**: The payload did not correctly match any of the available subschemas. This is common when a discriminator field is set, but the payload is missing other required fields for that type. - **Matches Multiple**: The payload was ambiguous and matched more than one subschema. This happens with generic schemas (for example, if a payload includes both an `email` and a `phone` field, it might match both an `email` and a `phone` schema definition, violating the "exactly one" rule). -To fix this, check the failing request body against the API schema definition. It will either be missing required fields for the intended type or include properties from multiple different, conflicting types that make it ambiguous. +To fix this, compare the sampled request with its schema definition. The request may omit required fields or match conflicting types. --- ## Availability -Schema validation is available for all customers. Refer to [Plans](/api-shield/plans/) for more information based on your plan type. - -[Schema learning](/api-shield/management-and-monitoring/endpoint-management/schema-learning/) is only available for customers subscribed to API Shield. +Customers with API Security already have access to Schema Profiles through Schema Learning and Schema Validation. Cloudflare is opening a closed beta to invited Enterprise customers without API Security. Interested customers can contact their account team to express interest. Closed-beta access does not imply future plan availability or pricing. diff --git a/src/content/docs/security/security-insights/index.mdx b/src/content/docs/security/security-insights/index.mdx index d4410bafb8a..2b858852d70 100644 --- a/src/content/docs/security/security-insights/index.mdx +++ b/src/content/docs/security/security-insights/index.mdx @@ -42,7 +42,6 @@ Listed below are the specific insights currently available: | [Overprovisioned Access Policies](/cloudflare-one/access-controls/policies/) | We detect an Access policy to allow everyone access to your application. | | [Client-side security not enabled](/client-side-security/get-started/) | Client-side security (formerly known as Page Shield) helps meet PCI DSS v4.0 compliance regarding requirement 6.4.3. | | [SPF Record Errors](/dns/manage-dns-records/reference/dns-record-types/#spf) | We detect an incorrect or missing `SPF` record. | -| [Schema Validation missing from eligible API endpoints](/api-shield/security/schema-validation/) | Apply the learned schema to protect your API against fuzzing attacks. | | [Sensitive data in API response](/api-shield/management-and-monitoring/#sensitive-data-detection) | Sensitive data in API responses detected. | | [Turn on JavaScript Detection](/bots/additional-configurations/javascript-detections/) | One or more of your Bot Management enabled zones does not have JavaScript Detection enabled, which is a critical part of our bot detection suite. | | [Unassigned Access seats](/cloudflare-one/) | We detect a Zero Trust subscription that is not configured yet. | diff --git a/src/content/docs/security/settings.mdx b/src/content/docs/security/settings.mdx index 01c555ce2a8..c467fa8aae0 100644 --- a/src/content/docs/security/settings.mdx +++ b/src/content/docs/security/settings.mdx @@ -65,7 +65,7 @@ Additionally, you can manage the following settings: - [Cloudflare managed ruleset](/waf/managed-rules/reference/cloudflare-managed-ruleset/) - [AI Security for Apps](/waf/detections/ai-security-for-apps/) - [Schema learning](/api-shield/management-and-monitoring/endpoint-management/schema-learning/) -- [Schema validation](/api-shield/security/schema-validation/) (requires you to upload a schema or apply a learned schema) +- [Schema validation](/api-shield/security/schema-validation/) (requires an uploaded schema) - [Under Attack mode](/fundamentals/reference/under-attack-mode/) (under Security Level) - SSL/TLS DDoS attack protection @@ -156,12 +156,11 @@ The following table links to additional information about each available setting | [OWASP Core](/waf/managed-rules/reference/owasp-core-ruleset/) ruleset | **Security** > **WAF** > **Managed rules** tab | | Rate limit authentication requests | **Security** > **WAF** > **Rate limiting rules** tab | | [Replace insecure JavaScript libraries](/waf/tools/replace-insecure-js-libraries/) | **Security** > **Settings** | -| [Schema learning](/api-shield/security/schema-validation/): | **Security** > **API Shield** > **Schema Validation** | +| [Schema learning](/api-shield/management-and-monitoring/endpoint-management/schema-learning/): | **Security** > **Web Assets** > **Operations** | | — [Session identifiers](/api-shield/management-and-monitoring/session-identifiers/) | **Security** > **API Shield** > **Settings** | | [Schema validation](/api-shield/security/schema-validation/) | **Security** > **API Shield** > **Schema Validation** | -| — [Endpoints](/api-shield/management-and-monitoring/endpoint-management/) | **Security** > **API Shield** | +| — [Operations](/api-shield/management-and-monitoring/endpoint-management/) | **Security** > **Web Assets** > **Operations** | | — [Active schemas](/api-shield/security/schema-validation/#view-active-schemas) | **Security** > **API Shield** > **Schema Validation** | -| — [Default action](/api-shield/security/schema-validation/#change-the-global-default-action-of-schema-validation) | **Security** > **API Shield** > **Schema Validation** | | [Security level: I'm under attack mode](/fundamentals/reference/under-attack-mode/) | **Security** > **Settings** | | [Security.txt](/security-center/infrastructure/security-file/) | **Security** > **Settings** | | [Sensitive data detection](/waf/managed-rules/reference/sensitive-data-detection/#configure-in-the-dashboard) ruleset | **Security** > **Sensitive Data** | diff --git a/src/content/docs/security/web-assets/get-started.mdx b/src/content/docs/security/web-assets/get-started.mdx index 5a8a9a4e71c..844908abf9d 100644 --- a/src/content/docs/security/web-assets/get-started.mdx +++ b/src/content/docs/security/web-assets/get-started.mdx @@ -22,7 +22,7 @@ Discovered operations can be used for matching and downstream security detection Add an operation when traffic you want to protect does not appear, or when you want to define the operation structure yourself. -Promote a discovered API endpoint to move its operation into the `full` state and learn its traffic profile. Refine an operation when its method, hostname pattern, or path pattern does not match how the traffic should be grouped or protected. +Manual creation and editing only update operation inventory. Refine an operation when its method, hostname pattern, or path pattern does not match your intended grouping. For more information, refer to [Manage operations](/security/web-assets/manage-operations/). @@ -46,11 +46,13 @@ Certain metrics, such as latency, may not populate when a request is handled by ## Use learned schemas -Schema learning observes live API traffic for operations in the `full` state. It discovers the parameters, headers, and body formats that your operations accept. You can export learned schemas in OpenAPI `v3.0.0` format. +Discovery, manual creation, and editing do not start profile learning. To learn a Schema Profile, select **Learn profile** from the operation overflow menu. + +After the profile becomes available, select **View details**. Review the learned schema under **Security overview**. If you already maintain OpenAPI schemas, you can upload them to create operations and use them with API Shield [Schema Validation](/api-shield/security/schema-validation/). -For more information, refer to [schema learning](/api-shield/management-and-monitoring/endpoint-management/schema-learning/). +For the complete workflow, refer to [Application Profiles](/waf/detections/application-profiles/) and [Schema learning](/api-shield/management-and-monitoring/endpoint-management/schema-learning/). ## Define security protections diff --git a/src/content/docs/security/web-assets/index.mdx b/src/content/docs/security/web-assets/index.mdx index bfa80622160..66776a8d78e 100644 --- a/src/content/docs/security/web-assets/index.mdx +++ b/src/content/docs/security/web-assets/index.mdx @@ -20,7 +20,7 @@ To access Web Assets in the Cloudflare dashboard, go to the **Web Assets** page. ## Definition of an operation -An operation is a group of HTTP requests that serve the same purpose in your application. Each operation is defined by: +An operation is Cloudflare's term for an endpoint. Each operation is identified by: - HTTP method - Hostname pattern @@ -52,11 +52,15 @@ Operations can come from several sources: These sources contribute to the same operation inventory. You do not need to review every discovered operation before security detections can use operation context. +Discovery and manual entry do not start profile learning. Select **Learn profile** for an operation to start intentionally. + ## Operation states and profile learning -Operations can be in the `candidate`, `shadow`, or `full` state. Promoting a candidate or shadow operation moves it to the `full` state and starts collecting data for profile learning. For more information, refer to [Promote an operation](/security/web-assets/manage-operations/#promote-an-operation). +Operations can be in the `candidate`, `shadow`, or `full` state. These states control operation matching and available features. + +An operation state alone does not start profile learning. To learn a Schema Profile, select **Learn profile** from the operation overflow menu. -For API endpoints, configure protections such as [Schema Validation](/api-shield/security/schema-validation/) separately. +For the profile lifecycle, refer to [Application Profiles](/waf/detections/application-profiles/). For uploaded OpenAPI schemas, refer to [Schema Validation](/api-shield/security/schema-validation/). ## Describe operations context diff --git a/src/content/docs/security/web-assets/manage-operations.mdx b/src/content/docs/security/web-assets/manage-operations.mdx index cd58d5bd3ef..b98e28fb41b 100644 --- a/src/content/docs/security/web-assets/manage-operations.mdx +++ b/src/content/docs/security/web-assets/manage-operations.mdx @@ -3,7 +3,7 @@ title: Manage operations pcx_content_type: how-to sidebar: order: 2 -description: Add, promote, review, refine, and delete HTTP request operations in Web Assets. +description: Manage operations and start profile learning in Web Assets. products: - security --- @@ -16,11 +16,11 @@ Each operation has one of the following states: | State | Meaning | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `full` | An operation that you promoted, added manually, or created from a schema. Full operations are used for matching, logging, detections, and rules. | +| `full` | An operation that you selected, added manually, or created from a schema. Full operations are used for matching, logging, detections, and rules. | | `candidate` | An operation that Cloudflare discovered from traffic. Candidate operations are used for matching, logging, detections, and rules before you manually review them. | | `shadow` | An operation that exists in Web Assets but is not used for matching, logging, detections, or rules. | -You do not need to promote every discovered operation to the `full` state. Candidate operations provide operation context automatically, while full operations support additional learning and protections. +You do not need to move every discovered operation to the `full` state. Candidate operations provide operation context automatically. Profile learning starts only when you select **Learn profile**. ## Discovery requirements @@ -47,24 +47,26 @@ Discovery can group them into one operation: GET api.example.com/profile/{var1} ``` -Discovered operations are used for matching before you manually refine them. This provides operation context for discovered traffic without requiring you to promote every discovery first. +Discovered operations are used for matching before you manually refine them. This provides operation context without requiring a state change first. Discovery-backed matching is subject to plan availability and system limits. Cloudflare currently sends up to 3,000 operations per zone to the edge for matching. Operations in the `full` state are prioritized first, followed by operations in the `candidate` state. -## Promote an operation +## Start profile learning -Promote a candidate or shadow operation to move it into the `full` state and start profile learning. +Select **Learn profile** to start intentional profile learning. Discovery, manual creation, and editing do not start profiling. -The **Learn profile** action is available to API Shield customers using unified operation discovery and other customers with access to profile learning. +Customers with API Security already have access to Schema Profiles through Schema Learning and Schema Validation. Cloudflare is opening a closed beta to invited Enterprise customers without API Security. Interested customers can contact their account team to express interest. Closed-beta access does not imply future plan availability or pricing. -After promotion, Cloudflare learns the expected request structure from observed traffic. For API endpoints, API Shield also collects data to learn and report additional context: +For a candidate or shadow operation, this action also moves the operation into the `full` state. An operation already in the `full` state remains there. Cloudflare then learns expected request structure from qualifying traffic. + +For API endpoints, API Shield also collects data for other context: - Request structures through [schema learning](/api-shield/management-and-monitoring/endpoint-management/schema-learning/) - Normal request volume through [rate limit recommendations](/api-shield/security/volumetric-abuse-detection/) - Authentication usage through [Authentication Posture](/api-shield/security/authentication-posture/) - Persisted security findings through [API endpoint risk labels](/api-shield/management-and-monitoring/endpoint-labels/#risk-labels) -Each feature has separate data and timing requirements. For example, [schema learning](/api-shield/management-and-monitoring/endpoint-management/schema-learning/#limitations) requires an operation to remain full for at least 24 hours. +Each feature has separate data and timing requirements. For Schema Profiles, refer to [Schema learning](/api-shield/management-and-monitoring/endpoint-management/schema-learning/). Full operations can also use protections that require a known API endpoint, including [Schema Validation](/api-shield/security/schema-validation/), [fallthrough rules](/api-shield/security/schema-validation/#add-validation-by-adding-a-fallthrough-rule), and [sequence mitigation](/api-shield/security/sequence-mitigation/). @@ -74,12 +76,12 @@ Full operations can also use protections that require a known API endpoint, incl -2. Open the row actions for a candidate or shadow operation. +2. Open the row actions for the operation. 3. Select **Learn profile**. -After promotion, the row action changes to **Profile learned**. +After the profile becomes available, select **View details**. Review the learned schema under **Security overview**. ## Traffic matching behavior @@ -118,6 +120,8 @@ Add an operation manually when traffic you want to protect has not been discover +Manual creation only adds the operation to inventory. Select **Learn profile** separately to start profiling. + ## Use variables in operation patterns When you add an operation manually, use variables to match similar traffic with one operation. @@ -169,10 +173,10 @@ Review overlapping operations before making changes. Cloudflare matches a reques -Editing a candidate or shadow operation promotes it to the `full` state with the edited values. +Editing updates the operation inventory entry. It does not start profile learning. :::caution[Editing this operation will change its ID] -Cloudflare computes operation IDs from the HTTP method, hostname, and path. Cloudflare relearns labels, schemas, and rate limiting recommendations for an operation with a new ID. +Cloudflare computes operation IDs from the HTTP method, hostname, and path. Changing these values creates a different operation ID. ::: ## Delete operations diff --git a/src/content/docs/waf/detections/ai-security-for-apps/get-started.mdx b/src/content/docs/waf/detections/ai-security-for-apps/get-started.mdx index 5dfedb0f951..f5ec1500fbc 100644 --- a/src/content/docs/waf/detections/ai-security-for-apps/get-started.mdx +++ b/src/content/docs/waf/detections/ai-security-for-apps/get-started.mdx @@ -52,20 +52,20 @@ curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/ai-security/settings" -## 2. Save or add an LLM-related endpoint +## 2. Review or add an LLM-related operation Once you have [onboarded your domain](/fundamentals/manage-domains/add-site/) to Cloudflare and some API traffic has already been [proxied by Cloudflare](/dns/proxy-status/), the Cloudflare dashboard will start showing [discovered endpoints](/api-shield/security/api-discovery/). -Save the relevant endpoint receiving LLM-related traffic to [Endpoint Management](/api-shield/management-and-monitoring/endpoint-management/) once it has been discovered, or add the endpoint manually. +In [Web Assets](/security/web-assets/manage-operations/), save the relevant discovered operation receiving LLM-related traffic to move it into the `full` state. If Cloudflare did not discover the operation, add it manually. -1. In the Cloudflare dashboard, go to the **Web assets** page. +1. In the Cloudflare dashboard, go to the **Web Assets** page. 2. Go to the **Discovery** tab. -3. Find the endpoint receiving requests with LLM prompts in the list and select **Save** next to the endpoint. +3. Find the candidate operation receiving requests with LLM prompts and select **Save** to move it into the `full` state. @@ -73,10 +73,10 @@ If you did not find the endpoint in the **Discovery** tab, you can add it manual -1. Go to the **Endpoints** tab. -2. Select **Add endpoints** > **Manually add**. -3. Choose the method from the dropdown menu and add the path and hostname for the endpoint. -4. Select **Add endpoints**. +1. Go to the **Operations** tab. +2. Select **Add operation** > **Manually add**. +3. Choose the method and add the hostname pattern and path pattern for the operation. +4. Select **Add operation**. diff --git a/src/content/docs/waf/detections/application-profiles/analyze-profile-detections.mdx b/src/content/docs/waf/detections/application-profiles/analyze-profile-detections.mdx new file mode 100644 index 00000000000..928b5942119 --- /dev/null +++ b/src/content/docs/waf/detections/application-profiles/analyze-profile-detections.mdx @@ -0,0 +1,45 @@ +--- +title: Analyze profile detections +pcx_content_type: how-to +description: Investigate profile conformance and sampled violation details. +products: + - waf +sidebar: + order: 4 +--- + +import { DashButton, Steps } from "~/components"; + +Use **Profile Analysis** in [Security Analytics](/waf/analytics/security-analytics/) to investigate profile detections. + +## Understand request statuses + +Profile Analysis classifies requests with these statuses: + +- **Conforms:** The evaluated request matched its applicable profile. +- **Violates:** The evaluated request did not match its applicable profile. +- **Not evaluated:** No applicable profile is available, or the profile does not apply. + +## Review detections + + + +1. In the Cloudflare dashboard, go to **Security** > **Analytics**. + + + +2. Open **Profile Analysis** and select a profile. +3. Review conformance trends over your selected time range. +4. Inspect sampled violations for the request component and affected field. +5. Review each sampled violation reason before configuring mitigation. +6. Filter by `cf.schema_validation.learned.violated` or `cf.schema_validation.uploaded.violated` to inspect the corresponding source. + + + +## Interpret violations + +A non-conforming request is not necessarily malicious. Releases, new clients, and valid edge cases can produce violations. + +Cloudflare runs an **always-on detection** after a profile becomes available. Detection does not block requests by itself. + +After reviewing representative traffic, refer to [Enforce profiles with Custom Rules](/waf/detections/application-profiles/enforce-profiles-with-custom-rules/). diff --git a/src/content/docs/waf/detections/application-profiles/enforce-profiles-with-custom-rules.mdx b/src/content/docs/waf/detections/application-profiles/enforce-profiles-with-custom-rules.mdx new file mode 100644 index 00000000000..be863490c2f --- /dev/null +++ b/src/content/docs/waf/detections/application-profiles/enforce-profiles-with-custom-rules.mdx @@ -0,0 +1,72 @@ +--- +title: Enforce profiles with Custom Rules +pcx_content_type: configuration +description: Mitigate profile violations with scoped Custom Rules. +products: + - waf +sidebar: + order: 5 + label: Enforce with Custom Rules +--- + +Application Profiles separate detection from mitigation. Cloudflare runs an **always-on detection** after a profile becomes available. + +A violation does not block a request automatically. Use a [Custom Rule](/waf/custom-rules/) when you are ready to mitigate traffic. + +## Select a detection field + +Use this expression for learned Schema Profiles: + +```txt +cf.schema_validation.learned.violated +``` + +Use this expression for uploaded Schema Profiles: + +```txt +cf.schema_validation.uploaded.violated +``` + +Monitor the selected field in [Security Analytics](/waf/analytics/security-analytics/) before creating a blocking rule. + +## Scope by application + +Limit mitigation to the intended hostname and path: + +```txt +cf.schema_validation.learned.violated and http.host eq "api.example.com" and starts_with(http.request.uri.path, "/v1/orders/") +``` + +Scope mitigation to an operation using its complete identity. Include the HTTP method, hostname, and path: + +```txt +cf.schema_validation.learned.violated and http.request.method eq "POST" and http.host eq "api.example.com" and http.request.uri.path eq "/v1/orders" +``` + +## Combine security signals + +Combine a profile violation with [Attack Score](/waf/detections/attack-score/): + +```txt +cf.schema_validation.learned.violated and cf.waf.score lt 20 +``` + +Combine an uploaded profile violation with [Bot Score](/bots/concepts/bot-score/): + +```txt +cf.schema_validation.uploaded.violated and cf.bot_management.score lt 10 +``` + +## Roll out mitigation + +Review production traffic and sampled violation reasons first. Then [create a Custom Rule](/waf/custom-rules/create-dashboard/) with a suitable action. + +Follow these rollout practices: + +- Start with monitoring in Security Analytics. +- Limit the first rule to one operation. +- Review the effect before expanding scope. +- Recheck profiles after application releases. +- Recheck violations after client changes. + +For field details, refer to [Application Profile fields](/waf/detections/application-profiles/fields/). diff --git a/src/content/docs/waf/detections/application-profiles/fields.mdx b/src/content/docs/waf/detections/application-profiles/fields.mdx new file mode 100644 index 00000000000..2557e92c9c5 --- /dev/null +++ b/src/content/docs/waf/detections/application-profiles/fields.mdx @@ -0,0 +1,31 @@ +--- +title: Fields +pcx_content_type: reference +description: Reference Schema Profile detection fields and usage. +products: + - waf +sidebar: + order: 6 + label: Fields +--- + +import { Type } from "~/components"; + +Schema Profile detections populate these fields after an applicable profile becomes available: + +| Field | Type | Source | Meaning | Available in | +| --- | --- | --- | --- | --- | +| `cf.schema_validation.learned.violated` | | Learned Schema Profile | `true` when an evaluated request violates the learned profile. | Security Analytics and Custom Rules | +| `cf.schema_validation.uploaded.violated` | | Uploaded schema | `true` when an evaluated request violates the supplied schema. | Security Analytics and Custom Rules | + +## Availability + +Customers with API Security already have access to Schema Profiles through Schema Learning and Schema Validation. Cloudflare is opening a closed beta to invited Enterprise customers without API Security. Interested customers can contact their account team to express interest. Closed-beta access does not imply future plan availability or pricing. + +## Evaluation + +Cloudflare evaluates requests after the corresponding profile becomes available. The profile must apply to the request operation. + +Requests without an applicable profile have **Not evaluated** status. + +For request statuses and investigation steps, refer to [Analyze profile detections](/waf/detections/application-profiles/analyze-profile-detections/). diff --git a/src/content/docs/waf/detections/application-profiles/get-started.mdx b/src/content/docs/waf/detections/application-profiles/get-started.mdx new file mode 100644 index 00000000000..2b7e2422b62 --- /dev/null +++ b/src/content/docs/waf/detections/application-profiles/get-started.mdx @@ -0,0 +1,61 @@ +--- +title: Get started +pcx_content_type: get-started +description: Learn a Schema Profile and safely configure mitigation. +products: + - waf +sidebar: + order: 2 +--- + +import { DashButton, Steps } from "~/components"; + +Create a learned Schema Profile for one operation. Then review its detections before configuring mitigation. + +:::note +Customers with API Security already have access to Schema Profiles through Schema Learning and Schema Validation. Cloudflare is opening a closed beta to invited Enterprise customers without API Security. Interested customers can contact their account team to express interest. Closed-beta access does not imply future plan availability or pricing. +::: + +## Review learning requirements + +Cloudflare learns profiles weekly from qualifying traffic during the previous seven days. Only requests that received a `2xx` response qualify. + +An operation needs 1,000 qualifying requests for the field-learning threshold. It needs 10,000 qualifying requests for the boundary-learning threshold. + +After meeting the field-learning threshold, Cloudflare can learn request fields. After meeting the boundary-learning threshold, Cloudflare can learn constraints such as numeric ranges and string lengths. + +The first profile appears after the next weekly learning run. This can take up to seven days after meeting the relevant threshold. + +## Learn and review a profile + + + +1. In the Cloudflare dashboard, go to **Web Assets** > **Operations**. + + + +2. Select a discovered operation or [add one manually](/security/web-assets/manage-operations/#add-operations-manually). An operation uses an HTTP method, hostname pattern, and path pattern. +3. From the operation overflow menu, select **Learn profile**. Discovery and manual creation do not start profiling. +4. Allow Cloudflare to collect enough qualifying traffic. +5. From the operation overflow menu, select **View details**. Review the learned schema under **Security overview**. +6. In **Security** > **Analytics**, open **Profile Analysis**. Review request time series for profile conformance and violations. + + + +7. Drill into sampled logs to review violation reasons. +8. After reviewing representative production traffic, [create a Custom Rule](/waf/custom-rules/create-dashboard/). +9. Scope the rule to the intended hostname, path, or operation. Then choose a mitigation action. + + + +After the profile becomes available, Cloudflare runs an **always-on detection**. It does not mitigate requests without a Custom Rule. + +If no learned schema appears, confirm that you selected **Learn profile**. Cloudflare may still be collecting enough qualifying traffic. + +For learning details and limitations, refer to [Schema Profiles](/waf/detections/application-profiles/schema-profiles/). + +## Use an uploaded schema + +If you have an OpenAPI schema, upload it through [Schema validation](/api-shield/security/schema-validation/). Uploaded schemas produce detections through `cf.schema_validation.uploaded.violated`. + +The API Shield reference covers upload formats, OpenAPI requirements, API configuration, Terraform configuration, and limitations. diff --git a/src/content/docs/waf/detections/application-profiles/index.mdx b/src/content/docs/waf/detections/application-profiles/index.mdx new file mode 100644 index 00000000000..0b36878f198 --- /dev/null +++ b/src/content/docs/waf/detections/application-profiles/index.mdx @@ -0,0 +1,48 @@ +--- +title: Application Profiles +pcx_content_type: overview +description: Compare requests with application-specific expected structures. +products: + - waf +sidebar: + order: 7 + group: + label: Application Profiles +--- + +import { DirectoryListing } from "~/components"; + +Application Profiles define application-specific expectations and classify requests against them. They add a positive-security model to your existing protections. + +Schema Profile is the only current profile type. It models supported request fields, types, formats, ranges, and values. + +:::note +Customers with API Security already have access to Schema Profiles through Schema Learning and Schema Validation. Cloudflare is opening a closed beta to invited Enterprise customers without API Security. Interested customers can contact their account team to express interest. Closed-beta access does not imply future plan availability or pricing. +::: + +## Understand the profile lifecycle + +A Schema Profile can come from observed traffic or an uploaded [OpenAPI schema](/api-shield/security/schema-validation/). Both sources produce the same profile type. + +An operation is Cloudflare's term for an endpoint identified by HTTP method, hostname pattern, and path pattern. [Web Assets](/security/web-assets/) continuously discovers operations, and you can add operations manually. + +Discovery and manual creation only add operations to your inventory. Profiling starts when you select **Learn profile** for an operation. + +After the profile becomes available, Cloudflare runs an **always-on detection**. The detection classifies requests but does not mitigate traffic. + +Review results in **Profile Analysis** before creating a [Custom Rule](/waf/custom-rules/). This keeps detection, investigation, and mitigation as separate steps. + +## Complement existing detections + +Positive security identifies requests outside your expected application structure. A non-conforming request does not need to match an attack signature. + +Application Profiles complement [Managed Rules](/waf/managed-rules/), [Attack Score](/waf/detections/attack-score/), and other negative-security detections. You can combine these signals in Custom Rules. + +## Explore Application Profiles + + + +## See also + +- [Schema learning](/api-shield/management-and-monitoring/endpoint-management/schema-learning/) +- [Schema validation](/api-shield/security/schema-validation/) diff --git a/src/content/docs/waf/detections/application-profiles/schema-profiles.mdx b/src/content/docs/waf/detections/application-profiles/schema-profiles.mdx new file mode 100644 index 00000000000..d4e65b99d29 --- /dev/null +++ b/src/content/docs/waf/detections/application-profiles/schema-profiles.mdx @@ -0,0 +1,67 @@ +--- +title: Schema Profiles +pcx_content_type: concept +description: Understand learned and uploaded Schema Profile sources. +products: + - waf +sidebar: + order: 3 +--- + +A Schema Profile models expected request fields and their constraints. You can learn one from traffic or supply an uploaded schema. + +After a profile becomes available, Cloudflare runs an **always-on detection**. Detection does not mitigate requests by itself. + +## Learn from traffic + +An operation is Cloudflare's term for an endpoint. Its identity combines an HTTP method, hostname pattern, and path pattern. + +[Web Assets](/security/web-assets/) continuously discovers operations under **Web Assets** > **Operations**. You can also add an operation manually. + +Both methods only add operations to the inventory. To start profiling, select **Learn profile** from the operation overflow menu. + +### Meet traffic requirements + +Learning runs weekly using qualifying traffic from the previous seven days. Only requests that received a `2xx` response contribute. + +The field-learning threshold requires 1,000 qualifying requests. The boundary-learning threshold requires 10,000 qualifying requests. + +The field-learning threshold allows Cloudflare to learn request fields. The boundary-learning threshold allows Cloudflare to learn constraints such as numeric ranges and string lengths. + +The first profile appears after the next weekly learning run. This can take up to seven days after meeting the relevant threshold. + +### Review learned content + +From the operation overflow menu, select **View details**. The learned schema appears under **Security overview**. + +Profiles can learn these request components where supported: + +- Path variables +- Query parameters +- Headers and cookies +- JSON request bodies +- Form-encoded request bodies + +Profiles can validate integers, strings, universally unique identifiers (UUIDs), and arrays. Supported constraints include numeric ranges, string lengths, character classes, and enumerations containing up to three values. + +Successful traffic can include bots, scanners, or malicious requests. Review the learned profile before enforcing its detection. + +Each weekly run can update a profile as qualifying traffic changes. For a fixed schema, [export the learned schema](/api-shield/management-and-monitoring/endpoint-management/schema-learning/#export-a-schema) as OpenAPI and [upload it for validation](/api-shield/security/schema-validation/#upload-a-schema). + +### Consider limitations + +Learned Schema Profiles have these limitations: + +- Multipart forms, GraphQL, and XML are unsupported. +- Repeated parameters have each value validated, without uniqueness enforcement. +- Required parameter presence is not enforced. +- New parameters alone do not produce violations. +- Constraints apply to learned fields, not a complete allowlist. + +## Use an uploaded schema + +An uploaded OpenAPI schema supplies expected structure instead of observed traffic. It produces detections through `cf.schema_validation.uploaded.violated`. + +API Shield provides the detailed [Schema validation reference](/api-shield/security/schema-validation/). It covers supported versions, import procedures, OpenAPI fields, body limits, and troubleshooting. + +For automation, refer to the [API](/api-shield/security/schema-validation/api/) and [Terraform](/api-shield/reference/terraform/#manage-schema-validation) instructions. diff --git a/src/content/docs/waf/detections/index.mdx b/src/content/docs/waf/detections/index.mdx index 6af5f621793..60a2aef3a00 100644 --- a/src/content/docs/waf/detections/index.mdx +++ b/src/content/docs/waf/detections/index.mdx @@ -18,10 +18,16 @@ import { DashButton, } from "~/components"; -Traffic detections check incoming requests for malicious or potentially malicious activity. Each enabled detection scores or classifies requests by populating one or more fields. These fields appear as filters in the [Security Analytics](/waf/analytics/security-analytics/) dashboard, and you can use them in rule expressions. +Traffic detections check incoming requests for malicious, potentially malicious, or non-conforming activity. Each enabled detection scores or classifies requests by populating one or more fields. These fields appear as filters in the [Security Analytics](/waf/analytics/security-analytics/) dashboard, and you can use them in rule expressions. Detections are always on once enabled, even if you have not configured any security rules that use them. You can review detection results in [Security Analytics](/waf/analytics/security-analytics/) to identify traffic patterns and spot potentially malicious traffic. For example, you can analyze traffic based on [attack score](/waf/detections/attack-score/), [bot score](/bots/concepts/bot-score/), [content scan results](/waf/detections/malicious-uploads/), or the [presence of personally identifiable information (PII)](/waf/detections/ai-security-for-apps/) in large language model (LLM) prompts. +[Application Profiles](/waf/detections/application-profiles/) compare requests with application-specific expected structures. Profile detections do not mitigate traffic without a security rule. + +:::note[Application Profiles availability] +Customers with API Security already have access to Schema Profiles through Schema Learning and Schema Validation. Cloudflare is opening a closed beta to invited Enterprise customers without API Security. Interested customers can contact their account team to express interest. Closed-beta access does not imply future plan availability or pricing. +::: + Cloudflare provides the following detections: @@ -32,9 +38,9 @@ Cloudflare provides the following detections: For more information on bot score, refer to [Bot scores](/bots/concepts/bot-score/). -## Turn on a detection +## Turn on a settings-managed detection -To turn on a traffic detection: +For detections managed through Security settings: @@ -47,7 +53,7 @@ To turn on a traffic detection: -Enabled detections will run for all incoming traffic. +Detections enabled through Security settings run for all incoming traffic. Application Profiles instead evaluate requests after a learned or uploaded profile becomes available. :::note[Notes] diff --git a/src/content/docs/waf/index.mdx b/src/content/docs/waf/index.mdx index 29b636e8a97..704d8711b8a 100644 --- a/src/content/docs/waf/index.mdx +++ b/src/content/docs/waf/index.mdx @@ -43,6 +43,14 @@ Learn how to [get started](/waf/get-started/). ## Features + + Compare requests with an application-specific expected structure. Review + profile detections before mitigating violations with Custom Rules. + + Create your own custom rules to protect your website and your APIs from malicious incoming traffic. Use advanced features like [WAF attack diff --git a/src/content/fields/index.yaml b/src/content/fields/index.yaml index 31018e78200..eff25e4fef0 100644 --- a/src/content/fields/index.yaml +++ b/src/content/fields/index.yaml @@ -515,6 +515,18 @@ entries: keywords: [request, api shield, client, visitor] summary: Indicates whether the request [violated the schema](/api-shield/security/schema-validation/) assigned to the respective saved endpoint. + - name: cf.schema_validation.learned.violated + data_type: Boolean + categories: [Request] + keywords: [request, schema validation, learned profile] + summary: Returns `true` when an evaluated request [violates the learned profile](/waf/detections/application-profiles/fields/). + + - name: cf.schema_validation.uploaded.violated + data_type: Boolean + categories: [Request] + keywords: [request, schema validation, uploaded schema] + summary: Returns `true` when an evaluated request [violates the supplied schema](/waf/detections/application-profiles/fields/). + - name: cf.api_gateway.fallthrough_detected data_type: Boolean categories: [Request]