Manual Chapter : Declarative Policy Entity Examples

Applies To:

Show Versions Show Versions

BIG-IP ASM

  • 15.1.10, 15.1.9, 15.1.8, 15.1.7, 15.1.6, 15.1.5, 15.1.4, 15.1.3, 15.1.2, 15.1.1, 15.1.0
Manual Chapter

Declarative Policy Entity Examples

Policy level settings

The basic policy level settings in a declarative policy, for example, application language, enforcement mode, and more.
The following is an example for different policy level settings:
"policy" : { ... "applicationLanguage": "utf-8", "enforcementMode": "blocking", "caseInsensitive": false, "protocolIndependent": false, "enablePassiveMode": false, ... }

General entity

The general settings of the declarative policy, such as, allowed response code and others.
The following is an example for
general
entity:
"general": { "enablePassiveMode": false, "enforcementMode": "blocking" }

Blocking settings entity

The blocking settings include definitions of the violations and sub-violations. For more information on violations, refer Violations.
The following is an example for
blocking settings
entity:
"blocking-settings": { "violations": [ { "name": "VIOL_FILETYPE", "alarm": true, "block": false, "learn": true }, { "name": "VIOL_COOKIE_MALFORMED", "alarm": false, "block": false, "learn": false } ], "http-protocols": [ { "description": "Body in GET or HEAD requests", "enabled": false, "learn": true, "maxHeaders": 20, "maxParams": 500 } ], "evasions": [ { "description": "%u decoding", "enabled": true, "learn": false, "maxDecodingPasses": 2 } ] }

Attack signatures

The attack signatures can be difficult to configure as there are a number of configuration items and values in different places that are confusing. Enable the attack signature violation, then configure which signature sets are to be enforced. Note that there are different ways to configure these sets and that might be some overlap when doing so. You can also enable or disable signatures individually.
In following example, attack signature violation is enabled and specified to enforce all signatures:
Block settings must not be empty.
{ "policy": { "name": "attack_sigs", "template": { "name": "POLICY_TEMPLATE_FUNDAMENTAL" }, "applicationLanguage": "utf-8", "enforcementMode": "blocking", "signature-sets": [ { "name": "All Signatures", "block": true, "alarm": true } ] } }
In following example, attack signature violation is enabled and specified to enforce only high accuracy signatures:
{ "policy": { "name": "attack_sigs", "template": { "name": "POLICY_TEMPLATE_FUNDAMENTAL" }, "applicationLanguage": "utf-8", "enforcementMode": "blocking", "signature-sets": [ { "name": "High Accuracy Signatures", "block": true, "alarm": true } ] } }
In following example, the signature ID 200001834 is excluded:
{ "policy": { "name": "signature_exclude", "template": { "name": "POLICY_TEMPLATE_FUNDAMENTAL" }, "applicationLanguage": "utf-8", "enforcementMode": "blocking", "signature-sets": [ { "name": "All Signatures", "block": true, "alarm": true, "learn": false } ], "signatures": [ { "signatureId": 200001834, "enabled": false } ] } }
In following example, policy is the same but a new section is added and the attack signatures to be modified are appended using the same signature ID 200001834:
{ "policy": { "name": "signature_modification_entitytype", "template": { "name": "POLICY_TEMPLATE_FUNDAMENTAL" }, "applicationLanguage": "utf-8", "enforcementMode": "blocking", "signature-sets": [ { "name": "All Signatures", "block": true, "alarm": true, "learn": false } ] }, "modifications": [ { "entityChanges": { "enabled": false }, "entity": { "signatureId": 200001834 }, "entityType": "signature", "action": "add-or-update" } ] }
The following is an example for multiple attack signatures, the signature IDs need to be added as separate entities under the modification list, each on its own, with only the signature ID updated:
"modifications": [ { "entityChanges": { "enabled": false }, "entity": { "signatureId": 200001834 }, "entityType": "signature", "action": "add-or-update" }, { "entityChanges": { "enabled": false }, "entity": { "signatureId": 200004461 }, "entityType": "signature", "action": "add-or-update" } ]

Signatures sets entity

