My Support
  1. AskF5 Home
  2. Knowledge Center
  3. BIG-IP Declarative Security Policies
  4. Working with Declarative Policy
Manual Chapter : Working with Declarative Policy

Applies To:

Show Versions Show Versions

BIG-IP ASM

  • 16.0.0, 15.1.0
Manual Chapter

Working with Declarative Policy

Using external referencing

An external reference in the declarative policy is a reference to a code block that can be used as part of the policy without including the actual code block within the policy file. A set of predefined configurations for parts of the policy are incorporated as part of the policy by referencing them. This ensures that the policy is always up-to-date in a constantly changing environment.
For example, to build a dynamic policy, configure the code block files relevant to the policy, and then configure the policy to reference the files. Every time the policy is imported into the BIG-IP, it uses the most up-to-date version of the referenced files.
External references are only supported from BIG-IP version 16.x.
The following are some recommendations to use with external reference:
  • Use HTTPS instead of HTTP.
  • Use trusted CA-signed certificates.
  • Make sure sensitive URLs cannot be accessed from BIG-IP as external references.
In the policy file, the direct property is suffixed by
Reference
 and
link
 is used to call the reference. For example, the property
urls
 is updated to
urlReference
 and
data-guard
 to
dataGuardReference
.
In following example, references are called using
link
: 
{
    "policy": {
        "name": "External_References",
        "description": "Testing 'link'",
        "template": {
            "name": "POLICY_TEMPLATE_FUNDAMENTAL"
        },
        "applicationLanguage": "utf-8",
        "enforcementMode": "blocking",
        "protocolIndependent": false,
        "enablePassiveMode": false,
        "urlReference": {
            "link": "http://172.29.42.75/REF_URLs.txt"
        },
        "dataGuardReference": {
            "link": "http://172.29.42.75/data-guard-ref.txt"
        },
        "filetypeReference": {
            "link": "http://172.29.42.75/File-types.txt"
        },
        "whitelistIpReference": {
            "link": "http://172.29.42.75/whitelist-ips-ref.txt"
        }
    },
    "modificationsReference": {
        "link": "file://my_modifications.json"
    }
}
The following is an example for whitelist IP reference file (whitelist-ips-ref.txt):
[
    {
        "ignoreIpReputation": false,
        "blockRequests": "policy-default",
        "ignoreAnomalies": false,
        "neverLogRequests": true,
        "ipAddress": "1.1.1.1",
        "neverLearnRequests": false,
        "ipMask": "255.255.255.255",
        "trustedByPolicyBuilder": false
    },
    {
        "ignoreIpReputation": false,
        "blockRequests": "policy-default",
        "ignoreAnomalies": true,
        "neverLogRequests": true,
        "ipAddress": "2.2.2.2",
        "neverLearnRequests": false,
        "ipMask": "255.255.255.255",
        "trustedByPolicyBuilder": true
    },
    {
        "ignoreIpReputation": true,
        "blockRequests": "policy-default",
        "ignoreAnomalies": false,
        "neverLogRequests": false,
        "ipAddress": "3.3.3.3",
        "neverLearnRequests": false,
        "ipMask": "255.255.255.255",
        "trustedByPolicyBuilder": false
    }
]

Uploading a user defined signatures set

User defined signature sets are only supported from BIG-IP version 16.x.
  1. Upload the signatures set file to the BIG-IP.
    Send a POST request to
    https:/ /<your-BIG-IP>/mgmt/tm/asm/file-transfer/uploads/sigfile.json
    .
    Use following headers:
    Authorization : Basic  <base64-encoded string of your BIG-IP username:password>
Content-Type  : application/json
Content-Range : 0-[filesize-1]/filesize
    The following is an example signatures set file content: 
    {
    "softwareVersion":"16.0.0",
    "tag":"user",
    "signatures":[
        {
            "name":"user_sig 5",
            "rule":"valuecontent:\"/userSig/V\"; nocase; httponly; norm;",
            "signatureType":"request",
            "attackType":{
                "name":"Brute Force Attack"
            },
            "systems":[
                {
                    "name":"Microsoft Windows"
                },
                {
                    "name":"Unix/Linux"
                }
            ],
            "risk":"medium",
            "accuracy":"medium",
            "description":"Users user defined sig 5 updated"
        },
        {
            "name":"user_sig_51",
            "rule":"re2:\"/UserSig51/V\"; nocase; norm;",
            "signatureType":"request",
            "attackType":{
                "name":"Brute Force Attack"
            },
            "systems":[
                {
                    "name":"Microsoft Windows"
                },
                {
                    "name":"Unix/Linux"
                }
            ],
            "risk":"medium",
            "accuracy":"medium",
            "description":"Users user defined sig 51 updated"
        }
    ]
}
  2. Update the signatures.
    Send a POST request to
    https:/ /<your-BIG-IP>/mgmt/tm/asm/tasks/update-signatures/
    .
    Use following headers:
    
