CloudGuard WAF
  • Documentation Overview
  • What is CloudGuard WAF?
  • Getting started
    • Prepare key information
    • Log in to the Infinity Portal
    • Protect a Web Application / API
    • Deploy Enforcement Point
      • Gateway/Virtual Machine
        • AWS
          • Store Certificates in AWS
          • Store certificates on Gateway
        • Azure
          • Store Certificates in Azure
          • Store Certificates on Gateway
        • VMware
          • Store Certificates on Gateway
          • Configure networking in VMware Deployments
      • WAF as a Service
        • Certificates Managed by Check Point
        • Bring Your Own Certificate
      • Kubernetes Ingress
        • Kong Application Security
        • Istio Application Security
      • Docker
        • Single Docker
          • Deployment using 'docker' command
            • Store Certificates Locally on Docker
          • Deployment in Azure App Services
        • Dual Docker: NGINX/Kong/Envoy + Security Agent
      • Linux / NGINX / Kong
    • Monitor Events
  • Concepts
    • Gateways & Agents
    • Management & Automation
    • Security Practices
    • Contextual Machine Learning
  • Additional Security Engines
    • Anti-Bot
    • API Protection
      • API Discovery
      • Track API Discovery Learning
      • Enforce API Schema
    • File Security
    • Intrusion Prevention System (IPS)
    • Rate Limit
    • Snort Rules
  • SETUP INSTRUCTIONS
    • Setup Custom Rules and Exceptions
    • Setup Web User Response Pages
    • Setup Log Triggers
    • Setup Report Triggers
    • Setup Notification Triggers
    • Setup Behavior Upon Failure
    • Setup Agent Upgrade Schedule
  • HOW TO
    • Edit Web Application/API Settings
    • Edit Reverse Proxy Advanced Settings for a Web Asset
    • Protect an existing production site with CloudGuard WAF's Gateway
    • View Policy of all your Web Applications/APIs
    • Add Data Loss Prevention (DLP) rules
    • Configure Contextual Machine Learning for Best Accuracy
    • Track Agent Status
    • Track Learning and Move from Learn/Detect to Prevent
    • Rotate profile authentication token
    • Upgrade your Reverse Proxy when a Linux/NGINX agent is installed
    • Use Terraform to Manage CloudGuard WAF
    • Authorize Temporary Access for Check Point Support
    • Restrict Access to Backend Servers from CloudGuard WAF as a Service IPs Only
  • Troubleshooting
    • WAF Gateway / Virtual Machine
      • Azure
        • "Unable to find a tag containing the vault's name in the VMSS" Error
        • How To: Configure Key Vault for a Single Gateway
      • NGINX Error: Upstream Sent Too Big Header While Reading Response Header from Upstream
      • How To: Compare Between the Gateway's Certificate and the Upstream Certificate
    • Linux
      • SELinux: Checking Status and Disabling
    • WAF as a Service
      • Certificate Validation Failed: Adjusting CAA Record
      • How To: Redirect a Root Domain to a Subdomain Protected by WAF SaaS
      • How To: Extend Connection Timeout to Upstream
      • How To: Update Expired Certificates
  • references
    • Agent CLI
    • Management API
    • Event Query Language
    • Writing Snort Signatures
    • Events/Logs Schema
    • CVE-2022-3786 and CVE-2022-3602: OpenSSL X.509 Email Address Buffer Overflows (HIGH)
    • CVE-2025-1097, CVE-2025-1098, CVE-2025-24514, CVE-2025-1974: Ingress NGINX Controller RCE (Critical)
  • Resources
    • GitHub
    • Docker Hub
Powered by GitBook
On this page
  • What is OpenAPI Specifiction (OAS)
  • API Discovery behavior change after activating Schema Validation
  • How to set up CloudGuard WAF Schema Validation

Was this helpful?

  1. Additional Security Engines
  2. API Protection

Enforce API Schema

PreviousTrack API Discovery LearningNextFile Security

Last updated 3 months ago

Was this helpful?

CloudGuard WAF's Schema Validation engine validates that API input conforms to the schema provided by the admin.

The admin provides the schema (using the OpenAPI specification, or OAS in short) and enhances the ability of CloudGuard WAF to detect and prevent illegal requests that do not comply.

What is OpenAPI Specifiction (OAS)

The defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.

An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.

API Discovery behavior change after activating Schema Validation