User defined signature sets are only supported from BIG-IP version 16.x.
The user defined signatures set can handle security policy enforcement unique to user networking environment, emergency situations, or analysis of specific activity on the network. A user can create a signatures set with user defined signatures and factory signatures for improved protection. The user defined signature set in a declarative policy are used to define signatures.
The following is an example for user defined
signature sets
entity:
{ "policy": { "name": "user_defined_sets", "template": { "name": "POLICY_TEMPLATE_FUNDAMENTAL" }, "signature-sets": [ { "name": "filter-based1", "block": false, "alarm": true, "signatureSet": { "type": "filter-based", "filter": { "attack_type": { "name": "Insecure Deserialization" }, "accuracy_filter": "ge", "accuracy_value": "medium" } } }, { "name": "manual1", "block": true, "alarm": true, "signatureSet": { "type": "manual", "signatures": [ { "signatureId": 200004887 }, { "signatureId": 200004885 } ] } }, { "name": "polak_sigs", "block": false, "learn": false, "signatureSet": { "filter": { "tagValue": "polak", "tagFilter": "eq" } } } ] } }

File types entity

The file types handle files like URL extensions: html, png, php, and other, allowed and disallowed.
Allowed file types include size limits for the URL, whole request, and more.
The following is an example for
file types
entity:
"filetypes": [ { "name": "ico", "type": "explicit", "queryStringLength": 400, "checkPostDataLength": true, "responseCheck": false, "checkRequestLength": true, "checkUrlLength": true, "postDataLength": 5000, "allowed": true, "performStaging": true, "requestLength": 300, "checkQueryStringLength": true, "urlLength": 20 }, { "name": "aaa", "allowed": false } ]

URLs entity

The
URLs
entity handles the HTTP requests by their URLs, allowed and disallowed.
Allowed URLs include settings regarding the expected payload, signature checks, and more.
The following is an example for
URLs
entity:
"urls": [ { "protocol": "http", "name": "/stuff/articles", "method": "*", "type": "wildcard", "wildcardIncludesSlash": true, "html5CrossOriginRequestsEnforcement": { "enforcementMode": "disabled" }, "methodsOverrideOnUrlCheck": false, "isAllowed": true, "description": "posssssi", "attackSignaturesCheck": true, "signatureOverrides": [ { "signatureId": 200101551, "enabled": false } ], "clickjackingProtection": false, "performStaging": true, "urlContentProfiles": [ { "headerValue": "*", "headerName": "*", "headerOrder": "default", "type": "apply-value-and-content-signatures" }, { "headerValue": "*form*", "headerName": "Content-Type", "headerOrder": "1", "type": "form-data" }, { "contentProfile": { "name": "Default" }, "headerValue": "*json*", "headerName": "Content-Type", "headerOrder": "2", "type": "json" }, { "contentProfile": { "name": "Default" }, "headerValue": "*xml*", "headerName": "Content-Type", "headerOrder": "3", "type": "xml" } ], "wildcardOrder": 1 }, { "name": "/foo", "protocol": "http", "signatureOverrides": [ { "signatureId": 200101553, "enabled": false } ] }, { "protocol": "http", "name": "/login.php", "method": "*", "type": "explicit" } ]

JSON profiles entity

Each profile determines how to validate JSON content within request payload or a specific parameter value to which this profile is associated. Validations include size limits, JSON schema, and more.
The following is an example for
JSON profiles
entity:
"json-profiles": [ { "name": "profil_json1", "isDefault": false, "defenseAttributes": { "maximumTotalLengthOfJSONData": 10000, "maximumArrayLength": 1000, "maximumStructureDepth": 10, "maximumValueLength": 100, "tolerateJSONParsingWarnings": false }, "handleJsonValuesAsParameters": true, "validationFiles": [] } ]

XML profiles entity

Each profile determines how to validate XML or SOAP content within request payload or a specific parameter value to which this profile is associated. Validations include size limits, XML or WSDL schema, and more.
The following is an example for
XML profile
entity:
"xml-profiles": [ { "name": "profil-xml2", "defenseAttributes": { "maximumAttributesPerElement": 30, "allowCDATA": true, "tolerateLeadingWhiteSpace": true }, "validationFiles": [ { "xmlValidationFile": { "fileName": "validation_file_profil2.xml", "contents": "<note>\r\n<to>Tove</to>\r\n<from>Jani</from>\r\n<heading>Reminder</heading>\r\n<body>Don't forget me this weekend!</body>\r\n</note>" } } ] } ]

Data guard entity

