Creating workflows for Microsoft Defender assets

Let Oomnitza be your single source of truth!

You'll get visibility of your assets as data from Microsoft Defender is automatically transformed into consumable information and actionable insights.

Connect Oomnitza and Microsoft Defender in minutes

You'll get visibility of your Microsoft Defender assets by creating configurable workflows to automate tasks such as:

• • Getting general machine information, including installed software, OS, last activity, and status.
  • Offboarding machines from Microsoft, isolating machines, and restricting the execution of all applications on a device.
  • Managing device security including getting the device vulnerabilities, device alerts, security recommendations and remotely triggering full or quick anti-virus updates.

Navigation

Before you start

Creating workflows

Create asset workflows

Before you start

Before you can create the integration with Oomnitza, you need to have completed the following steps:

1. Generated your credentials in Azure
2. Added your credentials to Oomnitza
3. Added a Microsoft Defender domain as a global variable (recommended)
4. Created an extended integration for Microsoft Defender assets. 

Creating workflows

Create asset workflows

To create an asset workflow, you must complete these steps:  

1. Click Configuration > Workflows 
2. Click Add (+) and select Assets from the list.
3. Edit the Begin Block and add rules to trigger the workflow. For example, if you set the  Actions to New, the workflow will run for every new asset record added to Oomnitza.
4. Drag and drop the API block onto the Sandbox.
5. Click Edit on the API block and enter Microsoft Defender in the search field. 
6. Select a preset from the list below. To choose a preset, click the forward arrow (>).
   
   • Microsoft Defender Add Machine Tag
   • Microsoft Defender Get Asset Details
   • Microsoft Defender Get Machine Alerts
   • Microsoft Defender Get Machine Software
   • Microsoft Defender Get Missing KBs
   • Microsoft Defender Get Security Recommendations
   • Microsoft Defender Get Vulnerabilities
   • Microsoft Defender Isolate Machine
   • Microsoft Defender Offboard Machine
   • Microsoft Defender Remove Machine Tag
   • Microsoft Defender Restrict App Execution
   • Microsoft Defender Run Antivirus Scan
   • Microsoft Defender Set Device Value
   • Microsoft Defender Unisolate Machine
   • Microsoft Defender Unrestrict App Execution
7. Select your Microsoft credentials from the list. 
8. Enter any mandatory information when prompted. 
9. Select Advanced Mode.
10. Select the Information tab. Ensure that the property {{microsoft_defender_device_id}}, exists in Oomnitza and is populated with information before you run this workflow. You can create an asset integration to retrieve this information before you run this workflow.
11. Select the Response tab. You can map the entire response by placing {{response}} in the Response field and mapping it to a custom long text Oomnitza field, such as API Response. Once you have the entire response, you can then parse the JSON response values to custom Oomnitza fields, as per the example below.
12. Connect the Blocks. 
13. Save, validate, and activate your workflow.

Fig: Mapping the Microsoft Defender Get Asset Details response.

Using the Microsoft Defender Add Machine Tag preset

The Microsoft Defender Add Machine Tag preset adds a tag to a specific Machine.

The machine to be updated is referenced in the Advanced Mode > Information tab in the property{{microsoft_defender_device_id}}.

Note
This workflow requires theMachine.Read.Writepermissions. You must have the Manage Security Setting role permission to run this workflow. For further information, see Microsoft Defender API Documentation: Add or remove machine tags API.

Using the Microsoft Defender Get Asset Details preset

The Microsoft Defender Get Asset Details preset gets the details of a machine, by Device ID.

The machine to be retrieved is referenced in the Advanced Mode > Information tab in the property{{microsoft_defender_device_id}}.

Note
This workflow requires theMachine.Read.Writepermissions. You must have the View Data role permission to run this workflow. For further information, see Microsoft Defender API Documentation: Get machine by ID API.

Using the Microsoft Defender Get Machine Alerts preset

The Microsoft Defender Get Machine Alerts preset retrieves all Alerts related to a specific machine, by Device ID.

The machine to be retrieved is referenced in the Advanced Mode > Information tab in the property{{microsoft_defender_device_id}}.

Note
This workflow requires theMachine.Read.Writepermissions. You must have the View Data role permission to run this workflow. For further information, see Microsoft Defender API Documentation: Get machine related alerts API.

Using the Microsoft Defender Get Machine Software preset

The Microsoft Defender Get Machine Software preset retrieves a collection of installed software related to a given Device ID.

The machine to be retrieved is referenced in the Advanced Mode > Information tab in the property{{microsoft_defender_device_id}}.

Note
This workflow requires Software.Readpermissions. For further information, see Microsoft Defender API Documentation: Get installed software.

Using the Microsoft Defender Get Missing KBs preset

The Microsoft Defender Get Missing KBs preset retrieves missing KBs (security updates) by Device ID.

The machine to be retrieved is referenced in the Advanced Mode > Information tab in the property{{microsoft_defender_device_id}}.

Note
This workflow requiresSoftware.Read.Allpermissions. For further information, see Microsoft Defender API Documentation: Get missing KBs by device ID.

Using the Microsoft Defender Get Security Recommendations preset

The Microsoft Defender Get Security Recommendations preset retrieves a collection of security recommendations related to a given device ID.

The machine to be retrieved is referenced in the Advanced Mode > Information tab in the property{{microsoft_defender_device_id}}.

Note
This workflow requiresSecurityRecommendation.Readpermissions. For further information, see Microsoft Defender API Documentation: Get security recommendations.

