waf options

The waf options command manages the WAF settings of a vService: it determines how tightly the inspections will be applied, what will be returned to the blocked request, how the body will be processed, how the rules will be learned and in which cases a warning will be produced.

Command Summary

TR7 WEB-CLI · waf options

# Tab after the command

admin@TR7LBWAF01> waf options

show update update-many

 

admin@TR7LBWAF01> waf options show poolId <vservice>

admin@TR7LBWAF01> waf options update poolId <vservice> …

admin@TR7LBWAF01> waf options update-many target selected …

admin@TR7LBWAF01>  

This resource is a single setting per vService: it does not have the add and delete actions. In every command, on which vService it is worked is stated by the field name and its value being written together.

Required Fields

Order	Field	Status	Value
1	poolId	Required	The vService record the settings belong to; it is asked for in the show and update commands

In the bulk update, instead of poolId, target is asked for (see Bulk Update).

The Basic Inspections

Field	What it does	What is written after it
--structureChecks	Turns on the request passing the structural inspections	true · false (the default is false)
--argumentChecks	Turns on the request arguments being inspected	true · false (the default is false)
--maxAllowedArguments	Determines at most how many arguments will be allowed in a request	1 or a larger integer (the default is 15)
--owaspProtectionLevel	Selects how tightly the OWASP rule set will be applied	24 — Elementary · 16 — Normal · 8 — Tight · 4 — Very tight · 2 — Aggressive. As the number gets smaller, the protection gets tighter
--maxOwaspExclusions	Limits at most how many OWASP exclusions can be defined in a rule	1 or a larger integer
--syncWithDefaultFwRules	Triggers the default WAF rule set of the service being set up again according to the protection level	true (the default) · false. It is not a stored setting but a writing trigger; it is not accepted in the bulk update

The Blocking Page

It determines which content and which status code will be returned to the blocked request.

Field	What it does	What is written after it
--blockingContentSource	Selects where the blocking content will come from	profile from the content profile (the default) · when it is left empty, the content is written manually
--blockingContentProfile	Selects which content profile will be used	The page content profile. It opens only while --blockingContentSource profile
--blockingContent	Determines the manually written blocking content	The content text (the default is BLOCKED). It opens only while the source is other than profile
--blockingContentType	Selects the type of the manually written content	text/html (the default) · text/plain · text/css · application/json · application/xml · application/x-ns-proxy-autoconfig. It opens only while the source is other than profile
--blockingStatusCode	Selects which HTTP status code will be returned to the blocked request	The status code (the default is 418); the set covers the 2xx, 3xx, 4xx and 5xx codes
--blockingPageRules.N.cond	Determines under which condition a different blocking page will be shown	The condition expression; every rule with its own index
--blockingPageRules.N.pageProfile	Selects which page profile will be shown when that condition is met	The page content profile
--blockingPageRules.N.statusCode	Selects the status code to be returned under that condition	The status code. When it is left empty, the general blocking code is used

The WAF Scope

Field	What it does	What is written after it
--dontWafStaticContent	Provides that the static content requests are not passed through the WAF inspection	true (the default) · false
--decodePaths	Turns on the request paths being decoded before the inspection	true (the default) · false
--wafConditionEnabled	Turns on the WAF exemption condition being applied	true · false (the default is false)
--wafCondition	Determines which requests will be kept exempt from the WAF inspection	The condition expression. It opens only while --wafConditionEnabled true
--wafLogSuppressionCondition	Determines which WAF events will not be written into the log	The condition expression

Blacklist

Field	What it does	What is written after it
--blacklistProtection	Turns on the protection against the sources in the blacklist	true · false
--blacklistProtectionCategories.N	Determines which blacklist categories will be applied	The category name; every category with its own index (the default is user)
--blacklistIps	Determines the blacklist addresses specific to this service	The address list; it is a multi-line text field
--blacklistExclusions	Determines the addresses to be kept exempt from the blacklist	The address list; it is a multi-line text field

The Body Processing

