ASM Policy Difference

Overview

The ASM Policy Difference API can generate a human-readable report that compares two security policies. This API can be used to compute the differences between the two policies for the purpose of distinguishing differences in security levels. The two policies, source and destination, can be located on different BIG-IPs which are being managed by a BIG-IQ. The BIG-IQ saves old policy difference tasks for two days and then deletes it and report.

The ASM Policy Analyzer API is the API that can analyze a security policy, calculate a security score, and store suggestions to improve the policy.

REST Endpoint: /mgmt/cm/asm/tasks/policy-diff

Requests

POST /mgmt/cm/asm/tasks/policy-diff

Send a POST request to the tasks/policy-diff endpoint to create a policy difference task. To run another difference task with the same policies, POST the task again and the previous task and its report will be removed internally.

Request Parameters

Name Type Required Description
policyFromReference object True A reference link to the source policy existing on the BIG-IQ.
     link string True URL of the source policy
policyToReference object True A reference link to the destination policy existing on the BIG-IQ.
     link string True URL of the destination policy

Query Parameters

None

Response

HTTP/1.1 200 OK

Name Type Description
currentStep string Current step of the of the policy difference task
diffReportReference object A reference link to the policy difference report.
     link string URL of policy difference report. When the task is finished, the report will be available by querying for the diffReportReference.
endDateTime string Date and time when the policy difference task ended. For example, “2020-08-23T03:40:49.384-0700”.
id string UUID of the policy difference task
ownerMachineId string UUID machine id
policyFromReference object A reference link to the source policy existing on the BIG-IQ. This must be a different policy than policyToReference. policyFromReference and policyToReference must share the same “application language” and “case insensitive” parameters.
     link string URL of the source policy
policyToReference object A reference link to the destination policy existing on the BIG-IQ. This must be a different policy than policyFromReference. policyFromReference and policyToReference must share the same “application language” and “case insensitive” parameters.
     link string URL of the destination policy
selfLink string URL of the policy difference task
startDateTime string Date and time when the policy difference task started. For example, “2020-08-23T03:37:09.815-0700”.
status string The status of the policy difference task.
username string Name of the user
userReference object A reference link to a user.
     link string URL of user

Permissions

Role Allow
Web Application Security Manager Yes
Web Application Security Editor Yes
Web Application Security Viewer Yes
Web Application Security Deployer Yes

DELETE /mgmt/cm/asm/tasks/policy-diff/{id}

Send a DELETE request to the tasks/policy-diff/{id} endpoint to delete an existing policy difference task. Replace a single policy difference task by specifying the task’s id. The value of id can be obtained from the response to a POST or GET.

Request Parameters

Name Type Required Description
policyFromReference object True A reference link to the source policy existing on the BIG-IQ.
     link string True URL of the source policy
policyToReference object True A reference link to the destination policy existing on the BIG-IQ.
     link string True URL of the destination policy

Query Parameters

None

Response

HTTP/1.1 200 OK

Name Type Description
policyFromReference object A reference link to the source policy existing on the BIG-IQ. This must be a different policy than policyToReference. policyFromReference and policyToReference must share the same “application language” and “case insensitive” parameters.
     link string URL of the source policy
policyToReference object A reference link to the destination policy existing on the BIG-IQ. This must be a different policy than policyFromReference. policyFromReference and policyToReference must share the same “application language” and “case insensitive” parameters.
     link string URL of the destination policy
id string UUID of the policy difference task
status string The status of the policy difference task.
selfLink string URL of the policy difference task
username string Name of the user
currentStep string Current step of the of the policy difference task
endDateTime string Date and time when the policy difference task ended. For example, “2020-08-23T03:40:49.384-0700”.
startDateTime string Date and time when the policy difference task started. For example, “2020-08-23T03:37:09.815-0700”.
userReference object A reference link to a user.
     link string URL of user
ownerMachineId string UUID machine id
diffReportReference object A reference link to the policy difference report.
     link string URL of policy difference report. When the task is finished, the report will be available by querying for the diffReportReference.

Permissions

Role Allow
Web Application Security Manager Yes
Web Application Security Editor Yes
Web Application Security Viewer Yes
Web Application Security Deployer Yes

REST Endpoint: /mgmt/cm/asm/reports/policy-diff

GET /mgmt/cm/asm/reports/policy-diff