As long as schema validation is not active yet, API discovery can differentiate real APIs from requests by online scanners, by disregarding all APIs that do not receive a 200 OK HTTP response code.

Once schema validation is active in prevent mode, it will block all responses that do not conform to the schema. For this reason, the only way to detect new APIs that are missing from the schema is to use data from requests that are blocked by schema validation as well.

Once schema validation is active in Prevent mode, the need to carefully review new API changes in the following versions of the detected schema becomes much more important. The user must not accept changes of new APIs that are not used by the web server.

Use the multi-select option explained below to remove new APIs that are not supported by your server.

How to set up CloudGuard WAF Schema Validation

Step 1: Follow API discovery until it is recommended to enforce the detected schema (or create an OpenAPI YAML file of your API manually)

The recommended flow, even if you already had a highly maintained openAPI schema file of your APIs, is to allow API discovery learning mechanism to detect the actually used APIs in your server.

Follow the instructions for and , to see when it is recommended to enforce the detected schema.

If you did have a highly maintained openAPI schema file, it is recommended to compare teh detected schema by CloudGuard WAF's API discovery and your own schema, and review the differences.

After merging the 2 schemas, and enforcing the new schema using the configuration described below, continue maintaining the schema through CloudGuard WAF which will track changes based on the uploaded schema file.

Step 2: Browse to Policy->Assets and edit the Web Application / API asset

Once the asset edit window opens, select the API Protection tab, choose the Mode you would like this practice will work on, and scroll to the Schema Validation sub-practice.

Step 3: Use the discovered schema (or, less recommended, upload a manually created schema file)

The recommended option is to select Use Discovered Schema and click Select. The schema selection window will appear:

The top will show the Currently enforced scheme name (or "No revision" upon the first time activating the schema validation feature).

Select:

  • Whether the "Changes" column will show APIs that have changed in any of their parameters and configuration, or just compare the endpoints (HTTP Method and URI) without query parameters, request body structure, etc.

The less recommended option is to select Use Custom Schema and Click on the Upload button the file selection window will appear:

  • Click the "Add File" icon to add a new file.

  • Optionally - you can click the "Download" icon to verify an existing file's content.

  • Select the file you wish to be used for schema validation.

  • Click OK.

When making the first change to the default Web API Best Practice's configuration such as uploading your unique OpenAPI schema file for Schema Validation purposes, you will be prompted to change the name of the Practice to your own custom practice name.

Step 4: Select if to enforce the schema according to the entire file or just API endpoints

It possible to enforce the schema at 2 levels:

  • Full schema - The entire schema file is enforced

  • API endpoints only - everything in the schema file, except the HTTP methods and URIs is disregarded. Requests are being compared to the schema for enforcement solely based on their HTTP method and URI.

Step 5: Make sure the Mode of the Schema Validation sub-practice is as desired

Setting the Mode to As Top Level means inheriting the primary mode of the practice.

Otherwise you can override it only for this specific sub-practice to Detect/Prevent/Disable.

It is recommended to initially set the mode to "Detect" to verify the input schema file is correct by looking at the logs created by this capability. Afterwards, restore the mode to the desired state.

Step 6: Enforce Policy

Click Enforce on the top banner of the Infinity Portal.

Activating schema validation if you already have a trusted schema file

Important reminder - The API discovery engine was designed to learn what API is actually being used. Even if you have a well-maintained schema file for your API, it is still recommended to wait before activating the Schema Validation Security engine, until the API discovery practice has learned the actual API usage in your system and suggested a schema.

At that point we recommend comparing the suggested schema with the schema file you had, and deciding on the exact schema to enforce accordingly.

If you decide to skip API discovery (not recommended) and move directly to schema validation with your own well-maintained schema file, skip directly to the following documentation and use the option of uploading your own schema file:

Which detected revision of the schema to select. Use the icon to change the table view to a multi-selection table. This will allow you to pick and choose which APIs will be enforced. You will be asked to provide a new name if you choose this option.

Once there is a well-maintained schema file, such as the schema the API discovery engine provides once it learned traffic to a high enough level, adding a schema file and activating the Schema Validation enforcement engine can further increase the security level by adding an schema file for your API. CloudGuard WAF will enforce the different unique applicative validations described in the schema file and alert upon attempts to use APIs in a way that does not match your schema.

OpenAPI Specification (OAS)
configuring API discovery
tracking its learning results
openAPI