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
  • Understand The Learning Level
  • Viewing Suggested Schema
  • Tuning Suggestions

Was this helpful?

  1. Additional Security Engines
  2. API Protection

Track API Discovery Learning

PreviousAPI DiscoveryNextEnforce API Schema

Last updated 3 months ago

Was this helpful?

When and API Discovery is activated, the underlying Machine Learning engine starts to gradually build a suggested schema of the web server's accepted APIs, as explained here:

API Discovery also generates visibiity of your API usage in a dashboard that shows data for all your defined assets that use API Discovery, as explained here:

As time passes, and depending on the size of traffic, variance of request sources, the learning level will gradually increase. When a certain maturity level is reached (Master and above, after a minimum of 10 days), it is recommended to perform a final review of the suggested schema, and use it in the configuration.

Following a certain maturity level, the learning engine will constantly continue to look at the traffic and discover potential suggested changes to the schema. However, at this stage changes will not be suggested until sufficient time has passed (several days, depending on the learn level it has reached) to make sure the changes detected are indeed consistent and required.

At times, the learning engine will request answers to questions about API where fine tuning is needed. Answering those questions improves the accuracy of the suggested schema.

Understand The Learning Level

When HTTP requests are inspected API Discovery learning agent will reach different learning levels. Each level represents the maturity of the learning model and helps to understand what it needs to reach the next level. It will also indicate when it is time to use the suggested schema and activate . The model progresses through the following learning levels:

Step 1: Track the learning level

  • Go to Policy->Assets and select the Asset you want to track.

  • Select the Learn tab. This tab shows the learning statistics of the last 7 days, the Elapsed Time, the Learning Level and the Recommendation at this level.

  • Below the summary you will find the detected schema and below that, the suggestions to the user that will help fine-tune the learning data (Tuning Suggestions).

Step 2: Address the recommended action

Recommendation
Action Required

Send Traffic

Verify agent installation

Keep Learning

No action required. The machine learning model requires additional HTTP requests (and additional time).

Enforce Schema

It is now recommended to use Schema Validation in Prevent mode. The suggested schema to use is the recommended schema to be used by Schema Validation. Activate Schema Validation with the latest suggested schema following a review. A recommended good practice is to activate Schema Validation in Detect mode for a few days, review the logs regarding traffic that would've been blocked by it, and then moving to Prevent.

Review Schema

Schema Validation is active and set to Prevent. It is recommended to replace the schema used by Schema Validation with the latest schema suggestion.

Schema is Enforced

No action required.

Well Done! The asset is protected and the latest learned schema is enforced. The are no further suggested changes.

Review Tuning Suggestions

Improve the accuracy of the suggested schema by answering the Tuning suggestions generated by the learning mechanism.

In the example below the Recommendation is to start enforcing the detected schema.

Viewing Suggested Schema

As the iterative learning model sees more and more traffic, a schema is built.

This learning process never stops, even after reaching the most mature level of the learning model, corresponding with the ever-changing life cycle of a web server, as new APIs are added and sometimes deprecated, causing a need to change the enforced schema.

  • It is possible to view the schema in a similar way to the view within the know API exploration UI tool Swagger. Click Open Schema:

  • It is possible to download the schema in YAML format. Click Download Schema.

  • Data for each endpoint includes:

    • Change status compared to the previously learned schema version.

    • Usage of sensitive data in requests to this endpoint.

    • Counts for requests and unique sources that use this endpoint.

    • Indication of public API (if it was accessed from other public addresses)

    • First and Last seen dates (this data is saved beyond 7 days).

Tuning Suggestions

Step 1: Review Tuning Suggestions

  1. Go to Cloud->Assets and select the Asset you want to review.

  2. Select the Learn tab. This tab, at its bottom, shows Tuning Suggestions and Tuning Decisions.

  3. Review the proposed Tuning Suggestions.

Step 2: Provide feedback to the proposed Tuning Suggestions

  1. Click on the Yes or No button next to the line of the Tuning Suggestion. Your Tuning Suggestion now moves to the Tuning Decisions list, where it is also possible to undo the decision.

Step 3: Review the new recommended action if exists

When the learning level becomes Master, it is recommended to use the suggested schema, after answering all fine tuning questions to achieve the highest accuracy of the suggested schema, review it, and enforce using it.

Hover over the Learning Level tooltip to learn the current learning level and the next level. It will also indicate what is required to reach the next level in the 'Watch next?' section. Positive contributing factors to the learning process are: Time elapsed, amount of traffic inspected, amount of supervised learning suggestions and some other model parameters.

Hover over the Recommendation tooltip to learn what the current recommended action is for the asset. Recommendations include:

The model may ask to review certain events, also called Tuning Suggestions. Providing feedback to these suggestions is not mandatory as the engine is capable of learning by itself. However doing this, allows the machine learning engine to reach a higher maturity level and therefore a better accuracy faster based on human guidance.

Go to of the previous section to learn what to do next to improve the learning process.

ℹ️
ℹ️
Schema Validation
Contextual Machine Learning
Step 2: Learn the recommended action
a new Web API asset is added
API Discovery
Monitor Events
Schema Validation enforcement
Schema Validation enforcement