Which Defender API confirms inspection of a specific file revision and when callbacks have finished?

Jeremiah ‎DiPilato 0 Reputation points
2026-11-18T17:59:54.8133333+00:00

For Microsoft Defender Antivirus platform 4.18.26100.4-0, which supported local API can an unelevated Windows desktop app use to determine whether Defender inspected the exact file revision it submitted?

MpScanStart documents scan completion, MPSCAN_RESULT identifies the operation, and MPSCAN_DATA provides cumulative counts. The performance analyzer also documents SkipReason. Is there a supported field or combination that binds the result and any remediation to the exact retained file revision and distinguishes a full inspection from a skipped or partial inspection, including archive members in files up to 512 MiB?

Does the API guarantee a maximum time for successful start acceptance? After completion, an abort on the scan handle, or loss of the client or service, what documented signal establishes that the last callback has returned and the engine has released the resource? If these guarantees are unavailable, a supported alternative or a reference specifying those limits would help.

Windows development | Windows API - Win32
0 comments No comments

1 answer

Sort by: Newest
  1. AI answer

    2026-11-18T18:01:15.4+00:00

    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 MpScanStart returns after successful initiation.
    • Synchronous MpScanStart returns after the scan finishes.
    • Success is S_OK; failure is an HRESULT.

    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

    1. MPRESOURCE_INFO structure
    2. MPSCAN_RESOURCES structure
    3. MPSCAN_RESULT structure
    4. MPSCAN_DATA structure
    5. MPRESOURCE_STATS structure
    6. MpScanStart function
    7. MPCALLBACK_DATA structure
    8. Performance analyzer for Microsoft Defender Antivirus
    9. Configure Microsoft Defender Antivirus using Microsoft Intune
    10. MpScanControl function
    11. MpHandleClose function
    12. AmsiScanBuffer function (amsi.h)
    13. Antimalware Scan Interface (AMSI)
    14. AmsiResultIsMalware macro (amsi.h)
    AI-generated content may be incorrect. Read our transparency notes for more information.

    Was this answer helpful?

Your answer

Answers can be marked as 'Accepted' by the question author and 'Recommended' by moderators, which helps users know the answer solved the author's problem.