Defender MpScanStart and proof of exact-file inspection and scan settlement

Jeremiah ‎DiPilato 0 Reputation points
2026-11-19T22:30:22.3233333+00:00

For an unelevated Windows desktop application scanning one harmless staged local file with Microsoft Defender Antivirus, is there a supported API or event that establishes which file revision was inspected and whether inspection was complete or the item was skipped, excluded, served from cache or partially inspected?

The published MpScanStart, MPRESOURCE_INFO and MPSCAN_DATA contracts describe initiation or synchronous return, a resource path and cumulative statistics. Which supported result fields, if any, establish the exact inspected revision and whether Defender acted on it?

After synchronous return or an exact asynchronous MpScanControl abort, which supported result establishes that the operation is terminal, no callbacks can follow, and the provider released the file? Is there a documented start-acceptance deadline or settlement rule after caller or service termination? If no supported public interface establishes those facts, please confirm which guarantees are unavailable.

Windows development | Windows API - Win32
0 comments No comments

2 answers

Sort by: Most helpful
  1. Gatlin Le (WICLOUD CORPORATION) 1,475 Reputation points Microsoft External Staff Moderator
    2026-11-20T03:57:22.5833333+00:00

    Hi @Jeremiah ‎DiPilato ,

    Based on the published documentation, neither the Defender client API nor the documented Defender event log provides the guarantees you are looking for. What the documentation does give you is threat-level information for a scan. It does not give you a per-file inspection receipt.

    The MpScanStart reference says the returned handle can be used to retrieve a scan result, and the documented way to do that is MpThreatOpen function (MpClient.h) - Win32 apps | Microsoft Learn with MPTHREAT_SOURCE_SCAN, which enumerates the threats associated with a specific scan handle. The reference describes that handle as a handle to a completed scan operation, so the documentation does not say whether this works for a scan that was aborted. Each entry returned by MpThreatEnumerate is an MPTHREAT_INFO structure (MpClient.h) - Win32 apps | Microsoft Learn structure. Its ThreatStatus member reports states such as detected, cleaned, or quarantined, its ResourceList member lists the resources identified with the threat, and RemediationResourceList lists the resources that failed during remediation. Those resources are MPRESOURCE_INFO entries, which identify files by path, so even when Defender did act on a file, the result is not tied to a particular revision of it. If the first call to MpThreatEnumerate returns S_FALSE, the enumeration is simply empty, and I could not find any statement that this means the file was fully inspected and found clean rather than skipped, excluded, served from cache, or partially inspected.

    The documented events do not close that gap either. In the Microsoft Defender Antivirus event IDs and error codes - Microsoft Defender for Endpoint | Microsoft Learn reference, scan events such as 1000 describe the scan ID, type, parameters, and scanned resources. Detection events such as 1116 describe the threat, the file path, the detection source, and the signature and engine versions. The event log does include content hashes in limited cases, for example event 1120, which records hashes for a threat resource, but the reference says it is logged only when the ThreatFileHashLogging policy is set, and it applies to threat resources rather than to a file that was found clean. I could not find a documented field in these events that records a per-file inspection outcome, and I could not find documentation stating that the scan ID in these events corresponds to any value obtained from an MpScanStart handle.

    On settlement, the MpScanControl reference describes control only for asynchronous scans, since its handle parameter is defined as a handle to an asynchronous scan operation. For a synchronous scan, the documentation only says that MpScanStart returns after the scan is finished. It does not describe that return as a point after which no callbacks can run or after which the file has been released.

    To answer your last question directly, the published documentation does not establish any revision identity for the bytes that were inspected. It does not provide a per-file inspection disposition through the API or the event log, and it does not define a terminal state that guarantees no further callbacks after synchronous return or after an abort on an asynchronous scan. I also could not find any statement that the provider has released the file at a given point, any deadline for a scan to be accepted and started, or any settlement rule that applies when the calling process or the Defender service terminates. Behavior observed beyond that on a particular build would be an implementation detail rather than a supported contract.

    I hope the references above help clarify what the public documentation does and does not commit to, and make it easier to decide how to approach the remaining points in your design. If you feel the information has helped you move forward, you are welcome to follow this guide when convenient, as it can help others with the same question find it more easily. If you later come across additional documentation on any of these points, you are always welcome to share it here as well.

    Thank you.

    Was this answer helpful?

    0 comments No comments

  2. AI answer

    2026-11-19T22:31:26.2833333+00:00

    No supported public Defender Win32 field or event documented here proves that a particular file revision was fully inspected, records a per-file skipped/excluded/cached/partial disposition, or guarantees callback and file-handle settlement after return or abort.

    What the public contracts establish

    • A resource scan identifies its input by Scheme and absolute Path. MPRESOURCE_INFO has no file ID, content hash, size, last-write time, USN, or other revision identifier. Its Class member classifies a resource associated with a threat; it is not an inspection disposition. ^1^
    • MPSCAN_DATA contains the scan type, optional resource information, cumulative resource statistics, and cumulative threat statistics. It has no per-file revision or outcome field. ^2^
    • MPRESOURCE_STATS reports aggregate counts—files, bytes, processes, registry keys—and approximate overall progress. Those counters cannot establish that the one named file, or a particular revision of it, supplied the increment. ^3^
    • Callback data adds a notification type, timestamp, failure HRESULT, and type-dependent payload. It does not add a content identity or per-file disposition. ^4^

    Consequently, none of these outcomes has a documented per-file proof field:

    • fully inspected;
    • skipped or only partially inspected;
    • excluded;
    • satisfied from cache;
    • inspected bytes matching the revision staged by the caller.

    MPNOTIFY_SCAN_ERROR can report an error for a specific resource, and MPNOTIFY_SCAN_INFECTED can identify an infected resource. The documentation also notes that an infected indication might not become a final threat because of exclusions. Neither notification provides a general “clean and fully inspected” receipt. ^5^

    Completion versus settlement

    For a synchronous scan, the documented behavior is that MpScanStart returns only after the scan is finished. For an asynchronous scan, it returns immediately after successful initiation. The callback set includes MPNOTIFY_SCAN_START, MPNOTIFY_SCAN_COMPLETE, MPNOTIFY_SCAN_CANCEL, resource errors, and internal failure. ^5^

    Those contracts do not document that:

    • synchronous return is a callback-drain barrier;
    • MPNOTIFY_SCAN_COMPLETE or MPNOTIFY_SCAN_CANCEL must be the final callback;
    • no callback can already be queued or execute concurrently afterward;
    • callback context is no longer in use when the API returns;
    • Defender has released every underlying file object or section;
    • the file can immediately be replaced, deleted, or exclusively reopened.

    For an asynchronous scan, MpScanControl(handle, MPCONTROL_ABORT) requests that the scan be aborted. S_OK means the control call succeeded; the contract does not define it as a synchronous cancellation-and-drain acknowledgment. It provides no timeout, terminal-state query, or callback-settlement rule. ^6^

    MpHandleClose only documents closing the scan handle. It does not state that closure waits for provider work, drains callbacks, or releases the scanned file. ^7^

    Therefore, callback-owned state cannot safely be freed merely on the assumption that abort success, synchronous return, or handle closure is a documented callback fence. Any stronger behavior observed experimentally remains an implementation observation, not a public API guarantee.

    MPSCAN_RESULT does not supply the missing proof

    MPSCAN_RESULT records scan-level metadata: scan type/source, GUID, start and end times, aggregate threat/resource statistics, and signature version. It contains neither the scanned path nor an exact-file identity or per-file disposition. ^8^

    MPSTATUS_INFO exposes the last quick- and full-scan results, but that does not correlate an individual resource revision with an inspection result. ^9^

    Although MpScanStart says its returned handle can be used in later calls “such as to retrieve a scan result,” the published public function index shown here does not identify a scan-handle result-retrieval function. The documented functions include start, control, status, threat enumeration, and handle close, but no public call that converts a resource-scan handle into stronger per-file evidence. ^10^

    Deadlines and process/service termination

    The public contracts cited above specify no:

    • deadline from S_OK initiation to MPNOTIFY_SCAN_START;
    • maximum resource-scan duration;
    • grace or settlement period following abort;
    • callback behavior after caller termination;
    • settlement guarantee after Defender service termination or restart;
    • deadline by which file resources must be released.

    The documented one-day and seven-day limits apply to particular scheduled or MpCmdRun quick/full scans. They do not establish a deadline for a resource scan started through this API and should not be applied to this case. ^11^

    If an application requires auditable proof for immutable bytes, a separate application-level protocol is necessary: preserve or snapshot the input revision, calculate its identity independently, and treat Defender’s result only as a scan-level signal. The available public Defender interface cannot bind that identity to a documented “fully inspected” disposition or provide the requested settlement fence.


    References

    1. MPRESOURCE_INFO structure
    2. MPSCAN_DATA structure
    3. MPRESOURCE_STATS structure
    4. MPCALLBACK_DATA structure
    5. MpScanStart function
    6. MpScanControl function
    7. MpHandleClose function
    8. MPSCAN_RESULT structure
    9. MPSTATUS_INFO structure
    10. Windows Defender Functions
    11. Troubleshoot Microsoft Defender Antivirus scan issues
    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.