API Use Cases: Manage and edit a WAF policy on BIG-IP Next Central Manager

The following provides use cases and procedures to modify your WAF policy using the BIG-IP Next Central Manager WAF OpenAPI.

These use cases are helpful if you are editing the WAF policy’s JSON declaration using your own editor, or the JSON editor provided in BIG-IP Next Central Manager’s UI.

If you prefer to use the UI for WAF policy management, see How To: Manage and edit a WAF policy on BIG-IP Next Central Manager.

The following provides endpoint workflows and links to JSON samples for each section of the WAF policy:

Edit and deploy policy changes

If you are using the OpenAPI to make changes to your policy, you can use the two general policy editing requests to modify and then deploy your policy change to all associated BIG-IP Next instances.

General policy editing

If you cannot apply a specific endpoint when modifying the WAF policy JSON declaration, you can use the following request. Ensure you include the WAF policy id in the request.

PUT https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/spaces/default/security/waf-policies/{id}/general-settings

Deploy changes

Use the following post with the policy_name:

POST  https://<BIG-IP-Next-Central-Manager-IP-Address>/api/waf/v1/tasks/deploy-policy

This task deploys or re-deploys policy changes to all associated BIG-IP Next instances.

General settings

To modify a policy’s general settings, use the following procedures:

General settings parameters

You can edit the following general settings on an existing WAF policy:

  • description - Additional information about the policy.

  • enforcement_mode - How the system processes a request that triggers a policy violation:

    • Blocking: Traffic is blocked if it causes a violation (configured for blocking).

    • Transparent: Traffic is not blocked even if a violation is triggered.

  • tags - Marking policies with specified labels.

  • allowed_response_codes- Specifies which responses a security policy permits. By default, the system accepts all response codes from 100 to 399 as valid responses. Response codes from 400 to 599 are considered invalid unless added to the Allowed Response Status Codes list. By default, 400, 401, 404, 407, 417, and 503 are on the list as allowed HTTP response status codes.

  • trust_xff - When enabled, the policy has confidence in an XFF (X-Forwarded-For) header in the request. When disabled, that the policy does not have confidence in an XFF header in the request. The default setting is disabled. Enable this option if the policy is deployed on an application that is behind an internal or other trusted proxy. The system then can use the IP address that initiated the connection to the proxy instead of the internal proxy’s IP address. Leave this option disabled if you think the HTTP header may be spoofed or crafted by a malicious client. With this setting disabled, if the system is deployed behind an internal proxy, the system uses the internal proxy’s IP address instead of the client’s IP address.

  • custom_xff_headers - If you require the policy to trust a server further than one hop toward the client (the last proxy traversed), you can use the Custom XFF (X-Forwarded-For) Headers setting to define a specific header that is inserted closer to, or at the client, that the system will trust. Additionally, if you require the system to trust a proxy server that uses a different header name than the XFF header name, you can add the desired header name to the Custom XFF Headers setting. When adding a custom header, the XFF header is not trusted anymore. In case the XFF header is to be trusted along with other headers, you must add it to the custom headers list.

  • maximum_http_header_length- Maximum HTTP Header Length must be greater than 0 and less than 65536 bytes (64K).

    Note: If 0 or any are set, then no restriction on the HTTP header length is applied.

  • maximum_cookie_header_length" - Maximum Cookie Header Length must be greater than 0 and less than 65536 bytes (64K).

    Note: If 0 or any are set, then no restriction on the cookie header length is applied.

  • disallowed_geolocations - Add country names from which to from which to restrict traffic to the application.

  • applications - Applications on which policy is enforced

Review your policy’s current general settings

Request the general settings based on the WAF policy id:
GET https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/spaces/default/security/waf-policies/{id}/general-settings

Update your policy general settings

Use the following request with the WAF policy id:
PUT https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/spaces/default/security/waf-policies/{id}/general-settings

Deploy changes

Use the following post with the policy_name in the request body:

POST  https://<BIG-IP-Next-Central-Manager-IP-Address>/api/waf/v1/tasks/deploy-policy

Example policy deployment body:

{
  "policy_name": "single_policy",
  "comment": "This is a comment"
}

This task deploys or re-deploys policy changes to all associated BIG-IP Next instances.

Manage Bot Defense

Bot Defense helps identify and mitigate attacks before they cause damage to the site. Enable or disable Bot Defense in your WAF policy using the policy editor or send a PUT request with updated policy changes in the WAF OpenAPI.

Note: Bot Defense is enabled by default on all WAF policy templates.

Use the requests found in edit and deploy policy changes to update and deploy your policy.

{
    "bot-defense": {
        "mitigations": {
            "classes": [
                {
                    "action": "ignore",
                    "name": "trusted-bot"
                },
                {
                    "action": "ignore",
                    "name": "untrusted-bot"
                },
                {
                    "action": "block",
                    "name": "malicious-bot"
                }
            ]
        },
        "settings": {
            "isEnabled": false
        }
    }
}

Manage Threat Campaigns

Threat Campaigns frequently update feeds containing contextual information about active attack campaigns currently being observed by F5 Threat Labs that WAF can provide protection against. You can enable or disable Threat Campaigns in the WAF policy using the BIG-IP Next Central Manager UI or send a PUT request with updated policy changes in the WAF OpenAPI.

Note: Threat Campaigns is enabled by default on all policy templates.

Use the requests found in edit and deploy policy changes to update and deploy your policy.

{
    "threat-campaign-settings": {
        "threatCampaignEnforcementReadinessPeriod": 1,
        "threatCampaignStaging": false
    }
}

Manage IP Intelligence

IP Intelligence incorporates external, intelligent services to enhance automated application delivery with better IP intelligence and stronger, context-based security. By identifying IP addresses and security categories associated with malicious activity, the IP Intelligence service can incorporate dynamic lists of threatening IP addresses into the BIG-IP Next, adding context to policy decisions. You can enable or disable IP Intelligence and categories in the WAF policy using the BIG-IP Next Central Manager UI or send a PUT request with updated policy changes in the WAF OpenAPI.

Note: IP Intelligence is enabled by default on all policy templates. To ensure IP Intelligence can regularly reach a third party vendor to identify IP addresses and security categories, you must ensure that your BIG-IP Next Central Manager or instances have Licensing activated. To activate your license, go to the ** Workspace icon > Instances > Select instance name > Licensing**. For more information about this BIG-IP Next license, log in to https://account.f5.com/myf5 with your F5 customer credentials.

Use the requests found in edit and deploy policy changes to update and deploy your policy.

{
    "ip-intelligence": {
        "enabled": true,
        "ipIntelligenceCategories": [
            {
                "alarm": true,
                "block": true,
                "category": "Spam Sources",
                "description": "The Spam Sources category includes Tunneling Spam messages through proxy, anomalous SMTP activities, and Forum Spam activities."
            },
            {
                "alarm": true,
                "block": true,
                "category": "Cloud-based Services",
                "description": "The Cloud-based Services category includes IP addresses and networks that are used by cloud providers."
            },
            {
                "alarm": true,
                "block": true,
                "category": "Mobile Threats",
                "description": "The Mobile Threats category includes IP addresses of malicious and unwanted mobile applications."
            },
            {
                "alarm": true,
                "block": true,
                "category": "Tor Proxies",
                "description": "The Tor Proxies category includes IP addresses acting as exit nodes for the Tor Network. Exit nodes are the last point along the proxy chain and make a direct connection to the originator’s intended destination."
            },
            {
                "alarm": true,
                "block": true,
                "category": "Windows Exploits",
                "description": "The Windows Exploits category includes active IP address offering or distributing malware, shell code, rootkits, worms, and viruses."
            },
            {
                "alarm": true,
                "block": true,
                "category": "Web Attacks",
                "description": "The Web Attacks category includes cross site scripting, iFrame injection, SQL injection, cross domain injection, and domain password brute force."
            },
            {
                "alarm": true,
                "block": true,
                "category": "BotNets",
                "description": "The Botnets category includes Botnet C&C channels and an infected zombie machine controlled by a Bot master."
            },
            {
                "alarm": true,
                "block": true,
                "category": "Scanners",
                "description": "The Scanners category includes all reconnaissance, such as probes, host scan, domain scan, and password brute force."
            },
            {
                "alarm": true,
                "block": true,
                "category": "Denial of Service",
                "description": "The Denial of Services category includes DOS, DDOS, anomalous syn flood, and anomalous traffic detection."
            },
            {
                "alarm": true,
                "block": true,
                "category": "Infected Sources",
                "description": "The Infected Sources category includes IP addresses currently known to be infected with malware, and IP addresses with an average low Reputation Index score. Enabling this category prevents access from sources identified to contact malware distribution points."
            },
            {
                "alarm": true,
                "block": true,
                "category": "Phishing Proxies",
                "description": "The Phishing Proxies category includes IP addresses hosting phishing sites, and other kind of fraud activities such as Ad Click Fraud and Gaming fraud."
            },
            {
                "alarm": true,
                "block": true,
                "category": "Anonymous Proxy",
                "description": "The Anonymous Proxy category includes IP addresses that provide proxy and anonymizing services."
            }
        ]
    }
}