Using the Microsoft Defender Get Vulnerabilities preset

The Microsoft Defender Get Vulnerabilities preset retrieves a collection of discovered vulnerabilities related to a given Device ID.

The machine to be retrieved is referenced in the Advanced Mode > Information tab in the property{{microsoft_defender_device_id}}.

Note
This workflow requires Vulnerability.Readpermissions. For further information, see Microsoft Defender API Documentation: Get discovered vulnerabilities.

Using the Microsoft Defender Isolate Machine preset

The Microsoft Defender Isolate Machine preset isolates a device from accessing external network. When you select this preset, you need to specify an Isolation Type. The permitted values are Full or Selective. You also need to supply a comment to associate with the action such as: Isolate machine due to alert 1234.

Full isolation is available for devices on Windows 10, version 1703, and on Windows 11. Selective isolation is available for devices on Windows 10, version 1709 or later, and on Windows 11.

The machine to be retrieved is referenced in the Advanced Mode > Information tab in the property{{microsoft_defender_device_id}}.

Note
This workflow requires Machine.Isolatepermissions. You must have the Active remediation actions role permission to run this workflow

Important
Consult the API documentation regarding the limitations of using this API. In addition to the Windows limitations mentioned above, isolated devices that are behind a full VPN tunnel won't be able to reach the Microsoft Defender for Endpoint cloud service after the device is isolated. For further information, see Microsoft Defender API Documentation: Isolate machine API.

Using the Microsoft Defender Offboard Machine preset

The Microsoft Defender Offboard Machine preset offboards a device from Defender for Endpoint. When you select this preset, you need to supply a comment to associate with the action.

The machine to be offboarded is referenced in the Advanced Mode > Information tab in the property{{microsoft_defender_device_id}}.

Note
This workflow requiresMachine.Offboardpermissions. You must have the Global Admin role permission to run this workflow.

Important
This API is supported on Windows 11, Windows 10, version 1703 and later, or Windows Server 2019 and later. It is not supported on MacOS or Linux devices. For further information, see Microsoft Defender API Documentation: Offboard machine API.

Using the Microsoft Defender Remove Machine Tag preset

The Microsoft Defender Remove Machine Tag preset removes a tag from a specific Machine.

The machine to be updated is referenced in the Advanced Mode > Information tab in the property{{microsoft_defender_device_id}}.

Note
This workflow requires Machine.Read.Writepermissions. You must have the Manage Security Setting role permission to run this workflow. For further information, see Microsoft Defender API Documentation: Add or remove machine tags API.

Using the Microsoft Defender Restrict App Execution preset

The Microsoft Defender Restrict App Execution preset restricts the execution of all applications on the device except a predefined set. When you select this preset, you need to supply a comment to associate with the action.

The machine to be restricted is referenced in the Advanced Mode > Information tab in the property{{microsoft_defender_device_id}}.

Note
This workflow requires Machine.RestrictExecutionpermissions. You must have the Active remediation actions role permission to run this workflow

Important
This action is available for devices on Windows 10, version 1709 or later, and on Windows 11. This feature is available if your organization uses Microsoft Defender Antivirus. For further information, see Microsoft Defender API Documentation: Restrict app execution API.

Using the Microsoft Defender Run Antivirus Scan preset

The Microsoft Defender Run Antivirus Scan preset initiates a Microsoft Defender Antivirus scan on a device. When you select this preset, you need to specify an Scan Type. The permitted values are Quick or Full.

The machine to be scanned is referenced in the Advanced Mode > Information tab in the property{{microsoft_defender_device_id}}.

Note
This workflow requires Machine.Scanpermissions. You must have the Active remediation actions role permission to run this workflow

Important
This API is supported on Windows 10, version 1709 or later, and on Windows 11 devices. For further information, see Microsoft Defender API Documentation: Run antivirus scan API.

Using the Microsoft Defender Set Device Value preset

The Microsoft Defender Set Device Value preset sets the device value of a specific Machine. When you select this preset, you need to specify a Device Value. The permitted values are Normal, Low or High.

The machine to be configured is referenced in the Advanced Mode > Information tab in the property{{microsoft_defender_device_id}}.

Note
This workflow requires Machine.Read.Writepermissions. You must have the Manage Security Setting role permission to run this workflow. For further information, see Microsoft Defender API Documentation: Set device value API.

Using the Microsoft Defender Unisolate Machine preset

The Microsoft Defender Unisolate Machine preset undos the isolation of a device. When you select this preset, you need to supply a comment to associate with the action.

The machine to be unisolated is referenced in the Advanced Mode > Information tab in the property{{microsoft_defender_device_id}}.

Note
This workflow requiresMachine.Isolatepermissions. You must have the Active remediation actions role permission to run this workflow.

For further information, see Microsoft Defender API Documentation: Release device from isolation API.

Using the Microsoft Defender Unrestrict App Execution preset

The Microsoft Defender Unrestrict App Execution preset enables the execution of any application on the device. When you select this preset, you need to supply a comment to associate with the action.

The machine to be unrestricted is referenced in the Advanced Mode > Information tab in the property{{microsoft_defender_device_id}}.

Note
This workflow requiresMachine.RestrictExecutionpermissions. You must have the Active remediation actions role permission to run this workflow.

For further information, see Microsoft Defender API Documentation: Remove app restriction API.

Reference articles for workflows

• Mapping positive and negative responses
• Troubleshooting workflows 
• Using the API block