Manual Chapter :
Working with Declarative Policy
Applies To:
Show Versions
BIG-IP ASM
- 17.1.2, 17.1.1, 17.1.0, 17.0.0, 16.1.5, 16.1.4, 16.1.3, 16.1.2, 16.1.1, 16.1.0
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 endpoint is suffixed by
Reference
and link
is used to call the endpoint reference. For example, the endpoint urls
is updated to urlReference
and data-guard
to dataGuardReference
.For list of all endpoints, refer List of endpoints.
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 } ]
The following is an example for modification reference file (my_modifications.json):
{ "modifications":[ { "entityChanges":{ "type":"explicit" }, "entity":{ "name":"log" }, "entityType":"filetype", "action":"delete", "description":"Delete Disallowed File Type" } ] }
Uploading a user defined signatures set
User defined signature sets are only supported from BIG-IP version 16.x.
- Upload the signatures set file to the BIG-IP.Send a POST request tohttps:/ /<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]/filesizeThe 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" } ] }
- Update the signatures.Send a POST request tohttps:/ /<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
- Verify the updated signatures.Send a GET request tohttps:/ /<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".
- Upload the policy to the BIG-IP.Refer to Declarative policy import.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
- Export policy builder suggestions.Send a POST request tohttps://<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 tohttps://<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" } ]
- Update the declarative policy with exported suggestions.Use theModificationsproperty 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" } ]
- Import the updated declarative policy, refer to Import declarative policy.
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.