Evasion technique violations

Evasion techniques refers to a technique that is typically used by hackers in an attempt to access resources or evade what would otherwise be identified as an attack. When this technique is detected, it triggers an evasion technique violation.

For a full list of violations and their protection status, see Reference: Violation Protection.

Review supported evasion technique violations

Request a complete list of all supported evasion violations:
GET https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/security/waf/evasion-violations

Request a list of a policy’s evasion violations to review enforcement action within the policy:
GET https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/spaces/default/security/waf-policies/{id}/evasion-violations

Manage evasion violations in a policy

Update the enforcement action in the list of evasion violations for a specific policy:
POST https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/spaces/default/security/waf-policies/{id}/evasion-violations/update

Update violation enforcement action of a specific HTTP RFC violation in a policy based on the viol-id:
PUT https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/spaces/default/security/waf-policies/{id}/evasion-violations/{viol-id}

Deploy changes

Use the following post with the policy_name:

POST  https://<BIG-IP-Next-Central-Manager-IP-Address>/api/waf/v1/tasks/deploy-policy

This task deploys or re-deploys policy changes to all associated BIG-IP Next instances.

HTTP Protocol Compliance violations

HTTP RFC non-compliance is one of the basic application security violations. It detects non-compliant violations and prevents the use of the HTTP protocol as an entry point to the application.

For a full list of violations and their protection status, see Reference: Violation Protection.

Review supported HTTP RFC violations

Request a complete list of all supported HTTP RFC violations:
GET https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/security/waf/http-rfc-violations

Request a list of a policy’s HTTP RFC violations to review enforcement action within the policy:
GET https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/spaces/default/security/waf-policies/{id}/http-rfc-violations

Manage HTTP RFC violations in a policy

Update the enforcement action in the list of HTTP RFC violations for a specific policy: POST https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/spaces/default/security/waf-policies/{id}/http-rfc-violations/update

Update violation enforcement action of a specific HTTP RFC violation in a policy based on the viol-id:
PUT https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/spaces/default/security/waf-policies/{id}/http-rfc-violations/{viol-id}

Deploy changes

Use the following post with the policy_name:

POST  https://<BIG-IP-Next-Central-Manager-IP-Address>/api/waf/v1/tasks/deploy-policy

This task deploys or re-deploys policy changes to all associated BIG-IP Next instances.

Manage attack signatures

Attack signatures in a security policy are compared with requests or responses to identify classes of attacks, for example, SQL injection, command injection, cross-site scripting, and directory traversal. WAF receives a client request (or a server response), the system compares the request or response against the attack signatures associated with the security policy. If a matching pattern is detected, the policy triggers an attack violation, and either alarms or blocks the request, based on the enforcement mode of the security policy.

When tuning your policy, specific attack signatures may require customization according to known traffic patterns to your application. You can override a signature’s settings for a specific property (e.g. cookies or URLs). To override specific attack signatures see Override a specific attack signature.

