Which rule changes in the background when I Allow / Teach (Learning Suggestion)?

Short answer

Allow / Teach does not turn off a signature; it finds the host group according to the Host value of the request and the page type rule according to its path, and writes the change to that rule (where rules come from). The target is searched in the following order: first the argument rule defined for that parameter in the rules that match the path (in the order exact path, glob or regex, Any Paths), otherwise the common rule for the field of the most specific rule that matches the path; if this rule defines no inspection at all for the field, the inspection of the field is copied from Any Paths and added to the rule (Existing rule will be extended). In a signature hit, the signature is added to the OWASP Exclusions list of the target. In a structural violation, the numeric limit is widened to slightly above the observed value, the name is added to the allowed list or removed from the required list, the method is added to the allowed methods, the value pattern is removed entirely or the block switch is turned off. In a blacklist hit, the rule does not change; the address is written to the Frontend Blacklist Exclusions list. Changes in the Header field are always written to the Any Paths rule. If the matched rule is Any Paths and the Rule Creation Policy covers the field of the attack, a new exact rule is opened for the path of the request (New rule will be created). The Learning Suggestion row on the Attacks tab of the Event Logs preview shows this decision as a sentence before the operation.

How Does It Work?

Allow / Teach finds the target for every attack in the following order:

Step	Selection
Host group	The Host value of the request is compared with the Virtual Host Patterns of the groups; if no group matches, the default group (Which host group does a request fall into; what if it matches none?)
Argument rule	The argument rule defined for that parameter in the rules that match the path; if it exists in more than one rule, the first one in the order exact path, glob or regex, Any Paths. In an attack in the Path field, no argument rule is searched; the rule's own path inspection is targeted
Common rule	If there is no argument rule, the common rule for the field of the most specific rule that matches the path (in the order exact path, glob or regex, Any Paths); if this rule defines no inspection at all for the field, a new common rule copied from Any Paths

Learning does not open a new argument rule; an argument rule is targeted only if it is already defined (learning methods). Structural inspections that belong to the field as a whole, such as the number of parameters and the key length, are always written to the common rule.

Learning Suggestion texts and their counterparts:

Learning Suggestion text	Change
<signature> will be marked as OWASP exclusion	The signature is added to the OWASP Exclusions list of the target
<field>: <name> will be added	The name is added to the allowed list (e.g. the allowed parameters)
<field>: <name> will be removed from the list	The name is removed from the required list
<field> is <old> now and will be <new>	The numeric limit is widened to slightly above the observed value (e.g. 1024 for an observed 1000, 384 for 300)
<field> will be updated as <new>	The method is added to the allowed methods
<field> will be disabled	The value pattern is removed entirely or the block switch (e.g. blocking an invalid body) is turned off
Adding <IP> as blacklist exclusion	The address is written to the Frontend Blacklist Exclusions list; if it is in the Frontend Blacklist list of the vService, it is removed from there (Does "Add to Whitelist (vService)" in Event Logs exempt an IP from WAF inspection, or does it only add a blacklist exclusion?)
Already learned	No change is needed; the teaching button is disabled

In a value pattern violation, the following note is added to the suggestion: Learning cannot narrow a regex, only remove it. To keep the pattern, the rule is edited manually (How do I edit the matching rule from a log with "Edit Corresponding Rule"?).

Rule Creation Policy determines whether a new rule is opened when the matched rule is Any Paths:

Rule Creation Policy	Fields for which a new exact rule is opened
Page Independent	None; the change is written to Any Paths
Data Based (default)	Query, JSON, XML, Raw, Form
Comprehensive	Path, Query, JSON, XML, Raw, Form

Header does not open a new rule in any policy (Why are rules learned from headers written to the Any Paths rule rather than per page?). An allowed method violation, on the other hand, always opens a new exact rule in the policies other than Page Independent. The new rule inherits the allowed methods, the path depth and the path OWASP settings from Any Paths (Does changing the Rule Creation Policy change existing rules?).

Reading and Reverting the Suggestion in TR7

• Reading the suggestion: In the Left Monitor Panel → WAF-Protected vServices → vService → Event Logs tab, the record is clicked; on the Attacks tab of the preview, the attack row is selected. The Corresponding Rule row shows the path of the target rule (with the parameter name if it is an argument rule), the Learning Suggestion row shows the change to be made, and the note below it shows the New rule will be created or Existing rule will be extended status.
• Applying: The change is applied after the Are you sure? confirmation without a separate preview or deployment step (How do I allow a request that was blocked by mistake?).
• Reverting: There is no revert operation on the Event Logs screen. In the Log tab of the WAF - WAAP Data Flow Panel on the right of the Dashboard or the WAF Management tab, the Revert Learning button under the learning record whose source is WAF Logs is used; full permission in the WAF area is required. If the rule opened by the learning has not been changed since that day, the rule is deleted. If the change was written to Any Paths, the revert affects all the paths that use that rule (Can I revert a learned rule?).
• Choosing the scope: For the change to go down to a single parameter, the argument rule of that parameter is added first (Should I fix a false positive for a single parameter only or for the whole page?).

Common Misconceptions

• "Allow turns off the signature." The signature becomes an exclusion only in the field of the target rule; it continues to be scanned in the other fields and pages.
• "The numeric limit is set equal to the observed value." The limit is rounded up to slightly above the observed value, leaving a margin.
• "A header false positive is taught only for that page." Header changes are always written to the Any Paths rule, that is, to the host group as a whole.
• "If the Corresponding Rule is Any Paths, the change is written to the whole site." If the policy covers the field, a new exact rule is opened for the path of the request; the note below the suggestion row shows this.

How it is done in the documentation

• Event Logs · Attacks Tab
• WAF Rules · Where Do the Rules Come From?
• Learning Methods · Rule Creation Policy

Related questions

• Should I fix a false positive for a single parameter only or for the whole page?
• Does changing the Rule Creation Policy change existing rules?
• Why are rules learned from headers written to the Any Paths rule rather than per page?