`client.machine_actions`¶

Inspect machine actions and trigger machine response operations.

Property¶

client.machine_actions

Methods¶

get_all(query: MachineActionsQuery | None = None) -> MachineActionsResults: list machine actions.
get(id: str) -> MachineActionsResults: fetch one machine action by ID.
getMachineActions(machine_id: str) -> MachineActionsResults: fetch machine actions for a specific machine.
latestMachineActions(machine_id: str) -> MachineActionsResults: fetch the latest machine actions for a machine.
availableMachineActions(id: str) -> ActionAvailabilityStatusResults: fetch available machine actions for a machine.
collectInvestigationPackage(device_id: str, payload) -> MachineActionsResults: collect an investigation package.
getPackage(id: str) -> str: return a package download URI for a completed investigation package action.
getLiveResponseResultDownloadLink(id: str, index: int = 0) -> str: return a live response result download URI.
isolate(device_id: str, payload) -> MachineActionsResults: isolate a machine.
unisolate(device_id: str, payload) -> MachineActionsResults: remove isolation.
restrictCodeExecution(device_id: str, payload) -> MachineActionsResults: restrict code execution.
unrestrictCodeExecution(device_id: str, payload) -> MachineActionsResults: remove code execution restrictions.
runAntiVirusScan(device_id: str, payload) -> MachineActionsResults: trigger an antivirus scan.
runLiveResponse(device_id: str, payload) -> MachineActionsResults: run a live response command.
offBoard(device_id: str, payload) -> MachineActionsResults: off-board a machine.
stopAndQuarantineFile(device_id: str, payload) -> MachineActionsResults: stop and quarantine a file.
cancel(id: str, payload) -> MachineActionsResults: cancel a machine action.

Notes¶

Most mutating methods return a MachineActionsResults wrapper rather than a boolean.
getPackage() and getLiveResponseResultDownloadLink() are the exceptions: they return temporary download URLs as strings.
The action methods delegate to machine-scoped paths under the hood, but the public entry point is client.machine_actions.

API¶

MachineActionsQuery ¶

Query parameters for the /api/machineactions endpoint.

MachineActionsResults ¶

MachineActionsResults(
    endpoint: BaseEndpoint,
    params: dict[str, str],
    *,
    path: str | None = None,
    single: bool = False,
    files: bool = False,
    method: str = "GET",
    request_kwargs: dict[str, Any] | None = None,
    use_concurrent_skip_pagination: bool | None = None,
    skip_page_size: int | None = None,
    skip_max_concurrent: int | None = None,
)

Results from the /api/machineactions endpoint.

ActionAvailabilityStatusResults ¶

ActionAvailabilityStatusResults(
    endpoint: BaseEndpoint,
    params: dict[str, str],
    *,
    path: str | None = None,
    single: bool = False,
    files: bool = False,
    method: str = "GET",
    request_kwargs: dict[str, Any] | None = None,
    use_concurrent_skip_pagination: bool | None = None,
    skip_page_size: int | None = None,
    skip_max_concurrent: int | None = None,
)

Results from the /api/machines/{id}/availableMachineActions endpoint.

MachineActionsEndpoint ¶

MachineActionsEndpoint(http: Client, auth: MSALAuth)

Endpoint for /api/machineactions

get_all ¶

get_all(
    query: MachineActionsQuery | None = None,
) -> MachineActionsResults

Get machine actions with optional filtering.

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/get-machineactions-collection

get ¶

get(id: str) -> MachineActionsResults

Get a specific machine action by ID.

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/get-machineaction-object

getMachineActions ¶

getMachineActions(machine_id: str) -> MachineActionsResults

Get machine actions for a specific machine.

Docs: Null (undocumented endpoint)

latestMachineActions ¶

latestMachineActions(
    machine_id: str,
) -> MachineActionsResults

Get the latest machine actions for a machine

Docs: Null (undocumented endpoint)

availableMachineActions ¶

availableMachineActions(
    id: str,
) -> ActionAvailabilityStatusResults

Get available machine actions for a machine

Docs: Null (undocumented endpoint)

collectInvestigationPackage ¶

collectInvestigationPackage(
    device_id: str,
    payload: CollectInvestigationPackagePayload,
) -> MachineActionsResults

Collect an investigation package from a machine.

If successful, this method returns 201 - Created response code and Machine Action in the response body. If a collection is already running, this returns 400 Bad Request.

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/collect-investigation-package