Note: F5 recommends using signature sets to manage your policy’s signatures. This will allow you to manage signatures based on a defined filter or attack-type, rather than each signature individually. See Manage attack signature sets for applying and managing signature sets.

Review policy signatures

Review a policy’s signatures to view the protection, parameters, type, signature ID, risk, accuracy, associated signature set, and additional settings. For more information about signature sets, see Reference: Attack Signature Sets.

Request a full list of signatures and their details in a policy:
GET https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/spaces/default/security/waf-policies/{id}/signatures

Request details of a specific signature in a policy based on set-id:
GET https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/spaces/default/security/waf-policies/{id}/signatures/{sig-id}

Manage a signature

Update the enforcement status on one or more signature within a policy. This starts the WAF policy update-signatures-enforcement task. Either filter or signature_ids is required. These must be used together with the action and policy_name settings.

action - Defines how the system manages a detected signature:

  • enforce - The detected signature is blocked.

  • stage - The detected signature is logged, but not blocked.

  • disable - Enforcement against the detected signature is disabled.

POST https://<BIG-IP-Next-Central-Manager-IP-Address>/api/waf/v1/tasks/update-signatures-enforcement

Review the updated signature enforcement task status:
GET https://<BIG-IP-Next-Central-Manager-IP-Address>/api/waf/v1/tasks/update-signatures-enforcement

Deploy changes

Use the following post with the policy_name:

POST  https://<BIG-IP-Next-Central-Manager-IP-Address>/api/waf/v1/tasks/deploy-policy

This task deploys or re-deploys policy changes to all associated BIG-IP Next instances.

Manage attack signature sets

An attack signature set is a logical grouping of attack signatures based on defined filters, or type. See Reference: Attack Signature Sets for more information. F5 recommends using signature sets rather than applying individual attack signatures to a security policy. Each security policy has its own attack signature set assignments. By default, a generic signature set is assigned to new security policies. You can assign additional signature sets to the security policy.

F5 recommends using signature sets when adding or removing signatures.

Review signature sets

Review the signature set to view the protection status, signature set ID and accuracy.

Request a full list of available signature sets:
GET https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/security/waf/signature-sets

Request a specific signature set This includes the details of the signature set’s attributes, including its signature list. For more information about signature set attributes, see :
GET https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/security/waf/signature-sets/{id}

Request a list of signature sets in a policy. This returns details of the accuracy-filter and accuracy-value, see Detection Filters for more information:
GET https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/spaces/default/security/waf-policies/{id}/signature-sets

Manage a signature set’s enforcement

Update the enforcement status on a signature set within a policy:

status - Defines the protection against detected signatures from a signature set:

  • enforce - The detected signature from the set is blocked.

  • stage - The detected signature from the set is logged, but is not blocked.

  • disable - Removes any enforcement from a detected signature from a set.

PUT https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/spaces/default/security/waf-policies/{id}/signature-sets/{set-id}

Delete a signature set

Remove a signature set from a policy:
DELETE https://{<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/spaces/default/security/waf-policies/{id}/signature-sets/{set-id}

IP address exceptions

Review a policy’s list of specified IP addresses:
GET https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/spaces/default/security/waf-policies/{id}/ip-addresses

Review a specified IP address in a policy. This returns the blocking details, and which policies include the IP address:
GET https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/spaces/default/security/waf-policies/{id}/ip-addresses/{ipAddressAndMask}

Manage IP addresses on a specific policy:
POST https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/spaces/default/security/waf-policies/{id}/ip-addresses

Specify IP addresses that are either always or never allowed access to your protected application. You can add, edit, or delete the IP address using the following settings:

  • action - (Required) Defines whether you would like to configure or delete the IP address:

    • create - A new IP address.

    • update - An existing IP address.

    • delete - Remove an IP address.

  • ip-address - (Required) The IP address.

  • ip-mask - Add an IP mask, if applicable.

  • blocking-mode - Specifies whether the IP address access to your application:

    • always- Requests from the IP address are always blocked.

    • never - Requests from this IP address are always allowed and never blocked.

    • policy-default - Requests from this IP address are blocked according to policy rules.

  • policies - Add WAF policy names that apply the IP address access rule. If a policy name is not specified, the IP address access rule is applied to all policies.