Field	What it does	What is written after it
--bodyParseLimit	Determines at most how much of the request body will be processed	An integer between 1 and 262144; the unit is kB
--bodyMaxLogSize	Determines at most how much of the body will be written into the log	0 or a larger integer; the unit is kB
--dontBufferRequest	Turns on the body being waited for a limited time, without the whole of it being waited for	true · false (the default is false)
--waitForBodyMs.val	Determines how long the body will be waited for	A number (the default is 300). It opens only while --dontBufferRequest true
--waitForBodyMs.unit	Selects the unit of that duration	ms (the default) · s

Rule Management and Sampling

Field	What it does	What is written after it
--createRulePolicy	Selects how narrowly the learned rules will be written	loose · onlyVar · strict
--smartSampling	Turns on the repetition of the requests of the same shape being reduced in the learning log	true (the default) · false
--smartSamplingCopies	Determines how many full copies will be stored for every request shape	An integer between 5 and 10000 (the default is 50). It opens only while --smartSampling true

The Trusted Sources

It provides that the learning is done only from the traffic that comes from certain sources.

Field	What it does	What is written after it
--smartLearning	Turns on the trusted source learning	true · false (the default is false)
--smartLearning_ip	Determines the traffic coming from which address will count as trusted	The address. It opens only while --smartLearning true
--smartLearning_cookie	Determines the request carrying which cookie will count as trusted	The cookie name. It opens only while --smartLearning true
--smartLearning_header	Determines the request carrying which header will count as trusted	The header name. It opens only while --smartLearning true
--fpcFrequency	Determines with which frequency the learning from the trusted source will be done	The frequency value

The AI Learning

It manages deriving rules from the traffic as a whole and which thresholds the derivation has to meet.

Field	What it does	What is written after it
--collectiveLearning	Turns on the learning from the traffic as a whole	true · false (the default is false)
--collectiveLearningFrequency	Determines with which frequency the learning will be done	The frequency value. It opens only while --collectiveLearning true
--countryFilter_SL.N	Determines the traffic coming from which countries will be counted in the learning	The country value; every country with its own index, the same country cannot be written twice
--onlyBrowsers	Provides that only the browser requests take part in the learning	true · false (the default is false)
--onlyDomains	Provides that only the requests that carry a valid domain name take part in the learning	true · false (the default is false)
--skipBlacklistIps	Provides that the traffic coming from the addresses in the blacklist does not take part in the learning	true · false (the default is false)
--minReq_SL	Determines the least number of requests needed for a rule to be derived	1 or a larger integer (the default is 10)
--minCi_SL	Determines the least number of clients needed	1 or a larger integer
--minCountry_SL	Determines the least number of countries needed	1 or a larger integer
--minNetwork_SL	Determines the least number of ASN networks needed	1 or a larger integer

The Analysis

Field	What it does	What is written after it
--analyze	Turns on the requests of a certain source being examined in detail	true · false (the default is false)
--analyze_ip	Determines the requests of which address will be examined	The address. It opens only while --analyze true
--analyze_cookie	Determines the requests carrying which cookie will be examined	The cookie name. It opens only while --analyze true
--analyze_header	Determines the requests carrying which header will be examined	The header name. It opens only while --analyze true

The E-mail Report

It determines to whom, in which format and with which frequency the scheduled WAF report will be sent.

Field	What it does	What is written after it
--emailReport	Turns on the scheduled report sending	true · false (the default is false)
--emailAddresses.N	Determines to which addresses the report will be sent	The e-mail address; every address with its own index. It opens only while --emailReport true
--emailFileTypes.N	Selects in which format the report will be attached	pdf (the default) · xlsx
--emailFrequency.N	Selects with which frequency the report will be sent	daily (the default) · weekly · monthly · annual

The Notifications

It determines through which channels the warning produced when the threshold is exceeded will be delivered.

Field	What it does	What is written after it
--notifyBlockRate	Determines with the exceeding of which threshold by the number of blockings per second a warning will be produced	1 or a larger integer. When it is left empty, this threshold is not applied
--notifyAttackRate	Determines with the exceeding of which threshold by the number of attack detections per second a warning will be produced	1 or a larger integer. When it is left empty, this threshold is not applied
--notifyEmail.N	Determines to which e-mail addresses the warning will be sent	The e-mail address; every address with its own index
--notifySms.N	Determines to which telephone numbers the warning will be sent	The telephone number; every number with its own index
--notifySnmp	Turns on the warning being sent as an SNMP notification	true · false (the default is false)
--notifyUi	Turns on the warning being shown in the management interface	true (the default) · false

