PSMDE is a PowerShell module providing interactive access to Device information, Advanced Hunting data and machine actions.

Module Functions

  • Connect-PSMDE
  • Get-PSMDEDeviceInfo
  • Get-PSMDELatestVersion
  • Invoke-PSMDEAvScan
  • Invoke-PSMDEAdvancedHunting
  • Invoke-PSMDEIsolation
  • Revoke-PSMDEIsolation
  • Invoke-PSMDEFileQuarantine
  • Save-PSMDESupportInfo
  • Test-PSMDEMapsConnection

Installation

Create Azure App

Create an Azure application to control authentication and authorization.
A step by step process is available here The API permissions required are available in the Help text of each module function.

Install MSAL.PS

PSMDE relies on another module for authentication. Install the MSAL.PS module from the PowerShell gallery.

Install-Module MSAL.PS -Scope CurrentUser

Download PSMDE

The PSMDE module is available from GitHub
Click on Code > Download Zip
Unblock the zip file and extract it to a folder in the $ENV:PSModule path
Make sure you rename the root folder from PSMDE-master to PSMDE
Edit the Public\Connect-PSMDE.ps1 file to set your TenantID and ApplicationID

# Connect-PSMDE before edit
Param(
        [parameter()]
        [ValidateNotNullOrEmpty()]
        [String]$TenantID = '00000000-0000-0000-0000-TENANTID'
        ,
        [parameter()]
        [ValidateNotNullOrEmpty()]
        [String]$ClientID = '00000000-0000-0000-0000-APPID'

Usage

Security Context

Start PowerShell in the context of an account with access to Defender information i.e. a member of

  • A built in reader role such as Global Reader or Security Reader
  • A privileged role such as Global Admin, Security Opertator, Security Admin
  • A custom role with delegated access to your tenant

Interactive PowerShell

Use the module interactively at PowerShell console and explore the module functions

Import-Module PSMDE # Load the module 
Get-Command -Module PSMDE # List available commands
Get-Help Get-PSMDEDeviceInfo # Get help on a command

EXAMPLE 1 - Get device information

The example below confirms the following for an endpoint:

  • Defender is active and onboarded
  • Engine and signatures are up-to-date
  • Last scan times
  • OS version and IP address information
  • Logged-on users
  • MDE alerts
  • Vulnerabilities
Import-Module PSMDE  
Connect-PSMDE -TenantID $TenantID -ClientID $AppID # Optional parameters. Set defaults in the Connect-PSMDE.ps1 file
Get-PSMDEDeviceInfo -Computername PC12345  

Computername                  : PC12345
osPlatform                    : Windows10
version                       : 22H2
osBuild                       : 19045
isPotentialDuplication        : False
machineTags                   : {MDEPilot}
healthStatus                  : Active
onboardingStatus              : Onboarded
defenderAvStatus              : Updated
exposureLevel                 : Medium
riskScore                     : Medium
avEngineVersion               : 1.1.23080.2005
avSignatureVersion            : 1.395.1403.0
avPlatformVersion             : 4.18.23080.2006
avIsSignatureUpToDate         : True
avIsEngineUpToDate            : True
avIsPlatformUpToDate          : True
avSignatureDataRefreshTime    : 27/08/2023 15:35:36
avSignatureDataRefreshTimeUTC : 27/08/2023 14:35:36
quickScanTime                 : 22/08/2023 03:16:00
quickScanTimeUTC              : 22/08/2023 02:16:00
fullScanTime                  : 
fullScanTimeUTC               : 
avmode                        : 0
LastSeen                      : 27/08/2023 14:53:08
LastSeenUTC                   : 27/08/2023 13:53:08
lastIpAddress                 : 192.168.1.140
lastExternalIpAddress         : 100.19.112.28
managedBy                     : Intune
loggedOnUsers                 : {@{id=RnD\user1; lastSeen=27/08/2023 16:23:38; logonTypes=RemoteInteractive}, @{id=azuread\admin1; lastSeen=27/08/2023 16:02:54; logonTypes=Interactive}}
alertCount                    : 9
alerts                        : {@{serverity=Informational; alertCreationTime=2023-05-08T19:45:47.8359999Z; detectionSource=AutomatedInvestigation; category=SuspiciousActivity; threatName=; threatFamilyName=}, 
                                @{serverity=Informational; alertCreationTime=2023-08-15T21:55:56.9250938Z; detectionSource=WindowsDefenderAv; category=Malware; threatName=Virus:DOS/EICAR_Test_File; 
                                threatFamilyName=EICAR_Test_File}, @{serverity=Medium; alertCreationTime=2023-05-08T16:11:02.4388031Z; detectionSource=WindowsDefenderAv; category=SuspiciousActivity; 
                                threatName=Trojan:PowerShell/Powersploit.L; threatFamilyName=Powersploit}, @{serverity=Medium; alertCreationTime=2023-05-08T16:02:13.0120825Z; detectionSource=WindowsDefenderAtp; 
                                category=Execution; threatName=; threatFamilyName=}...}
CVEs                          : {@{name=CVE-2023-33144; description=Visual Studio Code Spoofing Vulnerability; severity=Medium; publicExploit=False; firstDetected=2023-06-13T17:30:51Z}, @{name=CVE-2023-21779; 
                                description=Visual Studio Code Remote Code Execution Vulnerability; severity=High; publicExploit=False; firstDetected=2023-05-02T14:45:15Z}, @{name=CVE-2023-24893; description=Visual 
                                Studio Code Remote Code Execution Vulnerability; severity=High; publicExploit=False; firstDetected=2023-05-02T14:45:15Z}, @{name=CVE-2023-29338; description=Visual Studio Code 
                                Information Disclosure Vulnerability; severity=Medium; publicExploit=False; firstDetected=2023-06-08T10:30:35Z}}
deviceid                      : c6a833d9a0da6ad439076368d1781e7940c49fef

EXAMPLE 2: Scan computers based on Advanced Hunting Query results

The example below achieves the following:

  • Runs an Advanced Hunting query to find endpoints where a file has executed in the last 6 hours
  • Triggers a full scan on those endpoints
Invoke-PSMDEAdvancedHunting -Query @'  
DeviceProcessEvents
| where Timestamp > ago(6h)
| where ActionType == "ProcessCreated"
| where SHA1 == "1bc5066ddf693fc034d6514618854e26a85fd0d1"
| distinct DeviceName 
'@ | Invoke-PSMDEAvscan -ScanType Full

Computername     : PC123456
type             : RunAntiVirusScan
ScanType         : Full
status           : Pending
errorHResult     : 0
requestor        : admin@tenant.com
requestorComment : Full scan initiated by PSMDE
DeviceId         : c6a833d9a0da6ad439056368d1681e7940c49fee

EXAMPLE 3: Isolate computers

The example below performs the following:

  • Runs an Advanced Hunting query to find endpoints where PowerShell has communicated with a specific public IP
  • Triggers full isolation of those endpoints
Invoke-PSMDEAdvancedHunting -Query @'  
DeviceNetworkEvents
| where Timestamp > ago (6h)
| where InitiatingProcessFileName =~"PowerShell.exe"
| where RemoteIP == "20.50.201.195"
| distinct DeviceName
'@ | Invoke-PSMDEIsolation

computername  : PC123456
isolationType : Full
comment       : PSMDE: Isolate device
requestor     : <admin@tenant.com>
status        : Pending
deviceid      : c6a833d9a0da6ad439056368d1681e7940c49fee

EXAMPLE 4

The following example queries a Microsoft URI for the latest available version of Defender for Endpoint:

Get-PSMDELatestVersion

Engine         Platform        Signatures
------         --------        ----------
1.1.23070.1005 4.18.23070.1004 1.395.1451.0



This article was originally posted on Write-Verbose.com