Data Guard

In some web applications, a response may contain sensitive user information, such as credit card numbers or social security numbers (U.S. only). The Data Guard feature can prevent responses from exposing sensitive information by masking the data (this is also known as response scrubbing). Data Guard scans text in responses looking for the types of sensitive information that you specify.

For more information see Overview: Data Guard.

Enable or disable Data Guard

Enable or disable Data Guard in your policy’s template. The following example shows the data-guard set to disabled:

Use the requests found in edit and deploy policy changes to update and deploy your policy.

{
    "data-guard": {
        "enabled": false,
        "enforcementMode": "ignore-urls-in-list"
    }
}

CSRF

Add CSRF protection for specific URLs on applications, or exclude certain URLs from CSRF protection. Excluding CSRF protection may be required for applications with different request origins.

Enable or disable CSRF protection

Enable or disable CSRF protection in your policy’s template. The following example shows the csrf-protection set to enabled with a wildcard (*) URL defined:

Use the requests found in edit and deploy policy changes to update and deploy your policy.

{
    "csrf-protection": {
        "enabled": true
    },
    "csrf-urls": [
        {
            "enforcementAction": "verify-origin",
            "method": "POST",
            "requiredParameters": "ignore",
            "url": "*",
            "wildcardOrder": 1
        }
    ]
}

SSRF

Manages protection for an SSRF (Server-Side Request Forgery) attack. In an SSRF attack, the attacker takes advantage of parameters that contain dynamic IP addresses or domain names which the server application invokes. Identify the parameters that are subject to SSRF attack and configure the IP address or domain name to deny, allow, or resolve access from these parameters.

Review SSRF hosts and actions

Review the SSRF hosts in your WAF policy and actions that are currently used when detected. You can change the actions to one of the following:

  • disallow - If the SSRF host is detected in the payload parameters the request is always denied.

  • allow - If the SSRF host is detected in the payload parameters the request is always allowed.

  • resolve - This option is only relevant to domain names. When the host name is detected, the WAF policy will use the host name to look up IP address(es) using the configured DNS resolver. If one or more IP address corresponds with the domain name, they are looked up in the SSRF host list, if any IP addresses are set to Deny the configured mitigation action is taken. For the wildcard entry (*), the resolve action is interpreted as allow for IP addresses.

Use the requests found in edit and deploy policy changes to update and deploy your policy:

{
    "ssrf-hosts": [
        {
            "action": "disallow",
            "host": "metadata.google.internal"
        },
        {
            "action": "disallow",
            "host": "localhost"
        },
        {
            "action": "disallow",
            "host": "rancher-metadata"
        },
        {
            "action": "disallow",
            "host": "*.burpcollaborator.net"
        },
        {
            "action": "disallow",
            "host": "127.0.0.0/24"
        },
        {
            "action": "disallow",
            "host": "192.0.2.0/24"
        },
        {
            "action": "disallow",
            "host": "198.51.100.0/24"
        },
        {
            "action": "disallow",
            "host": "203.0.113.0/24"
        },
        {
            "action": "disallow",
            "host": "169.254.0.0/16"
        },
        {
            "action": "disallow",
            "host": "192.168.0.0/16"
        },
        {
            "action": "disallow",
            "host": "172.16.0.0/12"
        },
        {
            "action": "disallow",
            "host": "fe80::/10"
        },
        {
            "action": "disallow",
            "host": "10.0.0.0/8"
        },
        {
            "action": "disallow",
            "host": "127.0.0.0/8"
        },
        {
            "action": "disallow",
            "host": "0.0.0.0"
        },
        {
            "action": "disallow",
            "host": "100.100.100.200"
        },
        {
            "action": "disallow",
            "host": "168.63.129.16"
        },
        {
            "action": "disallow",
            "host": "169.254.169.254"
        },
        {
            "action": "disallow",
            "host": "192.0.0.192"
        },
        {
            "action": "disallow",
            "host": "::"
        },
        {
            "action": "disallow",
            "host": "::1"
        },
        {
            "action": "resolve",
            "host": "*"
        }
    ]
}