The
data guard
entity protects from leakage of sensitive information in responses, for example, credit card numbers data is masked.
The following is an example for
data guard
entity:
"data-guard": { "enabled": "true", "maskData": "true", "creditCardNumbers": true }

Response pages entity

The HTTP responses sent when rejecting a request including both headers and content. The device comes with a set of factory predefined pages for different contexts: HTML, JSON, and more. The user can replace each one with their custom pages.
The following is an example for
response pages
entity:
"response-pages": [ { "responseContent": "custom content", "responseHeader": "HTTP/1.1 302 OK\\r\\nConnection: close", "responseActionType": "custom", "responsePageType": "failed-login-honeypot" } ]

Parameters entity

Parameters are settings concerning the enforcement of parameters in query string, POST data body, or JSON body (if configured to do so in the respective JSON profile). Enforcement includes detection of signatures, meta characters, size limits, and more.
The following is an example for
parameters
entity:
"parameters": [ { "name": "global_stuff*", "type": "wildcard", "valueType": "xml", "contentProfile": { "name": "xml_test_profile" } }, { "name": "id*", "type": "wildcard" }, { "name": "a", "type": "wildcard", "valueType": "json", "contentProfile": { "name": "test_json_profile_with_parse" } } ]

Sensitive parameters entity

Sensitive parameters are parameters for which the value has to be masked in the request log. This feature is also available in the
parameters
entity. The
sensitive parameters
entity is meant to be used only for parameters that do not have any specific enforcement attributes other than the need to be masked.
The following is an example for
sensitive parameters
entity:
"sensitive-parameters": [ { "name": "password" }, { "name": "sens-param2" } ]

Cookies entity

The
cookies
entity is settings concerning the enforcement of cookies found in request. Enforcement includes integrity of cookie as set by the server, detection of signatures, and more.
The following is an example for
cookies
entity:
"cookies": [ { "name": "smaple_cookie", "type": "explicit", "performStaging": true, "enforcementType": "enforce" } ]

Methods entity

The
methods
entity is allowed HTTP methods.
The following is an example for
methods
entity:
"methods": [ { "name": "BMOVE" }, { "name": "OPTIONS" } ]

Whitelist IPs entity

The
whitelist IPs
entity is IP address ranges that are handled in special ways: black list, white list, trusted for learning, and more.
The following is an example for
whitelist IPs
entity:
"whitelist-ips": [ { "ipAddress": "1.1.1.1", "ipMask": "255.255.255.255", "neverLearnRequests": true }, { "ipAddress": "10.0.0.1", "ipMask": "255.255.255.255", "description": "always block only", "blockRequests": "always", "neverLearnRequests": false } ]

Geolocation

The BIG-IP WAF system has an IP geolocation feature that identifies the origin of traffic at country-level using a database of IPv4 and IPv6 addresses.
In addition to helping users interpret violation incidents and trends, with this data, user can block or allow access to an application based on the geographic origin of the traffic, blacklisting and whitelisting the IP addresses. The feature geolocation is used to block access requests from a particular country.
The following is an example to block traffic form multiple countries:
"disallowed-geolocations": [ { "countryName": "American Samoa" }, { "countryName": "Algeria" }, { "countryName": "Albania" } ]

OpenAPI

The OpenAPI specification is an API description format for REST APIs. An OpenAPI file describes the entire API. The API specifications are written in either JSON or YAML.
The declarative policy can protect the API and enforce each request according to the openAPI definition.
The
open-api-files
array item is a used with either
link
or
filename
attribute to retract the OpenAPI file. The URL is either HTTPS or HTTP and the file path is either local directory or mounted file system, for example,
file://apps/api/app4.json
.
In following example, the OpenAPI file is retracted using
filename
attribute:
"open-api-files": [ { "filename": "file://myapp.yaml" } ]
In following example, the OpenAPI file is retracted using
link
attribute:
"open-api-files": [ { "link": "https://myserver.com/apis/myapp.yaml" } ]
In following example, the
openApiFileReference
property is used with
link
attribute:
"openApiFileReference": { "link": "https://myserver.com/apis/myapp.yaml" }
Only the first item in a single array is processed. If there are more items in one
open-api-files
array or more than one array, or both
open-api-files
array and
openApiFileReference
parameter are available, the policy is rejected and not created on the device.
The policy is built in the following order, the order implies that each layer overrides setting of its predecessors:
  1. Template
    It is recommended to use the API Protection template, but any template can be used.
  2. OpenAPI file
    It is processed regardless of its physical placement within the file.
  3. JSON adjustment elements
    Other JSON elements excluding the openAPI file.
  4. Modifications
    The modifications in the modification section.
