When you want to track changes across your configuration or perform other audit-related tasks, you'll run Compare two versions.
Make the request
This operation doesn't enforce a linear sequence when you pass your request. This means you can pass version 8 as the from
value and version 4 as the to
value, like in cases where you want to roll back to a previous version and verify the changes. This is also helpful when comparing a much later configuration version to one active on production when there are extensive changes between the two.
Optionally, you can include unchanged data by including UNMODIFIED
in the request.
"outcomes": ["MODIFIED"]
Or,
"outcomes": ["MODIFIED", "UNMODIFIED"]
Steps
-
Run List configurations and select a
configId
. -
Run List configuration versions and select a
versionNumber
for each security configuration you want to compare. -
Create a request object.
-
Submit a POST request to Compare two versions.
The diff response
This operation returns your configurations in a similar format to the response in Export a configuration version. However, the response replaces each exported setting with a diff object for each type of data. There are four different ways the syntax differs depending on the response object's complexity : Simple data , simple arrays, changes to an object, or arrays of objects. In addition to changes in settings, this operation returns a changesCount object summarizing the changes in a particular array or object.
Objects in an array may change the order in which they appear. If the only change to an object is its place in an array, the API treats it as unchanged. Because of this, to identify persistent objects within an array, the diff uses certain data fields such as configId
and policyId
to identify them. The diff reflects whatever data it used as keys to compare the objects.
Note that some automatically generated values for fields like createdDate
and createdBy
aren't compared and are omitted from the response.
Simple data
An object that describes a change to simple data with from
,to
, and outcome
. For data that is ADDED
or REMOVED
, see Objects
{"allowSampling": false}
{"allowSampling": true}
{
"allowSampling": {
"from": false,
"outcome": "MODIFIED",
"to": true
}
}
Simple arrays
The response shows changes to object values as added
or removed
. If you want to see a change in the order of objects within the array, look at the from
and to
values in the response.
{
"selectedHosts": [
"host1.com",
"host2.com",
"host3.com"
]
}
{
"selectedHosts": [
"host2.com",
"host3.com",
"host4.com"
]
}
{
"selectedHosts": {
"added": [
"host4.com"
],
"from": [
"host1.com",
"host2.com",
"host3.com"
],
"outcome": "MODIFIED",
"removed": [
"host1.com"
],
"to": [
"host2.com",
"host3.com",
"host4.com"
]
}
}
In this example, host4.com
is added to the list of hostnames, host1.com
is removed, and the overall outcome of the selectedHosts
object is MODIFIED
.
Objects
Comparisons of objects summarize the number or types of changes.
{
"id": 7180,
"latestVersion": 9,
"name": "Corporate Sites WAF"
}
{
"id": 7180,
"latestVersion": 9,
"name": "App and API protector for corporate sites",
"description": "New name for an old configuration"
}
{
"name": {
"from": "Corporate Sites WAF",
"outcome": "MODIFIED",
"to": "App and API protector for corporate sites"
},
"description": {
"from": null,
"outcome": "ADDED",
"to": "New name for an old configuration"
}
}
Object change summary
Change count objects (changesCount
) are included within an object to summarize the rest of its changes. This object tells how many properties and objects were modified, added, removed, or unmodified within the particular node.
The changesCount
is aggregated on each node level. So any number of changes on the descendant nodes are counted as 1 change on the parent.
{
"changesCount": {
"modified": 2
},
"propertyA": {
"outcome": "MODIFIED"
},
"childNode": {
"outcome": "MODIFIED",
"changesCount": {
"modified": 2
},
"childPropertyA": {
"outcome": "MODIFIED"
},
"childPropertyB": {
"outcome": "MODIFIED"
}
}
}
Arrays of objects
This array presents all objects that have been added
, removed
, or modified
grouped in separate arrays. Optionally, return unmodified
data in the response as well. Objects are accompanied by immutable data, such as IDs, to provide context.
Different operations such as added
or removed
are grouped together, while an object array thatās MODIFIED
means any of its items are added, removed, or updated in place.
Note that for any added or deleted objects, all of the object's keys are also marked as added or deleted. For example, if a security policy is added or removed from the collection, all child objects in the rate policy will have an outcome of added
or removed
accordingly. A null
value appears for a field that's removed between versions.
{
"ratePolicies": [
{
"clientIdentifier": "ip",
"description": "Mitigating HTTP flood attacks using GET requests",
"id": 123,
"matchType": "path",
"name": "GET Page Requests"
},
{
"clientIdentifier": "ip",
"description": "Mitigating HTTP flood attacks using POST requests",
"id": 234,
"matchType": "path",
"name": "POST Page Requests"
}
]
}
{
"ratePolicies": [
{
"clientIdentifier": "ip",
"description": "Mitigating HTTP flood attacks using HEAD requests",
"id": 123,
"matchType": "path",
"name": "HEAD Page Requests"
},
{
"clientIdentifier": "ip",
"description": "Mitigating HTTP flood attacks using PATCH requests",
"id": 345,
"matchType": "path",
"name": "PATCH Page Requests"
}
]
}
{
"ratePolicies": {
"outcome": "MODIFIED",
"removed": [
{
"changesCount": {
"added": 0,
"modified": 0,
"removed": 4,
"unmodified": 0
},
"outcome": "REMOVED",
"id": 234,
"name": {
"outcome": "REMOVED",
"from": "POST Page Requests",
"to": null
},
"description": {
"outcome": "REMOVED",
"from": "Mitigating HTTP flood attacks using POST requests",
"to": null
},
"matchType": {
"outcome": "REMOVED",
"from": "path",
"to": null
},
"clientIdentifier": {
"outcome": "REMOVED",
"from": "ip",
"to": null
}
}
],
"added": [
{
"changesCount": {
"added": 4,
"modified": 0,
"removed": 0,
"unmodified": 0
},
"outcome": "ADDED",
"id": 345,
"name": {
"outcome": "ADDED",
"from": null,
"to": "PATCH Page Requests"
},
"description": {
"outcome": "ADDED",
"from": null,
"to": "Mitigating HTTP flood attacks using PATCH requests"
},
"matchType": {
"outcome": "ADDED",
"from": null,
"to": "path"
},
"clientIdentifier": {
"outcome": "ADDED",
"from": null,
"to": "ip"
}
}
],
"modified": [
{
"changesCount": {
"added": 0,
"modified": 3,
"removed": 0,
"unmodified": 0
},
"outcome": "MODIFIED",
"id": "1111_517317",
"webApplicationFirewall": {
"changesCount": {
"added": 0,
"modified": 1,
"removed": 0,
"unmodified": 0
},
"outcome": "MODIFIED",
"attackGroupActions": {
"outcome": "MODIFIED",
"modified": [
{
"changesCount": {
"added": 0,
"modified": 1,
"removed": 0,
"unmodified": 0
},
"outcome": "MODIFIED",
"group": "CMD",
"action": {
"outcome": "MODIFIED",
"from": "alert",
"to": "deny"
},
"rulesetVersionId": 7151
}
]
}
},
"requestBody": {
"changesCount": {
"added": 0,
"modified": 1,
"removed": 0,
"unmodified": 0
},
"outcome": "MODIFIED",
"requestBodyInspectionLimitInKB": {
"outcome": "MODIFIED",
"from": "6",
"to": "8"
}
}
}
]
}
}
Request body
Note that the plural outcomes
in the request body is different than the singular outcome
in the response.
Field | Description |
---|---|
from | The version number of the configuration to compare against. |
to | The version number of the configuration to compare against. |
outcomes | Optionally specify what you want to compare, such as both MODIFIED and UNMODIFIED data. If omitted, by default the diff shows only MODIFIED data. |
Response body
The outcome
, from
, and to
fields in the response body show the changes between versions, and don't represent the version numbers like in the request.
Field | Description |
---|---|
outcome | How data changed between the two versions, either ADDED , REMOVED , or MODIFIED . Optionally, if you included it in the request, you'll see UNMODIFIED data in the response. |
from | The initial value you're comparing. When comparing simple arrays, this shows the original array's sequence. In cases where a value is a new object key, the diff displays "from": null , accompanied by "to" with the new value. |
to | The updated value you're comparing. When comparing simple arrays, this shows the updated array's sequence. In cases where an object key is deleted, the diff displays "to": null , accompanied by "from" with the deleted value. |
added | When comparing arrays, added represents any item not in the original array. When comparing simple arrays, these are simple values like numbers and strings. When you're comparing object arrays, this contains diff objects. |
removed | When comparing arrays, removed represents any item no longer in the array. When comparing simple arrays, these are simple values like numbers and strings. When you're comparing object arrays, this contains diff objects. |
modified | When comparing arrays, modified represents any item with a change to an existing value. |
unmodified | When comparing arrays, unmodified represents any item that remains the same between versions. This field only returns when the request includes UNMODIFIED . |
The changesCount
object
changesCount
objectThis object appears in the response and tells you how many changes there are within the object or array of objects, and only appears in diffs that compare objects or arrays of objects.
Field | Description |
---|---|
modified | The number of keys whose values differ between two versions. |
unmodified | The number of keys that remain unchanged between the two versions. This only appears when you specify UNMODIFIED in the request. |
added | The number of keys added between versions. |
removed | The number of keys removed between versions. |