alexverboon / psmdatp Goto Github PK

View Code? Open in Web Editor NEW

67.0 6.0 16.0 254 KB

PowerShell Module for managing Microsoft Defender Advanced Threat Protection

License: MIT License

PowerShell 100.00%

powershell mdatp security automation defenderatp

psmdatp's Introduction

Microsoft Defender for Endpoint PowerShell Module

Welcome to the Microsoft Defender for Endpoint PowerShell module!

This module is a collection of easy-to-use cmdlets and functions designed to make it easy to interface with the Microsoft Defender for Endpoint API.

Motivation

I created this PowerShell module for MDATP for the following reasons:

Advance my PowerShell skills
Provide an easy way to interact with MDE through PowerShell because I prefer automation over manual tasks

Prerequisites

Windows PowerShell 5.1 (Testing for PowerShell 7 is in progress)
have configured authorization for access by registering an application in AzureAD

App Permissions

Below is an example of the App Permissions that you must grant. I will provide more details soon about the individual cmdlets and the permissions required

Getting Started

To get started with the module, open your PowerShell terminal and install the module from the PSGallery by running this simple command:

Install-Module PSMDATP -Scope CurrentUser

App Registration

Initial Configuration

When you have installed the module and registered the App in AzureAD, you will find a file TEMPLATE_PoshMTPconfig.json in the Module folder. Rename this file to PoshMTPConfig.json and enter your API settings. Then copy the file in the root of the Module folder.

Example:

"C:\Users\User1\Documents\WindowsPowerShell\Modules\PSMDATP"
───PSMDATP
│   │   PoshMTPconfig.json
│   │
│   └───0.0.2
│           PSMDATP.psd1
│           PSMDATP.psm1
│           TEMPLATE_PoshMTPconfig.json

At present the PSMDATP PowerShell module only requires the API_MDATP information

{
    "API_MDATP":  {
                      "AppName":  "WindowsDefenderATPPSMDATP",
                      "OAuthUri":  "https://login.windows.net/<YOUR TENANT ID>/oauth2/token",
                      "ClientID":  "CLIENT ID",
                      "ClientSecret":  "<CLIENT SECRET>"
                  },
    "API_MSGRAPH":  {
                        "AppName":  "xMSGraph",
                        "OAuthUri":  "https://login.windows.net/<YOUR TENANT ID>/oauth2/token",
                        "ClientID":  "<CLIENT ID>",
                        "ClientSecret":  "<CLIENT SECRET>"
                    }
}

Important

I am going to assume that you are familiar with MDATP as such and understand the consequences of triggering actions on devices. Where applicable the cmdlets support the use the -whatif parameter. Think before pressing the key!

Running your first commands

List included cmdlets

Let's first take a look at the cmdlets included in the PSMDATP Module

get-command -Module PSMDATP | Select Name

You will see something like this

Add-MDATPDeviceTag
Add-MDATPIndicator
Get-MDATPAlert
Get-MDATPCollectionPackageUri
Get-MDATPDevice
Get-MDATPDeviceAction
Get-MDATPDeviceTag
Get-MDATPIndicator
Get-MDATPInvestigation
Get-MDATPQuery
Get-MDATPTvmRecommendation
Get-MDATPTvmVulnerability
Get-MDATPEndpointStatus
Remove-MDATPDevice
Remove-MDATPDeviceTag
Remove-MDATPIndicator
Set-MDATPAlert
Start-MDATPAppRestriction
Start-MDATPAVScan
Start-MDATPInvestigation
Start-MDATPInvestigationPackageCollection
Start-MDATPIsolation
Stop-MDATPAppRestriction
Stop-MDATPIsolation

For more details about the cmdlets included in this module check out the cmdlets documentation page

Retrieve MDATP Alerts

Run the following command to retrieve alerts from the past 30 days

Get-MDATPAlert -Severity High

List MDATP Devices

Run the following command to list all MDATP registered devices

Get-MDATPDevice -All

Contributing

If you have an idea or want to contribute to this project please submit a suggestion

Authors

Alex Verboon Twitter

Contributors

Dan Lacher Twitter

Release Notes

Version	Date	Notes
0.0.1	15.04.2020	Initial Release
0.0.2	03.05.2020	Added Add-MDATPIndicator and Remove-MDATPIndictor cmdlets
1.0.0	18.07.2020	Added Get-MDATPTvmRecommendation and Get-MDATPTvmVulnerability
		cmdlets, updated the API uri for the Get-MDATPAlerts cmdlet
1.1.0	22.12.2020	Added Set-MDATPAlert and Get-MDATPEndpointStatus
1.1.1	22.11.2022	Added generateAlert flag to Add-MDATPIndicator

TODO

I have the following on my to-do list:

A better solution to store the API configuration in a more secure place
~~Add cmdlets for TVM~~ added in version 1.0.0
~~Add cmdlets to manage custom indicators~~ added in version 0.0.2
Add more query templates for advanced hunting
Create more Module related Pester tests

Credits

I used Catesta for this project

psmdatp's People

Contributors

Stargazers

Watchers

Forkers

albandrod rajivraj killvxk 5l1v3r1 zshell danlacher ianhockett sassdawe bozhinov linkops banhao digitalarche frankfanslc sweetasnz invenco-information-systems-iit-legacy mastergoogler

psmdatp's Issues

Get-MDATPDevice " with "-DeviceName" parameter can't get json format response.

Describe the bug
When I used "Get-MDATPDevice " with "-DeviceName" parameter, but can't get the json format information. Only have the following information.

PS C:\> Get-MDATPDevice -DeviceName _hostname_
VERBOSE: GET https://api.securitycenter.windows.com/api/machines?$filter=ComputerDNSName eq '_hostname_' with 0-byte payload
VERBOSE: received 93-byte response of content type application/json; odata.metadata=minimal

Add function to set device value

Add a function to set the device value
https://learn.microsoft.com/en-us/microsoft-365/security/defender-endpoint/set-device-value?view=o365-worldwide

Can't remove Server from Defender with remove-MDATPDevice

Describe the bug
A clear and concise description of what the bug is.

To Reproduce
Steps to reproduce the behavior:

Go to Powershell
type "remove-MDATPDevice -DeviceName "Server of Choice"
See error

Expected behavior
Successfully remove "offboard" the server with a success message

Screenshots

Error is : Request to failed with HTTP Status BadRequest Bad Request
Write-Error, WriteErrorException

See Screenshot.

Get-MDATPDevice -all only retrieves 10.000 objects

When running
Get-MDATPDevice -all it only retrieves 10.000 devices

It seems to be caused by the max page size being 10.000 as described in
https://docs.microsoft.com/en-us/microsoft-365/security/defender-endpoint/get-machines?view=o365-worldwide

Permissions are set and granted in API permissions but when I try to get data, this is the response.

Get-MDATPAlert -Severity High
VERBOSE: GET with 0-byte payload
Get-MDATPAlert : Error retrieving MDATP alert data [The remote server returned an error: (403) Forbidden.]
At line:1 char:1

Get-MDATPAlert -Severity High

  + CategoryInfo          : NotSpecified: (:) [Write-Error], WriteErrorException
  + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Get-MDATPAlert

Help with config encryption ?

Hi,

How about I help with encryption of the conf json file ?

Possible options are ConvertTo-SecureString for the entire file, but then only the user that encrypted it can read it

Some sort of obfuscation to avoid plain text passwords.

Momchil

Add-MDATPIndicator

I have written an update to Add-MDATPIndicator to take into account the new API for passing a $True or $False to the generate alert flag. I have started to use the false setting for Informational level alerts. Let me know how you would like the code changes.

add support for "high value tagging"

would be awesome if support for value tagging could be added to this module.
https://docs.microsoft.com/en-us/microsoft-365/security/defender-endpoint/add-or-remove-machine-tags?view=o365-worldwide

API call is documented here:
https://docs.microsoft.com/en-us/microsoft-365/security/defender-endpoint/set-device-value?view=o365-worldwide

Start-MDATPIsolation errors on DeviceName when using DeviceID

Describe the bug
Using the Start-MDATPIsolation command with a specified DeviceID errors out when tryign to get a device name. This occurs with or without the -whatif switch.

MetadataError: C:\Users\(install location)\Documents\WindowsPowerShell\Modules\PSMDATP\1.0.0\PSMDATP.psm1:3225
Line |
3225 |          $DeviceName = $DeviceName.ToLower()
     |          ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | The variable cannot be validated because the value  is not a valid value for the DeviceName variable.

VERBOSE: GET https://api.securitycenter.windows.com/api/machines with 0-byte payload
VERBOSE: received 4711333-byte response of content type application/json
VERBOSE: Content encoding: utf-8
What if: Performing the operation "Start Isolation: Full" on target "".

To Reprodce
Run a command like the below(occurs when not using -whatif switch):
Start-MDATPIsolation -DeviceID $ID -IsolationType Full -WhatIf

Desktop (please complete the following information):

OS: Windows 10
PSVersion 7.1.1

Additional context
Using version 1.0.0

alexverboon / psmdatp Goto Github PK

psmdatp's Introduction

Microsoft Defender for Endpoint PowerShell Module

Motivation

Prerequisites

App Permissions

Getting Started

App Registration

Initial Configuration

Important

Running your first commands

List included cmdlets

Retrieve MDATP Alerts

List MDATP Devices

Contributing

Authors

Contributors

Release Notes

TODO

Credits

psmdatp's People

Contributors

Stargazers

Watchers

Forkers

psmdatp's Issues

Recommend Projects

Recommend Topics

Recommend Org