The Advanced Notifications

It produces a warning with the exceeding of the threshold by the events counted in a certain scope and in a certain window. Every entry is written with its own index.

Field	What it does	What is written after it
--advancedNotifications.N.scope	Selects in which scope the count will be kept	global · src_ip · subnet · country · asn · nettype_group · nettype_category · host
--advancedNotifications.N.maskV4	Determines the IPv4 network mask in the subnet scope	The mask length (the default is 24). It opens only while scope subnet
--advancedNotifications.N.maskV6	Determines the IPv6 network mask in the subnet scope	The mask length (the default is 64). It opens only while scope subnet
--advancedNotifications.N.countType	Selects which events will be counted	block the blocked requests · detect the detected attacks
--advancedNotifications.N.window.val	Determines in which window the count will be kept	A number; the window cannot be shorter than 30 seconds and longer than 1 hour
--advancedNotifications.N.window.unit	Selects the unit of that window	s · m · h
--advancedNotifications.N.limit	Determines at how many events per window a warning will be produced	1 or a larger integer
--advancedNotifications.N.reportFileTypes.N	Selects in which format a report will be attached to the warning message	pdf · xlsx. When it is left empty, the message is sent without an attachment

The WAF Info Content

It determines the attack details written into the blocking page and into the log records.

Field	What it does	What is written after it
--wafInfoPayload	Selects whether the attack pattern will be written into the info content or not	1 it is written · 0 it is not written. When it is left empty, the field stays undefined
--wafInfoFields.N	Selects which details will take place in the info content	score · severity · scope · monitor · name · desc · category · cwe · mitre · capec · owaspWeb · owaspApi · target. By default score, scope and monitor are selected
--wafInfoLang	Selects the language of the info content	en (the default) · tr
--wafInfoDesc	Selects in which language the attack description will be written	en · tr. When it is left empty, the description is not written. The --wafInfoFields.N and --wafInfoLang pair has taken its place
--wafInfoSeverity	Selects in which language the attack severity will be written	en · tr. When it is left empty, it is not written. The --wafInfoFields.N and --wafInfoLang pair has taken its place

Bulk Update

The update-many applies the same change to many WAF setting records at once. The writing order is the same in every resource.

Step 1 Select the target

The only required field is target: selected for the records selected from the list, all for the entire collection.

Step 2 Add the fields to be written

Only the fields that can be written to many records with the same value are present; the fields specific to the record, such as the identifier, the name and the rule set synchronization, do not take place in this command.

Step 3 Mark the targets from the list

When target selected is written and no id is given, a selection list with checkboxes opens.

Step 4 Confirm

A warning stating how many records will be affected appears; nothing is written until the confirmation word is typed.

Field	Status	Value
target	Required	selected — the records selected from the list · all — the whole collection
--ids.N	Conditional	The target ids for target selected. It is not suggested in the Tab list: the targets are marked from the selection list. In a script and in a pipeline it is written manually.
--onError	Optional	abort (default) — if even one of the targets does not pass the validation, nothing is written · skip — the targets that pass are written

Writable Fields

TR7 WEB-CLI · update-many · Tab output

# Tab after the command

admin@TR7LBWAF01> waf options update-many

--info target

 

# Tab after the target field

admin@TR7LBWAF01> waf options update-many target

all selected

admin@TR7LBWAF01>  

The bulk update list of this command contains almost all of the fields in the single update command (71 fields). What the fields do is written in the sections above.

Fields that exist in the single command but not here, and the reasons:

Field	Why it is not here
poolId	On which vService it will be worked is determined with the selection list in the bulk command
--syncWithDefaultFwRules	It is marked as closed to bulk writing in the schema (batch: false): so as not to set up the rule set of more than one service again silently

Target Selection and Confirmation

TR7 WEB-CLI · selection list and confirmation

