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

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

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.

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.