Using advanced filter in Cayosoft Guardian
This article contains guidance on how to use the advanced filter in some scenarios where more precise filtering is required for Change History records.
NOTE: Before moving on with advanced filtering, check whether the same result can be achieved with the built-in filtering functionality. Learn more in: Change Monitoring: Built-in and custom queries.
The article also represents how to use advanced filter and examples of ODATA expressions for some special scenarios.
Navigating advanced filter
- Open the Cayosoft Guardian web portal.
- Navigate to Change History.
- In Change History, click Advanced on the Quick Filter panel.
- Enter an ODATA expression in the Advanced filter field.
Supported attribute names in the advanced filter
- For on-premise Active Directory, Cayosoft Guardian uses LDAP attribute names, which are documented in Active Directory Schema (AD Schema) - Win32 apps | Microsoft Docs. You can see these attribute names in Active Directory Users and Computers MMC snap-in on the Attribute Editor tab.
- For Entra ID, Cayosoft Guardian uses MS Graph property names, which are documented in Microsoft Graph beta endpoint reference - Microsoft Graph beta | Microsoft Docs. You can see these properties in Graph Explorer for Entra ID.
- There are virtual properties added by Cayosoft to show changes to attributes that do not have a good visual representation (e.g., Password Never Expires or Authentication Methods) in a user-friendly manner. Such properties have the va_ prefix, for example, va_passwordNeverExpires or va_authenticationMethods_removed.
-
If you found a change history record that you want to use as a template for filtering, you can open its properties and check the attribute names in parentheses:
- To see all properties available for filtering in all Change History records that are currently displaying on your screen, open the Export dropdown and select Export to JSON. Open the exported file in any text editor to observe Change History records attribute names and their values.
Default attribute names available for quick filtering via the UI
This table provides an overview of the default attributes available for quick filtering in the UI, including their corresponding advanced filter attribute names, descriptions, and possible values.
| Quick filter name in the UI | Attribute name for Advanced Filter | Description | Possible values |
|---|---|---|---|
| When | eventDateTime | Change history event timestamp |
A string in the format yyyy-mm-ddThh:mm:ssZ, e.g.:
|
| What | targetObjectName | Object name |
Anything you can see in the What field, e.g.:
|
| Properties - Object Type | nestedType | Object type |
Check the value in parentheses next to the drop-down options, e.g.:
|
| Properties - Modified Properties | modifiedProperties | Modified property (attribute) of an object. Allows filtering by changes that include the specified property. |
Available options depend on selected object type. Check the value in parentheses next to the drop-down options, e.g.:
|
|
Properties – New/added Properties – Old/Removed |
[propertyname]_added [propertyname]_removed |
The exact action on the selected property. When a property is modified, its new value can be filtered with _added and its old value can be filtered with _removed. |
The property name can be taken from the Change History record or from the JSON file and appended with _added or _removed suffix, e.g.:
|
| Action - Operation type | operationType | Operation type | There are the following options available:
|
| Action | auditCategories | The category of the action |
Check the list of actions in the dropdown, e.g.:
|
| Who | initiatorName | That account that performed the change |
The format of the initiator depends on how it is presented in the event collected from the corresponding system, e.g.:
|
| Where - (include/exlude) | targetObjectLocations | OU (for Active Directory) or Administrative Unit (for EntraID) of the object |
The object location should be in the canonical (DNS) format, e.g.: DOMAIN.mytest.net/ParentOU/ChildOU |
| Where - System type | systemType | The source system that generated the change event. |
Supported values include:
|
| - | I | Additional parameters collected for some change types |
UserPrincipalName attribute value, e.g.:
CallerComputerName for Lockout events, e.g.:
|
Supported expressions in the advanced filter
Cayosoft Guardian uses MS Graph (OData) operators in the advanced filter to display Change History records matching the filter expression.
| Operator group | Operator | Sample filter | Meaning |
|---|---|---|---|
| Logical operators | not, and, or | proxyAddresses_added/any() andnot(proxyAddresses_added/any(z:contains(z,'admin'))) | Show changes where an email alias was added and not show changes where it contains the word ‘admin’ |
| objectName eq 'Global Administrator' or objectName eq 'Company Administrator' | Changed object name is 'Global Administrator' or 'Company Administrator' | ||
| Comparison operators | eq (equal), ne (not equal), gt (greater than), lt (less than), ge (greater or equal), le (less or equal) | nestedType eq 'microsoft.graph.directoryRole' | Changed object type is equal to 'microsoft.graph. directoryRole' |
| (createdDateTime gt 2024-06-07T19:00:00.00Z) | Show all change history records created after the specified date/time | ||
| accountEnabled_added ne null | Show all change history records where displayName was added (not equal to empty) | ||
| Collection operators | any | member_added/any() or members_added/any() | A member was added to an Active Directory Group or an Entra Group |
|
parameters/any(i:i/name eq 'CallerComputerName' and i/value eq 'APP01') |
Account lockout events that happened on the computer APP01. | ||
| String functions | contains, startsWith, endsWith |
contains(distinguishedName_added,'OU=OU1,DC= corp,DC=test,DC=local') |
Change history records where an updated object DN contains OU1 path. |
| targetObjectLocations/any(i:startswith(i, 'test.local/Users')) | Change history records related to objects located in a container with the common name attribute starting with the specified value. | ||
| endsWith(targetObjectName,'_svc') | Change history records where the modified object name ends with “_svc” |
Working with Collection operators
There are two collection operators in OData: ‘all’ and ‘any’. Guardian only supports ‘any’.
Collection operators allow you to filter by attributes that can store multiple values or name-value pairs. To check if a specific attribute is a collection or not, check how it looks in the JSON export.
Below are not collections as the value goes right after the property name, and there are no square brackets to set the collection boundaries:
| Value | Property name |
|---|---|
|
"va_samAccountType_added": "groupObject"
|
"nestedDisplayType": "AD Group" |
Below are examples of collections as they can have multiple values specified in []. Even if a collection attribute has a single value in it, it is still a collection.
| Value | Property name |
|---|---|
|
"modifiedProperties": [ "countryCode", "displayName", ],
|
"targetObjectLocations": [ "test.cayotest.net/_Tests" ],
|
Collections with named elements may look as follows, i.e., each member has the name and the value:
| Value | Property name |
|---|---|
|
"member_added": [ { "id": "ac84b058789e4943b55eecf547ac974c", "objectName": "test", "objectType": "microsoft.ad.user", "originalId": "04c82a81-1ff3-4f7a-855d-188232f49860", "originalObjectPath": "msAd/forests/test.domain.net/partitions/023b5a99e/directoryObjects/ 04c82a81-160/microsoft.ad.user" } ],
|
"parameters": [ { "name": "CallerComputerName", "value": "APP01" }, { "name": "userPrincipalName", "value": "test.user@test.domain.net" } ],
|
If you want to find all changes that have a specific collection attribute present regardless of its value, you should add it with /any operator and empty parentheses. For example:
- member_added/any() – show all AD group membership changes
- assignedLicenses_added/any() – show all changes where a license was assigned to an Entra account
If you want filter by a specific collection value, the product will have to cycle through the list of values using an iterator. The syntax is attributename/any(iterator:expression). You can use any set of characters as the iterator name, usually it is just ‘i’ or ‘z’. For example:
- targetObjectLocations/any(i:i eq 'test.domain.net/_Tests') – shows all changes where the one of the target object locations is exactly 'test.domain.net/_Tests'
- modifiedProperties/any(z:z eq 'displayName') – show all changes where the displayName property was modified
- String functions can also be used with iterators, in this case the iterator is put inside the function:
- targetObjectLocations/any(i:startsWith(i,test.domain.net/AzureADSync')) – shows all changes where the target object locations include an element starting with test.domain.net/AzureADSync
- description_added/any(z:contains(z,'suspended')) – shows all changes where the description was added and contains the word ‘suspended’
To filter by specific values in named collections, you should specify the element name right after the iterator:
- member_added/any(z:contains(z/objectName,'test')) - this filter will go through the changes where AD group members were added, and only show those where one of the added member names (objectName) contains the word ‘test’
You can make the filter more granular by specifying several named fields:
- parameters/any(i:i/name eq 'CallerComputerName' and i/value eq 'APP01') – this filter will only show changes where the parameters collection item includes the element ‘name’ equal to ‘CallerComputerName’ and the element value of the same item is equal to ‘APP01’.
Comments
0 comments
Please sign in to leave a comment.