Brute force protection

You can configure WAF to protect against brute force attacks for allowed URLs. The security policy detects brute force attacks based on failed login rates by suspected malicious users. You can adjust the WAF policy to enable/disable enforcement and the threshold for login attempts.

For more information see Overview: Brute force protection.

Use the requests found in edit and deploy policy changes to update and deploy your policy.

{
    "brute-force-attack-preventions": [
        {
            "bruteForceProtectionForAllLoginPages": false,
            "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
        }
    ]
}

L7 DoS protection

Manage the L7 DoS protection settings that mitigates denial-of-service (DoS) attack by slowing down traffic when an attack is detected.

L7 DoS protection applies machine learning and data analysis of HTTP signatures, TLS fingerprinting, and bad actors (assessment of IP addresses by traffic behavior and anomaly detection).

You can enable, or disable the detection and mitigation techniques based on your application’s security requirements.

In addition, you can set the mitigation mode, which allows you to increase or decrease the rate at which the policy mitigates requests discovered using L7 DoS detection.

Note: You can deploy L7 DoS protection on up to 70 applications for a single BIG-IP Next instance.

Special instructions for L7 Dos Protection

If you plan to use the L7 DoS Visibility in BIG-IP Next Central Manager’s UI, F5 recommends a specific policy configuration and deployment procedure to ensure your L7 DoS protection has the best, and most accurate visibility in BIG-IP Next Central Manager’s L7 dashboard and event logs.

If you do not configure your L7 DoS protection according to recommended best practices, visibility of L7 DoS protection to your applications might be inaccurate.

When creating a L7 DoS protection apply the following:

IMPORTANT

If you require L7 DoS protection on a pool member (endpoint) that is located on a different BIG-IP Next instance, you must create or clone a separate L7 DoS WAF policy and attach it to another dedicated application service that has only one virtual server (you can clone the existing L7 DoS application service but ensure it is attached to the correct policy.)

Special instructions for L7 Dos Protection

If you plan to use the L7 DoS Visibility in BIG-IP Next Central Manager’s UI, F5 recommends a specific policy configuration and deployment procedure to ensure your L7 DoS protection has the best, and most accurate visibility in BIG-IP Next Central Manager’s L7 dashboard and event logs.

If you do not configure your L7 DoS protection according to recommended best practices, visibility of L7 DoS protection to your applications might be inaccurate.

When creating a L7 DoS protection apply the following:

