No documented Defender MpClient.dll API provides the complete guarantee requested: MpScanStart can identify a scan operation and report aggregate completion, but it does not bind that result to an immutable file revision, attest that every byte or archive member was inspected, or signal that all callbacks and engine references have drained.
What MpScanStart actually guarantees
For a resource scan, the caller supplies one or more MPRESOURCE_INFO entries. A file resource contains an absolute path, not a file handle, file ID, version token, hash, USN, or content snapshot. Therefore, the public contract does not establish which revision of a changing path was inspected. ^1^ ^2^
The scan handle identifies the initiated operation. Its MPSCAN_RESULT contains:
-
ScanGuid - scan start and end times
- threat and resource statistics
- signature version
It has no per-resource revision identifier, completeness flag, skip reason, remediation record, archive-member list, or “callbacks drained” field. ^3^
Likewise, MPSCAN_DATA contains resource information plus cumulative resource and threat statistics. MPRESOURCE_STATS.FileCount and FileBytesCount are counts, not proof that a particular revision or every byte/member was inspected. ^4^ ^5^
MPNOTIFY_SCAN_COMPLETE establishes completion of the scan operation. Other notifications distinguish cancellation, per-resource errors, infection, and internal failure, but the callback payload still exposes no revision or full-inspection attestation. ^6^ ^7^
The performance analyzer’s SkipReason values—Not Skipped, Optimization, and User skipped—belong to performance-report output. They are not documented as fields in the MpScanStart callback or result contract. ^8^
Archives and the 512-MiB requirement
MPSCAN_OPTION_ARCHIVES requests scanning of archive contents, but the API documentation does not promise enumeration or successful inspection of every member. ^6^
Archive processing is also policy-dependent:
- Archive scanning can be enabled or disabled.
- Maximum extraction depth can be configured.
- Maximum archive size can be configured.
- The defaults are no depth limit and no archive-size limit. ^9^
Thus, a 512-MiB archive is not inherently excluded by the documented default, but neither its size nor a successful completion notification proves that every member received a full inspection.
Start timing and callback/resource lifetime
The public contract documents no maximum latency for successful start acceptance:
- Asynchronous
MpScanStartreturns after successful initiation. - Synchronous
MpScanStartreturns after the scan finishes. - Success is
S_OK; failure is anHRESULT.
No upper time bound is specified. ^6^
For asynchronous scans, MpScanControl(..., MPCONTROL_ABORT) requests abortion and returns an HRESULT; its documentation does not say that successful return is a callback-drain barrier. ^10^
Similarly, MpHandleClose closes the scan handle, but its contract does not state that it waits for in-flight callbacks, proves the final callback has returned, or confirms release of the scanned file/resource. ^11^ No documented signal covers client termination or service loss either.
Consequently, callback context and other callback-reachable storage should not be destroyed on an undocumented assumption that abort, completion notification, or handle close acts as a drain fence. A stronger lifecycle contract would require confirmation from Microsoft through a support case.
Supported alternative for exact submitted bytes
If the application needs a verdict on an immutable byte sequence under its control, use AmsiScanBuffer. It scans the supplied memory buffer and returns an AMSI_RESULT synchronously; contentName is descriptive and can identify the application’s revision. ^12^
AMSI_RESULT result{};
HRESULT hr = AmsiScanBuffer(
amsiContext,
bytes.data(),
static_cast<ULONG>(bytes.size()),
L"item-id:revision-id",
nullptr,
&result);
if (FAILED(hr))
return ScanFailed;
return AmsiResultIsMalware(result) ? Block : Allow;
This binds the verdict to the bytes supplied by the application and avoids an on-disk path-replacement race. It does not provide remediation, archive-member coverage, a full-file-inspection attestation, or Defender-specific provenance; AMSI is vendor-agnostic and returns whether the submitted content should be blocked. ^13^ ^14^
For strict archive assurance, the application must retain immutable input, parse the archive itself under its own size/depth policy, and submit each extracted member as a separate buffer. The available public contracts do not supply a single Defender attestation combining exact revision, complete recursive inspection, remediation completion, bounded acceptance time, and callback drainage.
References
- MPRESOURCE_INFO structure
- MPSCAN_RESOURCES structure
- MPSCAN_RESULT structure
- MPSCAN_DATA structure
- MPRESOURCE_STATS structure
- MpScanStart function
- MPCALLBACK_DATA structure
- Performance analyzer for Microsoft Defender Antivirus
- Configure Microsoft Defender Antivirus using Microsoft Intune
- MpScanControl function
- MpHandleClose function
- AmsiScanBuffer function (amsi.h)
- Antimalware Scan Interface (AMSI)
- AmsiResultIsMalware macro (amsi.h)