Track API Discovery Learning
When a new Web API asset is added 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:
pageAPI DiscoveryAPI 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:
pageMonitor EventsAs 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 Schema Validation enforcement 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 Schema Validation enforcement. The model progresses through the following learning levels:
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 Schema Validation using it.
Step 1: Track the learning level
Go to Cloud->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).
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.
Step 2: Address the recommended action
Hover over the Recommendation tooltipℹ️ to learn what the current recommended action is for the asset. Recommendations include:
| 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
The Contextual Machine Learning 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.
Step 1: Review Tuning Suggestions
Go to Cloud->Assets and select the Asset you want to review.
Select the Learn tab. This tab, at its bottom, shows Tuning Suggestions and Tuning Decisions.
Review the proposed Tuning Suggestions.
Step 2: Provide feedback to the proposed Tuning Suggestions
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
Go to Step 2: Learn the recommended action of the previous section to learn what to do next to improve the learning process.
Last updated
