{
	"id": "c63f6373-a4b4-4908-afa3-e15b785126c4",
	"created_at": "2026-04-06T00:21:54.96602Z",
	"updated_at": "2026-04-10T03:21:17.405088Z",
	"deleted_at": null,
	"sha1_hash": "73d2e61f11742fe502051b2b024e3a95f1a86a5a",
	"title": "Polling for Changes Using the DirSync Control - Win32 apps",
	"llm_title": "",
	"authors": "",
	"file_creation_date": "0001-01-01T00:00:00Z",
	"file_modification_date": "0001-01-01T00:00:00Z",
	"file_size": 54748,
	"plain_text": "Polling for Changes Using the DirSync Control - Win32 apps\r\nBy GrantMeStrength\r\nArchived: 2026-04-05 17:18:56 UTC\r\nActive Directory directory synchronization (DirSync) control is an LDAP server extension that enables an\r\napplication to search an directory partition for objects that have changed since a previous state.\r\nUse the DirSync control through ADSI by specifying the ADS_SEARCHPREF_DIRSYNC search preference\r\nwhen using IDirectorySearch. For more information and a code example, see Example Code Using\r\nADS_SEARCHPREF_DIRSYNC. You can also perform a DirSync search using the LDAP API. The following\r\ndescribes the ADSI implementation, most of which also applies to using LDAP directly, except as discussed at the\r\nend of this topic.\r\nWhen you perform a DirSync search, you pass in a provider-specific data element (cookie) that identifies the\r\ndirectory state at the time of the previous DirSync search. For the first search, you pass in a null cookie, and the\r\nsearch returns all objects that match the filter. The search also returns a valid cookie. Store the cookie in the same\r\nstorage that you are synchronizing with the Active Directory server. On subsequent searches, get the cookie from\r\nstorage and pass it with the search request. The search results now include only the objects and attributes that have\r\nchanged since the previous state identified by the cookie. The search also returns a new cookie to store for the\r\nnext search.\r\nThe following table lists search parameters that the client search request can specify.\r\nParameter Description\r\nBase of the\r\nsearch\r\nThe base of a DirSync search must be the root of a directory partition, which can be a domain\r\npartition, the configuration partition, or the schema partition.\r\nScope\r\nThe scope of a DirSync search must be ADS_SCOPE_SUBTREE, that is, the entire subtree\r\nof the partition. Be aware that for a search of a domain partition, the subtree includes the\r\nheads, but not the contents, of the configuration and schema partitions. To poll for changes in a\r\nsmaller scope, use the USNChanged technique instead of DirSync.\r\nFilter\r\nYou can specify any valid search filter. For an initial search with a null cookie, the results\r\ninclude all objects that match the filter. For subsequent searches with a valid cookie, the search\r\nresults include data only for objects that match the filter and have changed since the state\r\nindicated by the cookie. For more information about search filters, see Creating a Query Filter.\r\nAttributes You can specify a list of attributes to be returned when a change occurs. For each object, the\r\ninitial results include all the requested attributes set on the object. Subsequent search results\r\ninclude only the specified attributes that have changed. Unchanged attributes are not included\r\nin the search results. In the ADSI implementation, the search results always include the\r\nhttps://msdn.microsoft.com/en-us/library/ms677626.aspx\r\nPage 1 of 4\n\nParameter Description\r\nobjectGUID and instanceType of each object. Also, the specified attribute list acts as an\r\nadditional filter: the initial search results include only objects that have at least one of the\r\nspecified attributes set; subsequent searches include only objects on which one or more of the\r\nattributes have changed (values added or deleted).\r\nAlso, be aware that:\r\nFor incremental searches, the best practice is to bind to the same domain controller (DC) used in the\r\nprevious search, that is, the DC that generated the cookie. If the same DC is unavailable, either wait until it\r\nis, or bind to a new DC and perform a full synchronization. Store the DNS name of the DC in the\r\nsecondary storage with the cookie.\r\nYou can pass a cookie generated by one DC to a different DC hosting a replica of the same directory\r\npartition. There is no chance that a client will miss changes by using a cookie from one DC on another DC.\r\nHowever, it is possible that the search results from the new DC may include reported changes by the old\r\nDC; in some cases, the new DC may return all objects and attributes, as with a full synchronization. The\r\nclient should just make its database consistent with reported search results for any given DirSync call, that\r\nis, handle all incremental results as if they were the latest state. It does not matter whether you have seen\r\nthe change before or are even going back to a previous state because repeated incremental synchronizations\r\nwill converge on consistency.\r\nIt is also possible the other DC rejects the cookie returned from the original DC. The search generates an\r\nLDAP error on the server like \"0000203D: LdapErr: DSID-xxxxxxxx, comment: Error processing control,\r\ndata 0\", and the client application may generate an error such as\r\n\"System.DirectoryServices.Protocols.DirectoryOperationException: A protocol error occurred.\" This may\r\nhappen, for example, when the cookie is older, and the internal contents of the cookie are expected to be\r\ndifferent when processed by an LDAP server running a different version of Windows. The cookie is an\r\nopaque structure and is not guaranteed to be structurally consistent among all Windows OS versions. The\r\nclient application should handle this case and retry with a full sync if this error is encountered.\r\nWhen an object is renamed or moved, its child objects, if any, are not included in the search results, even\r\nthough the distinguished names of the child objects have changed. Similarly, when an inheritable ACE is\r\nmodified in an object security-descriptor, the child objects of the object are not included in the search\r\nresults, even though the security-descriptors of the child objects have changed.\r\nUse the objectGUID attribute to identify the tracked objects. The objectGUID of each object remains\r\nunchanged regardless of where the object is moved within the forest.\r\nBe aware that the search results of a DirSync search indicate the state of the objects on a replica of the\r\ndirectory partition at the time of the search. This means that changes made on other DCs will not be\r\nincluded if they have not been replicated to the target DC. It also means that an object's attributes may have\r\nchanged several times since the previous DirSync search, but the search will show only the final state, not\r\nthe sequence of changes.\r\nhttps://msdn.microsoft.com/en-us/library/ms677626.aspx\r\nPage 2 of 4\n\nIn the ADSI implementation, the application must handle the cookie as opaque and not make any\r\nassumptions about its internal organization or value.\r\nBe aware that the client stores the cookie, cookie length, and DNS name of the DC in the same storage that\r\ncontains the synchronized object data. This ensures that the cookie and other parameters remain in sync\r\nwith the object data if the storage is ever restored from a backup.\r\nTo retrieve the parentGUID attribute, which is constructed for the DirSync control, it is also necessary to\r\nrequest the name attribute.\r\nTo use the DirSync control, caller must have the \"directory get changes\" right assigned on the root of the partition\r\nbeing monitored. By default, this right is assigned to the Administrator and LocalSystem accounts on domain\r\ncontrollers. The caller must also have the DS-Replication-Get-Changes extended control access right. For more\r\ninformation about implementing a change-tracking mechanism for applications that must run under an account\r\nthat does not have this right, see Polling for Changes Using USNChanged. For more information about privileges,\r\nsee Privileges.\r\nRetrieving Deleted Objects With a DirSync Search\r\nThe ADS_SEARCHPREF_DIRSYNC search results automatically include deleted objects (tombstones) that\r\nmatch the specified search filter. However, a search filter that will match an object when it is live may not match\r\nthe object after it is deleted. This is because tombstones retain only a subset of the attributes present on the\r\noriginal object. For example, you would typically use the following filter for user objects.\r\n(\u0026(objectClass=user)(objectCategory=person))\r\nThe objectCategory attribute is removed when an object is deleted, so the filter above would not match any\r\ntombstone objects. Conversely, the objectClass attribute is retained on tombstone objects, so a filter of \"\r\n(objectClass=user)\" would match deleted user objects.\r\nThe attribute list that you specify with a DirSync search also acts as a filter; search results include only objects on\r\nwhich one or more of the specified attributes have changed since the previous DirSync search. If the attribute list\r\ndoes not include any attributes that are retained on tombstones, the search results will not include tombstones. To\r\nhandle this, request all attributes by specifying a null attribute list; or you can request the isDeleted attribute, set to\r\nTRUE on all tombstones. Tombstone attributes have the 0x8 bit set in the searchFlags attribute of the\r\nattributeSchema definition.\r\nFor more information, see Retrieving Deleted Objects.\r\nLDAP Implementation of the DirSync Control\r\nYou can also perform a DirSync search by using the LDAP API with the LDAP_SERVER_DIRSYNC_OID\r\ncontrol. If you use the LDAP API, also specify the LDAP_SERVER_EXTENDED_DN_OID and\r\nLDAP_SERVER_SHOW_DELETED_OID controls. The LDAP_SERVER_EXTENDED_DN_OID control\r\ncauses an LDAP search to return an extended form of the distinguished name that includes the objectGUID and\r\nhttps://msdn.microsoft.com/en-us/library/ms677626.aspx\r\nPage 3 of 4\n\nobjectSID for security principal objects such as users, groups, and computers. The\r\nLDAP_SERVER_SHOW_DELETED_OID control causes the search results to include data for deleted objects.\r\nBe aware that these controls are automatically included in the ADSI implementation.\r\nSource: https://msdn.microsoft.com/en-us/library/ms677626.aspx\r\nhttps://msdn.microsoft.com/en-us/library/ms677626.aspx\r\nPage 4 of 4",
	"extraction_quality": 1,
	"language": "EN",
	"sources": [
		"MITRE"
	],
	"references": [
		"https://msdn.microsoft.com/en-us/library/ms677626.aspx"
	],
	"report_names": [
		"ms677626.aspx"
	],
	"threat_actors": [],
	"ts_created_at": 1775434914,
	"ts_updated_at": 1775791277,
	"ts_creation_date": 0,
	"ts_modification_date": 0,
	"files": {
		"pdf": "https://archive.orkl.eu/73d2e61f11742fe502051b2b024e3a95f1a86a5a.pdf",
		"text": "https://archive.orkl.eu/73d2e61f11742fe502051b2b024e3a95f1a86a5a.txt",
		"img": "https://archive.orkl.eu/73d2e61f11742fe502051b2b024e3a95f1a86a5a.jpg"
	}
}