**IMPORTANT**: If you require L7 DoS protection on a pool member (endpoint) that is located on a different BIG-IP Next instance, you must [create](cm_awaf_how_to_create_policy.md#create-a-new-security-policy-using-a-template---api) or [clone](cm_awaf_how_to_create_policy.md#clone-a-waf-policy---api) a separate L7 DoS WAF policy and attach it to another dedicated application service that has only one virtual server (you can clone the existing L7 DoS application service but ensure it is attached to the correct policy.)

Enable or disable L7 DoS protection

Enable or disable L7 DoS protection in your policy’s template. The following example shows the dos-protection set to enabled (true).

Use the requests found in edit and deploy policy changes to update and deploy your policy.

You can change the mitigation rate (mitigationLevel) and detection and mitigation techniques using the following parameters:

  • mitigationLevel - The rate at which the policy slows traffic when DoS behavior is detected: *standard - (Default) - Rate limits traffic based on global mitigation rates. For badActorDetection this slows down requests from anomalous IP addresses based on its anomaly detection confidence and server health. Rate limits requests from anomalous IP addresses and, if necessary, rate limits all requests based on server health. If signatures are enabled, this blocks requests that match behavioral signatures.

    • conservative - Rate limits traffic detected as an attack. For badActorDetection this slows down and rate limits requests from anomalous IP addresses based on anomaly detection confidence and server health. If signatures are enabled, this blocks requests that match behavioral signatures.

    • none - No mitigation is performed. L7 DoS protection learns and monitors traffic behavior, but takes no action.

  • enableHttpSignatures (enabled by default) - The policy examines HTTP requests and creates behavioral signatures that describe patterns found in attacks identified.

  • enableTlsSignatures (disabled by default) - The policy examines TLS sessions and creates behavioral signatures that describe patterns found in attacks identified.

  • badActorDetection (enabled by default) - The policy identifies IP addresses of bad actors by examining traffic behavior and anomaly detection

    • enableTlsIndexing (enabled by default) - The policy uses TLS fingerprinting to distinguish between bad and good actors behind the same IP (NAT) and only blocks traffic from bad actors.

{
    "dos-protection": {
        "enabled": true,
        "behavioral-dos": {
            "mitigationLevel": "standard",
            "enableHttpSignatures": true,
            "enableTlsSignatures": false,
            "badActorDetection": {
                "enabled": true,
                "enableTlsIndexing": true
            }
        }
    }
}

OpenAPI Protection

The OpenAPI Protection feature is designed to simplify the process of configuring a WAF policy by automatically matching it to the customer’s application instead of requiring a manual definition of all components.

Create File Workflow

To add or upload a new OpenAPI file in the Central Manager, you must select the file of .json, .yaml, .yml format. Upload or create new OpenAPI file by sending a POST request to /spaces/default/security/waf/files endpoint.

POST https://{{CM_IP}}/api/v1/spaces/default/security/waf/files

For the request payload, use the following example, modifying the values as required.

Key Value Description
file File simple_swagger.json
file_type Text openapi
file_name Text simpleswagger.json

Update File Workflow

To change the current file in the Central Manager, you will need to delete the file first and then upload it again. Deleting the file is necessary because the file may be linked to one or more security policies (rules or configurations) within the WAF. Delete the file by sending a DELETE request to /spaces/default/security/waf/files/{id} endpoint. Identify the ID of the file that you want to delete.

DELETE https://{{CM_IP}}/api/v1/spaces/default/security/waf/files/{id}

Create New Policy Workflow

A new WAF policy using an OpenAPI file can be created by sending a POST request to the /spaces/default/security/waf-policies endpoint. The ‘name’ field is required, while all other fields are optional.

POST https://{{CM_IP}}/api/v1/spaces/default/security/waf-policies

For the request payload, use the following example, modifying the values as required.

{
    "name": "policy11",
    "openapi_file_reference": {
    "link": "/api/v1/spaces/default/security/waf/files/79e2da77-ddf5-446e-a446-68de142a77a5"
   }
}

Update OpenAPI Reference Workflow

To update the OpenAPI reference for a specific policy, by sending a PUT request to the /spaces/default/security/waf-policies/{policy_id}/openapi endpoint to provide the new file reference. This procedure will trigger the creation of a new policy using the current configuration and OpenAPI file entities.

PUT https://{{CM_IP}}/api/v1/spaces/default/security/waf-policies/{policy_id}/openapi

For the request payload, use the following example, modifying the values as required.


{
    "id": "5f101aa1-3677-5dd8-9a1b-2e3e852289dc",
            "openapi_file_reference": {
                "id": 66ff9223-ede1-73ba-864c-57a0750a71e8,
                "name": "simpleswagger12.json",
                "link": "/api/v1/spaces/default/security/waf/files/79e2da77-ddf5-446e-a446-68de142a77a5"
             }
}

Manage file types

Manage which files types are always or never allowed access to your protected application.

For more information about the file type violations, default allowed/disallowed file types, and wildcard syntax, see Reference: File Types.

Manage disallowed file types

You can manage your disallowed file types using the API. Use the following procedures:

Review the current settings of your configured file types by policy ID:

GET https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/spaces/default/security/waf-policies/{id}/filetypes

Update the status of a policy’s disallowed file type

Configure the protection policy to allow or disallow requests containing a specified file type from accessing the application. Use the allow field to specify whether this file type is allowed (true) or disallowed (false).

PUT https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/spaces/default/security/waf-policies/{id}/filetypes/{filetype-id}

Add a disallowed file type to a policy

Specify a file type to allow or disallow your protected application:

POST https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/spaces/default/security/waf-policies/{id}/filetypes

Delete a disallowed policy file type

Remove a file type rule from a policy’s configuration:

DELETE https://<BIG-IP-Next-Central-Manager-IP-Address>/api/v1/spaces/default/security/waf-policies/{id}/filetypes/{filetype-id}

Manage URLS

Specify the HTTP URLs that are allowed in traffic to the protected web application. By default, wildcard URLs of * (representing all HTTP URLs) are added to the Allowed URLs list.

Use the requests found in edit and deploy policy changes to update and deploy your policy.

View the following JSON examples for configuring a URL, managing metacharacters, and enabling/disabling signatures on a URL:

Manage Methods

All security policies accept standard HTTP methods by default. If your web application uses HTTP methods other than the default allowed methods, you can add them to the security policy. The system treats any incoming HTTP request that uses an HTTP method other than an allowed method as an invalid request. The system ignores, learns, logs, or blocks the request depending on the settings configured.

Default allowed methods vary according to your selected policy template.

Note: GET and POST are always allowed and cannot be removed.

Use the requests found in edit and deploy policy changes to update and deploy your policy.

The following is an example of the allowed methods in a rating-based template. To change the settings for illegal methods, search the JSON declaration for VIOL_METHOD.

{
    "methods": [
        {
            "actAsMethod": "POST",
            "name": "POST"
        },
        {
            "actAsMethod": "GET",
            "name": "GET"
        },
        {
            "actAsMethod": "POST",
            "name": "PUT"
        },
        {
            "actAsMethod": "GET",
            "name": "HEAD"
        },
        {
            "actAsMethod": "GET",
            "name": "OPTIONS"
        },
        {
            "actAsMethod": "GET",
            "name": "DELETE"
        },
        {
            "actAsMethod": "POST",
            "name": "PATCH"
        }
    ]
}

Manage Cookies

WAF allows you to add cookies with different characteristics to security policies. You can specify the cookies that you want to allow, and the ones you want to enforce in a security policy:

  • Allow - The security policy ignores certain known and recognized cookie headers that are included in HTTP requests and allows clients to change the cookies.

  • Enforce - The security policy prevents changes to specific cookies, such as session-related cookies that are set by the protected application. The cookie in the request must not be modified, or it generates the Modified Domain Cookie violation.

Both allowed and enforced cookies can be put in staging when they are created so that you can make sure that they do not cause false positives during the staging period.

Use the requests found in edit and deploy policy changes to update and deploy your policy.

The following is an example of the cookie settings in a rating-based template. To change the settings for illegal methods, search the JSON declaration for: VIOL_COOKIE_MODIFIED, VIOL_COOKIE_MALFORMED, VIOL_COOKIE_EXPIRED, VIOL_COOKIE_LENGTH.

Note: You can specify globally how WAF policies handle traffic with known cookie violations and/or specific cookie parameters. For more information about cookie violations, cookie properties, see Reference: Cookie Enforcement.

See Reference: Violation Protection for information about template default settings.

{
    "cookies": [
        {
            "accessibleOnlyThroughTheHttpProtocol": false,
            "attackSignaturesCheck": true,
            "enforcementType": "allow",
            "insertSameSiteAttribute": "lax",
            "isBase64": false,
            "maskValueInLogs": false,
            "name": "*",
            "performStaging": false,
            "securedOverHttpsConnection": true,
            "type": "wildcard",
            "wildcardOrder": 1
        }
    ]
}

Manage parameters

Configure sensitive parameters to protect applications against client/server-side tampering attacks, malicious file uploads, or SSRF attacks.

By default, a wildcard parameter with a user input value type and alpha-numeric data type is added to the list. This means that any alpha-numeric values (e.g. comments, names, or phone numbers) added by the user in a request is permitted by the WAF policy, unless another user input parameter is specified.

Use the requests found in edit and deploy policy changes to update and deploy your policy.

View the following JSON examples for defining a parameter:

Note: The examples refer to management on a BIG-IP Next instance. Ensure you are using the BIG-IP Next Central Manager API endpoints when deploying additions and changes to your policy JSON.