For example, if the maximum length of a parameter
p1
is 5 in the template, 15 resulting from the OpenAPI file,10 in the JSON adjustments, and 20 in a specific modification, then the final policy will have the value of 20 from the modification. If there is no modification, the value would be 10 from the JSON adjustment.

Policy builder configuration

When the policy builder is in an automatic learning mode, the system identifies authorized application usage and starts to build a security policy based on a statistical analysis of the traffic and intended behavior of the application. You can specify how the policy builder learns which entities to block and allow, including file types, parameters, URLs, cookies, and redirection domains.
The following is an example configuration of the policy builder:
"policy-builder": { "autoApply": { "frequency": "real-time" }, "trustAllIps": false, "trustedTrafficLoosen": { "differentSources": 1, "maxDaysBetweenSamples": 7, "minHoursBetweenSamples": 0 }, "policy-builder-filetype": { "learnExplicitFiletypes": "compact", "maximumFileTypes": 50 }, "policy-builder-server-technologies": { "enableServerTechnologiesDetection": true } }

Threat campaigns

Attackers are constantly looking for ways to exploit the latest vulnerabilities and new ways to exploit old vulnerabilities. The F5 Threat Research team is constantly monitoring malicious activity around the globe and creating signatures specific to these exploits. These Threat Campaign signatures are based on in-the-wild attacks. The Threat Campaign signatures contain contextual information about the nature and purpose of the attack.
As an example, a normal WAF signature might notify that SQL injection was attempted. A Threat Campaign signature notifies that a known threat actor used a specific exploit of the latest Apache Struts vulnerability in an attempt to deploy ransomware for cryptomining software.
The following is an example for threat campaign:
"name": "campaigns", "threat-campaigns": [ { "displayName": "SQL Injection - 999999.9", "performStaging": true, "isEnabled": false } ]

Brute force

The brute force attacks are attempts to break into secured areas of a web application by trying exhaustive, systematic, user name and password combinations to discover legitimate authentication credentials. To prevent brute force attacks, the system tracks the number of failed attempts to reach the configured login URLs. The system considers it to be an attack if the failed login rate increased at a very high number or if failed logins reached a certain number.
The following is an example for brute force attacks prevention:
"brute-force-attack-preventions": [ { "captchaBypassCriteria": { "action": "alarm-and-drop", "enabled": true, "threshold": 5 }, "clientSideIntegrityBypassCriteria": { "action": "alarm-and-captcha", "enabled": true, "threshold": 3 }, "detectionCriteria": { "action": "alarm-and-captcha", "credentialsStuffingMatchesReached": 100, "detectCredentialsStuffingAttack": true, "detectDistributedBruteForceAttack": true, "failedLoginAttemptsRateReached": 100 }, "leakedCredentialsCriteria": { "action": "alarm-and-blocking-page", "enabled": false }, "loginAttemptsFromTheSameDeviceId": { "action": "alarm-and-captcha", "enabled": false, "threshold": 3 }, "loginAttemptsFromTheSameIp": { "action": "alarm-and-captcha", "enabled": true, "threshold": 20 }, "loginAttemptsFromTheSameUser": { "action": "alarm-and-captcha", "enabled": true, "threshold": 3 }, "measurementPeriod": 900, "preventionDuration": "3600", "reEnableLoginAfter": 3600, "sourceBasedProtectionDetectionPeriod": 3600, "url": { "method": "*", "name": "/login", "protocol": "http", "type": "explicit" } } ]

Webhooks entity

The Webhooks notify external system about events such as policy apply, incident start, HTTP request, and more.
The following is an example for webhooks:
"webhooks": [ { "body": "{\"type\":\"message\", \"text\":\"apply-policy had been activated, this message was sent from webhook to chatops\"}", "contentType": "application/json", "triggerEvent": "apply-policy", "url": "https://<URL>", "name": "apply" } ]

Server technologies entity

Server technologies apply sets of signatures that would be relevant to attacks targeted to a specific OS, application, or server type. For available server technologies, refer to Server technologies.
The following is an example:
"server-technologies": [ { "serverTechnologyName": "Apache/NCSA HTTP Server" } ]