Manual Chapter : Getting Started with Declarative Policies

Applies To:

Show Versions Show Versions

BIG-IP ASM

  • 16.0.0, 15.1.0
Manual Chapter

Getting Started with Declarative Policies

About declarative security policies

The Advanced Web Application Firewall (Advanced WAF) or Application Security Manager (ASM) security policies can be deployed using the declarative JSON format, facilitating easy integration into a CI/CD pipeline. The declarative policies are extracted from a source control system, for example Git, and imported into the BIG-IP.
Using the provided declarative policy templates, you can modify the necessary parameters, save the JSON file, and import the updated security policy into your BIG-IP devices. The declarative policy copies the content of the template and adds the adjustments and modifications on to it. The templates therefore allow you to concentrate only on the specific settings that need to be adapted for the specific application that the policy protects.
The code examples in this document are for reference only.

Prerequisites

Before working with declarative policies, make sure you are familiar with the F5 BIG-IP Application Security Manager and general BIG-IP terminology. Information is found in the F5 Knowledge Centers.
To read, modify, or import declarative policies, you must have:
  • BIG-IP devices running version 15.1.x or later
  • BIG-IP Administrator role permissions
  • An active ASM or Advanced WAF license on the BIG-IP devices

About the declarative policy structure

Declarative security policies are created in the declarative JSON format.The supported declarative policy structure includes three logical sections: the "core" and "adjustment" sections, defined under the
policy
property, and the modifications section, defined below the first two sections, under the
modifications
array property.
The modifications section is optional, and, when the section is excluded, the top
policy
property can also be omitted from the JSON schema.
Each logical section in the declarative policy JSON schema has a specific purpose.
  • Core
    Defined within the root
    policy
    property, the core section includes the name, description, and template for the policy.
    The template field is mandatory, and referenced by name. Templates are prepared policies designed for a category of applications. The template name implies the level of security and the attack surface it protects.
    The template file must be stored on the BIG-IP device in which the policy is created. F5 provides a set of predefined templates, which users can modify and save to create their own templates. For more information about these templates, refer to Predefined templates.
    The following is an example of the core section within the declarative policy:
    "name": "AppPolicy01", "description": "AppV1.1 - DEMO FOR DECLARATIVE AND WEBHOOKS CAPABILITIES", "template": { "name": "POLICY_TEMPLATE_FUNDAMENTAL" },
  • Adjustments
    Defined within the root
    policy
    property after the core section, the adjustments section includes attributes of the policy that override or add to those defined in the template .
    Attributes included in this section can include both properties that are particular to the protected application, such as server technologies, URLs, or parameters, and modifications to settings defined by the template, such as enabling the Data Guard if it is disabled in the template, and specifying Data Guard attributes.
    The adjustments section contains all the entities of the security policy. All adjustments are optional. If there are no adjustments, the values are taken from the defined template.
    The following is an example of the adjustments section within the declarative policy:
    "enforcementMode": "blocking", "server-technologies": [ { "serverTechnologyName": "MySQL" } ], "signature-settings": { "signatureStaging": false },
  • Modifications
    Defined within the
    modifications
    property, after the core and adjustments sections, the modifications section includes actions that modify the declarative policy as it is defined in the adjustments section. The modifications section is updated manually, with the changes generally driven by the learning suggestions provided by the BIG-IP.
    Changes to the template can be defined in either the adjustments or modifications sections. In general, the adjustments section is used for defining major features of the policy which are different from template, while the modifications section is used for frequent and granular changes that are required to tune the policy, such as reducing false positives, patching vulnerabilities, etc.
    When an attribute is defined in both the adjustments and modifications sections, the policy is deployed with the value as it appears in the modifications section. When an attribute appears in the modifications section multiple times, the policy is deployed with the value as it appears in the latest definition in the modifications section.
    The following is an example of the modifications section within the declarative policy:
    "modifications": [ { "entityChanges": { "type": "explicit" }, "entity": { "name": "log" }, "entityType": "filetypes", "action": "delete", "description": "Delete Disallowed File Type" } ]
The following is an example of a declarative policy with all three logical sections:
{ "policy": { "name": "PolicyApp01", "description": "PolicyApp01 Description Example", "template": { "name": "POLICY_TEMPLATE_RAPID_DEPLOYMENT" }, "enforcementMode": "blocking", "server-technologies": [ { "serverTechnologyName": "MySQL" } ], "signature-settings": { "signatureStaging": false }, "signatures": [ { "signatureId": 200101552, "enabled": false, "performStaging": false } ], "whitelist-ips": [ { "ipAddress": "10.0.0.1", "ipMask": "255.255.255.255", "description": "always block this ip address", "blockRequests": "always" } ], "disallowed-geolocations": [ { "countryName": "American Samoa" } ] }, "modifications": [] }