admin@TR7LBWAF01> waf options update-many target selected --owaspProtectionLevel 8

 

?  Target objects

    space: mark · ctrl+a: all · enter: confirm

    Filter: (filter by typing) · esc: cancel

 

  [x] <record-1>

  [x] <record-2>

  [ ] <record-3>

    2 selected / 3

 

⚠  2 objects will be updated

    <record-1>, <record-2>

 

Type "yes" to confirm: yes

admin@TR7LBWAF01>  

TR7 WEB-CLI · the whole collection and writing in a script

# the whole collection: the list does not open, the confirmation comes directly

admin@TR7LBWAF01> waf options update-many target all --dontWafStaticContent true

⚠  This operation will update ALL the objects in the collection

Type "yes" to confirm:

 

# in a script or in a pipeline: the targets are written by hand, the list does not open

admin@TR7LBWAF01> waf options update-many target selected \

--ids.0 <id-1> --ids.1 <id-2> --owaspProtectionLevel 8 --onError skip

admin@TR7LBWAF01>  

The screen language depends on the user

The texts in the selection list and on the confirmation screen come according to the language preference of the signed-in user. The confirmation word is yes in the English interface and evet in the Turkish interface.

The detailed behavior of bulk update — which fields can be written in bulk and the report returned for each target — is on the API Commands page.

Examples

TR7 WEB-CLI · A) Protection and the blocking page

admin@TR7LBWAF01> waf options update poolId <vservice> \

--structureChecks true --argumentChecks true --owaspProtectionLevel 8 \

--blockingContentSource profile --blockingContentProfile <profile> \

--blockingStatusCode 403

admin@TR7LBWAF01>  

TR7 WEB-CLI · B) Learning and notification

# learning from the traffic as a whole, with thresholds

admin@TR7LBWAF01> waf options update poolId <vservice> \

--collectiveLearning true --minReq_SL 50 --minCi_SL 10 \

--onlyBrowsers true --skipBlacklistIps true

 

# warn at 20 blockings per second, e-mail and interface notification

admin@TR7LBWAF01> waf options update poolId <vservice> \

--notifyBlockRate 20 --notifyEmail.0 guvenlik@kurum.com.tr --notifyUi true

 

# warn if there are 100 blockings in 5 minutes per source address

admin@TR7LBWAF01> waf options update poolId <vservice> \

--advancedNotifications.0.scope src_ip --advancedNotifications.0.countType block \

--advancedNotifications.0.window.val 5 --advancedNotifications.0.window.unit m \

--advancedNotifications.0.limit 100

admin@TR7LBWAF01>  

Things to Know

• A setting belongs to a vService. In every command it is stated with poolId on the settings of which service it is worked.
• The required fields do not take --. poolId and the target in the bulk command are written with the field name and its value side by side; the other fields are in the --field value form. The detail is on the API Commands page.
• In the protection level, the tightness increases as the number gets smaller. 24 is the loosest and 2 the tightest level; the tight levels raise the probability of a wrong blocking.
• --syncWithDefaultFwRules is a trigger. It is not a stored setting: when true is written, the default rule set of the service is set up again according to the protection level. The bulk update does not accept this field.
• The blocking content comes either from a profile or manually. While --blockingContentSource profile, the profile field opens, and when it is left empty, the content and the content type fields open.
• The conditional blocking pages are evaluated in order. The --blockingPageRules.N entries take the place of the general blocking page; in the entries whose status code is left empty, the general code is used.
• The exemption condition depends on its switch. --wafCondition is listed only while --wafConditionEnabled true.
• The learning has two separate ways. The learning from the trusted sources is turned on with --smartLearning and the learning from the traffic as a whole with --collectiveLearning; the two are independent of each other.
• Two fields in the info content have now left their place. The --wafInfoDesc and --wafInfoSeverity fields have been replaced by the --wafInfoFields.N and --wafInfoLang pair; the old fields are preserved so that the existing profiles stay valid.
• The rules are managed in separate commands. The host groups are in the waf host-groups command, the path rules in the waf fw-rules command and the inspection parts in the waf rule-parts command.