Send a GET request to the reports/policy-diff endpoint to retrieve the collection of policy difference reports.

Request Parameters

None

Query Parameters

None

Response

HTTP/1.1 200 OK

Name Type Description
policyFromReference object A reference link to the source policy existing on the BIG-IQ. This must be a different policy than policyToReference. policyFromReference and policyToReference must share the same “application language” and “case insensitive” parameters.
     link string URL of the source policy
policyToReference object A reference link to the destination policy existing on the BIG-IQ. This must be a different policy than policyFromReference. policyFromReference and policyToReference must share the same “application language” and “case insensitive” parameters.
     link string URL of the destination policy
selfLink string URL of this collection policy difference report
noDiffsFound boolean This value is only set to true if the two policies are identical. Otherwise this is parameter is absent.
changed object Attributes which changed between source to destination policies
     parameters object An array of objects which describe parameters that have changed between the source and destination policies
          toObject object Changed attributes in the destination policy as: {“attribute_field”:value, **insert other changed attributes here**, “selfLink”: value} Where the values of “attribute_field” and “selfLink” are from policyToReference.
          fromObject object Changed object and value in the source policy as {“attribute_field”:value, **insert other changed attributes here**, “selfLink”: value} Where the values of “attribute_field” and “selfLink” are from policyFromReference.
     urls object An array of objects which describe parameters that have changed between the source and destination policies
          toObject object Changed attributes in the destination policy as: {“attribute_field”:value, **insert other changed attributes here**, “selfLink”: value} Where the values of “attribute_field” and “selfLink” are from policyToReference.
          fromObject object Changed object and value in the source policy as {“attribute_field”:value, **insert other changed attributes here**, “selfLink”: value} Where the values of “attribute_field” and “selfLink” are from policyFromReference.
added object Attributes added to destination policy
     parameters object An array of objects which describe parameters were added to the destination policy
          toObject object Changed attributes in the destination policy as: {“attribute_field”:value, **insert other changed attributes here**, “selfLink”: value} Where the values of “attribute_field” and “selfLink” are from policyToReference.
     urls object An array of objects which describe parameters that have changed between the source and destination policies
          toObject object Changed attributes in the destination policy as: {“attribute_field”:value, **insert other changed attributes here**, “selfLink”: value} Where the values of “attribute_field” and “selfLink” are from policyToReference.
removed object Attributes removed from the source policy
     parameters object An array of objects which describe parameters that have changed between the source and destination policies
          fromObject object Changed object and value in the source policy as {“attribute_field”:value, **insert other changed attributes here**, “selfLink”: value} Where the values of “attribute_field” and “selfLink” are from policyFromReference.
     urls object An array of objects which describe parameters that have changed between the source and destination policies
          fromObject object Changed object and value in the source policy as {“attribute_field”:value, **insert other changed attributes here**, “selfLink”: value} Where the values of “attribute_field” and “selfLink” are from policyFromReference.

Permissions

Role Allow
Web Application Security Manager Yes
Web Application Security Editor Yes
Web Application Security Viewer Yes
Web Application Security Deployer Yes

Examples

POST to create a policy difference task

The following example sends a POST request to create a policy difference task.

POST https://<BIG-IQ>/mgmt/cm/asm/tasks/policy-diff

The JSON in the body of the POST can look similar to the following example.

{
    "policyFromReference": {
            "link": "https: //localhost/mgmt/cm/asm/working-config/policies/95d37173-5c5d-32de-b6a3-59094e0b99cd"
    },
    "policyToReference": {
            "link": "https: //localhost/mgmt/cm/asm/working-config/policies/1697e404-8ee3-3a6d-af8b-c33f259044f1"
    }
}

Response

The JSON in the response to the POST can look similar to the following.

HTTP/1.1 200 OK