getPackage ¶

getPackage(id: str) -> str

Get the investigation package content.

If Successfull it'll return the URI to the package in the "value" parameter of the response.

If successful, this method returns 200, Ok response code with object that holds the link to the package in the "value" parameter. This link is valid for a short time and should be used immediately for downloading the package to a local storage. If the machine action for the collection exists but isn't complete, this returns 404 Not Found.

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/get-package-sas-uri

getLiveResponseResultDownloadLink ¶

getLiveResponseResultDownloadLink(
    id: str, index: int = 0
) -> str

Get the download link for live response result.

If successful, this method returns 200, Ok response code with object that holds the link to the command result in the value property. This link is valid for 30 minutes and should be used immediately for downloading the package to a local storage. An expired link can be re-created by another call, and there's no need to run live response again.

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/get-live-response-result

isolate ¶

isolate(
    device_id: str, payload: IsolatePayload
) -> MachineActionsResults

Isolate a machine.

If successful, this method returns 201 - Created response code and Machine Action in the response body. If the machine is already isolated, this returns 400 Bad Request.

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/isolate-machine

unisolate ¶

unisolate(
    device_id: str, payload: UnisolatePayload
) -> MachineActionsResults

Unisolate a machine.

If successful, this method returns 201 - Created response code and Machine Action in the response body. If the machine is not isolated, this returns 400 Bad Request.

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/unisolate-machine

restrictCodeExecution ¶

restrictCodeExecution(
    device_id: str, payload: RestrictCodeExecutionPayload
) -> MachineActionsResults

Restrict code execution on a machine.

If successful, this method returns 201 - Created response code and Machine Action in the response body. If code execution is already restricted, this returns 400 Bad Request.

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/restrict-code-execution

unrestrictCodeExecution ¶

unrestrictCodeExecution(
    device_id: str, payload: UnrestrictCodeExecutionPayload
) -> MachineActionsResults

Unrestrict code execution on a machine.

If successful, this method returns 201 - Created response code and Machine Action in the response body. If code execution is not restricted, this returns 400 Bad Request.

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/unrestrict-code-execution

runAntiVirusScan ¶

runAntiVirusScan(
    device_id: str, payload: RunAntiVirusScanPayload
) -> MachineActionsResults

Run an antivirus scan on a machine.

If successful, this method returns 201 - Created response code and Machine Action in the response body. If an antivirus scan is already running, this returns 400 Bad Request.

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/run-av-scan

runLiveResponse ¶

runLiveResponse(
    device_id: str, payload: RunLiveResponsePayload
) -> MachineActionsResults

Run a live response command on a machine.

If successful, this method returns 201 - Created response code and Machine Action in the response body. If a live response command is already running, this returns 400 Bad Request.

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/run-live-response

offBoard ¶

offBoard(
    device_id: str, payload: OffBoardPayload
) -> MachineActionsResults

Off-board a machine.

If successful, this method returns 201 - Created response code and Machine Action in the response body. If the machine is already off-boarded, this returns 400 Bad Request.

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/offboard-machine-api

stopAndQuarantineFile ¶

stopAndQuarantineFile(
    device_id: str, payload: StopAndQuarantineFilePayload
) -> MachineActionsResults

Stop and quarantine a file on a machine.

If successful, this method returns 201 - Created response code and Machine Action in the response body. If the file is already quarantined, this returns 400 Bad Request.

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/stop-and-quarantine-file

cancel ¶

cancel(
    id: str, payload: CancelPayload
) -> MachineActionsResults

Cancel a machine action.

If successful, this method returns 200, OK response code with a Machine Action entity.

If machine action entity with the specified id wasn't found - 404 Not Found.

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/cancel-machine-action

client.machine_actions¶

Property¶

Methods¶

Notes¶

API¶

MachineActionsQuery ¶

MachineActionsResults ¶

ActionAvailabilityStatusResults ¶

MachineActionsEndpoint ¶

get_all ¶

get ¶

getMachineActions ¶

latestMachineActions ¶

availableMachineActions ¶

collectInvestigationPackage ¶

getPackage ¶

getLiveResponseResultDownloadLink ¶

isolate ¶

unisolate ¶

restrictCodeExecution ¶

unrestrictCodeExecution ¶

runAntiVirusScan ¶

runLiveResponse ¶

offBoard ¶

stopAndQuarantineFile ¶

cancel ¶

`client.machine_actions`¶