Authorization : Basic  <base64-encoded string of your BIG-IP username:password>
Content-Type  : application/json
  3. Verify the updated signatures.
    Send a GET request to
    https:/ /<your-BIG-IP>/mgmt/tm/asm/tasks/update-signatures/<task-ID>
    .
    The signatures are updated successfully if the response contain status code 200 with "
    status": "COMPLETED"
    .
  4. Upload the policy to the BIG-IP.
    The following is an example policy file with reference user defined signatures:
    {
    "policy":{
        "name":"policy_override_user_defined_sig_on_parameter_foo",
        "description":"JSON declarative policy for CICD",
        "template":{
            "name":"POLICY_TEMPLATE_FUNDAMENTAL"
        },
        "applicationLanguage":"utf-8",
        "enforcementMode":"blocking",
        "caseInsensitive":false,
        "protocolIndependent":false,
        "enablePassiveMode":false,
        "signature-requirements":[
            {
                "tag":"user",
                "minRevisionDatetime":"2019-01-15T08:57:10Z",
                "maxRevisionDatetime":"2020-02-15T08:57:10Z"
            }
        ],
        "signatures":[
            {
                "name":"user_sig",
                "tag":"user",
                "enabled":true,
                "learn":true,
                "performStaging":false
            }
        ],
        "signature-sets":[
            {
                "name":"user_sigs",
                "block":true,
                "learn":true,
                "signatureSet":{
                    "filter":{
                        "tagValue":"user",
                        "tagFilter":"eq"
                    }
                }
            }
        ]
    }
}

Incorporating policy builder suggestions

  1. Export policy builder suggestions.
    Send a POST request to
    https://<your-BIG-IP>/mgmt/tm/asm/tasks/export-suggestions
    . Use the following body content:
    {
    "inline": "true",
    "policyReference": {
        "link": "https://<Your_BigIP_Ip>/mgmt/tm/asm/policies/Policy_Key/"
    }
}
    Send a GET request to
    https://<your-BIG-IP>/mgmt/tm/asm/tasks/export-suggestions
    .
    The following is an example for exported suggestions:
    "suggestions": [
    {
        "entityChanges": {
            "signatureOverrides": [
                {
                    "name": "my_TAGGED_SIG",
                    "tag": "my_tag",
                    "enabled": false
                }
            ],
            "type": "explicit"
        },
        "entity": {
            "protocol": "http",
            "name": "/index.php",
            "method": "*"
        },
        "entityType": "url",
        "action": "update-append",
        "description": "Disable the matched signature on the matched URL"
    },
    {
        "entityChanges": {
            "signatureOverrides": [
                {
                    "name": "my_UNTAGGED_SIG",
                    "tag": "",
                    "enabled": false
                }
            ],
            "type": "explicit"
        },
        "entity": {
            "protocol": "http",
            "name": "/index.php",
            "method": "*"
        },
        "entityType": "url",
        "action": "update-append",
        "description": "Disable the matched signature on the matched URL"
    }
]
  2. Update the declarative policy with exported suggestions.
    Use the
    Modifications
     property to add suggestions in the policy. The following is an example:
    "modifications": [
    {
        "entity": {
            "protocol": "http",
            "name": "/index.php",
            "method": "*"
        },
        "entityChanges": {
            "signatureOverrides": [
                {
                    "name": "my_TAGGED_SIG",
                    "tag": "my_tag",
                    "enabled": false
                }
            ],
            "type": "explicit"
        },
        "entityType": "url",
        "action": "update-append",
        "description": "Disable the matched signature on the matched URL"
    },
    {
        "entity": {
            "protocol": "http",
            "name": "/index.php",
            "method": "*"
        },
        "entityChanges": {
            "signatureOverrides": [
                {
                    "name": "my_UNTAGGED_SIG",
                    "tag": "",
                    "enabled": false
                }
            ],
            "type": "explicit"
        },
        "entityType": "url",
        "action": "update-append",
        "description": "Disable the matched signature on the matched URL"
    }
]
  3. Import the updated declarative policy, refer to Declarative policy import.

Declarative policy log files

Advanced WAF and ASM store the import policy log file in BIG-IP device folder
/var/log/asm
.
These log files can be used to identify and troubleshoot issues while processing the declarative policies.

Have a Question?

Support and Sales >

About F5

Education

F5 Sites

Support Tasks

©2020 F5, Inc. All rights reserved.

Policies Privacy Trademarks