{
    "policyFromReference": {
            "link": "https://localhost/mgmt/cm/asm/working-config/policies/95d37173-5c5d-32de-b6a3-59094e0b99cd"
    },
    "policyToReference": {
            "link": "https://localhost/mgmt/cm/asm/working-config/policies/1697e404-8ee3-3a6d-af8b-c33f259044f1"
    },
    "id": "e919bf4a-d255-496f-92a5-f623397c5dc5",
    "kind": "cm:asm:tasks:policy-diff:policydifftaskitemstate",
    "status": "FINISHED",
    "selfLink": "https://localhost/mgmt/cm/asm/tasks/policy-diff/e919bf4a-d255-496f-92a5-f623397c5dc5",
    "username": "admin",
    "generation": 50,
    "currentStep": "DONE",
    "endDateTime": "2020-08-23T03:40:49.384-0700",
    "startDateTime": "2020-08-23T03:37:09.815-0700",
    "userReference": {
            "link": "https://localhost/mgmt/shared/authz/users/admin"
    },
    "ownerMachineId": "72d4d775-73fc-41df-a944-f7b21c8c2b96",
    "lastUpdateMicros": 1598179249435171,
    "diffReportReference": {
            "link": "https://localhost/mgmt/cm/asm/reports/policy-diff/4d5f640c-b9fb-491a-875e-846d2844fe0b"
    }
}

GET to retrieve a policy difference report

The following example sends a GET request to retrieve the policy difference report.

GET https://<BIG-IQ>/mgmt/cm/asm/reports/policy-diff

Response

The JSON in the response to the GET can look similar to the following. There can be an array of objects for each subcollection which has a difference in changed, added, or removed.

HTTP/1.1 200 OK

{
    "policyFromReference": { "link": "https://localhost/mgmt/cm/asm/working-config/policies/95d37173-5c5d-32de-b6a3-59094e0b99cd"},
    "policyToReference": { "link": "https://localhost/mgmt/cm/asm/working-config/policies/1697e404-8ee3-3a6d-af8b-c33f259044f1"},
    "selfLink": "https://localhost/mgmt/cm/asm/reports/policy-diff/03abd4fe-7580-40a6-88a7-fd67c2ff0661",
    "noDiffsFound": true,
    "changed": {
        "parameters":[
            {
                "toObject":{
                                    "isBase64": "true",
                                    "other_changed_attribute": "value",
                                    "other_changed_attribute": "value",
                                    "other_changed_attribute": "value",
                                    "selfLink": "https://localhost/mgmt/cm/asm/working-config/policies/1697e404-8ee3-3a6d-af8b-c33f259044f1/parameters/uuid"},
                "fromObject":{
                                    "isBase64": "false",
                                    "other_changed_attribute": "value",
                                    "other_changed_attribute": "value",
                                    "other_changed_attribute": "value",
                                    "selfLink": "https://localhost/mgmt/cm/asm/working-config/policies/95d37173-5c5d-32de-b6a3-59094e0b99cd/parameters/uuid"}
            }
        ],
        "urls":[
            {
                "toObject":{
                                    "wildcardIncludesSlash": true,
                                    "other_changed_attribute": "value",
                                    "other_changed_attribute": "value",
                                    "other_changed_attribute": "value",
                                    "selfLink": "https://localhost/mgmt/cm/asm/working-config/policies/1697e404-8ee3-3a6d-af8b-c33f259044f1/urls/uuid"},
                "fromObject": {
                                    "wildcardIncludesSlash": false,
                                    "other_changed_attribute": "value",
                                    "other_changed_attribute": "value",
                                    "other_changed_attribute": "value",
                                    "selfLink": "https://localhost/mgmt/cm/asm/working-config/policies/95d37173-5c5d-32de-b6a3-59094e0b99cd/urls/uuid"}
            }
        ]
    },
    "added": {
        "parameters":[
            {
                "toObject":{"Full_state_object_here" + ""selfLink": "https://localhost/mgmt/cm/asm/working-config/policies/1697e404-8ee3-3a6d-af8b-c33f259044f1/parameters/uuid""}
            }
        ],
        "urls":[
            {
                "toObject":{"Full_state_object_here" + ""selfLink": "https://localhost/mgmt/cm/asm/working-config/policies/1697e404-8ee3-3a6d-af8b-c33f259044f1/urls/uuid""}
            }
        ]
    },
    "removed": {
        "parameters":[
            {
                "fromObject":{"Full_state_object_here" + ""selfLink": "https://localhost/mgmt/cm/asm/working-config/policies/1697e404-8ee3-3a6d-af8b-c33f259044f1/parameters/uuid""}
            }
        ],
        "urls":[
            {
                "fromObject":{"Full_state_object_here" + ""selfLink": "https://localhost/mgmt/cm/asm/working-config/policies/1697e404-8ee3-3a6d-af8b-c33f259044f1/urls/uuid""}
            }
        ]
    }
}