Diff configuration versions

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

  1. Run List configurations and select a configId.

  2. Run List configuration versions and select a versionNumber for each security configuration you want to compare.

  3. Create a request object.

  4. 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.

FieldDescription
fromThe version number of the configuration to compare against.
toThe version number of the configuration to compare against.
outcomesOptionally 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.

FieldDescription
outcomeHow 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.
fromThe 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.
toThe 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.
addedWhen 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.
removedWhen 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.
modifiedWhen comparing arrays, modified represents any item with a change to an existing value.
unmodifiedWhen comparing arrays, unmodified represents any item that remains the same between versions. This field only returns when the request includes UNMODIFIED.

The changesCount object

This 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.

FieldDescription
modifiedThe number of keys whose values differ between two versions.
unmodifiedThe number of keys that remain unchanged between the two versions. This only appears when you specify UNMODIFIED in the request.
addedThe number of keys added between versions.
removedThe number of keys removed between versions.