Blog Post

Microsoft Defender for Endpoint Blog
3 MIN READ

Automated machine tagging in just a few simple steps...

Tomer Brand's avatar
Tomer Brand
Icon for Microsoft rankMicrosoft
Jan 06, 2019

...or how simple it is to use the Windows Defender ATP APIs

 

The new year offers a (somewhat) fresh start, giving us the opportunity to reflect on the past year about the good things, how could we have done better, and how new insights can carry over as resolutions for the coming year. In the world of security operations, particularly triage and prioritization, we might ask ourselves two key questions:

  • Are all machines created equal?
  • And what about users, should security operations center (SOC) analysts treat them all the same?

If you answered any of these questions with a “no”, then this blog post is for you! And even if you have answered “yes”, we still recommend you continue reading—it might help you spark some new and innovative ideas.

 

SOC life in a world of tags

Imagine a world where your machines are all tagged with unique attributes:

  • Functional or task-oriented tags: accounting, finance devices, network edge servers, kiosk, shared machine, reception desk
  • Ownership tags: Red team (i.e., “No need to panic. John is testing his tool… again.”), C-level (i.e., “It is the right time to start panicking!”)

With all machines tagged, your SOC analyst can triage alerts more efficiently. Proactive threat hunting can be more focused and can be done with fewer, simpler steps.

All this goodness is now possible with Windows Defender ATP APIs and you certainly don’t need to be a top-notch developer to get this done!

 

Step 1: Find C-level machines

Let’s identify the machines owned by your CEO and other C-level users.

You can always do this by integrating with an external system that manages your assets. But a simpler way would be to check where your C-level users are active by running the following query on Windows Defender ATP advanced hunting:

 

DeviceLogonEvents
| where Timestamp > ago(7d)
| where LogonType in ("Interactive", "RemoteInteractive", "CachedInteractive","CachedRemoteInteractive")
| summarize InteractiveLoginCount = count(LogonType) by DeviceId, DeviceName, AccountName
| where InteractiveLoginCount > 0
| summarize (InteractiveLoginCount, AccountName) = argmax(InteractiveLoginCount, AccountName) by DeviceId, DeviceName
| where AccountName in ("CEO-user", "CFO-user", "CTO-user") // Replace these with values relevant to your org :smiling_face_with_smiling_eyes:
| distinct DeviceId

 

Try running the query to validate it. Once validated, you now have a quick and easy way to identify the C-level machines. Let’s see how we can use this further.

 

Step 2: Automate machine finding

Let’s automate the finding and tagging of C-level machines. For this blog, we’ll use Microsoft Flow to talk to the APIs, but do note that you can get similar results with other tools like Logic Apps.

 

Create a new flow

Sign in to Microsoft Flow and create a new flow from blank. We will walk you through configuring the flow so that it automatically runs the advanced hunting query and tags the machines returned by the query.

  

     

Define the trigger

Use the built-in Recurrence trigger to set the flow to run at regular intervals.

   

    

 

Set the flow to run every Sunday, ensuring new C-level machines are tagged weekly.

   

    

 

 

Add “Advance Hunting” as the first action

To keep things simple, we’ve provided a dedicated action type for advanced hunting. Add this as the first action of your flow.

   

    

Paste the query you have validated in step 1.

   

    

 

 Add “Tag Machine” as the second action

   

       

 

For ID of the machine, use dynamic content MachineID as shown below. Specify your preferred tag (in this example, we use “Executive”) and set the action to Add.

   

      

Step 3 — Test your flow

Before running a test, ensure your flow has the three steps shown below and click Save.

 

    

     

 

When ready, simply click Test to trigger the flow. Select I’ll perform the trigger action when prompted.

  

     

 

After running the test, validate whether your tags have been applied. Go to the Windows Defender ATP portal and check for tags on one of your C-level machines.

 

And we are done!

Let’s summarize what we have learned:

  • We helped the SOC analyst in their alert triage process by adding organizational context and knowledge to the machines.
  • We scheduled a regular flow that keeps the tags in sync automatically.
  • We learned how easy it is to leverage Windows Defender ATP APIs and achieve more.

Would you like to share an example or two describing your own experiences applying the Windows Defender ATP APIs?

Don’t be shy. Send us a smiley face feedback via the portal, and we’ll take care of the rest!

 

 

  

Thank you!

Windows Defender ATP team

Updated Jun 17, 2020
Version 5.0
  • hippyjm's avatar
    hippyjm
    Copper Contributor

    Is there a way that we can take the property from device primary user in intune. Wanting to ensure its not taking admin accounts or anything its not. 

  • gd2020's avatar
    gd2020
    Copper Contributor

    How do i just change this to just user devices ? 

    where AccountName in ("CEO-user", "CFO-user", "CTO-user") // Replace these with values relevant to your org :smiling_face_with_smiling_eyes:

  • mdgary's avatar
    mdgary
    Copper Contributor

    Tomer Brand do you know if there will be a Flow Connector to allow hunting activities from security.microsoft.com similar to the MD ATP Flow connector? This would probably make more sense than connecting the other service graph data to MD ATP portal as you've suggested.

     

    Hopefully I'm describing this correctly. Basically looking to expand on this capability with respect to hunt queries:

    https://docs.microsoft.com/en-us/windows/security/threat-protection/microsoft-defender-atp/api-microsoft-flow

     

    Michael

  • mdgary MDATP only holds device information,  the query you try to run belongs to M365 Defender. 

     

    Hunting activities are best done over security.microsoft.com 

  • mdgary's avatar
    mdgary
    Copper Contributor

    Will the new M365 schemas be available for use within the MD ATP premium connector in the future (or will this be a separate connector)? I've successfully completed the queries above using the "DeviceLogonEvents" queries but the search fails when using something from the "IdentityInfo" schema.

     

    Effectively trying to use a query from a hunt here: https://security.microsoft.com/hunting

    Instead of here: https://securitycenter.windows.com/hunting

     

    I understand this may have to do with the way the data is managed on the backend.

  • sunshineaugie's avatar
    sunshineaugie
    Copper Contributor

    Does anyone have any updates to the query?  It looks like the syntax may have changed.  I keep getting errors or no results.  

    • Brent Morris's avatar
      Brent Morris
      Brass Contributor

      Please comment if it was Hard or Easy to do? -Thanks

      • Kristin_Burke's avatar
        Kristin_Burke
        Icon for Microsoft rankMicrosoft

        Easy! and i now have it set up to run to tag any new machines with the same domain weekly!

  • MarkinhusZN's avatar
    MarkinhusZN
    Copper Contributor
    Got a question regarding the Advanced Hunting, Can I see the User Type mentioned in the ATP when doing a query on advanced hunting? If so, where? because I can't for the life of me find the User Type category. I am trying to find users with local admins rights and their machine name.
    • Tomer Brand's avatar
      Tomer Brand
      Icon for Microsoft rankMicrosoft
      Hi, the admin / regular user flag is indeed not yet exposed in the hunting scheme.
      Please submit a feedback via the portal - we will follow up with you on the topic.

      Thanks,
      Tomer