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""}
}
]
}
}