├── .github └── ISSUE_TEMPLATE │ ├── bug_report.md │ └── feature_request.md ├── .gitignore ├── .vscode ├── extensions.json ├── settings.json └── tasks.json ├── LICENSE ├── README.md ├── _config.yml ├── actions_bootstrap.ps1 ├── docs ├── Add-MDATPDeviceTag.md ├── Add-MDATPIndicator.md ├── Get-MDATPAlert.md ├── Get-MDATPCollectionPackageUri.md ├── Get-MDATPDevice.md ├── Get-MDATPDeviceAction.md ├── Get-MDATPDeviceTag.md ├── Get-MDATPEndpointStatus.md ├── Get-MDATPIndicator.md ├── Get-MDATPInvestigation.md ├── Get-MDATPQuery.md ├── Get-MDATPTvmRecommendation.md ├── Get-MDATPTvmVulnerability.md ├── PSMDATP.md ├── Remove-MDATPDevice.md ├── Remove-MDATPDeviceTag.md ├── Remove-MDATPIndicator.md ├── Set-MDATPAlert.md ├── Start-MDATPAVScan.md ├── Start-MDATPAppRestriction.md ├── Start-MDATPInvestigation.md ├── Start-MDATPInvestigationPackageCollection.md ├── Start-MDATPIsolation.md ├── Stop-MDATPAppRestriction.md └── Stop-MDATPIsolation.md ├── media ├── apppermissions.png ├── psmdatp.png └── small_psmdatp.png └── src ├── PSMDATP.Settings.ps1 ├── PSMDATP.build.ps1 ├── PSMDATP ├── Imports.ps1 ├── PSMDATP.psd1 ├── PSMDATP.psm1 ├── Public │ ├── Add-MDATPDeviceTag.ps1 │ ├── Add-MDATPIndicator.ps1 │ ├── Get-MDATPAlert.ps1 │ ├── Get-MDATPCollectionPackageUri.ps1 │ ├── Get-MDATPDevice.ps1 │ ├── Get-MDATPDeviceAction.ps1 │ ├── Get-MDATPDeviceTag.ps1 │ ├── Get-MDATPEndpointStatus.ps1 │ ├── Get-MDATPIndicator.ps1 │ ├── Get-MDATPInvestigation.ps1 │ ├── Get-MDATPQuery.ps1 │ ├── Get-MDATPTvmRecommendation.ps1 │ ├── Get-MDATPTvmVulnerability.ps1 │ ├── Remove-MDATPDevice.ps1 │ ├── Remove-MDATPDeviceTag.ps1 │ ├── Remove-MDATPIndicator.ps1 │ ├── Set-MDATPAlert.ps1 │ ├── Start-MDATPAVScan.ps1 │ ├── Start-MDATPAppRestriction.ps1 │ ├── Start-MDATPInvestigation.ps1 │ ├── Start-MDATPInvestigationPackageCollection.ps1 │ ├── Start-MDATPIsolation.ps1 │ ├── Stop-MDATPAppRestriction.ps1 │ └── Stop-MDATPIsolation.ps1 └── TEMPLATE_PoshMTPconfig.json ├── PSScriptAnalyzerSettings.psd1 └── Tests ├── Infrastructure └── SampleInfraTest.Tests.ps1 └── Unit └── PSMDATP-Module.Tests.ps1 /.github/ISSUE_TEMPLATE/bug_report.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Bug report 3 | about: Create a report to help us improve 4 | title: '' 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Describe the bug** 11 | A clear and concise description of what the bug is. 12 | 13 | **To Reproduce** 14 | Steps to reproduce the behavior: 15 | 1. Go to '...' 16 | 2. Click on '....' 17 | 3. Scroll down to '....' 18 | 4. See error 19 | 20 | **Expected behavior** 21 | A clear and concise description of what you expected to happen. 22 | 23 | **Screenshots** 24 | If applicable, add screenshots to help explain your problem. 25 | 26 | **Desktop (please complete the following information):** 27 | - OS: [e.g. iOS] 28 | - Browser [e.g. chrome, safari] 29 | - Version [e.g. 22] 30 | 31 | **Smartphone (please complete the following information):** 32 | - Device: [e.g. iPhone6] 33 | - OS: [e.g. iOS8.1] 34 | - Browser [e.g. stock browser, safari] 35 | - Version [e.g. 22] 36 | 37 | **Additional context** 38 | Add any other context about the problem here. 39 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature_request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Feature request 3 | about: Suggest an idea for this project 4 | title: '' 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Is your feature request related to a problem? Please describe.** 11 | A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] 12 | 13 | **Describe the solution you'd like** 14 | A clear and concise description of what you want to happen. 15 | 16 | **Describe alternatives you've considered** 17 | A clear and concise description of any alternative solutions or features you've considered. 18 | 19 | **Additional context** 20 | Add any other context or screenshots about the feature request here. 21 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | Archive 2 | Artifacts 3 | BuildLocal 4 | cov.xml 5 | poshmtpconfig.json 6 | # OS generated files # 7 | ###################### 8 | .DS_Store 9 | .DS_Store? 10 | ._* 11 | .Spotlight-V100 12 | .Trashes 13 | ehthumbs.db 14 | Thumbs.db -------------------------------------------------------------------------------- /.vscode/extensions.json: -------------------------------------------------------------------------------- 1 | { 2 | // See http://go.microsoft.com/fwlink/?LinkId=827846 3 | // for the documentation about the extensions.json format 4 | "recommendations": [ 5 | "ms-vscode.PowerShell", 6 | "ryanluker.vscode-coverage-gutters", 7 | "DavidAnson.vscode-markdownlint" 8 | ] 9 | } -------------------------------------------------------------------------------- /.vscode/settings.json: -------------------------------------------------------------------------------- 1 | { 2 | // When enabled, will trim trailing whitespace when you save a file. 3 | "files.trimTrailingWhitespace": true, 4 | // specifies the location of the explicity ScriptAnalyzer settings file 5 | "powershell.scriptAnalysis.settingsPath": "PSScriptAnalyzerSettings.psd1", 6 | // specifies the PowerShell coding style used in this project (https://github.com/PoshCode/PowerShellPracticeAndStyle/issues/81) 7 | "powershell.codeFormatting.preset": "Stroustrup", 8 | "cSpell.words": [ 9 | "mdatpav", 10 | "scan" 11 | ] 12 | } 13 | 14 | -------------------------------------------------------------------------------- /.vscode/tasks.json: -------------------------------------------------------------------------------- 1 | // Available variables which can be used inside of strings. 2 | // ${workspaceRoot}: the root folder of the team 3 | // ${file}: the current opened file 4 | // ${relativeFile}: the current opened file relative to workspaceRoot 5 | // ${fileBasename}: the current opened file's basename 6 | // ${fileDirname}: the current opened file's dirname 7 | // ${fileExtname}: the current opened file's extension 8 | // ${cwd}: the current working directory of the spawned process 9 | // If you are using InvokeBuild you can enhance this tasks.json using the New-VSCodeTask command: 10 | // Install-Script New-VSCodeTask 11 | // New-VSCodeTask.ps1 -BuildFile .\src\YourModuleName.build.ps1 12 | { 13 | // See https://go.microsoft.com/fwlink/?LinkId=733558 14 | // for the documentation about the tasks.json format 15 | "version": "2.0.0", 16 | 17 | // Start PowerShell 18 | "windows": { 19 | "options": { 20 | "shell": { 21 | //"executable": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe", 22 | // "executable": "C:\\Program Files\\PowerShell\\6\\pwsh.exe", 23 | "executable": "C:\\Program Files\\PowerShell\\7\\pwsh.exe", 24 | "args": [ "-NoProfile", "-ExecutionPolicy", "Bypass", "-Command" ] 25 | } 26 | } 27 | }, 28 | "linux": { 29 | "options": { 30 | "shell": { 31 | "executable": "/usr/bin/pwsh", 32 | "args": [ "-NoProfile", "-Command" ] 33 | } 34 | } 35 | }, 36 | "osx": { 37 | "options": { 38 | "shell": { 39 | "executable": "/usr/local/bin/pwsh", 40 | "args": [ "-NoProfile", "-Command" ] 41 | } 42 | } 43 | }, 44 | 45 | // Associate with test task runner 46 | "tasks": [ 47 | { 48 | "label": "Test", 49 | "type": "shell", 50 | "group": { 51 | "kind": "test", 52 | "isDefault": true 53 | }, 54 | "problemMatcher": [ "$pester" ], 55 | "command": "Invoke-Pester -PesterOption @{IncludeVSCodeMarker=$true}" 56 | } 57 | ] 58 | } 59 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2020 Alex Verboon 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Microsoft Defender for Endpoint PowerShell Module 2 | 3 | [![Minimum Supported PowerShell Version](https://img.shields.io/badge/PowerShell-5.1+-purple.svg)](https://github.com/PowerShell/PowerShell) ![Cross Platform](https://img.shields.io/badge/platform-windows-lightgrey) 4 | [![PowerShell Gallery Version](https://img.shields.io/powershellgallery/v/psmdatp)](https://www.powershellgallery.com/packages/PSMDATP) [![PowerShell Gallery](https://img.shields.io/powershellgallery/dt/psmdatp)](https://www.powershellgallery.com/packages/PSMDATP) 5 | 6 | 7 |

8 | PSMDATP Logo 9 |

10 | 11 | Welcome to the Microsoft Defender for Endpoint PowerShell module! 12 | 13 | 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. 14 | 15 | ## Motivation 16 | 17 | I created this PowerShell module for MDATP for the following reasons: 18 | 19 | 1. Advance my PowerShell skills 20 | 2. Provide an easy way to interact with MDE through PowerShell because I prefer automation over manual tasks 21 | 22 | ## Prerequisites 23 | 24 | - Windows PowerShell 5.1 (Testing for PowerShell 7 is in progress) 25 | - have configured authorization for access by registering an application in AzureAD 26 | 27 | ### App Permissions 28 | 29 | 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 30 | 31 |

32 | App permissions 33 |

34 | 35 | 36 | ## Getting Started 37 | 38 | To get started with the module, open your PowerShell terminal and install the module from the PSGallery by running this simple command: 39 | ```powershell 40 | Install-Module PSMDATP -Scope CurrentUser 41 | ``` 42 | ## App Registration 43 | 44 | ## Initial Configuration 45 | 46 | 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. 47 | 48 | ***Example:*** 49 | 50 | ```powershell 51 | "C:\Users\User1\Documents\WindowsPowerShell\Modules\PSMDATP" 52 | ───PSMDATP 53 | │ │ PoshMTPconfig.json 54 | │ │ 55 | │ └───0.0.2 56 | │ PSMDATP.psd1 57 | │ PSMDATP.psm1 58 | │ TEMPLATE_PoshMTPconfig.json 59 | ``` 60 | 61 | At present the PSMDATP PowerShell module only requires the API_MDATP information 62 | 63 | ```json 64 | { 65 | "API_MDATP": { 66 | "AppName": "WindowsDefenderATPPSMDATP", 67 | "OAuthUri": "https://login.windows.net//oauth2/token", 68 | "ClientID": "CLIENT ID", 69 | "ClientSecret": "" 70 | }, 71 | "API_MSGRAPH": { 72 | "AppName": "xMSGraph", 73 | "OAuthUri": "https://login.windows.net//oauth2/token", 74 | "ClientID": "", 75 | "ClientSecret": "" 76 | } 77 | } 78 | ``` 79 | 80 | ## Important 81 | 82 | 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! 83 | 84 | ## Running your first commands 85 | 86 | ### List included cmdlets 87 | 88 | Let's first take a look at the cmdlets included in the PSMDATP Module 89 | 90 | ```powershell 91 | get-command -Module PSMDATP | Select Name 92 | ``` 93 | 94 | You will see something like this 95 | 96 | ```powershell 97 | 98 | Add-MDATPDeviceTag 99 | Add-MDATPIndicator 100 | Get-MDATPAlert 101 | Get-MDATPCollectionPackageUri 102 | Get-MDATPDevice 103 | Get-MDATPDeviceAction 104 | Get-MDATPDeviceTag 105 | Get-MDATPIndicator 106 | Get-MDATPInvestigation 107 | Get-MDATPQuery 108 | Get-MDATPTvmRecommendation 109 | Get-MDATPTvmVulnerability 110 | Get-MDATPEndpointStatus 111 | Remove-MDATPDevice 112 | Remove-MDATPDeviceTag 113 | Remove-MDATPIndicator 114 | Set-MDATPAlert 115 | Start-MDATPAppRestriction 116 | Start-MDATPAVScan 117 | Start-MDATPInvestigation 118 | Start-MDATPInvestigationPackageCollection 119 | Start-MDATPIsolation 120 | Stop-MDATPAppRestriction 121 | Stop-MDATPIsolation 122 | 123 | ``` 124 | 125 | For more details about the cmdlets included in this module check out the [cmdlets documentation page](./docs/PSMDATP.md) 126 | 127 | ### Retrieve MDATP Alerts 128 | 129 | Run the following command to retrieve alerts from the past 30 days 130 | 131 | ```powershell 132 | Get-MDATPAlert -Severity High 133 | ``` 134 | 135 | ### List MDATP Devices 136 | 137 | Run the following command to list all MDATP registered devices 138 | 139 | ```powershell 140 | Get-MDATPDevice -All 141 | ``` 142 | 143 | --- 144 | 145 | ## Contributing 146 | 147 | If you have an idea or want to contribute to this project please submit a suggestion 148 | 149 | ## Authors 150 | 151 | **Alex Verboon** [Twitter](https://twitter.com/alexverboon) 152 | 153 | ## Contributors 154 | 155 | **Dan Lacher** [Twitter](https://twitter.com/DanLacher) 156 | 157 | --- 158 | 159 | ## Release Notes 160 | 161 | | Version | Date | Notes | 162 | | ------- | ---------- | -------------------------------------------------------------- | 163 | | 0.0.1 | 15.04.2020 | Initial Release | 164 | | 0.0.2 | 03.05.2020 | Added Add-MDATPIndicator and Remove-MDATPIndictor cmdlets | 165 | | 1.0.0 | 18.07.2020 | Added Get-MDATPTvmRecommendation and Get-MDATPTvmVulnerability | 166 | | | | cmdlets, updated the API uri for the Get-MDATPAlerts cmdlet | 167 | | 1.1.0 | 22.12.2020 | Added Set-MDATPAlert and Get-MDATPEndpointStatus | 168 | | 1.1.1 | 22.11.2022 | Added generateAlert flag to Add-MDATPIndicator | 169 | 170 | --- 171 | 172 | ## TODO 173 | 174 | I have the following on my to-do list: 175 | 176 | - A better solution to store the API configuration in a more secure place 177 | - ~~Add cmdlets for TVM~~ added in version 1.0.0 178 | - ~~Add cmdlets to manage custom indicators~~ added in version 0.0.2 179 | - Add more query templates for advanced hunting 180 | - Create more Module related Pester tests 181 | 182 | --- 183 | 184 | ## Credits 185 | 186 | I used [Catesta](https://github.com/techthoughts2/Catesta/blob/master/README.md) for this project -------------------------------------------------------------------------------- /_config.yml: -------------------------------------------------------------------------------- 1 | theme: jekyll-theme-slate -------------------------------------------------------------------------------- /actions_bootstrap.ps1: -------------------------------------------------------------------------------- 1 | # Bootstrap dependencies 2 | 3 | # https://docs.microsoft.com/powershell/module/packagemanagement/get-packageprovider 4 | Get-PackageProvider -Name Nuget -ForceBootstrap | Out-Null 5 | 6 | # https://docs.microsoft.com/powershell/module/powershellget/set-psrepository 7 | Set-PSRepository -Name PSGallery -InstallationPolicy Trusted 8 | 9 | # List of PowerShell Modules required for the build 10 | $modulesToInstall = [System.Collections.ArrayList]::new() 11 | # https://github.com/pester/Pester 12 | $null = $modulesToInstall.Add(([PSCustomObject]@{ 13 | ModuleName = 'Pester' 14 | ModuleVersion = '4.10.1' 15 | })) 16 | # https://github.com/nightroman/Invoke-Build 17 | $null = $modulesToInstall.Add(([PSCustomObject]@{ 18 | ModuleName = 'InvokeBuild' 19 | ModuleVersion = '5.5.7' 20 | })) 21 | # https://github.com/PowerShell/PSScriptAnalyzer 22 | $null = $modulesToInstall.Add(([PSCustomObject]@{ 23 | ModuleName = 'PSScriptAnalyzer' 24 | ModuleVersion = '1.18.3' 25 | })) 26 | # https://github.com/PowerShell/platyPS 27 | # older version used due to: https://github.com/PowerShell/platyPS/issues/457 28 | $null = $modulesToInstall.Add(([PSCustomObject]@{ 29 | ModuleName = 'platyPS' 30 | ModuleVersion = '0.12.0' 31 | })) 32 | 33 | 'Installing PowerShell Modules' 34 | foreach ($module in $modulesToInstall) { 35 | $installSplat = @{ 36 | Name = $module.ModuleName 37 | RequiredVersion = $module.ModuleVersion 38 | Repository = 'PSGallery' 39 | Force = $true 40 | ErrorAction = 'Stop' 41 | } 42 | try { 43 | Install-Module @installSplat 44 | Import-Module -Name $module.ModuleName -ErrorAction Stop 45 | ' - Successfully installed {0}' -f $module.ModuleName 46 | } 47 | catch { 48 | $message = 'Failed to install {0}' -f $module.ModuleName 49 | " - $message" 50 | throw $message 51 | } 52 | } -------------------------------------------------------------------------------- /docs/Add-MDATPDeviceTag.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: PSMDATP-help.xml 3 | Module Name: PSMDATP 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Add-MDATPDeviceTag 9 | 10 | ## SYNOPSIS 11 | Add-MDATPDeviceTag 12 | 13 | ## SYNTAX 14 | 15 | ### DeviceName 16 | ``` 17 | Add-MDATPDeviceTag -DeviceName -Tag [-MTPConfigFile ] [-WhatIf] [-Confirm] 18 | [] 19 | ``` 20 | 21 | ### DeviceID 22 | ``` 23 | Add-MDATPDeviceTag -DeviceID -Tag [-MTPConfigFile ] [-WhatIf] [-Confirm] 24 | [] 25 | ``` 26 | 27 | ## DESCRIPTION 28 | Add-MDATPDeviceTag adds the specified Tag to the MDATP device 29 | 30 | ## EXAMPLES 31 | 32 | ### EXAMPLE 1 33 | ``` 34 | Add-MDATPDeviceTag -DeviceName computer02 -Tag 'Testing' -verbose 35 | ``` 36 | 37 | This command adds the tag 'testing' to the device 'computer02' 38 | 39 | ## PARAMETERS 40 | 41 | ### -DeviceName 42 | Computername of the device 43 | 44 | ```yaml 45 | Type: String 46 | Parameter Sets: DeviceName 47 | Aliases: 48 | 49 | Required: True 50 | Position: Named 51 | Default value: None 52 | Accept pipeline input: False 53 | Accept wildcard characters: False 54 | ``` 55 | 56 | ### -DeviceID 57 | The unique device ID of the device 58 | 59 | ```yaml 60 | Type: String 61 | Parameter Sets: DeviceID 62 | Aliases: 63 | 64 | Required: True 65 | Position: Named 66 | Default value: None 67 | Accept pipeline input: False 68 | Accept wildcard characters: False 69 | ``` 70 | 71 | ### -Tag 72 | The value of the tag to be added 73 | 74 | ```yaml 75 | Type: String 76 | Parameter Sets: (All) 77 | Aliases: 78 | 79 | Required: True 80 | Position: Named 81 | Default value: None 82 | Accept pipeline input: False 83 | Accept wildcard characters: False 84 | ``` 85 | 86 | ### -MTPConfigFile 87 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 88 | 89 | ```yaml 90 | Type: String 91 | Parameter Sets: (All) 92 | Aliases: 93 | 94 | Required: False 95 | Position: Named 96 | Default value: None 97 | Accept pipeline input: False 98 | Accept wildcard characters: False 99 | ``` 100 | 101 | ### -WhatIf 102 | Shows what would happen if the cmdlet runs. 103 | The cmdlet is not run. 104 | 105 | ```yaml 106 | Type: SwitchParameter 107 | Parameter Sets: (All) 108 | Aliases: wi 109 | 110 | Required: False 111 | Position: Named 112 | Default value: None 113 | Accept pipeline input: False 114 | Accept wildcard characters: False 115 | ``` 116 | 117 | ### -Confirm 118 | Prompts you for confirmation before running the cmdlet. 119 | 120 | ```yaml 121 | Type: SwitchParameter 122 | Parameter Sets: (All) 123 | Aliases: cf 124 | 125 | Required: False 126 | Position: Named 127 | Default value: None 128 | Accept pipeline input: False 129 | Accept wildcard characters: False 130 | ``` 131 | 132 | ### CommonParameters 133 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. 134 | For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). 135 | 136 | ## INPUTS 137 | 138 | ## OUTPUTS 139 | 140 | ## NOTES 141 | Version: 1.0 142 | Author: Alex Verboon 143 | Creation Date: 16.03.2020 144 | Purpose/Change: Initial script development 145 | 146 | ## RELATED LINKS 147 | -------------------------------------------------------------------------------- /docs/Add-MDATPIndicator.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: PSMDATP-help.xml 3 | Module Name: PSMDATP 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Add-MDATPIndicator 9 | 10 | ## SYNOPSIS 11 | Add-MDATPIndicator 12 | 13 | ## SYNTAX 14 | 15 | ``` 16 | Add-MDATPIndicator [-IndicatorValue] [-IndicatorType] [-Action] 17 | [[-Application] ] [-Title] [-Description] [[-expirationTime] ] 18 | [-severity] [[-recommendedActions] ] [[-MTPConfigFile] ] [-WhatIf] [-Confirm] 19 | [] 20 | ``` 21 | 22 | ## DESCRIPTION 23 | Add-MDATPIndicator Submits or Updates new Indicator entity. 24 | 25 | ## EXAMPLES 26 | 27 | ### EXAMPLE 1 28 | ``` 29 | Add-MDATPIndicator -IndicatorValue "https://www.sample.com" -IndicatorType Url -Action Alert -Title "Sample URL detected" -Description "Access to the website sample.com detected" -severity High 30 | ``` 31 | 32 | This command adds the URL indicator for https://www.sample.com 33 | 34 | ### EXAMPLE 2 35 | ``` 36 | Add-MDATPIndicator -IndicatorType DomainName www.somedomain.com -Action Alert -Title "somedomain domain detected" -Description "somedomain domain detected from custom indicator" -severity Informational 37 | ``` 38 | 39 | This command ads the domain indicator for www.somedomain.com 40 | 41 | ### EXAMPLE 3 42 | ``` 43 | Add-MDATPIndicator -IndicatorValue "A4B52BBC94F10572296D3F8F4E25B39A1837D00F3036955C3761A9E7B2207A58" -IndicatorType FileSha256 -Action Alert -Title "Dummy File" -severity Informational -Description "dummy file detected" 44 | ``` 45 | 46 | This command creates FileSha256 indicator 47 | 48 | ### EXAMPLE 4 49 | ``` 50 | Add-MDATPIndicator -IndicatorType IpAddress -IndicatorValue 138.223.70.10 -Action Alert -Title "IP Address indicator 138.223.70.10" -Description "access detected" -severity Medium 51 | ``` 52 | 53 | ### EXAMPLE 5 54 | ``` 55 | Add-MDATPIndicator -IndicatorType IpAddress -IndicatorValue 138.223.70.10 -Action Alert -Title "IP Address indicator 138.223.70.10" -Description "access detected" -severity Medium -generateAlert $False 56 | ``` 57 | 58 | This command adds an IP indicator 59 | 60 | ## PARAMETERS 61 | 62 | ### -IndicatorValue 63 | Identity of the Indicator entity. 64 | Required 65 | 66 | ```yaml 67 | Type: String 68 | Parameter Sets: (All) 69 | Aliases: 70 | 71 | Required: True 72 | Position: 1 73 | Default value: None 74 | Accept pipeline input: False 75 | Accept wildcard characters: False 76 | ``` 77 | 78 | ### -IndicatorType 79 | Type of the indicator. 80 | Possible values are: "FileSha1", "FileSha256", "IpAddress", "DomainName" and "Url". 81 | Required 82 | 83 | ```yaml 84 | Type: String 85 | Parameter Sets: (All) 86 | Aliases: 87 | 88 | Required: True 89 | Position: 2 90 | Default value: None 91 | Accept pipeline input: False 92 | Accept wildcard characters: False 93 | ``` 94 | 95 | ### -Action 96 | The action that will be taken if the indicator will be discovered in the organization. 97 | Possible values are: "Allow", Alert", "AlertAndBlock", "Block", and "BlockAndRemediate". 98 | Required 99 | 100 | ```yaml 101 | Type: String 102 | Parameter Sets: (All) 103 | Aliases: 104 | 105 | Required: True 106 | Position: 3 107 | Default value: None 108 | Accept pipeline input: False 109 | Accept wildcard characters: False 110 | ``` 111 | 112 | ### -Application 113 | The application associated with the indicator. 114 | Optional 115 | 116 | ```yaml 117 | Type: String 118 | Parameter Sets: (All) 119 | Aliases: 120 | 121 | Required: False 122 | Position: 4 123 | Default value: None 124 | Accept pipeline input: False 125 | Accept wildcard characters: False 126 | ``` 127 | 128 | ### -Title 129 | Indicator alert title. 130 | Required 131 | 132 | ```yaml 133 | Type: String 134 | Parameter Sets: (All) 135 | Aliases: 136 | 137 | Required: True 138 | Position: 5 139 | Default value: None 140 | Accept pipeline input: False 141 | Accept wildcard characters: False 142 | ``` 143 | 144 | ### -Description 145 | Description of the indicator. 146 | Required 147 | 148 | ```yaml 149 | Type: String 150 | Parameter Sets: (All) 151 | Aliases: 152 | 153 | Required: True 154 | Position: 6 155 | Default value: None 156 | Accept pipeline input: False 157 | Accept wildcard characters: False 158 | ``` 159 | 160 | ### -expirationTime 161 | The expiration time of the indicator. 162 | Optional 163 | 164 | ```yaml 165 | Type: String 166 | Parameter Sets: (All) 167 | Aliases: 168 | 169 | Required: False 170 | Position: 7 171 | Default value: None 172 | Accept pipeline input: False 173 | Accept wildcard characters: False 174 | ``` 175 | 176 | ### -severity 177 | The severity of the indicator. 178 | possible values are: "Informational", "Low", "Medium" and "High". 179 | Optional 180 | 181 | ```yaml 182 | Type: String 183 | Parameter Sets: (All) 184 | Aliases: 185 | 186 | Required: True 187 | Position: 8 188 | Default value: None 189 | Accept pipeline input: False 190 | Accept wildcard characters: False 191 | ``` 192 | 193 | ### -recommendedActions 194 | TI indicator alert recommended actions. 195 | Optional 196 | 197 | ```yaml 198 | Type: String 199 | Parameter Sets: (All) 200 | Aliases: 201 | 202 | Required: False 203 | Position: 9 204 | Default value: None 205 | Accept pipeline input: False 206 | Accept wildcard characters: False 207 | ``` 208 | 209 | ### -recommendedActions 210 | TI indicator generate alert. 211 | Optional 212 | 213 | ```yaml 214 | Type: Boolean 215 | Parameter Sets: (All) 216 | Aliases: 217 | 218 | Required: False 219 | Position: 10 220 | Default value: None ($True) 221 | Accept pipeline input: False 222 | Accept wildcard characters: False 223 | ``` 224 | 225 | ### -MTPConfigFile 226 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 227 | 228 | ```yaml 229 | Type: String 230 | Parameter Sets: (All) 231 | Aliases: 232 | 233 | Required: False 234 | Position: 11 235 | Default value: None 236 | Accept pipeline input: False 237 | Accept wildcard characters: False 238 | ``` 239 | 240 | ### -WhatIf 241 | Shows what would happen if the cmdlet runs. 242 | The cmdlet is not run. 243 | 244 | ```yaml 245 | Type: SwitchParameter 246 | Parameter Sets: (All) 247 | Aliases: wi 248 | 249 | Required: False 250 | Position: Named 251 | Default value: None 252 | Accept pipeline input: False 253 | Accept wildcard characters: False 254 | ``` 255 | 256 | ### -Confirm 257 | Prompts you for confirmation before running the cmdlet. 258 | 259 | ```yaml 260 | Type: SwitchParameter 261 | Parameter Sets: (All) 262 | Aliases: cf 263 | 264 | Required: False 265 | Position: Named 266 | Default value: None 267 | Accept pipeline input: False 268 | Accept wildcard characters: False 269 | ``` 270 | 271 | ### CommonParameters 272 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. 273 | For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). 274 | 275 | ## INPUTS 276 | 277 | ## OUTPUTS 278 | 279 | ## NOTES 280 | Version: 1.1.1 281 | Author: Alex Verboon 282 | Creation Date: 05.05.2020 283 | Purpose/Change: Initial script development 284 | 285 | ## RELATED LINKS 286 | -------------------------------------------------------------------------------- /docs/Get-MDATPAlert.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: PSMDATP-help.xml 3 | Module Name: PSMDATP 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Get-MDATPAlert 9 | 10 | ## SYNOPSIS 11 | Get-MDATPAlert 12 | 13 | ## SYNTAX 14 | 15 | ``` 16 | Get-MDATPAlert [[-Severity] ] [[-PastHours] ] [[-MTPConfigFile] ] [] 17 | ``` 18 | 19 | ## DESCRIPTION 20 | Get-MDATPAlert retrieves Microsoft Defender Advanced Threat Protection alerts exposed through the Microsoft Defender Advanced Threat Protection Alerts Rest API. 21 | 22 | ## EXAMPLES 23 | 24 | ### EXAMPLE 1 25 | ``` 26 | Get-WDATPAlert 27 | ``` 28 | 29 | This command retrieves all alerts 30 | 31 | ### EXAMPLE 2 32 | ``` 33 | Get-MDATPAlert -PastHours 168 -Severity Informational 34 | ``` 35 | 36 | This command retrieves all alerts from the past 7 days with severity level Informational 37 | 38 | ## PARAMETERS 39 | 40 | ### -Severity 41 | Provides an option to filter the output by Severity. 42 | Low, Medium, High. 43 | 44 | ```yaml 45 | Type: String 46 | Parameter Sets: (All) 47 | Aliases: 48 | 49 | Required: False 50 | Position: 1 51 | Default value: None 52 | Accept pipeline input: False 53 | Accept wildcard characters: False 54 | ``` 55 | 56 | ### -PastHours 57 | Provides an option to filter the results by past hours when the alert was created. 58 | 59 | ```yaml 60 | Type: String 61 | Parameter Sets: (All) 62 | Aliases: 63 | 64 | Required: False 65 | Position: 2 66 | Default value: None 67 | Accept pipeline input: False 68 | Accept wildcard characters: False 69 | ``` 70 | 71 | ### -MTPConfigFile 72 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 73 | 74 | ```yaml 75 | Type: String 76 | Parameter Sets: (All) 77 | Aliases: 78 | 79 | Required: False 80 | Position: 3 81 | Default value: None 82 | Accept pipeline input: False 83 | Accept wildcard characters: False 84 | ``` 85 | 86 | ### CommonParameters 87 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. 88 | For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). 89 | 90 | ## INPUTS 91 | 92 | ## OUTPUTS 93 | 94 | ## NOTES 95 | Version: 1.2 96 | Author: Alex Verboon 97 | Creation Date: 18.07.2020 98 | Purpose/Change: updated API uri 99 | 100 | ## RELATED LINKS 101 | -------------------------------------------------------------------------------- /docs/Get-MDATPCollectionPackageUri.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: PSMDATP-help.xml 3 | Module Name: PSMDATP 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Get-MDATPCollectionPackageUri 9 | 10 | ## SYNOPSIS 11 | Get-MDATPCollectionPackageUri 12 | 13 | ## SYNTAX 14 | 15 | ``` 16 | Get-MDATPCollectionPackageUri [-ActionID] [[-MTPConfigFile] ] [-Download] [] 17 | ``` 18 | 19 | ## DESCRIPTION 20 | Get-MDATPCollectionPackageUri retrieves the Investigation Collection Package download URI and optionally download the package 21 | 22 | Use the Get-MDATPDeviceActions cmdlet to retrieve the ActionID of the investigation package collection request. 23 | 24 | ## EXAMPLES 25 | 26 | ### EXAMPLE 1 27 | ``` 28 | $lastcollectionrequestid = Get-MDATPDeviceActions -DeviceName testclient6 -ActionType CollectInvestigationPackage | Select-Object -First 1 29 | Get-MDATPCollectionPackageUri -ActionID $lastcollectionrequestid.id 30 | ``` 31 | 32 | 33 | This comand first retrieves the last collection package request ID and then retrieves the download URI 34 | 35 | ### EXAMPLE 2 36 | ``` 37 | $lastcollectionrequestid = Get-MDATPDeviceActions -DeviceName testclient6 -ActionType CollectInvestigationPackage | Select-Object -First 1 38 | Get-MDATPCollectionPackageUri -ActionID $lastcollectionrequestid.id -Download 39 | ``` 40 | 41 | 42 | This comand first retrieves the last collection package request ID and stores the investigation package into the users download folder 43 | 44 | ## PARAMETERS 45 | 46 | ### -ActionID 47 | The Action ID of the investigation package collection request. 48 | 49 | ```yaml 50 | Type: String 51 | Parameter Sets: (All) 52 | Aliases: 53 | 54 | Required: True 55 | Position: 1 56 | Default value: None 57 | Accept pipeline input: False 58 | Accept wildcard characters: False 59 | ``` 60 | 61 | ### -MTPConfigFile 62 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 63 | 64 | ```yaml 65 | Type: String 66 | Parameter Sets: (All) 67 | Aliases: 68 | 69 | Required: False 70 | Position: 2 71 | Default value: None 72 | Accept pipeline input: False 73 | Accept wildcard characters: False 74 | ``` 75 | 76 | ### -Download 77 | Downloads the investigation pacakge ZIP file into the users Downloads folder 78 | 79 | ```yaml 80 | Type: SwitchParameter 81 | Parameter Sets: (All) 82 | Aliases: 83 | 84 | Required: False 85 | Position: Named 86 | Default value: False 87 | Accept pipeline input: False 88 | Accept wildcard characters: False 89 | ``` 90 | 91 | ### CommonParameters 92 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. 93 | For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). 94 | 95 | ## INPUTS 96 | 97 | ## OUTPUTS 98 | 99 | ## NOTES 100 | Version: 1.0 101 | Author: Alex Verboon 102 | Creation Date: 12.04.2020 103 | Purpose/Change: Initial script development 104 | 105 | ## RELATED LINKS 106 | 107 | -------------------------------------------------------------------------------- /docs/Get-MDATPDevice.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: PSMDATP-help.xml 3 | Module Name: PSMDATP 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Get-MDATPDevice 9 | 10 | ## SYNOPSIS 11 | Get-MDATPDevice 12 | 13 | ## SYNTAX 14 | 15 | ### DeviceName 16 | ``` 17 | Get-MDATPDevice -DeviceName [-MTPConfigFile ] [] 18 | ``` 19 | 20 | ### DeviceID 21 | ``` 22 | Get-MDATPDevice -DeviceID [-MTPConfigFile ] [] 23 | ``` 24 | 25 | ### All 26 | ``` 27 | Get-MDATPDevice [-All] [-HealthStatus ] [-RiskScore ] [-MTPConfigFile ] 28 | [] 29 | ``` 30 | 31 | ## DESCRIPTION 32 | Get-MDATPDevice retrieves MDATP device information 33 | 34 | ## EXAMPLES 35 | 36 | ### EXAMPLE 1 37 | ``` 38 | Get-MDATPDevice -all 39 | ``` 40 | 41 | This command retrieves all MDATP devices 42 | 43 | ### EXAMPLE 2 44 | ``` 45 | Get-MDATPDevice -All -HealthStatus Inactive 46 | ``` 47 | 48 | This command lists all inactive devices 49 | 50 | ### EXAMPLE 3 51 | ``` 52 | Get-MDATPDevice -All -RiskScore Medium 53 | ``` 54 | 55 | This command lists all devices with a medium risk score 56 | 57 | ### EXAMPLE 4 58 | ``` 59 | Get-MDATPDevice -DeviceName Computer01 60 | ``` 61 | 62 | This command retrieves device information for Computer01 63 | 64 | ## PARAMETERS 65 | 66 | ### -DeviceName 67 | Computername of the device 68 | 69 | ```yaml 70 | Type: String 71 | Parameter Sets: DeviceName 72 | Aliases: 73 | 74 | Required: True 75 | Position: Named 76 | Default value: None 77 | Accept pipeline input: False 78 | Accept wildcard characters: False 79 | ``` 80 | 81 | ### -DeviceID 82 | The unique device ID of the device 83 | 84 | ```yaml 85 | Type: String 86 | Parameter Sets: DeviceID 87 | Aliases: 88 | 89 | Required: True 90 | Position: Named 91 | Default value: None 92 | Accept pipeline input: False 93 | Accept wildcard characters: False 94 | ``` 95 | 96 | ### -All 97 | Lists machine actions for all managed devices 98 | 99 | ```yaml 100 | Type: SwitchParameter 101 | Parameter Sets: All 102 | Aliases: 103 | 104 | Required: True 105 | Position: Named 106 | Default value: False 107 | Accept pipeline input: False 108 | Accept wildcard characters: False 109 | ``` 110 | 111 | ### -HealthStatus 112 | Filters the results by device heatlh. 113 | 114 | ```yaml 115 | Type: String 116 | Parameter Sets: All 117 | Aliases: 118 | 119 | Required: False 120 | Position: Named 121 | Default value: None 122 | Accept pipeline input: False 123 | Accept wildcard characters: False 124 | ``` 125 | 126 | ### -RiskScore 127 | Filters the results by device risk score 128 | 129 | ```yaml 130 | Type: String 131 | Parameter Sets: All 132 | Aliases: 133 | 134 | Required: False 135 | Position: Named 136 | Default value: None 137 | Accept pipeline input: False 138 | Accept wildcard characters: False 139 | ``` 140 | 141 | ### -MTPConfigFile 142 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 143 | 144 | ```yaml 145 | Type: String 146 | Parameter Sets: (All) 147 | Aliases: 148 | 149 | Required: False 150 | Position: Named 151 | Default value: None 152 | Accept pipeline input: False 153 | Accept wildcard characters: False 154 | ``` 155 | 156 | ### CommonParameters 157 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. 158 | For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). 159 | 160 | ## INPUTS 161 | 162 | ## OUTPUTS 163 | 164 | ## NOTES 165 | Version: 1.0 166 | Author: Alex Verboon 167 | Creation Date: 14.04.2020 168 | Purpose/Change: Initial script development 169 | 170 | ## RELATED LINKS 171 | -------------------------------------------------------------------------------- /docs/Get-MDATPDeviceAction.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: PSMDATP-help.xml 3 | Module Name: PSMDATP 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Get-MDATPDeviceAction 9 | 10 | ## SYNOPSIS 11 | Get-MDATPDeviceAction 12 | 13 | ## SYNTAX 14 | 15 | ### DeviceName 16 | ``` 17 | Get-MDATPDeviceAction -DeviceName [-ActionType ] [-MTPConfigFile ] 18 | [] 19 | ``` 20 | 21 | ### DeviceID 22 | ``` 23 | Get-MDATPDeviceAction -DeviceID [-ActionType ] [-MTPConfigFile ] [] 24 | ``` 25 | 26 | ### All 27 | ``` 28 | Get-MDATPDeviceAction [-All] [-ActionType ] [-MTPConfigFile ] [] 29 | ``` 30 | 31 | ### id 32 | ``` 33 | Get-MDATPDeviceAction [-Id ] [-ActionType ] [-MTPConfigFile ] [] 34 | ``` 35 | 36 | ## DESCRIPTION 37 | Get-MDATPDeviceAction retrieves machine MDATP actions 38 | 39 | ## EXAMPLES 40 | 41 | ### EXAMPLE 1 42 | ``` 43 | Get-MDATPDeviceAction -DeviceName computer02 44 | ``` 45 | 46 | This command retrieves the actions for device 'computer02' 47 | 48 | ### EXAMPLE 2 49 | ``` 50 | Get-MDATPDeviceAction -DeviceID 70077ccc272ab3baeb991c09442c5657d22bfc5c 51 | ``` 52 | 53 | This command retrieves the actions for the device with the specified device id 54 | 55 | ### EXAMPLE 3 56 | ``` 57 | Get-MDATPDeviceAction -ActionType CollectInvestigationPackage 58 | ``` 59 | 60 | This command retreives all machine actions with the specified action type 61 | 62 | ### EXAMPLE 4 63 | ``` 64 | Get-MDATPDeviceAction -All 65 | ``` 66 | 67 | This command retrieves machine actions for all devices 68 | 69 | ## PARAMETERS 70 | 71 | ### -DeviceName 72 | Computername of the device 73 | 74 | ```yaml 75 | Type: String 76 | Parameter Sets: DeviceName 77 | Aliases: 78 | 79 | Required: True 80 | Position: Named 81 | Default value: None 82 | Accept pipeline input: False 83 | Accept wildcard characters: False 84 | ``` 85 | 86 | ### -DeviceID 87 | The unique device ID of the device 88 | 89 | ```yaml 90 | Type: String 91 | Parameter Sets: DeviceID 92 | Aliases: 93 | 94 | Required: True 95 | Position: Named 96 | Default value: None 97 | Accept pipeline input: False 98 | Accept wildcard characters: False 99 | ``` 100 | 101 | ### -All 102 | Lists machine actions for all managed devices 103 | 104 | ```yaml 105 | Type: SwitchParameter 106 | Parameter Sets: All 107 | Aliases: 108 | 109 | Required: True 110 | Position: Named 111 | Default value: False 112 | Accept pipeline input: False 113 | Accept wildcard characters: False 114 | ``` 115 | 116 | ### -Id 117 | The machine action id 118 | 119 | ```yaml 120 | Type: String 121 | Parameter Sets: id 122 | Aliases: 123 | 124 | Required: False 125 | Position: Named 126 | Default value: None 127 | Accept pipeline input: False 128 | Accept wildcard characters: False 129 | ``` 130 | 131 | ### -ActionType 132 | Action Type 133 | 134 | ```yaml 135 | Type: String 136 | Parameter Sets: (All) 137 | Aliases: 138 | 139 | Required: False 140 | Position: Named 141 | Default value: None 142 | Accept pipeline input: False 143 | Accept wildcard characters: False 144 | ``` 145 | 146 | ### -MTPConfigFile 147 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 148 | 149 | ```yaml 150 | Type: String 151 | Parameter Sets: (All) 152 | Aliases: 153 | 154 | Required: False 155 | Position: Named 156 | Default value: None 157 | Accept pipeline input: False 158 | Accept wildcard characters: False 159 | ``` 160 | 161 | ### CommonParameters 162 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. 163 | For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). 164 | 165 | ## INPUTS 166 | 167 | ## OUTPUTS 168 | 169 | ## NOTES 170 | Version: 1.0 171 | Author: Alex Verboon 172 | Creation Date: 12.04.2020 173 | Purpose/Change: Initial script development 174 | 175 | ## RELATED LINKS 176 | -------------------------------------------------------------------------------- /docs/Get-MDATPDeviceTag.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: PSMDATP-help.xml 3 | Module Name: PSMDATP 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Get-MDATPDeviceTag 9 | 10 | ## SYNOPSIS 11 | Get-MDATPDeviceTag 12 | 13 | ## SYNTAX 14 | 15 | ### DeviceName 16 | ``` 17 | Get-MDATPDeviceTag -DeviceName [-MTPConfigFile ] [] 18 | ``` 19 | 20 | ### DeviceID 21 | ``` 22 | Get-MDATPDeviceTag -DeviceID [-MTPConfigFile ] [] 23 | ``` 24 | 25 | ### All 26 | ``` 27 | Get-MDATPDeviceTag [-All] [-MTPConfigFile ] [] 28 | ``` 29 | 30 | ## DESCRIPTION 31 | Get-MDATPDeviceTag retrieves tags assigned on the specified device 32 | 33 | ## EXAMPLES 34 | 35 | ### EXAMPLE 1 36 | ``` 37 | Get-MDATPDeviceTag -DeviceName computer02 38 | ``` 39 | 40 | This command reads all the tags assigned to the device 'computer02' 41 | 42 | ## PARAMETERS 43 | 44 | ### -DeviceName 45 | Computername of the device 46 | 47 | ```yaml 48 | Type: String 49 | Parameter Sets: DeviceName 50 | Aliases: 51 | 52 | Required: True 53 | Position: Named 54 | Default value: None 55 | Accept pipeline input: False 56 | Accept wildcard characters: False 57 | ``` 58 | 59 | ### -DeviceID 60 | The unique device ID of the device 61 | 62 | ```yaml 63 | Type: String 64 | Parameter Sets: DeviceID 65 | Aliases: 66 | 67 | Required: True 68 | Position: Named 69 | Default value: None 70 | Accept pipeline input: False 71 | Accept wildcard characters: False 72 | ``` 73 | 74 | ### -All 75 | Switch to retrieve tags from all devices 76 | 77 | ```yaml 78 | Type: SwitchParameter 79 | Parameter Sets: All 80 | Aliases: 81 | 82 | Required: True 83 | Position: Named 84 | Default value: False 85 | Accept pipeline input: False 86 | Accept wildcard characters: False 87 | ``` 88 | 89 | ### -MTPConfigFile 90 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 91 | 92 | ```yaml 93 | Type: String 94 | Parameter Sets: (All) 95 | Aliases: 96 | 97 | Required: False 98 | Position: Named 99 | Default value: None 100 | Accept pipeline input: False 101 | Accept wildcard characters: False 102 | ``` 103 | 104 | ### CommonParameters 105 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. 106 | For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). 107 | 108 | ## INPUTS 109 | 110 | ## OUTPUTS 111 | 112 | ## NOTES 113 | Version: 1.0 114 | Author: Alex Verboon 115 | Creation Date: 16.03.2020 116 | Purpose/Change: Initial script development 117 | 118 | ## RELATED LINKS 119 | -------------------------------------------------------------------------------- /docs/Get-MDATPEndpointStatus.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: PSMDATP-help.xml 3 | Module Name: PSMDATP 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Get-MDATPEndpointStatus 9 | 10 | ## SYNOPSIS 11 | Get-MDATPEndpointStatus 12 | 13 | ## SYNTAX 14 | 15 | ``` 16 | Get-MDATPEndpointStatus [[-DeviceName] ] [[-MTPConfigFile] ] [] 17 | ``` 18 | 19 | ## DESCRIPTION 20 | Get-MDATPEndpointStatus retrieves information about the Endpoint Status 21 | 22 | https://github.com/microsoft/Microsoft-365-Defender-Hunting-Queries/blob/master/General%20queries/Endpoint%20Agent%20Health%20Status%20Report.md 23 | 24 | This query will provide a report of many of the best practice configurations for Defender ATP deployment. 25 | Special Thanks to Gilad Mittelman for the initial inspiration and concept. 26 | Any tests which are reporting "BAD" as a result imply that the associated capability is not configured per best practice recommendation. 27 | 28 | Limitations 29 | 1. 30 | The results will include a maximum of 100,000 rows. 31 | 2. 32 | The number of executions is limited per tenant: up to 15 calls per minute, 15 minutes of running time every hour and 4 hours of running time a day. 33 | 3. 34 | The maximal execution time of a single request is 10 minutes. 35 | 36 | ## EXAMPLES 37 | 38 | ### EXAMPLE 1 39 | ``` 40 | Get-MDATPEndpointStatus -DeviceName TestClient4 41 | ``` 42 | 43 | ### EXAMPLE 2 44 | ``` 45 | Get-MDATPEndpointStatus 46 | ``` 47 | 48 | ## PARAMETERS 49 | 50 | ### -DeviceName 51 | Computername of the device.If no DeviceName is provided all devices are querried 52 | 53 | ```yaml 54 | Type: String 55 | Parameter Sets: (All) 56 | Aliases: 57 | 58 | Required: False 59 | Position: 1 60 | Default value: None 61 | Accept pipeline input: False 62 | Accept wildcard characters: False 63 | ``` 64 | 65 | ### -MTPConfigFile 66 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 67 | 68 | ```yaml 69 | Type: String 70 | Parameter Sets: (All) 71 | Aliases: 72 | 73 | Required: False 74 | Position: 2 75 | Default value: None 76 | Accept pipeline input: False 77 | Accept wildcard characters: False 78 | ``` 79 | 80 | ### CommonParameters 81 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. 82 | For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). 83 | 84 | ## INPUTS 85 | 86 | ## OUTPUTS 87 | 88 | ## NOTES 89 | Version: 1.0 90 | Author: Alex Verboon 91 | Creation Date: 22.12.2020 92 | Purpose/Change: Initial script development 93 | 94 | ## RELATED LINKS 95 | -------------------------------------------------------------------------------- /docs/Get-MDATPIndicator.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: PSMDATP-help.xml 3 | Module Name: PSMDATP 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Get-MDATPIndicator 9 | 10 | ## SYNOPSIS 11 | Get-MDATPIndicator 12 | 13 | ## SYNTAX 14 | 15 | ``` 16 | Get-MDATPIndicator [[-IndicatorType] ] [[-MTPConfigFile] ] [] 17 | ``` 18 | 19 | ## DESCRIPTION 20 | Get-MDATPIndicator retrieves Microsoft Defender Advanced Threat Protection custom indicators exposed 21 | through the Microsoft Defender Advanced Threat Protection indicators Rest API. 22 | 23 | ## EXAMPLES 24 | 25 | ### EXAMPLE 1 26 | ``` 27 | Get-MDATPIndicator 28 | ``` 29 | 30 | This command retrieves all TI indicators 31 | 32 | ### EXAMPLE 2 33 | ``` 34 | Get-MDATPIndicator -IndicatorType DomainName 35 | ``` 36 | 37 | This command retrieves all DomainName TI indicators 38 | 39 | ### EXAMPLE 3 40 | ``` 41 | $indicators = Get-MDATPIndicator -MTPConfigFile "C:\Dev\Private\MSSecurityPowerShell\Config\PoshMTPconfigBaseVISION.json" 42 | $indicators | Where-Object {$_.Source -like "WindowsDefenderATPThreatIntelAPI"} 43 | ``` 44 | 45 | 46 | This sample shows how to filter results by TI source 47 | 48 | ## PARAMETERS 49 | 50 | ### -IndicatorType 51 | Filters the indicator by the specified IndicatorType. 52 | Possible values are: DomainName, Url, FileSha256,IpAddress,WebCategory 53 | 54 | ```yaml 55 | Type: String 56 | Parameter Sets: (All) 57 | Aliases: 58 | 59 | Required: False 60 | Position: 1 61 | Default value: None 62 | Accept pipeline input: False 63 | Accept wildcard characters: False 64 | ``` 65 | 66 | ### -MTPConfigFile 67 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 68 | 69 | ```yaml 70 | Type: String 71 | Parameter Sets: (All) 72 | Aliases: 73 | 74 | Required: False 75 | Position: 2 76 | Default value: None 77 | Accept pipeline input: False 78 | Accept wildcard characters: False 79 | ``` 80 | 81 | ### CommonParameters 82 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. 83 | For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). 84 | 85 | ## INPUTS 86 | 87 | ## OUTPUTS 88 | 89 | ## NOTES 90 | Version: 1.0 91 | Author: Alex Verboon 92 | Creation Date: 20.03.2020 93 | Purpose/Change: Initial script development 94 | 95 | ## RELATED LINKS 96 | 97 | -------------------------------------------------------------------------------- /docs/Get-MDATPInvestigation.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: PSMDATP-help.xml 3 | Module Name: PSMDATP 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Get-MDATPInvestigation 9 | 10 | ## SYNOPSIS 11 | Get-MDATPInvestigation 12 | 13 | ## SYNTAX 14 | 15 | ### All (Default) 16 | ``` 17 | Get-MDATPInvestigation [-All] [-State ] [-MTPConfigFile ] [] 18 | ``` 19 | 20 | ### DeviceName 21 | ``` 22 | Get-MDATPInvestigation [-DeviceName ] [-State ] [-MTPConfigFile ] [] 23 | ``` 24 | 25 | ### DeviceID 26 | ``` 27 | Get-MDATPInvestigation [-DeviceID ] [-State ] [-MTPConfigFile ] [] 28 | ``` 29 | 30 | ### id 31 | ``` 32 | Get-MDATPInvestigation [-Id ] [-State ] [-MTPConfigFile ] [] 33 | ``` 34 | 35 | ## DESCRIPTION 36 | Get-MDATPInvestigation retrieves Microsoft Defender ATP automated investigation information 37 | 38 | ## EXAMPLES 39 | 40 | ### EXAMPLE 1 41 | ``` 42 | Get-MDATPInvestigation 43 | ``` 44 | 45 | This command retrieves all investigations 46 | 47 | ### EXAMPLE 2 48 | ``` 49 | Get-MDATPInvestigation -DeviceName Computer01 50 | ``` 51 | 52 | This command retrieves all investigations for Computer01 53 | 54 | ### EXAMPLE 3 55 | ``` 56 | Get-MDATPInvestigation -DeviceID 70077ccc272ab3baeb991c09442c5657d22bfc5c 57 | ``` 58 | 59 | This command retrieves all investigations for the device with the specified 60 | device id. 61 | 62 | ### EXAMPLE 4 63 | ``` 64 | Get-MDATPInvestigation -State Running 65 | ``` 66 | 67 | This command retireves all investigations with the state Running 68 | 69 | ### EXAMPLE 5 70 | ``` 71 | Get-MDATPInvestigation -Id 12 72 | ``` 73 | 74 | This command retrieves investigation details for the investigation with id 12 75 | 76 | ### EXAMPLE 6 77 | ``` 78 | Get-MDATPInvestigation -DeviceName computer01 -State SuccessfullyRemediated 79 | ``` 80 | 81 | This command retrieves all SuccessfullyRemediated investigations for device computer01 82 | 83 | ## PARAMETERS 84 | 85 | ### -All 86 | Switch to list all devices 87 | 88 | ```yaml 89 | Type: SwitchParameter 90 | Parameter Sets: All 91 | Aliases: 92 | 93 | Required: False 94 | Position: Named 95 | Default value: False 96 | Accept pipeline input: False 97 | Accept wildcard characters: False 98 | ``` 99 | 100 | ### -DeviceName 101 | Computername of the device 102 | 103 | ```yaml 104 | Type: String 105 | Parameter Sets: DeviceName 106 | Aliases: 107 | 108 | Required: False 109 | Position: Named 110 | Default value: None 111 | Accept pipeline input: False 112 | Accept wildcard characters: False 113 | ``` 114 | 115 | ### -DeviceID 116 | The unique device ID of the device 117 | 118 | ```yaml 119 | Type: String 120 | Parameter Sets: DeviceID 121 | Aliases: 122 | 123 | Required: False 124 | Position: Named 125 | Default value: None 126 | Accept pipeline input: False 127 | Accept wildcard characters: False 128 | ``` 129 | 130 | ### -Id 131 | The investigation id 132 | 133 | ```yaml 134 | Type: String 135 | Parameter Sets: id 136 | Aliases: 137 | 138 | Required: False 139 | Position: Named 140 | Default value: None 141 | Accept pipeline input: False 142 | Accept wildcard characters: False 143 | ``` 144 | 145 | ### -State 146 | The current state of the investigation. 147 | Possible values are: 148 | Unknown, Terminated, SuccessfullyRemediated, Benign, Failed, PartiallyRemediated, Running, PendingApproval, PendingResource, PartiallyInvestigated, TerminatedByUser, TerminatedBySystem, Queued, InnerFailure, PreexistingAlert, UnsupportedOs, UnsupportedAlertType, SuppressedAlert 149 | 150 | ```yaml 151 | Type: String 152 | Parameter Sets: (All) 153 | Aliases: 154 | 155 | Required: False 156 | Position: Named 157 | Default value: None 158 | Accept pipeline input: False 159 | Accept wildcard characters: False 160 | ``` 161 | 162 | ### -MTPConfigFile 163 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 164 | 165 | ```yaml 166 | Type: String 167 | Parameter Sets: (All) 168 | Aliases: 169 | 170 | Required: False 171 | Position: Named 172 | Default value: None 173 | Accept pipeline input: False 174 | Accept wildcard characters: False 175 | ``` 176 | 177 | ### CommonParameters 178 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. 179 | For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). 180 | 181 | ## INPUTS 182 | 183 | ## OUTPUTS 184 | 185 | ## NOTES 186 | Version: 1.0 187 | Author: Alex Verboon 188 | Creation Date: 12.04.2020 189 | Purpose/Change: Initial script development 190 | 191 | ## RELATED LINKS 192 | -------------------------------------------------------------------------------- /docs/Get-MDATPQuery.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: PSMDATP-help.xml 3 | Module Name: PSMDATP 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Get-MDATPQuery 9 | 10 | ## SYNOPSIS 11 | Get-MDATPQuery 12 | 13 | ## SYNTAX 14 | 15 | ``` 16 | Get-MDATPQuery [-Schema] [[-DeviceName] ] [[-TimeRange] ] [[-MTPConfigFile] ] 17 | [] 18 | ``` 19 | 20 | ## DESCRIPTION 21 | Get-MDATPQuery executes MDATP advanced hunting queries through the 22 | Microsoft Defender Advanced Threat Protection Alerts Rest API. 23 | 24 | Limitations 25 | 1. 26 | You can only run a query on data from the last 30 days. 27 | 2. 28 | The results will include a maximum of 100,000 rows. 29 | 3. 30 | The number of executions is limited per tenant: up to 15 calls per minute, 15 minutes of running time every hour and 4 hours of running time a day. 31 | 4. 32 | The maximal execution time of a single request is 10 minutes. 33 | 34 | ## EXAMPLES 35 | 36 | ### EXAMPLE 1 37 | ``` 38 | Get-MDATPQuery -Schema DeviceLogonEvents -DeviceName TestClient4 39 | ``` 40 | 41 | The above query retrieves all logon events for the specified device 42 | 43 | ## PARAMETERS 44 | 45 | ### -Schema 46 | The Schema to use for the query 47 | 48 | ```yaml 49 | Type: String 50 | Parameter Sets: (All) 51 | Aliases: 52 | 53 | Required: True 54 | Position: 1 55 | Default value: None 56 | Accept pipeline input: False 57 | Accept wildcard characters: False 58 | ``` 59 | 60 | ### -DeviceName 61 | Computername of the device.If no DeviceName is provided all devices are querried 62 | 63 | ```yaml 64 | Type: String 65 | Parameter Sets: (All) 66 | Aliases: 67 | 68 | Required: False 69 | Position: 2 70 | Default value: None 71 | Accept pipeline input: False 72 | Accept wildcard characters: False 73 | ``` 74 | 75 | ### -TimeRange 76 | The Time Range 77 | 78 | ```yaml 79 | Type: String 80 | Parameter Sets: (All) 81 | Aliases: 82 | 83 | Required: False 84 | Position: 3 85 | Default value: None 86 | Accept pipeline input: False 87 | Accept wildcard characters: False 88 | ``` 89 | 90 | ### -MTPConfigFile 91 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 92 | 93 | ```yaml 94 | Type: String 95 | Parameter Sets: (All) 96 | Aliases: 97 | 98 | Required: False 99 | Position: 4 100 | Default value: None 101 | Accept pipeline input: False 102 | Accept wildcard characters: False 103 | ``` 104 | 105 | ### CommonParameters 106 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. 107 | For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). 108 | 109 | ## INPUTS 110 | 111 | ## OUTPUTS 112 | 113 | ## NOTES 114 | Version: 1.0 115 | Author: Alex Verboon 116 | Creation Date: 17.02.2020 117 | Purpose/Change: Initial script development 118 | 119 | ## RELATED LINKS 120 | -------------------------------------------------------------------------------- /docs/Get-MDATPTvmRecommendation.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: PSMDATP-help.xml 3 | Module Name: PSMDATP 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Get-MDATPTvmRecommendation 9 | 10 | ## SYNOPSIS 11 | Get-MDATPTvmRecommendation 12 | 13 | ## SYNTAX 14 | 15 | ``` 16 | Get-MDATPTvmRecommendation [[-recommendationCategory] ] [-publicexploit] [[-MTPConfigFile] ] 17 | [] 18 | ``` 19 | 20 | ## DESCRIPTION 21 | Get-MDATPTvmRecommendation retrieves Microsoft Defender Advanced Threat Protection Threat and Vulnerability Management 22 | security recommendations 23 | 24 | ## EXAMPLES 25 | 26 | ### EXAMPLE 1 27 | ``` 28 | Get-MDATPTvmRecommendation 29 | ``` 30 | 31 | This command retrieves all TVM security recommendations 32 | 33 | ### EXAMPLE 2 34 | ``` 35 | $tvmrecommendations = Get-MDATPTvmRecommendation -MTPConfigFile "C:\Users\Alex\Documents\WindowsPowerShell\Modules\PSMDATP\PoshMTPconfig.json" 36 | ``` 37 | 38 | ## PARAMETERS 39 | 40 | ### -recommendationCategory 41 | Category or grouping to which the configuration belongs: Application, OS, Network, Accounts, Security controls 42 | 43 | ```yaml 44 | Type: String 45 | Parameter Sets: (All) 46 | Aliases: 47 | 48 | Required: False 49 | Position: 1 50 | Default value: None 51 | Accept pipeline input: False 52 | Accept wildcard characters: False 53 | ``` 54 | 55 | ### -publicexploit 56 | Setting this parameter limits the results to security recommendations that address a public exploit 57 | 58 | ```yaml 59 | Type: SwitchParameter 60 | Parameter Sets: (All) 61 | Aliases: 62 | 63 | Required: False 64 | Position: Named 65 | Default value: False 66 | Accept pipeline input: False 67 | Accept wildcard characters: False 68 | ``` 69 | 70 | ### -MTPConfigFile 71 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 72 | 73 | ```yaml 74 | Type: String 75 | Parameter Sets: (All) 76 | Aliases: 77 | 78 | Required: False 79 | Position: 2 80 | Default value: None 81 | Accept pipeline input: False 82 | Accept wildcard characters: False 83 | ``` 84 | 85 | ### CommonParameters 86 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. 87 | For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). 88 | 89 | ## INPUTS 90 | 91 | ## OUTPUTS 92 | 93 | ## NOTES 94 | Version: 1.0 95 | Author: Alex Verboon 96 | Creation Date: 18.07.2020 97 | Purpose/Change: Initial script development 98 | 99 | ## RELATED LINKS 100 | -------------------------------------------------------------------------------- /docs/Get-MDATPTvmVulnerability.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: PSMDATP-help.xml 3 | Module Name: PSMDATP 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Get-MDATPTvmVulnerability 9 | 10 | ## SYNOPSIS 11 | Get-MDATPTvmVulnerability 12 | 13 | ## SYNTAX 14 | 15 | ``` 16 | Get-MDATPTvmVulnerability [[-SeverityLevel] ] [-IsExploitAvailable] [[-MTPConfigFile] ] 17 | [] 18 | ``` 19 | 20 | ## DESCRIPTION 21 | Get-MDATPTvmVulnerability retrieves Microsoft Defender Advanced Threat Protection Threat and Vulnerability Management 22 | vulnerability informaition 23 | 24 | ## EXAMPLES 25 | 26 | ### EXAMPLE 1 27 | ``` 28 | Get-MDATPTvmVulnerability 29 | ``` 30 | 31 | This command retrieves all TVM vulnerability information 32 | 33 | ### EXAMPLE 2 34 | ``` 35 | $tvmvulninfo = Get-MDATPTvmVulnerability -MTPConfigFile "C:\Users\Alex\Documents\WindowsPowerShell\Modules\PSMDATP\PoshMTPconfig.json" 36 | ``` 37 | 38 | ## PARAMETERS 39 | 40 | ### -SeverityLevel 41 | Severity level 42 | 43 | ```yaml 44 | Type: String 45 | Parameter Sets: (All) 46 | Aliases: 47 | 48 | Required: False 49 | Position: 1 50 | Default value: None 51 | Accept pipeline input: False 52 | Accept wildcard characters: False 53 | ``` 54 | 55 | ### -IsExploitAvailable 56 | Setting this parameter limits the results to vulnerabilities where exploit code for the vulnerability is publicly available 57 | 58 | ```yaml 59 | Type: SwitchParameter 60 | Parameter Sets: (All) 61 | Aliases: 62 | 63 | Required: False 64 | Position: Named 65 | Default value: False 66 | Accept pipeline input: False 67 | Accept wildcard characters: False 68 | ``` 69 | 70 | ### -MTPConfigFile 71 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 72 | 73 | ```yaml 74 | Type: String 75 | Parameter Sets: (All) 76 | Aliases: 77 | 78 | Required: False 79 | Position: 2 80 | Default value: None 81 | Accept pipeline input: False 82 | Accept wildcard characters: False 83 | ``` 84 | 85 | ### CommonParameters 86 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. 87 | For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). 88 | 89 | ## INPUTS 90 | 91 | ## OUTPUTS 92 | 93 | ## NOTES 94 | Version: 1.0 95 | Author: Alex Verboon 96 | Creation Date: 18.07.2020 97 | Purpose/Change: Initial script development 98 | 99 | ## RELATED LINKS 100 | -------------------------------------------------------------------------------- /docs/PSMDATP.md: -------------------------------------------------------------------------------- 1 | --- 2 | Module Name: PSMDATP 3 | Module Guid: 5b1f66a1-78d5-4d12-9c89-0bb749da773f 4 | Download Help Link: NA 5 | Help Version: 1.1.0 6 | Locale: en-US 7 | --- 8 | 9 | # PSMDATP Module 10 | ## Description 11 | "Manage Microsoft Defender for Endpoint with PowerShell" 12 | 13 | ## PSMDATP Cmdlets 14 | ### [Add-MDATPDeviceTag](Add-MDATPDeviceTag.md) 15 | Add-MDATPDeviceTag 16 | 17 | ### [Add-MDATPIndicator](Add-MDATPIndicator.md) 18 | Add-MDATPIndicator 19 | 20 | ### [Get-MDATPAlert](Get-MDATPAlert.md) 21 | Get-MDATPAlert 22 | 23 | ### [Get-MDATPCollectionPackageUri](Get-MDATPCollectionPackageUri.md) 24 | Get-MDATPCollectionPackageUri 25 | 26 | ### [Get-MDATPDevice](Get-MDATPDevice.md) 27 | Get-MDATPDevice 28 | 29 | ### [Get-MDATPDeviceAction](Get-MDATPDeviceAction.md) 30 | Get-MDATPDeviceAction 31 | 32 | ### [Get-MDATPDeviceTag](Get-MDATPDeviceTag.md) 33 | Get-MDATPDeviceTag 34 | 35 | ### [Get-MDATPEndpointStatus](Get-MDATPEndpointStatus.md) 36 | Get-MDATPEndpointStatus 37 | 38 | ### [Get-MDATPIndicator](Get-MDATPIndicator.md) 39 | Get-MDATPIndicator 40 | 41 | ### [Get-MDATPInvestigation](Get-MDATPInvestigation.md) 42 | Get-MDATPInvestigation 43 | 44 | ### [Get-MDATPQuery](Get-MDATPQuery.md) 45 | Get-MDATPQuery 46 | 47 | ### [Get-MDATPTvmRecommendation](Get-MDATPTvmRecommendation.md) 48 | Get-MDATPTvmRecommendation 49 | 50 | ### [Get-MDATPTvmVulnerability](Get-MDATPTvmVulnerability.md) 51 | Get-MDATPTvmVulnerability 52 | 53 | ### [Remove-MDATPDevice](Remove-MDATPDevice.md) 54 | Remove-MDATPDevice 55 | 56 | ### [Remove-MDATPDeviceTag](Remove-MDATPDeviceTag.md) 57 | Remove-MDATPDeviceTag 58 | 59 | ### [Remove-MDATPIndicator](Remove-MDATPIndicator.md) 60 | Remove-MDATPIndicator 61 | 62 | ### [Set-MDATPAlert](Set-MDATPAlert.md) 63 | Set-MDATPAlert 64 | 65 | ### [Start-MDATPAppRestriction](Start-MDATPAppRestriction.md) 66 | Start-MDATPAppRestriction 67 | 68 | ### [Start-MDATPAVScan](Start-MDATPAVScan.md) 69 | Start-MDATPAVScan 70 | 71 | ### [Start-MDATPInvestigation](Start-MDATPInvestigation.md) 72 | Start-MDATPInvestigation 73 | 74 | ### [Start-MDATPInvestigationPackageCollection](Start-MDATPInvestigationPackageCollection.md) 75 | Start-MDATPInvestigationPackageCollection 76 | 77 | ### [Start-MDATPIsolation](Start-MDATPIsolation.md) 78 | Start-MDATPIsolation 79 | 80 | ### [Stop-MDATPAppRestriction](Stop-MDATPAppRestriction.md) 81 | Stop-MDATPAppRestriction 82 | 83 | ### [Stop-MDATPIsolation](Stop-MDATPIsolation.md) 84 | Stop-MDATPIsolation 85 | 86 | 87 | -------------------------------------------------------------------------------- /docs/Remove-MDATPDevice.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: PSMDATP-help.xml 3 | Module Name: PSMDATP 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Remove-MDATPDevice 9 | 10 | ## SYNOPSIS 11 | Remove-MDATPDevice 12 | 13 | ## SYNTAX 14 | 15 | ### DeviceName 16 | ``` 17 | Remove-MDATPDevice -DeviceName [-OffboardReason ] [-MTPConfigFile ] [-WhatIf] 18 | [-Confirm] [] 19 | ``` 20 | 21 | ### DeviceID 22 | ``` 23 | Remove-MDATPDevice -DeviceID [-OffboardReason ] [-MTPConfigFile ] [-WhatIf] [-Confirm] 24 | [] 25 | ``` 26 | 27 | ## DESCRIPTION 28 | Remove-MDATPDevice offboards a device from MDATP and adds a tag 'Offboarded' to the device. 29 | 30 | ## EXAMPLES 31 | 32 | ### EXAMPLE 1 33 | ``` 34 | Remove-MDATPDevice -DeviceName Computer02 35 | ``` 36 | 37 | This command offboards device Computer02 from MDATP 38 | 39 | ## PARAMETERS 40 | 41 | ### -DeviceName 42 | Computername of the device 43 | 44 | ```yaml 45 | Type: String 46 | Parameter Sets: DeviceName 47 | Aliases: 48 | 49 | Required: True 50 | Position: Named 51 | Default value: None 52 | Accept pipeline input: False 53 | Accept wildcard characters: False 54 | ``` 55 | 56 | ### -DeviceID 57 | The unique device ID of the device 58 | 59 | ```yaml 60 | Type: String 61 | Parameter Sets: DeviceID 62 | Aliases: 63 | 64 | Required: True 65 | Position: Named 66 | Default value: None 67 | Accept pipeline input: False 68 | Accept wildcard characters: False 69 | ``` 70 | 71 | ### -OffboardReason 72 | Comment to be added to the offboard action, when no value is specified a default comment 'Offobard machine by automation' is added 73 | 74 | ```yaml 75 | Type: String 76 | Parameter Sets: (All) 77 | Aliases: 78 | 79 | Required: False 80 | Position: Named 81 | Default value: Offobard machine by automation 82 | Accept pipeline input: False 83 | Accept wildcard characters: False 84 | ``` 85 | 86 | ### -MTPConfigFile 87 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 88 | 89 | ```yaml 90 | Type: String 91 | Parameter Sets: (All) 92 | Aliases: 93 | 94 | Required: False 95 | Position: Named 96 | Default value: None 97 | Accept pipeline input: False 98 | Accept wildcard characters: False 99 | ``` 100 | 101 | ### -WhatIf 102 | Shows what would happen if the cmdlet runs. 103 | The cmdlet is not run. 104 | 105 | ```yaml 106 | Type: SwitchParameter 107 | Parameter Sets: (All) 108 | Aliases: wi 109 | 110 | Required: False 111 | Position: Named 112 | Default value: None 113 | Accept pipeline input: False 114 | Accept wildcard characters: False 115 | ``` 116 | 117 | ### -Confirm 118 | Prompts you for confirmation before running the cmdlet. 119 | 120 | ```yaml 121 | Type: SwitchParameter 122 | Parameter Sets: (All) 123 | Aliases: cf 124 | 125 | Required: False 126 | Position: Named 127 | Default value: None 128 | Accept pipeline input: False 129 | Accept wildcard characters: False 130 | ``` 131 | 132 | ### CommonParameters 133 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. 134 | For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). 135 | 136 | ## INPUTS 137 | 138 | ## OUTPUTS 139 | 140 | ## NOTES 141 | Version: 1.0 142 | Author: Alex Verboon 143 | Creation Date: 14.03.2020 144 | Purpose/Change: Initial script development 145 | 146 | ## RELATED LINKS 147 | -------------------------------------------------------------------------------- /docs/Remove-MDATPDeviceTag.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: PSMDATP-help.xml 3 | Module Name: PSMDATP 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Remove-MDATPDeviceTag 9 | 10 | ## SYNOPSIS 11 | Remove-MDATPDeviceTag 12 | 13 | ## SYNTAX 14 | 15 | ### DeviceName 16 | ``` 17 | Remove-MDATPDeviceTag -DeviceName -Tag [-MTPConfigFile ] [-WhatIf] [-Confirm] 18 | [] 19 | ``` 20 | 21 | ### DeviceID 22 | ``` 23 | Remove-MDATPDeviceTag -DeviceID -Tag [-MTPConfigFile ] [-WhatIf] [-Confirm] 24 | [] 25 | ``` 26 | 27 | ## DESCRIPTION 28 | Remove-MDATPDeviceTag removes the specified Tag to the MDATP device. 29 | 30 | ## EXAMPLES 31 | 32 | ### EXAMPLE 1 33 | ``` 34 | Remove-MDATPDeviceTag -DeviceName computer02 -Tag 'Testing' -verbose 35 | ``` 36 | 37 | This command removes the tag 'testing' from device 'computer02' 38 | 39 | ## PARAMETERS 40 | 41 | ### -DeviceName 42 | Computername of the device 43 | 44 | ```yaml 45 | Type: String 46 | Parameter Sets: DeviceName 47 | Aliases: 48 | 49 | Required: True 50 | Position: Named 51 | Default value: None 52 | Accept pipeline input: False 53 | Accept wildcard characters: False 54 | ``` 55 | 56 | ### -DeviceID 57 | The unique device ID of the device 58 | 59 | ```yaml 60 | Type: String 61 | Parameter Sets: DeviceID 62 | Aliases: 63 | 64 | Required: True 65 | Position: Named 66 | Default value: None 67 | Accept pipeline input: False 68 | Accept wildcard characters: False 69 | ``` 70 | 71 | ### -Tag 72 | The value of the tag to be removed 73 | 74 | ```yaml 75 | Type: String 76 | Parameter Sets: (All) 77 | Aliases: 78 | 79 | Required: True 80 | Position: Named 81 | Default value: None 82 | Accept pipeline input: False 83 | Accept wildcard characters: False 84 | ``` 85 | 86 | ### -MTPConfigFile 87 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 88 | 89 | ```yaml 90 | Type: String 91 | Parameter Sets: (All) 92 | Aliases: 93 | 94 | Required: False 95 | Position: Named 96 | Default value: None 97 | Accept pipeline input: False 98 | Accept wildcard characters: False 99 | ``` 100 | 101 | ### -WhatIf 102 | Shows what would happen if the cmdlet runs. 103 | The cmdlet is not run. 104 | 105 | ```yaml 106 | Type: SwitchParameter 107 | Parameter Sets: (All) 108 | Aliases: wi 109 | 110 | Required: False 111 | Position: Named 112 | Default value: None 113 | Accept pipeline input: False 114 | Accept wildcard characters: False 115 | ``` 116 | 117 | ### -Confirm 118 | Prompts you for confirmation before running the cmdlet. 119 | 120 | ```yaml 121 | Type: SwitchParameter 122 | Parameter Sets: (All) 123 | Aliases: cf 124 | 125 | Required: False 126 | Position: Named 127 | Default value: None 128 | Accept pipeline input: False 129 | Accept wildcard characters: False 130 | ``` 131 | 132 | ### CommonParameters 133 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. 134 | For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). 135 | 136 | ## INPUTS 137 | 138 | ## OUTPUTS 139 | 140 | ## NOTES 141 | Version: 1.0 142 | Author: Alex Verboon 143 | Creation Date: 16.03.2020 144 | Purpose/Change: Initial script development 145 | 146 | ## RELATED LINKS 147 | -------------------------------------------------------------------------------- /docs/Remove-MDATPIndicator.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: PSMDATP-help.xml 3 | Module Name: PSMDATP 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Remove-MDATPIndicator 9 | 10 | ## SYNOPSIS 11 | Remove-MDATPIndicator 12 | 13 | ## SYNTAX 14 | 15 | ``` 16 | Remove-MDATPIndicator [-IndicatorID] [[-MTPConfigFile] ] [-WhatIf] [-Confirm] 17 | [] 18 | ``` 19 | 20 | ## DESCRIPTION 21 | Remove-MDATPIndicator removes a custom indicator from the Microsoft Defender ATP 22 | instance 23 | 24 | ## EXAMPLES 25 | 26 | ### EXAMPLE 1 27 | ``` 28 | Remove-MDATPIndicator -IndicatorID 25 29 | ``` 30 | 31 | This command removes the custom indicator with id 25 32 | 33 | ## PARAMETERS 34 | 35 | ### -IndicatorID 36 | The unique custom indicator ID 37 | 38 | ```yaml 39 | Type: Int32 40 | Parameter Sets: (All) 41 | Aliases: 42 | 43 | Required: True 44 | Position: 1 45 | Default value: 0 46 | Accept pipeline input: False 47 | Accept wildcard characters: False 48 | ``` 49 | 50 | ### -MTPConfigFile 51 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 52 | 53 | ```yaml 54 | Type: String 55 | Parameter Sets: (All) 56 | Aliases: 57 | 58 | Required: False 59 | Position: 2 60 | Default value: None 61 | Accept pipeline input: False 62 | Accept wildcard characters: False 63 | ``` 64 | 65 | ### -WhatIf 66 | Shows what would happen if the cmdlet runs. 67 | The cmdlet is not run. 68 | 69 | ```yaml 70 | Type: SwitchParameter 71 | Parameter Sets: (All) 72 | Aliases: wi 73 | 74 | Required: False 75 | Position: Named 76 | Default value: None 77 | Accept pipeline input: False 78 | Accept wildcard characters: False 79 | ``` 80 | 81 | ### -Confirm 82 | Prompts you for confirmation before running the cmdlet. 83 | 84 | ```yaml 85 | Type: SwitchParameter 86 | Parameter Sets: (All) 87 | Aliases: cf 88 | 89 | Required: False 90 | Position: Named 91 | Default value: None 92 | Accept pipeline input: False 93 | Accept wildcard characters: False 94 | ``` 95 | 96 | ### CommonParameters 97 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. 98 | For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). 99 | 100 | ## INPUTS 101 | 102 | ## OUTPUTS 103 | 104 | ## NOTES 105 | Version: 1.0 106 | Author: Alex Verboon 107 | Creation Date: 05.05.2020 108 | Purpose/Change: Initial script development 109 | 110 | ## RELATED LINKS 111 | -------------------------------------------------------------------------------- /docs/Set-MDATPAlert.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: PSMDATP-help.xml 3 | Module Name: PSMDATP 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Set-MDATPAlert 9 | 10 | ## SYNOPSIS 11 | Set-MDATPAlert 12 | 13 | ## SYNTAX 14 | 15 | ``` 16 | Set-MDATPAlert [-AlertID] [[-status] ] [[-assignedTo] ] [[-classification] ] 17 | [[-determination] ] [[-comments] ] [[-MTPConfigFile] ] [-WhatIf] [-Confirm] 18 | [] 19 | ``` 20 | 21 | ## DESCRIPTION 22 | Set-MDATPAlert updates a Microsoft Defender Advanced Threat Protection alert through the Microsoft Defender Advanced Threat Protection Alerts Rest API. 23 | 24 | ## EXAMPLES 25 | 26 | ### EXAMPLE 1 27 | ``` 28 | Set-WDATPAlert -AlertID 121688558380765161_2136280442 -status Resolved -assignedTo secop2@contoso.com -classification FalsePositive -determination Malware -comments "Resolve my alert and assign to secop2 29 | ``` 30 | 31 | ## PARAMETERS 32 | 33 | ### -AlertID 34 | Identity of the Indicator entity. 35 | Required 36 | 37 | ```yaml 38 | Type: String 39 | Parameter Sets: (All) 40 | Aliases: 41 | 42 | Required: True 43 | Position: 1 44 | Default value: None 45 | Accept pipeline input: False 46 | Accept wildcard characters: False 47 | ``` 48 | 49 | ### -status 50 | The status that will be set for the alert in the organization. 51 | Possible values are: "New", "InProgress", and "Resolved". 52 | Optional 53 | 54 | ```yaml 55 | Type: String 56 | Parameter Sets: (All) 57 | Aliases: 58 | 59 | Required: False 60 | Position: 2 61 | Default value: None 62 | Accept pipeline input: False 63 | Accept wildcard characters: False 64 | ``` 65 | 66 | ### -assignedTo 67 | The userid that will be set for assigned to field for the the alert in the organization. 68 | Example: secop2@contoso.com. 69 | Optional 70 | 71 | ```yaml 72 | Type: String 73 | Parameter Sets: (All) 74 | Aliases: 75 | 76 | Required: False 77 | Position: 3 78 | Default value: None 79 | Accept pipeline input: False 80 | Accept wildcard characters: False 81 | ``` 82 | 83 | ### -classification 84 | The classification that will be set for the alert in the organization. 85 | Possible values are: "Unknown", "FalsePositive", and "TruePositive". 86 | Optional 87 | 88 | ```yaml 89 | Type: String 90 | Parameter Sets: (All) 91 | Aliases: 92 | 93 | Required: False 94 | Position: 4 95 | Default value: None 96 | Accept pipeline input: False 97 | Accept wildcard characters: False 98 | ``` 99 | 100 | ### -determination 101 | The determination that will be set for the alert in the organization. 102 | Possible values are: "NotAvailable", "Apt", "Malware", "SecurityPersonnel", "SecurityTesting", "UnwantedSoftware", and "Other". 103 | Optional 104 | 105 | ```yaml 106 | Type: String 107 | Parameter Sets: (All) 108 | Aliases: 109 | 110 | Required: False 111 | Position: 5 112 | Default value: None 113 | Accept pipeline input: False 114 | Accept wildcard characters: False 115 | ``` 116 | 117 | ### -comments 118 | The comment field that will be set for the the alert in the organization. 119 | Optional 120 | 121 | ```yaml 122 | Type: String 123 | Parameter Sets: (All) 124 | Aliases: 125 | 126 | Required: False 127 | Position: 6 128 | Default value: None 129 | Accept pipeline input: False 130 | Accept wildcard characters: False 131 | ``` 132 | 133 | ### -MTPConfigFile 134 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 135 | 136 | ```yaml 137 | Type: String 138 | Parameter Sets: (All) 139 | Aliases: 140 | 141 | Required: False 142 | Position: 7 143 | Default value: None 144 | Accept pipeline input: False 145 | Accept wildcard characters: False 146 | ``` 147 | 148 | ### -WhatIf 149 | Shows what would happen if the cmdlet runs. 150 | The cmdlet is not run. 151 | 152 | ```yaml 153 | Type: SwitchParameter 154 | Parameter Sets: (All) 155 | Aliases: wi 156 | 157 | Required: False 158 | Position: Named 159 | Default value: None 160 | Accept pipeline input: False 161 | Accept wildcard characters: False 162 | ``` 163 | 164 | ### -Confirm 165 | Prompts you for confirmation before running the cmdlet. 166 | 167 | ```yaml 168 | Type: SwitchParameter 169 | Parameter Sets: (All) 170 | Aliases: cf 171 | 172 | Required: False 173 | Position: Named 174 | Default value: None 175 | Accept pipeline input: False 176 | Accept wildcard characters: False 177 | ``` 178 | 179 | ### CommonParameters 180 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. 181 | For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). 182 | 183 | ## INPUTS 184 | 185 | ## OUTPUTS 186 | 187 | ## NOTES 188 | Version: 1.0 189 | Author: Daniel Lacher 190 | Creation Date: 02.11.2020 191 | Purpose/Change: Initial pass at creation of function to allow for update to MDATP Alerts via API and PSMDATP framework. 192 | 193 | ## RELATED LINKS 194 | -------------------------------------------------------------------------------- /docs/Start-MDATPAVScan.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: PSMDATP-help.xml 3 | Module Name: PSMDATP 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Start-MDATPAVScan 9 | 10 | ## SYNOPSIS 11 | Start-MDATPAVScan 12 | 13 | ## SYNTAX 14 | 15 | ### DeviceName 16 | ``` 17 | Start-MDATPAVScan -DeviceName -ScanType [-Comment ] [-MTPConfigFile ] 18 | [-WhatIf] [-Confirm] [] 19 | ``` 20 | 21 | ### DeviceID 22 | ``` 23 | Start-MDATPAVScan -DeviceID -ScanType [-Comment ] [-MTPConfigFile ] [-WhatIf] 24 | [-Confirm] [] 25 | ``` 26 | 27 | ## DESCRIPTION 28 | Start-MDATPAVScan initiates an Antivirus scan on the specified device 29 | 30 | ## EXAMPLES 31 | 32 | ### EXAMPLE 1 33 | ``` 34 | Start-MDATPAVScan -DeviceName testclient6 -ScanType Quick -Comment "better check" 35 | ``` 36 | 37 | This command starts a quck AV scan on device testclient6 38 | 39 | ## PARAMETERS 40 | 41 | ### -DeviceName 42 | Computername of the device 43 | 44 | ```yaml 45 | Type: String 46 | Parameter Sets: DeviceName 47 | Aliases: 48 | 49 | Required: True 50 | Position: Named 51 | Default value: None 52 | Accept pipeline input: False 53 | Accept wildcard characters: False 54 | ``` 55 | 56 | ### -DeviceID 57 | The unique device ID of the device 58 | 59 | ```yaml 60 | Type: String 61 | Parameter Sets: DeviceID 62 | Aliases: 63 | 64 | Required: True 65 | Position: Named 66 | Default value: None 67 | Accept pipeline input: False 68 | Accept wildcard characters: False 69 | ``` 70 | 71 | ### -ScanType 72 | The type of scan to perform, Full or Quick 73 | 74 | ```yaml 75 | Type: String 76 | Parameter Sets: (All) 77 | Aliases: 78 | 79 | Required: True 80 | Position: Named 81 | Default value: None 82 | Accept pipeline input: False 83 | Accept wildcard characters: False 84 | ``` 85 | 86 | ### -Comment 87 | Comment that is added to the request, if no comment is provided the default commment 'submitted by automation' is used. 88 | 89 | ```yaml 90 | Type: String 91 | Parameter Sets: (All) 92 | Aliases: 93 | 94 | Required: False 95 | Position: Named 96 | Default value: None 97 | Accept pipeline input: False 98 | Accept wildcard characters: False 99 | ``` 100 | 101 | ### -MTPConfigFile 102 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 103 | 104 | ```yaml 105 | Type: String 106 | Parameter Sets: (All) 107 | Aliases: 108 | 109 | Required: False 110 | Position: Named 111 | Default value: None 112 | Accept pipeline input: False 113 | Accept wildcard characters: False 114 | ``` 115 | 116 | ### -WhatIf 117 | Shows what would happen if the cmdlet runs. 118 | The cmdlet is not run. 119 | 120 | ```yaml 121 | Type: SwitchParameter 122 | Parameter Sets: (All) 123 | Aliases: wi 124 | 125 | Required: False 126 | Position: Named 127 | Default value: None 128 | Accept pipeline input: False 129 | Accept wildcard characters: False 130 | ``` 131 | 132 | ### -Confirm 133 | Prompts you for confirmation before running the cmdlet. 134 | 135 | ```yaml 136 | Type: SwitchParameter 137 | Parameter Sets: (All) 138 | Aliases: cf 139 | 140 | Required: False 141 | Position: Named 142 | Default value: None 143 | Accept pipeline input: False 144 | Accept wildcard characters: False 145 | ``` 146 | 147 | ### CommonParameters 148 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. 149 | For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). 150 | 151 | ## INPUTS 152 | 153 | ## OUTPUTS 154 | 155 | ## NOTES 156 | Version: 1.0 157 | Author: Alex Verboon 158 | Creation Date: 17.03.2020 159 | Purpose/Change: Initial script development 160 | 161 | ## RELATED LINKS 162 | -------------------------------------------------------------------------------- /docs/Start-MDATPAppRestriction.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: PSMDATP-help.xml 3 | Module Name: PSMDATP 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Start-MDATPAppRestriction 9 | 10 | ## SYNOPSIS 11 | Start-MDATPAppRestriction 12 | 13 | ## SYNTAX 14 | 15 | ### DeviceName 16 | ``` 17 | Start-MDATPAppRestriction -DeviceName [-Comment ] [-MTPConfigFile ] [-WhatIf] 18 | [-Confirm] [] 19 | ``` 20 | 21 | ### DeviceID 22 | ``` 23 | Start-MDATPAppRestriction -DeviceID [-Comment ] [-MTPConfigFile ] [-WhatIf] [-Confirm] 24 | [] 25 | ``` 26 | 27 | ## DESCRIPTION 28 | Start-MDATPAppRestriction restricts execution of all applications on the machine. 29 | 30 | ## EXAMPLES 31 | 32 | ### EXAMPLE 1 33 | ``` 34 | Start-MDATPAppRestriction -DeviceName computer02 -Comment "incident1973" 35 | ``` 36 | 37 | This command restricts application execution on device computer02 38 | 39 | ## PARAMETERS 40 | 41 | ### -DeviceName 42 | Computername of the device 43 | 44 | ```yaml 45 | Type: String 46 | Parameter Sets: DeviceName 47 | Aliases: 48 | 49 | Required: True 50 | Position: Named 51 | Default value: None 52 | Accept pipeline input: False 53 | Accept wildcard characters: False 54 | ``` 55 | 56 | ### -DeviceID 57 | The unique device ID of the device 58 | 59 | ```yaml 60 | Type: String 61 | Parameter Sets: DeviceID 62 | Aliases: 63 | 64 | Required: True 65 | Position: Named 66 | Default value: None 67 | Accept pipeline input: False 68 | Accept wildcard characters: False 69 | ``` 70 | 71 | ### -Comment 72 | Comment that is added to the request, if no comment is provided the default commment 'submitted by automation' is used. 73 | 74 | ```yaml 75 | Type: String 76 | Parameter Sets: (All) 77 | Aliases: 78 | 79 | Required: False 80 | Position: Named 81 | Default value: None 82 | Accept pipeline input: False 83 | Accept wildcard characters: False 84 | ``` 85 | 86 | ### -MTPConfigFile 87 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 88 | 89 | ```yaml 90 | Type: String 91 | Parameter Sets: (All) 92 | Aliases: 93 | 94 | Required: False 95 | Position: Named 96 | Default value: None 97 | Accept pipeline input: False 98 | Accept wildcard characters: False 99 | ``` 100 | 101 | ### -WhatIf 102 | Shows what would happen if the cmdlet runs. 103 | The cmdlet is not run. 104 | 105 | ```yaml 106 | Type: SwitchParameter 107 | Parameter Sets: (All) 108 | Aliases: wi 109 | 110 | Required: False 111 | Position: Named 112 | Default value: None 113 | Accept pipeline input: False 114 | Accept wildcard characters: False 115 | ``` 116 | 117 | ### -Confirm 118 | Prompts you for confirmation before running the cmdlet. 119 | 120 | ```yaml 121 | Type: SwitchParameter 122 | Parameter Sets: (All) 123 | Aliases: cf 124 | 125 | Required: False 126 | Position: Named 127 | Default value: None 128 | Accept pipeline input: False 129 | Accept wildcard characters: False 130 | ``` 131 | 132 | ### CommonParameters 133 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. 134 | For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). 135 | 136 | ## INPUTS 137 | 138 | ## OUTPUTS 139 | 140 | ## NOTES 141 | Version: 1.0 142 | Author: Alex Verboon 143 | Creation Date: 12.04.2020 144 | Purpose/Change: Initial script development 145 | 146 | ## RELATED LINKS 147 | -------------------------------------------------------------------------------- /docs/Start-MDATPInvestigation.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: PSMDATP-help.xml 3 | Module Name: PSMDATP 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Start-MDATPInvestigation 9 | 10 | ## SYNOPSIS 11 | Start-MDATPInvestigation 12 | 13 | ## SYNTAX 14 | 15 | ### DeviceName 16 | ``` 17 | Start-MDATPInvestigation -DeviceName [-Comment ] [-MTPConfigFile ] [-WhatIf] 18 | [-Confirm] [] 19 | ``` 20 | 21 | ### DeviceID 22 | ``` 23 | Start-MDATPInvestigation -DeviceID [-Comment ] [-MTPConfigFile ] [-WhatIf] [-Confirm] 24 | [] 25 | ``` 26 | 27 | ## DESCRIPTION 28 | Start-MDATPInvestigation initiates an automated investigation on the targeted device 29 | 30 | ## EXAMPLES 31 | 32 | ### EXAMPLE 1 33 | ``` 34 | Start-MDATPInvestigation -DeviceName computer02 -Comment "incident1973" 35 | ``` 36 | 37 | This command starts an automated investigation on device computer02 38 | 39 | ## PARAMETERS 40 | 41 | ### -DeviceName 42 | Computername of the device 43 | 44 | ```yaml 45 | Type: String 46 | Parameter Sets: DeviceName 47 | Aliases: 48 | 49 | Required: True 50 | Position: Named 51 | Default value: None 52 | Accept pipeline input: False 53 | Accept wildcard characters: False 54 | ``` 55 | 56 | ### -DeviceID 57 | The unique device ID of the device 58 | 59 | ```yaml 60 | Type: String 61 | Parameter Sets: DeviceID 62 | Aliases: 63 | 64 | Required: True 65 | Position: Named 66 | Default value: None 67 | Accept pipeline input: False 68 | Accept wildcard characters: False 69 | ``` 70 | 71 | ### -Comment 72 | Comment that is added to the request, if no comment is provided the default commment 'submitted by automation' is used. 73 | Comment to associate with the action 74 | 75 | ```yaml 76 | Type: String 77 | Parameter Sets: (All) 78 | Aliases: 79 | 80 | Required: False 81 | Position: Named 82 | Default value: None 83 | Accept pipeline input: False 84 | Accept wildcard characters: False 85 | ``` 86 | 87 | ### -MTPConfigFile 88 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 89 | 90 | ```yaml 91 | Type: String 92 | Parameter Sets: (All) 93 | Aliases: 94 | 95 | Required: False 96 | Position: Named 97 | Default value: None 98 | Accept pipeline input: False 99 | Accept wildcard characters: False 100 | ``` 101 | 102 | ### -WhatIf 103 | Shows what would happen if the cmdlet runs. 104 | The cmdlet is not run. 105 | 106 | ```yaml 107 | Type: SwitchParameter 108 | Parameter Sets: (All) 109 | Aliases: wi 110 | 111 | Required: False 112 | Position: Named 113 | Default value: None 114 | Accept pipeline input: False 115 | Accept wildcard characters: False 116 | ``` 117 | 118 | ### -Confirm 119 | Prompts you for confirmation before running the cmdlet. 120 | 121 | ```yaml 122 | Type: SwitchParameter 123 | Parameter Sets: (All) 124 | Aliases: cf 125 | 126 | Required: False 127 | Position: Named 128 | Default value: None 129 | Accept pipeline input: False 130 | Accept wildcard characters: False 131 | ``` 132 | 133 | ### CommonParameters 134 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. 135 | For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). 136 | 137 | ## INPUTS 138 | 139 | ## OUTPUTS 140 | 141 | ## NOTES 142 | Version: 1.0 143 | Author: Alex Verboon 144 | Creation Date: 17.03.2020 145 | Purpose/Change: Initial script development 146 | 147 | ## RELATED LINKS 148 | -------------------------------------------------------------------------------- /docs/Start-MDATPInvestigationPackageCollection.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: PSMDATP-help.xml 3 | Module Name: PSMDATP 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Start-MDATPInvestigationPackageCollection 9 | 10 | ## SYNOPSIS 11 | Start-MDATPInvestigationPackageCollection 12 | 13 | ## SYNTAX 14 | 15 | ### DeviceName 16 | ``` 17 | Start-MDATPInvestigationPackageCollection -DeviceName [-Comment ] [-MTPConfigFile ] 18 | [-WhatIf] [-Confirm] [] 19 | ``` 20 | 21 | ### DeviceID 22 | ``` 23 | Start-MDATPInvestigationPackageCollection -DeviceID [-Comment ] [-MTPConfigFile ] 24 | [-WhatIf] [-Confirm] [] 25 | ``` 26 | 27 | ## DESCRIPTION 28 | Start-MDATPInvestigationPackageCollection initiates the collection of an investigation package 29 | 30 | ## EXAMPLES 31 | 32 | ### EXAMPLE 1 33 | ``` 34 | Start-MDATPInvestigationPackageCollection -DeviceName computer02 35 | ``` 36 | 37 | This command starts the collection of the investigation package on device computer02 38 | 39 | ## PARAMETERS 40 | 41 | ### -DeviceName 42 | Computername of the device 43 | 44 | ```yaml 45 | Type: String 46 | Parameter Sets: DeviceName 47 | Aliases: 48 | 49 | Required: True 50 | Position: Named 51 | Default value: None 52 | Accept pipeline input: False 53 | Accept wildcard characters: False 54 | ``` 55 | 56 | ### -DeviceID 57 | The unique device ID of the device 58 | 59 | ```yaml 60 | Type: String 61 | Parameter Sets: DeviceID 62 | Aliases: 63 | 64 | Required: True 65 | Position: Named 66 | Default value: None 67 | Accept pipeline input: False 68 | Accept wildcard characters: False 69 | ``` 70 | 71 | ### -Comment 72 | Comment that is added to the request, if no comment is provided the default commment 'submitted by automation' is used. 73 | 74 | ```yaml 75 | Type: String 76 | Parameter Sets: (All) 77 | Aliases: 78 | 79 | Required: False 80 | Position: Named 81 | Default value: None 82 | Accept pipeline input: False 83 | Accept wildcard characters: False 84 | ``` 85 | 86 | ### -MTPConfigFile 87 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 88 | 89 | ```yaml 90 | Type: String 91 | Parameter Sets: (All) 92 | Aliases: 93 | 94 | Required: False 95 | Position: Named 96 | Default value: None 97 | Accept pipeline input: False 98 | Accept wildcard characters: False 99 | ``` 100 | 101 | ### -WhatIf 102 | Shows what would happen if the cmdlet runs. 103 | The cmdlet is not run. 104 | 105 | ```yaml 106 | Type: SwitchParameter 107 | Parameter Sets: (All) 108 | Aliases: wi 109 | 110 | Required: False 111 | Position: Named 112 | Default value: None 113 | Accept pipeline input: False 114 | Accept wildcard characters: False 115 | ``` 116 | 117 | ### -Confirm 118 | Prompts you for confirmation before running the cmdlet. 119 | 120 | ```yaml 121 | Type: SwitchParameter 122 | Parameter Sets: (All) 123 | Aliases: cf 124 | 125 | Required: False 126 | Position: Named 127 | Default value: None 128 | Accept pipeline input: False 129 | Accept wildcard characters: False 130 | ``` 131 | 132 | ### CommonParameters 133 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. 134 | For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). 135 | 136 | ## INPUTS 137 | 138 | ## OUTPUTS 139 | 140 | ## NOTES 141 | Version: 1.0 142 | Author: Alex Verboon 143 | Creation Date: 17.03.2020 144 | Purpose/Change: Initial script development 145 | 146 | ## RELATED LINKS 147 | -------------------------------------------------------------------------------- /docs/Start-MDATPIsolation.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: PSMDATP-help.xml 3 | Module Name: PSMDATP 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Start-MDATPIsolation 9 | 10 | ## SYNOPSIS 11 | Start-MDATPIsolation 12 | 13 | ## SYNTAX 14 | 15 | ### DeviceName 16 | ``` 17 | Start-MDATPIsolation -DeviceName -IsolationType [-Comment ] [-MTPConfigFile ] 18 | [-WhatIf] [-Confirm] [] 19 | ``` 20 | 21 | ### DeviceID 22 | ``` 23 | Start-MDATPIsolation -DeviceID -IsolationType [-Comment ] [-MTPConfigFile ] 24 | [-WhatIf] [-Confirm] [] 25 | ``` 26 | 27 | ## DESCRIPTION 28 | Start-MDATPIsolation initiates the isolation of the specified device from the network 29 | 30 | ## EXAMPLES 31 | 32 | ### EXAMPLE 1 33 | ``` 34 | Start-MDATPIsolation -DeviceName computer02 -IsolationType Full -Comment "incident1973" 35 | ``` 36 | 37 | This command isolates device computer02 from the network 38 | 39 | ### EXAMPLE 2 40 | ``` 41 | Start-MDATPIsolation -DeviceName computer02 -IsolationType Selective -Comment "incident1973" 42 | ``` 43 | 44 | This command isolates device computer02 from the network but allows communication through Outlook and Skype 45 | 46 | ## PARAMETERS 47 | 48 | ### -DeviceName 49 | Computername of the device 50 | 51 | ```yaml 52 | Type: String 53 | Parameter Sets: DeviceName 54 | Aliases: 55 | 56 | Required: True 57 | Position: Named 58 | Default value: None 59 | Accept pipeline input: False 60 | Accept wildcard characters: False 61 | ``` 62 | 63 | ### -DeviceID 64 | The unique device ID of the device 65 | 66 | ```yaml 67 | Type: String 68 | Parameter Sets: DeviceID 69 | Aliases: 70 | 71 | Required: True 72 | Position: Named 73 | Default value: None 74 | Accept pipeline input: False 75 | Accept wildcard characters: False 76 | ``` 77 | 78 | ### -IsolationType 79 | Type of the isolation. 80 | Allowed values are: 'Full' or 'Selective'. 81 | 82 | ```yaml 83 | Type: String 84 | Parameter Sets: (All) 85 | Aliases: 86 | 87 | Required: True 88 | Position: Named 89 | Default value: None 90 | Accept pipeline input: False 91 | Accept wildcard characters: False 92 | ``` 93 | 94 | ### -Comment 95 | Comment that is added to the request, if no comment is provided the default commment 'submitted by automation' is used. 96 | 97 | ```yaml 98 | Type: String 99 | Parameter Sets: (All) 100 | Aliases: 101 | 102 | Required: False 103 | Position: Named 104 | Default value: None 105 | Accept pipeline input: False 106 | Accept wildcard characters: False 107 | ``` 108 | 109 | ### -MTPConfigFile 110 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 111 | 112 | ```yaml 113 | Type: String 114 | Parameter Sets: (All) 115 | Aliases: 116 | 117 | Required: False 118 | Position: Named 119 | Default value: None 120 | Accept pipeline input: False 121 | Accept wildcard characters: False 122 | ``` 123 | 124 | ### -WhatIf 125 | Shows what would happen if the cmdlet runs. 126 | The cmdlet is not run. 127 | 128 | ```yaml 129 | Type: SwitchParameter 130 | Parameter Sets: (All) 131 | Aliases: wi 132 | 133 | Required: False 134 | Position: Named 135 | Default value: None 136 | Accept pipeline input: False 137 | Accept wildcard characters: False 138 | ``` 139 | 140 | ### -Confirm 141 | Prompts you for confirmation before running the cmdlet. 142 | 143 | ```yaml 144 | Type: SwitchParameter 145 | Parameter Sets: (All) 146 | Aliases: cf 147 | 148 | Required: False 149 | Position: Named 150 | Default value: None 151 | Accept pipeline input: False 152 | Accept wildcard characters: False 153 | ``` 154 | 155 | ### CommonParameters 156 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. 157 | For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). 158 | 159 | ## INPUTS 160 | 161 | ## OUTPUTS 162 | 163 | ## NOTES 164 | Version: 1.0 165 | Author: Alex Verboon 166 | Creation Date: 12.04.2020 167 | Purpose/Change: Initial script development 168 | 169 | ## RELATED LINKS 170 | -------------------------------------------------------------------------------- /docs/Stop-MDATPAppRestriction.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: PSMDATP-help.xml 3 | Module Name: PSMDATP 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Stop-MDATPAppRestriction 9 | 10 | ## SYNOPSIS 11 | Stop-MDATPAppRestriction 12 | 13 | ## SYNTAX 14 | 15 | ### DeviceName 16 | ``` 17 | Stop-MDATPAppRestriction -DeviceName [-Comment ] [-MTPConfigFile ] [-WhatIf] 18 | [-Confirm] [] 19 | ``` 20 | 21 | ### DeviceID 22 | ``` 23 | Stop-MDATPAppRestriction -DeviceID [-Comment ] [-MTPConfigFile ] [-WhatIf] [-Confirm] 24 | [] 25 | ``` 26 | 27 | ## DESCRIPTION 28 | Stop-MDATPAppRestriction removes app execution restrictions on the machine. 29 | 30 | ## EXAMPLES 31 | 32 | ### EXAMPLE 1 33 | ``` 34 | Stop-MDATPAppRestriction -DeviceName computer02 -Comment "incident1973" 35 | ``` 36 | 37 | This command removes app execution restrictions from device computer02 38 | 39 | ## PARAMETERS 40 | 41 | ### -DeviceName 42 | Computername of the device 43 | 44 | ```yaml 45 | Type: String 46 | Parameter Sets: DeviceName 47 | Aliases: 48 | 49 | Required: True 50 | Position: Named 51 | Default value: None 52 | Accept pipeline input: False 53 | Accept wildcard characters: False 54 | ``` 55 | 56 | ### -DeviceID 57 | The unique device ID of the device 58 | 59 | ```yaml 60 | Type: String 61 | Parameter Sets: DeviceID 62 | Aliases: 63 | 64 | Required: True 65 | Position: Named 66 | Default value: None 67 | Accept pipeline input: False 68 | Accept wildcard characters: False 69 | ``` 70 | 71 | ### -Comment 72 | Comment that is added to the request, if no comment is provided the default commment 'submitted by automation' is used. 73 | 74 | ```yaml 75 | Type: String 76 | Parameter Sets: (All) 77 | Aliases: 78 | 79 | Required: False 80 | Position: Named 81 | Default value: None 82 | Accept pipeline input: False 83 | Accept wildcard characters: False 84 | ``` 85 | 86 | ### -MTPConfigFile 87 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 88 | 89 | ```yaml 90 | Type: String 91 | Parameter Sets: (All) 92 | Aliases: 93 | 94 | Required: False 95 | Position: Named 96 | Default value: None 97 | Accept pipeline input: False 98 | Accept wildcard characters: False 99 | ``` 100 | 101 | ### -WhatIf 102 | Shows what would happen if the cmdlet runs. 103 | The cmdlet is not run. 104 | 105 | ```yaml 106 | Type: SwitchParameter 107 | Parameter Sets: (All) 108 | Aliases: wi 109 | 110 | Required: False 111 | Position: Named 112 | Default value: None 113 | Accept pipeline input: False 114 | Accept wildcard characters: False 115 | ``` 116 | 117 | ### -Confirm 118 | Prompts you for confirmation before running the cmdlet. 119 | 120 | ```yaml 121 | Type: SwitchParameter 122 | Parameter Sets: (All) 123 | Aliases: cf 124 | 125 | Required: False 126 | Position: Named 127 | Default value: None 128 | Accept pipeline input: False 129 | Accept wildcard characters: False 130 | ``` 131 | 132 | ### CommonParameters 133 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. 134 | For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). 135 | 136 | ## INPUTS 137 | 138 | ## OUTPUTS 139 | 140 | ## NOTES 141 | Version: 1.0 142 | Author: Alex Verboon 143 | Creation Date: 12.04.2020 144 | Purpose/Change: Initial script development 145 | 146 | ## RELATED LINKS 147 | -------------------------------------------------------------------------------- /docs/Stop-MDATPIsolation.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: PSMDATP-help.xml 3 | Module Name: PSMDATP 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Stop-MDATPIsolation 9 | 10 | ## SYNOPSIS 11 | Stop-MDATPIsolation 12 | 13 | ## SYNTAX 14 | 15 | ### DeviceName 16 | ``` 17 | Stop-MDATPIsolation -DeviceName [-Comment ] [-MTPConfigFile ] [-WhatIf] [-Confirm] 18 | [] 19 | ``` 20 | 21 | ### DeviceID 22 | ``` 23 | Stop-MDATPIsolation -DeviceID [-Comment ] [-MTPConfigFile ] [-WhatIf] [-Confirm] 24 | [] 25 | ``` 26 | 27 | ## DESCRIPTION 28 | Stop-MDATPIsolation removes network isolation for the specified device 29 | 30 | ## EXAMPLES 31 | 32 | ### EXAMPLE 1 33 | ``` 34 | Stop-MDATPIsolation -DeviceName computer02 -Comment "incident1973" 35 | ``` 36 | 37 | This command removes network isolation for device computer02 38 | 39 | ## PARAMETERS 40 | 41 | ### -DeviceName 42 | Computername of the device 43 | 44 | ```yaml 45 | Type: String 46 | Parameter Sets: DeviceName 47 | Aliases: 48 | 49 | Required: True 50 | Position: Named 51 | Default value: None 52 | Accept pipeline input: False 53 | Accept wildcard characters: False 54 | ``` 55 | 56 | ### -DeviceID 57 | The unique device ID of the device 58 | 59 | ```yaml 60 | Type: String 61 | Parameter Sets: DeviceID 62 | Aliases: 63 | 64 | Required: True 65 | Position: Named 66 | Default value: None 67 | Accept pipeline input: False 68 | Accept wildcard characters: False 69 | ``` 70 | 71 | ### -Comment 72 | Comment that is added to the request, if no comment is provided the default commment 'submitted by automation' is used. 73 | 74 | ```yaml 75 | Type: String 76 | Parameter Sets: (All) 77 | Aliases: 78 | 79 | Required: False 80 | Position: Named 81 | Default value: None 82 | Accept pipeline input: False 83 | Accept wildcard characters: False 84 | ``` 85 | 86 | ### -MTPConfigFile 87 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 88 | 89 | ```yaml 90 | Type: String 91 | Parameter Sets: (All) 92 | Aliases: 93 | 94 | Required: False 95 | Position: Named 96 | Default value: None 97 | Accept pipeline input: False 98 | Accept wildcard characters: False 99 | ``` 100 | 101 | ### -WhatIf 102 | Shows what would happen if the cmdlet runs. 103 | The cmdlet is not run. 104 | 105 | ```yaml 106 | Type: SwitchParameter 107 | Parameter Sets: (All) 108 | Aliases: wi 109 | 110 | Required: False 111 | Position: Named 112 | Default value: None 113 | Accept pipeline input: False 114 | Accept wildcard characters: False 115 | ``` 116 | 117 | ### -Confirm 118 | Prompts you for confirmation before running the cmdlet. 119 | 120 | ```yaml 121 | Type: SwitchParameter 122 | Parameter Sets: (All) 123 | Aliases: cf 124 | 125 | Required: False 126 | Position: Named 127 | Default value: None 128 | Accept pipeline input: False 129 | Accept wildcard characters: False 130 | ``` 131 | 132 | ### CommonParameters 133 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. 134 | For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). 135 | 136 | ## INPUTS 137 | 138 | ## OUTPUTS 139 | 140 | ## NOTES 141 | Version: 1.0 142 | Author: Alex Verboon 143 | Creation Date: 12.04.2020 144 | Purpose/Change: Initial script development 145 | 146 | ## RELATED LINKS 147 | -------------------------------------------------------------------------------- /media/apppermissions.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/alexverboon/PSMDATP/db3f639d0b7710b63c2ac2951e00d46b30643d80/media/apppermissions.png -------------------------------------------------------------------------------- /media/psmdatp.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/alexverboon/PSMDATP/db3f639d0b7710b63c2ac2951e00d46b30643d80/media/psmdatp.png -------------------------------------------------------------------------------- /media/small_psmdatp.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/alexverboon/PSMDATP/db3f639d0b7710b63c2ac2951e00d46b30643d80/media/small_psmdatp.png -------------------------------------------------------------------------------- /src/PSMDATP.Settings.ps1: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/alexverboon/PSMDATP/db3f639d0b7710b63c2ac2951e00d46b30643d80/src/PSMDATP.Settings.ps1 -------------------------------------------------------------------------------- /src/PSMDATP/Imports.ps1: -------------------------------------------------------------------------------- 1 | # This is a locally sourced Imports file for local development. 2 | # It can be imported by the psm1 in local development to add script level variables. 3 | # It will merged in the build process. This is for local development only. 4 | 5 | # region script variables 6 | # $script:resourcePath = "$PSScriptRoot\Resources" 7 | -------------------------------------------------------------------------------- /src/PSMDATP/PSMDATP.psd1: -------------------------------------------------------------------------------- 1 | # 2 | # Module manifest for module 'PSMDATP' 3 | # 4 | # Generated by: Alex Verboon 5 | # 6 | # Generated on: 12/22/2020 7 | # 8 | 9 | @{ 10 | 11 | # Script module or binary module file associated with this manifest. 12 | RootModule = 'PSMDATP.psm1' 13 | 14 | # Version number of this module. 15 | ModuleVersion = '1.1.0' 16 | 17 | # Supported PSEditions 18 | # CompatiblePSEditions = @() 19 | 20 | # ID used to uniquely identify this module 21 | GUID = '5b1f66a1-78d5-4d12-9c89-0bb749da773f' 22 | 23 | # Author of this module 24 | Author = 'Alex Verboon' 25 | 26 | # Company or vendor of this module 27 | CompanyName = 'Anything About IT' 28 | 29 | # Copyright statement for this module 30 | Copyright = '(c) 2020 Alex Verboon. All rights reserved.' 31 | 32 | # Description of the functionality provided by this module 33 | Description = '"Manage Microsoft Defender for Endpoint with PowerShell"' 34 | 35 | # Minimum version of the Windows PowerShell engine required by this module 36 | # PowerShellVersion = '' 37 | 38 | # Name of the Windows PowerShell host required by this module 39 | # PowerShellHostName = '' 40 | 41 | # Minimum version of the Windows PowerShell host required by this module 42 | # PowerShellHostVersion = '' 43 | 44 | # Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only. 45 | # DotNetFrameworkVersion = '' 46 | 47 | # Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only. 48 | # CLRVersion = '' 49 | 50 | # Processor architecture (None, X86, Amd64) required by this module 51 | # ProcessorArchitecture = '' 52 | 53 | # Modules that must be imported into the global environment prior to importing this module 54 | # RequiredModules = @() 55 | 56 | # Assemblies that must be loaded prior to importing this module 57 | # RequiredAssemblies = @() 58 | 59 | # Script files (.ps1) that are run in the caller's environment prior to importing this module. 60 | # ScriptsToProcess = @() 61 | 62 | # Type files (.ps1xml) to be loaded when importing this module 63 | # TypesToProcess = @() 64 | 65 | # Format files (.ps1xml) to be loaded when importing this module 66 | # FormatsToProcess = @() 67 | 68 | # Modules to import as nested modules of the module specified in RootModule/ModuleToProcess 69 | # NestedModules = @() 70 | 71 | # Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export. 72 | FunctionsToExport = 'Add-MDATPDeviceTag', 73 | 'Add-MDATPIndicator', 74 | 'Get-MDATPAlert', 75 | 'Get-MDATPCollectionPackageUri', 76 | 'Get-MDATPDevice','Get-MDATPDeviceAction', 77 | 'Get-MDATPDeviceTag', 78 | 'Get-MDATPEndpointStatus', 79 | 'Get-MDATPIndicator', 80 | 'Get-MDATPInvestigation', 81 | 'Get-MDATPQuery', 82 | 'Get-MDATPTvmVulnerability', 83 | 'Get-MDATPTvmRecommendation', 84 | 'Remove-MDATPDevice', 85 | 'Remove-MDATPDeviceTag', 86 | 'Remove-MDATPIndicator', 87 | 'Start-MDATPAppRestriction', 88 | 'Start-MDATPAVScan', 89 | 'Set-MDATPAlert', 90 | 'Start-MDATPInvestigation', 91 | 'Start-MDATPInvestigationPackageCollection', 92 | 'Start-MDATPIsolation', 93 | 'Stop-MDATPAppRestriction', 94 | 'Stop-MDATPIsolation' 95 | 96 | # Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export. 97 | CmdletsToExport = '*' 98 | 99 | # Variables to export from this module 100 | VariablesToExport = '*' 101 | 102 | # Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export. 103 | AliasesToExport = '*' 104 | 105 | # DSC resources to export from this module 106 | # DscResourcesToExport = @() 107 | 108 | # List of all modules packaged with this module 109 | # ModuleList = @() 110 | 111 | # List of all files packaged with this module 112 | # FileList = @() 113 | 114 | # Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell. 115 | PrivateData = @{ 116 | 117 | PSData = @{ 118 | 119 | # Tags applied to this module. These help with module discovery in online galleries. 120 | Tags = @( 121 | 'PowerShell','MDATP','Security','MicrosoftDefender','MicrosoftDefenderATP','Automation','API','MDE','DefenderforEndpoint') 122 | 123 | # A URL to the license for this module. 124 | # LicenseUri = '' 125 | 126 | # A URL to the main website for this project. 127 | ProjectUri = 'https://github.com/alexverboon/PSMDATP' 128 | 129 | # A URL to an icon representing this module. 130 | # IconUri = '' 131 | 132 | # ReleaseNotes of this module 133 | # ReleaseNotes = '' 134 | 135 | } # End of PSData hashtable 136 | 137 | } # End of PrivateData hashtable 138 | 139 | # HelpInfo URI of this module 140 | # HelpInfoURI = '' 141 | 142 | # Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix. 143 | # DefaultCommandPrefix = '' 144 | 145 | } 146 | 147 | 148 | -------------------------------------------------------------------------------- /src/PSMDATP/PSMDATP.psm1: -------------------------------------------------------------------------------- 1 | # this psm1 is for local testing and development use only 2 | 3 | # dot source the parent import for local development variables 4 | . $PSScriptRoot\Imports.ps1 5 | 6 | # discover all ps1 file(s) in Public and Private paths 7 | 8 | $itemSplat = @{ 9 | Filter = '*.ps1' 10 | Recurse = $true 11 | ErrorAction = 'Stop' 12 | } 13 | try { 14 | $public = @(Get-ChildItem -Path "$PSScriptRoot\Public" @itemSplat) 15 | $private = @(Get-ChildItem -Path "$PSScriptRoot\Private" @itemSplat) 16 | } 17 | catch { 18 | Write-Error $_ 19 | throw "Unable to get get file information from Public & Private src." 20 | } 21 | 22 | # dot source all .ps1 file(s) found 23 | foreach ($file in @($public + $private)) { 24 | try { 25 | . $file.FullName 26 | } 27 | catch { 28 | throw "Unable to dot source [$($file.FullName)]" 29 | 30 | } 31 | } 32 | 33 | # export all public functions 34 | Export-ModuleMember -Function $public.Basename -------------------------------------------------------------------------------- /src/PSMDATP/Public/Add-MDATPDeviceTag.ps1: -------------------------------------------------------------------------------- 1 | function Add-MDATPDeviceTag{ 2 | <# 3 | .Synopsis 4 | Add-MDATPDeviceTag 5 | 6 | .DESCRIPTION 7 | Add-MDATPDeviceTag adds the specified Tag to the MDATP device 8 | 9 | .PARAMETER DeviceName 10 | Computername of the device 11 | 12 | .PARAMETER DeviceID 13 | The unique device ID of the device 14 | 15 | .PARAMETER Tag 16 | The value of the tag to be added 17 | 18 | .PARAMETER MTPConfigFile 19 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 20 | 21 | .EXAMPLE 22 | Add-MDATPDeviceTag -DeviceName computer02 -Tag 'Testing' -verbose 23 | 24 | This command adds the tag 'testing' to the device 'computer02' 25 | 26 | .NOTES 27 | Version: 1.0 28 | Author: Alex Verboon 29 | Creation Date: 16.03.2020 30 | Purpose/Change: Initial script development 31 | 32 | #> 33 | [CmdletBinding(SupportsShouldProcess)] 34 | Param( 35 | # Computername of the MDATP managed device 36 | [Parameter(Mandatory=$true, 37 | ParameterSetName='DeviceName')] 38 | [ValidateNotNullOrEmpty()] 39 | [String]$DeviceName, 40 | 41 | # Unique device id of the MDATP managed device 42 | [Parameter(Mandatory=$true, 43 | ParameterSetName='DeviceID')] 44 | [ValidateNotNullOrEmpty()] 45 | [String]$DeviceID, 46 | 47 | # Tag to be added to the device 48 | [Parameter(Mandatory=$true)] 49 | [ValidateNotNullorEmpty()] 50 | [String]$Tag, 51 | 52 | # API Configuration file 53 | [Parameter(Mandatory=$false)] 54 | [String]$MTPConfigFile 55 | ) 56 | 57 | Begin{ 58 | # Begin Get API Information 59 | If ($MTPConfigFile){ 60 | $PoshMTPconfigFilePath = $MTPConfigFile 61 | Write-Verbose "MTP ConfigFile parameter: $PoshMTPconfigFilePath" 62 | } 63 | Else{ 64 | # If no configfile is defined we use a defined lcoation .\Config\PoshMTPconfig.json 65 | $ConfigFileDir = [IO.Directory]::GetParent($PSScriptRoot) 66 | $PoshMTPconfigFilePath = "$ConfigFileDir\" + "PoshMTPconfig.json" 67 | Write-Verbose "MTP ConfigFile static: $PoshMTPconfigFilePath" 68 | } 69 | 70 | Write-Verbose "Checking for $PoshMTPconfigFilePath" 71 | If (Test-Path -Path "$PoshMTPconfigFilePath" -PathType Leaf ){ 72 | $ConfigSettings = @(Get-Content -Path "$PoshMTPconfigFilePath" | ConvertFrom-Json) 73 | $OAuthUri = $ConfigSettings.API_MDATP.OAuthUri 74 | $ClientID = $ConfigSettings.API_MDATP.ClientID 75 | $ClientSecret = $ConfigSettings.API_MDATP.ClientSecret 76 | } 77 | Else{ 78 | Write-Error "$PoshMTPconfigFilePath not found" 79 | Break 80 | } 81 | # End Get API Information 82 | 83 | # Connect with MDATP API 84 | [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 85 | $Body = @{ 86 | resource = "https://api.securitycenter.windows.com" 87 | client_id = "$ClientID" 88 | client_secret = "$ClientSecret" 89 | grant_type = 'client_credentials' 90 | redirectUri = "https://localhost:8000" 91 | } 92 | $Response = Invoke-RestMethod -Method Post -Uri $OAuthUri -Body $Body 93 | #$Authorization = Invoke-RestMethod -Method Post -Uri $OAuthUri -Body $Body -ContentType "application/x-www-form-urlencoded" -UseBasicParsing 94 | #$access_token = $Authorization.access_token 95 | 96 | $headers = @{ 97 | 'Content-Type' = 'application/json' 98 | Accept = 'application/json' 99 | Authorization = "Bearer $($Response.access_token)" 100 | } 101 | } 102 | Process{ 103 | # MDATP API URI 104 | $MDATP_API_URI = "https://api.securitycenter.windows.com/api" 105 | 106 | # change the devicename to lowercase 107 | $DeviceName = $DeviceName.ToLower() 108 | 109 | # Get the MDATP devices 110 | $MachineAPI = "$MDATP_API_URI/machines" 111 | $Machines = @(Invoke-RestMethod -Uri "$MachineAPI" -Headers $Headers -Method Get -Verbose -ContentType application/json) 112 | If ($DeviceName){ 113 | $ActionDevice = @($machines.value | Select-Object * | Where-Object {$_.computerDnsName -like "$DeviceName"}) 114 | } 115 | Elseif ($DeviceID){ 116 | $ActionDevice = @($machines.value | Select-Object * | Where-Object {$_.id -like "$DeviceID"}) 117 | } 118 | 119 | If($ActionDevice.count -gt 1){ 120 | Write-Warning "There are multiple device records with this computername, please specify the MDATP device id" 121 | $ActionDevice | Select-Object computerDnsName, id 122 | Break 123 | } 124 | Elseif($ActionDevice.count -eq 0){ 125 | Write-Warning "No device records found that match DeviceName $DeviceName" 126 | Break 127 | } 128 | Elseif($ActionDevice.count -eq 1){ 129 | $MDATPDeviceID = $ActionDevice.id 130 | if ($pscmdlet.ShouldProcess("$DeviceName", "Adding tag: $Tag")){ 131 | Try{ 132 | # Tag machine 133 | $AddTag = @{"Value" = "$Tag"; "Action"= "Add"} | ConvertTo-Json 134 | $Taguri = "$MachineAPI/$MDATPDeviceID/tags" 135 | $response =Invoke-WebRequest -Uri $Taguri -Headers $Headers -Method Post -Body $AddTag 136 | # end tag machine 137 | If ($response.StatusCode -eq 200){ 138 | Write-Verbose "Tag: $Tag was successfully added to device $DeviceName" 139 | $True 140 | } 141 | Else{ 142 | Write-Warning "Adding tag $Tag to device $DeviceName failed!" 143 | Write-Error "StatusCode: $($response.StatusCode)" 144 | $False 145 | } 146 | } 147 | Catch{ 148 | $ex = $_.Exception 149 | $errorResponse = $ex.Response.GetResponseStream() 150 | $reader = New-Object System.IO.StreamReader($errorResponse) 151 | $reader.BaseStream.Position = 0 152 | $reader.DiscardBufferedData() 153 | $responseBody = $reader.ReadToEnd(); 154 | Write-Verbose "Response content:`n$responseBody" 155 | Write-Error "Request to $Uri failed with HTTP Status $($ex.Response.StatusCode) $($ex.Response.StatusDescription)" 156 | } 157 | } 158 | } 159 | } 160 | End{ 161 | Write-Verbose "Device: $DeviceName" 162 | Write-Verbose "DeviceID: $MDATPDeviceID" 163 | Write-Verbose "Added tag: $Tag" 164 | Write-Verbose "StatusCode: $($response.statuscode)" 165 | Write-Verbose "StatusDescription: $($response.StatusDescription)" 166 | } 167 | } -------------------------------------------------------------------------------- /src/PSMDATP/Public/Get-MDATPAlert.ps1: -------------------------------------------------------------------------------- 1 | function Get-MDATPAlert{ 2 | <# 3 | .Synopsis 4 | Get-MDATPAlert 5 | 6 | .Description 7 | Get-MDATPAlert retrieves Microsoft Defender Advanced Threat Protection alerts exposed through the Microsoft Defender Advanced Threat Protection Alerts Rest API. 8 | 9 | .PARAMETER Severity 10 | Provides an option to filter the output by Severity. Low, Medium, High. 11 | 12 | .PARAMETER PastHours 13 | Provides an option to filter the results by past hours when the alert was created. 14 | 15 | .PARAMETER MTPConfigFile 16 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 17 | 18 | .EXAMPLE 19 | Get-WDATPAlert 20 | 21 | This command retrieves all alerts 22 | 23 | .EXAMPLE 24 | Get-MDATPAlert -PastHours 168 -Severity Informational 25 | 26 | This command retrieves all alerts from the past 7 days with severity level Informational 27 | 28 | .NOTES 29 | Version: 1.2 30 | Author: Alex Verboon 31 | Creation Date: 18.07.2020 32 | Purpose/Change: updated API uri 33 | 34 | #> 35 | [CmdletBinding()] 36 | Param( 37 | # Alert Severity level 38 | [Parameter(Mandatory=$false)] 39 | [ValidateSet('High', 'Medium', 'Low','Informational')] 40 | [String]$Severity, 41 | 42 | # Show alerts from past n hours 43 | [Parameter(Mandatory=$false)] 44 | [ValidateSet('12', '24', '48','72','168','720')] 45 | [String]$PastHours, 46 | 47 | # API Configuration file 48 | [Parameter(Mandatory=$false)] 49 | [String]$MTPConfigFile 50 | ) 51 | 52 | Begin{ 53 | # Begin Get API Information 54 | 55 | If ($MTPConfigFile){ 56 | $PoshMTPconfigFilePath = $MTPConfigFile 57 | Write-Verbose "MTP ConfigFile parameter: $PoshMTPconfigFilePath" 58 | } 59 | Else{ 60 | # If no configfile is defined we use a defined lcoation .\PoshMTPconfig.json 61 | $ConfigFileDir = [IO.Directory]::GetParent($PSScriptRoot) 62 | $PoshMTPconfigFilePath = "$ConfigFileDir\" + "PoshMTPconfig.json" 63 | Write-Verbose "MTP ConfigFile static: $PoshMTPconfigFilePath" 64 | } 65 | 66 | Write-Verbose "Checking for $PoshMTPconfigFilePath" 67 | If (Test-Path -Path $PoshMTPconfigFilePath -PathType Leaf){ 68 | $ConfigSettings = @(Get-Content -Path "$PoshMTPconfigFilePath" | ConvertFrom-Json) 69 | $OAuthUri = $ConfigSettings.API_MDATP.OAuthUri 70 | $ClientID = $ConfigSettings.API_MDATP.ClientID 71 | $ClientSecret = $ConfigSettings.API_MDATP.ClientSecret 72 | } 73 | Else{ 74 | Write-Error "$PoshMTPconfigFilePath not found" 75 | Break 76 | } 77 | 78 | # End Get API Information 79 | 80 | #WDATP Alerts - Europe 81 | $uri = "https://api.securitycenter.windows.com/api/alerts" 82 | 83 | # Connect with MDATP API 84 | [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 85 | $Body = @{ 86 | resource = "https://api.securitycenter.windows.com" 87 | client_id = "$ClientID" 88 | client_secret = "$ClientSecret" 89 | grant_type = 'client_credentials' 90 | redirectUri = "https://localhost:8000" 91 | } 92 | $Response = Invoke-RestMethod -Method Post -Uri $OAuthUri -Body $Body 93 | $Headers = @{ Authorization = "Bearer $($Response.access_token)"} 94 | 95 | } 96 | Process{ 97 | # Define the time range 98 | If ($null -eq $PastHours){ 99 | $PastHours = 24 100 | } 101 | Else{ 102 | $dateTime = (Get-Date).ToUniversalTime().AddHours(-$PastHours).ToString("o") 103 | $body = @{sinceTimeUtc = $dateTime} 104 | } 105 | 106 | # Retrieve MDATP alert data 107 | Try{ 108 | $output = @(Invoke-RestMethod -Uri $uri -Headers $Headers -Body $Body -Method Get -Verbose -ContentType application/json) 109 | } 110 | Catch{ 111 | $errorMessage = $_.Exception.Message 112 | Write-Error "Error retrieving MDATP alert data [$errorMessage]" 113 | } 114 | 115 | # Handle the output 116 | If ([string]::IsNullOrEmpty($Severity)){ 117 | $output.value 118 | } 119 | Else{ 120 | $output.value | Where-Object {$_.Severity -eq "$Severity"} 121 | } 122 | } 123 | End{ 124 | } 125 | } -------------------------------------------------------------------------------- /src/PSMDATP/Public/Get-MDATPCollectionPackageUri.ps1: -------------------------------------------------------------------------------- 1 | function Get-MDATPCollectionPackageUri{ 2 | <# 3 | .Synopsis 4 | Get-MDATPCollectionPackageUri 5 | 6 | .DESCRIPTION 7 | Get-MDATPCollectionPackageUri retrieves the Investigation Collection Package download URI and optionally download the package 8 | 9 | Use the Get-MDATPDeviceActions cmdlet to retrieve the ActionID of the investigation package collection request. 10 | 11 | .PARAMETER ActionID 12 | The Action ID of the investigation package collection request. 13 | 14 | .PARAMETER Download 15 | Downloads the investigation pacakge ZIP file into the users Downloads folder 16 | 17 | .PARAMETER MTPConfigFile 18 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 19 | 20 | .EXAMPLE 21 | 22 | $lastcollectionrequestid = Get-MDATPDeviceActions -DeviceName testclient6 -ActionType CollectInvestigationPackage | Select-Object -First 1 23 | Get-MDATPCollectionPackageUri -ActionID $lastcollectionrequestid.id 24 | 25 | This comand first retrieves the last collection package request ID and then retrieves the download URI 26 | 27 | .EXAMPLE 28 | $lastcollectionrequestid = Get-MDATPDeviceActions -DeviceName testclient6 -ActionType CollectInvestigationPackage | Select-Object -First 1 29 | Get-MDATPCollectionPackageUri -ActionID $lastcollectionrequestid.id -Download 30 | 31 | This comand first retrieves the last collection package request ID and stores the investigation package into the users download folder 32 | 33 | .NOTES 34 | Version: 1.0 35 | Author: Alex Verboon 36 | Creation Date: 12.04.2020 37 | Purpose/Change: Initial script development 38 | #> 39 | 40 | [CmdletBinding()] 41 | Param( 42 | # ActionID 43 | [Parameter(Mandatory=$true)] 44 | [ValidateNotNullOrEmpty()] 45 | [String]$ActionID, 46 | 47 | # API Configuration 48 | [Parameter(Mandatory=$false)] 49 | [String]$MTPConfigFile, 50 | 51 | # Download switch 52 | [switch]$Download 53 | ) 54 | 55 | Begin{ 56 | # Begin Get API Information 57 | If ($MTPConfigFile){ 58 | $PoshMTPconfigFilePath = $MTPConfigFile 59 | Write-Verbose "MTP ConfigFile parameter: $PoshMTPconfigFilePath" 60 | } 61 | Else{ 62 | # If no configfile is defined we use a defined lcoation .\Config\PoshMTPconfig.json 63 | $ConfigFileDir = [IO.Directory]::GetParent($PSScriptRoot) 64 | $PoshMTPconfigFilePath = "$ConfigFileDir\" + "PoshMTPconfig.json" 65 | Write-Verbose "MTP ConfigFile static: $PoshMTPconfigFilePath" 66 | } 67 | 68 | Write-Verbose "Checking for $PoshMTPconfigFilePath" 69 | If (Test-Path -Path $PoshMTPconfigFilePath -PathType Leaf){ 70 | $ConfigSettings = @(Get-Content -Path "$PoshMTPconfigFilePath" | ConvertFrom-Json) 71 | $OAuthUri = $ConfigSettings.API_MDATP.OAuthUri 72 | $ClientID = $ConfigSettings.API_MDATP.ClientID 73 | $ClientSecret = $ConfigSettings.API_MDATP.ClientSecret 74 | } 75 | Else{ 76 | Write-Error "$PoshMTPconfigFilePath not found" 77 | Break 78 | } 79 | 80 | # MDATP API URI 81 | $MDATP_API_URI = "https://api.securitycenter.windows.com/api" 82 | 83 | # Connect with MDATP API 84 | [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 85 | $Body = @{ 86 | resource = "https://api.securitycenter.windows.com" 87 | client_id = $ClientID 88 | client_secret = $ClientSecret 89 | grant_type = 'client_credentials' 90 | redirectUri = "https://localhost:8000" 91 | } 92 | $Response = Invoke-RestMethod -Method Post -Uri $OAuthUri -Body $Body 93 | #$Authorization = Invoke-RestMethod -Method Post -Uri $OAuthUri -Body $Body -ContentType "application/x-www-form-urlencoded" -UseBasicParsing 94 | #$access_token = $Authorization.access_token 95 | 96 | $headers = @{ 97 | 'Content-Type' = 'application/json' 98 | Accept = 'application/json' 99 | Authorization = "Bearer $($Response.access_token)" 100 | } 101 | } 102 | Process{ 103 | # Define the request URI 104 | $MachineActionAPI = "$MDATP_API_URI/machineactions" 105 | $getPackageUri = "getPackageUri" 106 | $RequestURI = "$MachineActionAPI/$ActionID/$getPackageUri" 107 | Write-Verbose "Request URI: $($RequestURI)" 108 | 109 | # Let's get the Investigation Collection Package download URL 110 | Try{ 111 | $URIresponse = @(Invoke-RestMethod -Uri "$RequestURI" -Headers $Headers -Method Get -Verbose -ContentType application/json) 112 | $URIresponse.value 113 | } 114 | Catch{ 115 | $ex = $_.Exception 116 | $errorResponse = $ex.Response.GetResponseStream() 117 | $reader = New-Object System.IO.StreamReader($errorResponse) 118 | $reader.BaseStream.Position = 0 119 | $reader.DiscardBufferedData() 120 | $responseBody = $reader.ReadToEnd(); 121 | Write-Verbose "Response content:`n$responseBody" 122 | Write-Error "Request to $Uri failed with HTTP Status $($ex.Response.StatusCode) $($ex.Response.StatusDescription)" 123 | } 124 | 125 | If($Download){ 126 | $fileuri = $URIresponse.value 127 | $OutPutFile = "$ENV:USERPROFILE\Downloads\MDATP_InvestigationPackage_$($ActionID).zip" 128 | Try{ 129 | Invoke-WebRequest -UseBasicParsing -Uri $fileuri -OutFile "$OutPutFile" 130 | } 131 | Catch{ 132 | Write-Error "Investigation Package download failed" 133 | } 134 | } 135 | } 136 | End{} 137 | } -------------------------------------------------------------------------------- /src/PSMDATP/Public/Get-MDATPDevice.ps1: -------------------------------------------------------------------------------- 1 | function Get-MDATPDevice{ 2 | <# 3 | .SYNOPSIS 4 | Get-MDATPDevice 5 | 6 | .DESCRIPTION 7 | Get-MDATPDevice retrieves MDATP device information 8 | 9 | .PARAMETER DeviceName 10 | Computername of the device 11 | 12 | .PARAMETER DeviceID 13 | The unique device ID of the device 14 | 15 | .PARAMETER All 16 | Lists machine actions for all managed devices 17 | 18 | .PARAMETER HealthStatus 19 | Filters the results by device heatlh. 20 | 21 | .PARAMETER RiskScore 22 | Filters the results by device risk score 23 | 24 | .PARAMETER MTPConfigFile 25 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 26 | 27 | 28 | .EXAMPLE 29 | Get-MDATPDevice -all 30 | 31 | This command retrieves all MDATP devices 32 | 33 | .EXAMPLE 34 | Get-MDATPDevice -All -HealthStatus Inactive 35 | 36 | This command lists all inactive devices 37 | 38 | .EXAMPLE 39 | Get-MDATPDevice -All -RiskScore Medium 40 | 41 | This command lists all devices with a medium risk score 42 | 43 | .EXAMPLE 44 | 45 | Get-MDATPDevice -DeviceName Computer01 46 | 47 | This command retrieves device information for Computer01 48 | 49 | .NOTES 50 | Version: 1.0 51 | Author: Alex Verboon 52 | Creation Date: 14.04.2020 53 | Purpose/Change: Initial script development 54 | #> 55 | 56 | [CmdletBinding()] 57 | Param( 58 | # Computername of the MDATP managed device 59 | [Parameter(Mandatory=$true, 60 | ParameterSetName='DeviceName')] 61 | [ValidateNotNullOrEmpty()] 62 | [String]$DeviceName, 63 | 64 | # Unique device id of the MDATP managed device 65 | [Parameter(Mandatory=$true, 66 | ParameterSetName='DeviceID')] 67 | [ValidateNotNullOrEmpty()] 68 | [String]$DeviceID, 69 | 70 | # Switch to retrieve actions from all devices 71 | [Parameter(Mandatory=$true, 72 | ParameterSetName='All')] 73 | [switch]$All, 74 | 75 | # The HealthStatus of the device 76 | [Parameter(Mandatory=$false, 77 | ParameterSetName='All')] 78 | [ValidateNotNullOrEmpty()] 79 | [ValidateSet('Inactive','Active')] 80 | [String]$HealthStatus, 81 | 82 | # The device Risk Score 83 | [Parameter(Mandatory=$false, 84 | ParameterSetName='All')] 85 | [ValidateSet('None','Low','Medium','High')] 86 | [String]$RiskScore, 87 | 88 | # API Configuration 89 | [Parameter(Mandatory=$false)] 90 | [String]$MTPConfigFile 91 | ) 92 | 93 | Begin{ 94 | # Begin Get API Information 95 | If ($MTPConfigFile){ 96 | $PoshMTPconfigFilePath = $MTPConfigFile 97 | Write-Verbose "MTP ConfigFile parameter: $PoshMTPconfigFilePath" 98 | } 99 | Else{ 100 | # If no configfile is defined we use a defined lcoation .\Config\PoshMTPconfig.json 101 | $ConfigFileDir = [IO.Directory]::GetParent($PSScriptRoot) 102 | $PoshMTPconfigFilePath = "$ConfigFileDir\" + "PoshMTPconfig.json" 103 | Write-Verbose "MTP ConfigFile static: $PoshMTPconfigFilePath" 104 | } 105 | 106 | Write-Verbose "Checking for $PoshMTPconfigFilePath" 107 | If (Test-Path -Path $PoshMTPconfigFilePath -PathType Leaf){ 108 | $ConfigSettings = @(Get-Content -Path "$PoshMTPconfigFilePath" | ConvertFrom-Json) 109 | $OAuthUri = $ConfigSettings.API_MDATP.OAuthUri 110 | $ClientID = $ConfigSettings.API_MDATP.ClientID 111 | $ClientSecret = $ConfigSettings.API_MDATP.ClientSecret 112 | } 113 | Else{ 114 | Write-Error "$PoshMTPconfigFilePath not found" 115 | Break 116 | } 117 | 118 | # End Get API Information 119 | 120 | # Connect with MDATP API 121 | [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 122 | $Body = @{ 123 | resource = "https://api.securitycenter.windows.com" 124 | client_id = $ClientID 125 | client_secret = $ClientSecret 126 | grant_type = 'client_credentials' 127 | redirectUri = "https://localhost:8000" 128 | } 129 | $Response = Invoke-RestMethod -Method Post -Uri $OAuthUri -Body $Body 130 | $headers = @{ 131 | 'Content-Type' = 'application/json' 132 | Accept = 'application/json' 133 | Authorization = "Bearer $($Response.access_token)" 134 | } 135 | } 136 | Process{ 137 | $DeviceUri = "https://api.securitycenter.windows.com/api/machines" 138 | 139 | If($PSBoundParameters.ContainsKey("HealthStatus")){ 140 | $HealthFilter = "healthStatus eq '$Healthstatus'" 141 | } 142 | 143 | If($PSBoundParameters.ContainsKey("RiskScore")){ 144 | $RiskFilter = "riskscore eq '$RiskScore'" 145 | } 146 | 147 | If ($HealthFilter -and $RiskFilter){ 148 | $DeviceUri = $DeviceUri + "?`$filter=" + $HealthFilter + " and " + $RiskFilter 149 | } 150 | Elseif($HealthFilter){ 151 | $DeviceUri = $DeviceUri + "?`$filter=" + $HealthFilter 152 | } 153 | ElseIf ($RiskFilter){ 154 | $DeviceUri = $DeviceUri + "?`$filter="+$RiskFilter 155 | } 156 | 157 | 158 | If ($PSBoundParameters.ContainsKey("DeviceName")){ 159 | $DeviceUri = $DeviceUri + "?`$filter=" + "ComputerDNSName eq '$DeviceName'" 160 | } 161 | 162 | If ($PSBoundParameters.ContainsKey("DeviceID")){ 163 | $DeviceUri = $DeviceUri + "?`$filter=" + "id eq '$DeviceID'" 164 | } 165 | 166 | Write-Verbose "API Request: $DeviceUri" 167 | Try{ 168 | $DeviceList = @(Invoke-RestMethod -Uri "$DeviceUri" -Headers $Headers -Method Get -Verbose -ContentType application/json) 169 | $Devicelist.value 170 | } 171 | Catch{ 172 | $errorMessage = $_.Exception.Message 173 | Write-Error "Error retrieving MDATP device data [$errorMessage]" 174 | } 175 | } 176 | End{ 177 | } 178 | } 179 | 180 | -------------------------------------------------------------------------------- /src/PSMDATP/Public/Get-MDATPDeviceTag.ps1: -------------------------------------------------------------------------------- 1 | function Get-MDATPDeviceTag{ 2 | <# 3 | .Synopsis 4 | Get-MDATPDeviceTag 5 | 6 | .Description 7 | Get-MDATPDeviceTag retrieves tags assigned on the specified device 8 | 9 | .PARAMETER DeviceName 10 | Computername of the device 11 | 12 | .PARAMETER DeviceID 13 | The unique device ID of the device 14 | 15 | .PARAMETER MTPConfigFile 16 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 17 | 18 | 19 | .EXAMPLE 20 | Get-MDATPDeviceTag -DeviceName computer02 21 | 22 | This command reads all the tags assigned to the device 'computer02' 23 | 24 | .NOTES 25 | Version: 1.0 26 | Author: Alex Verboon 27 | Creation Date: 16.03.2020 28 | Purpose/Change: Initial script development 29 | #> 30 | 31 | [CmdletBinding()] 32 | Param( 33 | # Computername of the MDATP managed device 34 | [Parameter(Mandatory=$true, 35 | ParameterSetName='DeviceName')] 36 | [ValidateNotNullOrEmpty()] 37 | [String]$DeviceName, 38 | 39 | # Unique device id of the MDATP managed device 40 | [Parameter(Mandatory=$true, 41 | ParameterSetName='DeviceID')] 42 | [ValidateNotNullOrEmpty()] 43 | [String]$DeviceID, 44 | 45 | # Switch to retrieve tags from all devices 46 | [Parameter(Mandatory=$true, 47 | ParameterSetName='All')] 48 | [switch]$All, 49 | 50 | # API Configuration 51 | [Parameter(Mandatory=$false)] 52 | [String]$MTPConfigFile 53 | ) 54 | 55 | Begin{ 56 | # Begin Get API Information 57 | If ($MTPConfigFile){ 58 | $PoshMTPconfigFilePath = $MTPConfigFile 59 | Write-Verbose "MTP ConfigFile parameter: $PoshMTPconfigFilePath" 60 | } 61 | Else{ 62 | # If no configfile is defined we use a defined lcoation .\Config\PoshMTPconfig.json 63 | $ConfigFileDir = [IO.Directory]::GetParent($PSScriptRoot) 64 | $PoshMTPconfigFilePath = "$ConfigFileDir\" + "PoshMTPconfig.json" 65 | Write-Verbose "MTP ConfigFile static: $PoshMTPconfigFilePath" 66 | } 67 | 68 | Write-Verbose "Checking for $PoshMTPconfigFilePath" 69 | If (Test-Path -Path $PoshMTPconfigFilePath -PathType Leaf){ 70 | $ConfigSettings = @(Get-Content -Path "$PoshMTPconfigFilePath" | ConvertFrom-Json) 71 | $OAuthUri = $ConfigSettings.API_MDATP.OAuthUri 72 | $ClientID = $ConfigSettings.API_MDATP.ClientID 73 | $ClientSecret = $ConfigSettings.API_MDATP.ClientSecret 74 | } 75 | Else{ 76 | Write-Error "$PoshMTPconfigFilePath not found" 77 | Break 78 | } 79 | 80 | # End Get API Information 81 | 82 | # Connect with MDATP API 83 | [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 84 | $Body = @{ 85 | resource = "https://api.securitycenter.windows.com" 86 | client_id = $ClientID 87 | client_secret = $ClientSecret 88 | grant_type = 'client_credentials' 89 | redirectUri = "https://localhost:8000" 90 | } 91 | $Response = Invoke-RestMethod -Method Post -Uri $OAuthUri -Body $Body 92 | #$Authorization = Invoke-RestMethod -Method Post -Uri $OAuthUri -Body $Body -ContentType "application/x-www-form-urlencoded" -UseBasicParsing 93 | #$access_token = $Authorization.access_token 94 | 95 | $headers = @{ 96 | 'Content-Type' = 'application/json' 97 | Accept = 'application/json' 98 | Authorization = "Bearer $($Response.access_token)" 99 | } 100 | } 101 | Process{ 102 | $MDATP_API_URI = "https://api.securitycenter.windows.com/api" 103 | # Get the MDATP devices 104 | $MachineAPI = "$MDATP_API_URI/machines" 105 | $Machines = @(Invoke-RestMethod -Uri "$MachineAPI" -Headers $Headers -Method Get -Verbose -ContentType application/json) 106 | 107 | If ($DeviceName){ 108 | # change the devicename to lowercase 109 | $DeviceName = $DeviceName.ToLower() 110 | $ActionDevice = @($machines.value | Select-Object * | Where-Object {$_.computerDnsName -like "$DeviceName"}) 111 | } 112 | Elseif ($DeviceID){ 113 | $ActionDevice = @($machines.value | Select-Object * | Where-Object {$_.id -like "$DeviceID"}) 114 | } 115 | Elseif($All){ 116 | $ActionDevice = @($machines.value) 117 | } 118 | 119 | If($ActionDevice.Count -gt 0 -and $All -eq $true){ 120 | $Result = ForEach($device in $ActionDevice){ 121 | [PSCustomObject]@{ 122 | DeviceName = $device.ComputerDnsName 123 | id = $device.id 124 | machineTags = $device.machineTags 125 | } 126 | } 127 | $Result 128 | } 129 | ElseIf($ActionDevice.count -gt 1){ 130 | Write-Warning "There are multiple device records with this computername, please specify the MDATP device id" 131 | $ActionDevice | Select-Object computerDnsName, id 132 | Break 133 | } 134 | Elseif($ActionDevice.count -eq 0){ 135 | Write-Warning "No device records found that match DeviceName $DeviceName" 136 | Break 137 | } 138 | Elseif($ActionDevice.count -eq 1){ 139 | $Result = [PSCustomObject]@{ 140 | DeviceName = $ActionDevice.ComputerDnsName 141 | id = $ActionDevice.id 142 | machineTags = $ActionDevice.machineTags 143 | } 144 | $Result 145 | } 146 | } 147 | End{} 148 | } -------------------------------------------------------------------------------- /src/PSMDATP/Public/Get-MDATPEndpointStatus.ps1: -------------------------------------------------------------------------------- 1 | function Get-MDATPEndpointStatus{ 2 | <# 3 | .Synopsis 4 | Get-MDATPEndpointStatus 5 | 6 | .DESCRIPTION 7 | Get-MDATPEndpointStatus retrieves information about the Endpoint Status 8 | 9 | https://github.com/microsoft/Microsoft-365-Defender-Hunting-Queries/blob/master/General%20queries/Endpoint%20Agent%20Health%20Status%20Report.md 10 | 11 | This query will provide a report of many of the best practice configurations for Defender ATP deployment. Special Thanks to Gilad Mittelman for the initial inspiration and concept. 12 | Any tests which are reporting "BAD" as a result imply that the associated capability is not configured per best practice recommendation. 13 | 14 | Limitations 15 | 1. The results will include a maximum of 100,000 rows. 16 | 2. The number of executions is limited per tenant: up to 15 calls per minute, 15 minutes of running time every hour and 4 hours of running time a day. 17 | 3. The maximal execution time of a single request is 10 minutes. 18 | 19 | .PARAMETER DeviceName 20 | Computername of the device.If no DeviceName is provided all devices are querried 21 | 22 | .PARAMETER MTPConfigFile 23 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 24 | 25 | .EXAMPLE 26 | Get-MDATPEndpointStatus -DeviceName TestClient4 27 | 28 | .EXAMPLE 29 | Get-MDATPEndpointStatus 30 | 31 | 32 | .NOTES 33 | Version: 1.0 34 | Author: Alex Verboon 35 | Creation Date: 22.12.2020 36 | Purpose/Change: Initial script development 37 | 38 | #> 39 | [CmdletBinding()] 40 | Param 41 | ( 42 | # Computername of the MDATP managed device 43 | [Parameter(Mandatory=$false)] 44 | [String]$DeviceName, 45 | 46 | # API Configuration 47 | [Parameter(Mandatory=$false)] 48 | [String]$MTPConfigFile 49 | ) 50 | Begin{ 51 | # Begin Get API Information 52 | If ($MTPConfigFile){ 53 | $PoshMTPconfigFilePath = $MTPConfigFile 54 | Write-Verbose "MTP ConfigFile parameter: $PoshMTPconfigFilePath" 55 | } 56 | Else{ 57 | # If no configfile is defined we use a defined lcoation .\Config\PoshMTPconfig.json 58 | $ConfigFileDir = [IO.Directory]::GetParent($PSScriptRoot) 59 | $PoshMTPconfigFilePath = "$ConfigFileDir\" + "PoshMTPconfig.json" 60 | Write-Verbose "MTP ConfigFile static: $PoshMTPconfigFilePath" 61 | } 62 | 63 | Write-Verbose "Checking for $PoshMTPconfigFilePath" 64 | If (Test-Path -Path $PoshMTPconfigFilePath -PathType Leaf){ 65 | $ConfigSettings = @(Get-Content -Path "$PoshMTPconfigFilePath" | ConvertFrom-Json) 66 | $OAuthUri = $ConfigSettings.API_MDATP.OAuthUri 67 | $ClientID = $ConfigSettings.API_MDATP.ClientID 68 | $ClientSecret = $ConfigSettings.API_MDATP.ClientSecret 69 | } 70 | Else{ 71 | Write-Error "$PoshMTPconfigFilePath not found" 72 | Break 73 | } 74 | # End Get API Information 75 | 76 | # Connect with MDATP API 77 | [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 78 | $Body = @{ 79 | resource = "https://api.securitycenter.windows.com" 80 | client_id = $ClientID 81 | client_secret = $ClientSecret 82 | grant_type = 'client_credentials' 83 | redirectUri = "https://localhost:8000" 84 | } 85 | $Response = Invoke-RestMethod -Method Post -Uri $OAuthUri -Body $Body 86 | 87 | $headers = @{ 88 | 'Content-Type' = 'application/json' 89 | Accept = 'application/json' 90 | Authorization = "Bearer $($Response.access_token)" 91 | } 92 | } 93 | Process{ 94 | $kqlquery = @" 95 | // Best practice endpoint configurations for Microsoft Defender for Endpoint deployment. 96 | DeviceTvmSecureConfigurationAssessment 97 | //DEVICENAME 98 | | where ConfigurationId in ("scid-91", "scid-2000", "scid-2001", "scid-2002", "scid-2003", "scid-2010", "scid-2011", "scid-2012", "scid-2013", "scid-2014", "scid-2016") 99 | | summarize arg_max(Timestamp, IsCompliant, IsApplicable) by DeviceId, DeviceName, ConfigurationId 100 | | extend Test = case( 101 | ConfigurationId == "scid-2000", "SensorEnabled", 102 | ConfigurationId == "scid-2001", "SensorDataCollection", 103 | ConfigurationId == "scid-2002", "ImpairedCommunications", 104 | ConfigurationId == "scid-2003", "TamperProtection", 105 | ConfigurationId == "scid-2010", "AntivirusEnabled", 106 | ConfigurationId == "scid-2011", "AntivirusSignatureVersion", 107 | ConfigurationId == "scid-2012", "RealtimeProtection", 108 | ConfigurationId == "scid-91", "BehaviorMonitoring", 109 | ConfigurationId == "scid-2013", "PUAProtection", 110 | ConfigurationId == "scid-2014", "AntivirusReporting", 111 | ConfigurationId == "scid-2016", "CloudProtection", 112 | "N/A"), 113 | Result = case(IsApplicable == 0, "N/A", IsCompliant == 1, "GOOD", "BAD") 114 | | extend packed = pack(Test, Result) 115 | | summarize Tests = make_bag(packed) by DeviceId, DeviceName 116 | | evaluate bag_unpack(Tests) 117 | "@ 118 | 119 | 120 | 121 | If ([string]::IsNullOrEmpty($DeviceName)){ 122 | # nothing to do , we run the query against all devices 123 | } 124 | Else{ 125 | $DeviceName = $DeviceName.ToLower() 126 | $replacestring = "| where DeviceName == '$DeviceName'" 127 | $kqlquery = $kqlquery.Replace("//DEVICENAME","$replacestring") 128 | } 129 | $uri = "https://api.securitycenter.windows.com/api/advancedqueries/run" 130 | $body = ConvertTo-Json -InputObject @{ 'Query' = $kqlquery} 131 | Try{ 132 | $webResponse = @(Invoke-WebRequest -Method Post -Uri $uri -Headers $headers -Body $body) 133 | $response = $webResponse | ConvertFrom-Json 134 | $results = $response.Results 135 | $results 136 | } 137 | Catch{ 138 | $errorMessage = $_.Exception.Message 139 | Write-Error "Error running advanced hunting query [$errorMessage]" 140 | } 141 | } 142 | End{ 143 | Write-Verbose "Schema: $Schema" 144 | Write-Verbose "Device: $DeviceTarget" 145 | Write-Verbose "Query: $ExecQuery" 146 | Write-Verbose "Retrieved $($results.count) records" 147 | } 148 | } -------------------------------------------------------------------------------- /src/PSMDATP/Public/Get-MDATPIndicator.ps1: -------------------------------------------------------------------------------- 1 | function Get-MDATPIndicator{ 2 | <# 3 | .Synopsis 4 | Get-MDATPIndicator 5 | 6 | .DESCRIPTION 7 | Get-MDATPIndicator retrieves Microsoft Defender Advanced Threat Protection custom indicators exposed 8 | through the Microsoft Defender Advanced Threat Protection indicators Rest API. 9 | 10 | .PARAMETER IndicatorType 11 | Filters the indicator by the specified IndicatorType. Possible values are: DomainName, Url, FileSha256,IpAddress,WebCategory 12 | 13 | .PARAMETER MTPConfigFile 14 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 15 | 16 | .EXAMPLE 17 | Get-MDATPIndicator 18 | 19 | This command retrieves all TI indicators 20 | 21 | .EXAMPLE 22 | Get-MDATPIndicator -IndicatorType DomainName 23 | 24 | This command retrieves all DomainName TI indicators 25 | 26 | .EXAMPLE 27 | $indicators = Get-MDATPIndicator -MTPConfigFile "C:\Dev\Private\MSSecurityPowerShell\Config\PoshMTPconfigBaseVISION.json" 28 | $indicators | Where-Object {$_.Source -like "WindowsDefenderATPThreatIntelAPI"} 29 | 30 | This sample shows how to filter results by TI source 31 | 32 | .NOTES 33 | Version: 1.0 34 | Author: Alex Verboon 35 | Creation Date: 20.03.2020 36 | Purpose/Change: Initial script development 37 | #> 38 | [CmdletBinding()] 39 | Param( 40 | # Indicator type 41 | [Parameter(Mandatory=$false)] 42 | [ValidateSet('DomainName','Url','FileSha256','IpAddress','WebCategory')] 43 | [String]$IndicatorType, 44 | 45 | # MDATP configfile 46 | [Parameter(Mandatory=$false)] 47 | [String]$MTPConfigFile 48 | ) 49 | 50 | Begin{ 51 | # Begin Get API Information 52 | If ($MTPConfigFile){ 53 | $PoshMTPconfigFilePath = $MTPConfigFile 54 | Write-Verbose "MTP ConfigFile parameter: $PoshMTPconfigFilePath" 55 | } 56 | Else{ 57 | # If no configfile is defined we use a defined lcoation .\Config\PoshMTPconfig.json 58 | $ConfigFileDir = [IO.Directory]::GetParent($PSScriptRoot) 59 | $PoshMTPconfigFilePath = "$ConfigFileDir\" + "PoshMTPconfig.json" 60 | Write-Verbose "MTP ConfigFile static: $PoshMTPconfigFilePath" 61 | } 62 | 63 | Write-Verbose "Checking for $PoshMTPconfigFilePath" 64 | If (Test-Path -Path $PoshMTPconfigFilePath -PathType Leaf){ 65 | $ConfigSettings = @(Get-Content -Path "$PoshMTPconfigFilePath" | ConvertFrom-Json) 66 | $OAuthUri = $ConfigSettings.API_MDATP.OAuthUri 67 | $ClientID = $ConfigSettings.API_MDATP.ClientID 68 | $ClientSecret = $ConfigSettings.API_MDATP.ClientSecret 69 | } 70 | Else{ 71 | Write-Error "$PoshMTPconfigFilePath not found" 72 | Break 73 | } 74 | # End Get API Information 75 | 76 | # Connect with MDATP API 77 | [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 78 | $Body = @{ 79 | resource = "https://api.securitycenter.windows.com" 80 | client_id = $ClientID 81 | client_secret = $ClientSecret 82 | grant_type = 'client_credentials' 83 | redirectUri = "https://localhost:8000" 84 | } 85 | $Response = Invoke-RestMethod -Method Post -Uri $OAuthUri -Body $Body 86 | #$Authorization = Invoke-RestMethod -Method Post -Uri $OAuthUri -Body $Body -ContentType "application/x-www-form-urlencoded" -UseBasicParsing 87 | #$access_token = $Authorization.access_token 88 | 89 | $headers = @{ 90 | 'Content-Type' = 'application/json' 91 | Accept = 'application/json' 92 | Authorization = "Bearer $($Response.access_token)" 93 | } 94 | } 95 | Process{ 96 | Try{ 97 | $indicatorsuri = "https://api.securitycenter.windows.com/api/indicators" 98 | $indicators = @(Invoke-RestMethod -Uri $indicatorsuri -Headers $Headers -Body $Body -Method Get -ContentType application/json) 99 | 100 | } 101 | Catch{ 102 | $errorMessage = $_.Exception.Message 103 | Write-Error "Error retrieving MDATP TI indicators data [$errorMessage]" 104 | } 105 | 106 | If ($IndicatorType){ 107 | $indicators.value | Where-Object {$_.IndicatorType -eq "$IndicatorType"} 108 | } 109 | Else{ 110 | $indicators.value 111 | } 112 | } 113 | End{} 114 | } -------------------------------------------------------------------------------- /src/PSMDATP/Public/Get-MDATPQuery.ps1: -------------------------------------------------------------------------------- 1 | function Get-MDATPQuery{ 2 | <# 3 | .Synopsis 4 | Get-MDATPQuery 5 | 6 | .DESCRIPTION 7 | Get-MDATPQuery executes MDATP advanced hunting queries through the 8 | Microsoft Defender Advanced Threat Protection Alerts Rest API. 9 | 10 | Limitations 11 | 1. You can only run a query on data from the last 30 days. 12 | 2. The results will include a maximum of 100,000 rows. 13 | 3. The number of executions is limited per tenant: up to 15 calls per minute, 15 minutes of running time every hour and 4 hours of running time a day. 14 | 4. The maximal execution time of a single request is 10 minutes. 15 | 16 | .PARAMETER Schema 17 | The Schema to use for the query 18 | 19 | .PARAMETER DeviceName 20 | Computername of the device.If no DeviceName is provided all devices are querried 21 | 22 | .PARAMETER MTPConfigFile 23 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 24 | 25 | .EXAMPLE 26 | Get-MDATPQuery -Schema DeviceLogonEvents -DeviceName TestClient4 27 | 28 | The above query retrieves all logon events for the specified device 29 | 30 | .NOTES 31 | Version: 1.0 32 | Author: Alex Verboon 33 | Creation Date: 17.02.2020 34 | Purpose/Change: Initial script development 35 | 36 | #> 37 | [CmdletBinding()] 38 | Param 39 | ( 40 | # The MDATP Schema to search for 41 | [Parameter(Mandatory=$true)] 42 | [ValidateSet('DeviceAlertEvents','DeviceInfo','DeviceNetworkInfo','DeviceProcessEvents','DeviceFileEvents','DeviceRegistryEvents','DeviceLogonEvents','DeviceImageLoadEvents','DeviceEvents')] 43 | [String]$Schema, 44 | 45 | # Computername of the MDATP managed device 46 | [Parameter(Mandatory=$false)] 47 | [String]$DeviceName, 48 | 49 | # The Time Range 50 | [Parameter(Mandatory=$false)] 51 | [ValidateSet('1h', '12h', '1d','7d','30d')] 52 | [String]$TimeRange, 53 | 54 | # API Configuration 55 | [Parameter(Mandatory=$false)] 56 | [String]$MTPConfigFile 57 | ) 58 | 59 | Begin{ 60 | # Begin Get API Information 61 | If ($MTPConfigFile){ 62 | $PoshMTPconfigFilePath = $MTPConfigFile 63 | Write-Verbose "MTP ConfigFile parameter: $PoshMTPconfigFilePath" 64 | } 65 | Else{ 66 | # If no configfile is defined we use a defined lcoation .\Config\PoshMTPconfig.json 67 | $ConfigFileDir = [IO.Directory]::GetParent($PSScriptRoot) 68 | $PoshMTPconfigFilePath = "$ConfigFileDir\" + "PoshMTPconfig.json" 69 | Write-Verbose "MTP ConfigFile static: $PoshMTPconfigFilePath" 70 | } 71 | 72 | Write-Verbose "Checking for $PoshMTPconfigFilePath" 73 | If (Test-Path -Path $PoshMTPconfigFilePath -PathType Leaf){ 74 | $ConfigSettings = @(Get-Content -Path "$PoshMTPconfigFilePath" | ConvertFrom-Json) 75 | $OAuthUri = $ConfigSettings.API_MDATP.OAuthUri 76 | $ClientID = $ConfigSettings.API_MDATP.ClientID 77 | $ClientSecret = $ConfigSettings.API_MDATP.ClientSecret 78 | } 79 | Else{ 80 | Write-Error "$PoshMTPconfigFilePath not found" 81 | Break 82 | } 83 | # End Get API Information 84 | 85 | # Connect with MDATP API 86 | [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 87 | $Body = @{ 88 | resource = "https://api.securitycenter.windows.com" 89 | client_id = $ClientID 90 | client_secret = $ClientSecret 91 | grant_type = 'client_credentials' 92 | redirectUri = "https://localhost:8000" 93 | } 94 | $Response = Invoke-RestMethod -Method Post -Uri $OAuthUri -Body $Body 95 | #$Authorization = Invoke-RestMethod -Method Post -Uri $OAuthUri -Body $Body -ContentType "application/x-www-form-urlencoded" -UseBasicParsing 96 | #$access_token = $Authorization.access_token 97 | 98 | $headers = @{ 99 | 'Content-Type' = 'application/json' 100 | Accept = 'application/json' 101 | Authorization = "Bearer $($Response.access_token)" 102 | } 103 | } 104 | Process{ 105 | #WDATP API 106 | $uri = "https://api.securitycenter.windows.com/api/advancedqueries/run" 107 | # Define devices to include in query 108 | if ($DeviceName){ 109 | $DeviceName = $DeviceName.ToLower() 110 | $ExecQuery = "$Schema | where DeviceName == '$DeviceName'" 111 | } 112 | Else{ 113 | $ExecQuery = "$Schema" 114 | } 115 | $DeviceTarget = if([string]::IsNullOrEmpty($DeviceName)) {"All Devices"}Else {"$DeviceName"} 116 | 117 | If ($TimeRange){ 118 | $ExecQuery = $ExecQuery + "|where Timestamp > ago($($TimeRange))" 119 | } 120 | 121 | 122 | Try{ 123 | $body = ConvertTo-Json -InputObject @{ 'Query' = $ExecQuery} 124 | $webResponse = @(Invoke-WebRequest -Method Post -Uri $uri -Headers $headers -Body $body) 125 | $response = $webResponse | ConvertFrom-Json 126 | $results = $response.Results 127 | $results 128 | } 129 | Catch{ 130 | $errorMessage = $_.Exception.Message 131 | Write-Error "Error running advanced hunting query [$errorMessage]" 132 | } 133 | } 134 | End{ 135 | Write-Verbose "Schema: $Schema" 136 | Write-Verbose "Device: $DeviceTarget" 137 | Write-Verbose "Query: $ExecQuery" 138 | Write-Verbose "Retrieved $($results.count) records" 139 | } 140 | } -------------------------------------------------------------------------------- /src/PSMDATP/Public/Get-MDATPTvmRecommendation.ps1: -------------------------------------------------------------------------------- 1 | function Get-MDATPTvmRecommendation{ 2 | <# 3 | .Synopsis 4 | Get-MDATPTvmRecommendation 5 | 6 | .DESCRIPTION 7 | Get-MDATPTvmRecommendation retrieves Microsoft Defender Advanced Threat Protection Threat and Vulnerability Management 8 | security recommendations 9 | 10 | .PARAMETER recommendationCategory 11 | 12 | Category or grouping to which the configuration belongs: Application, OS, Network, Accounts, Security controls 13 | 14 | .PARAMETER publicexploit 15 | 16 | Setting this parameter limits the results to security recommendations that address a public exploit 17 | 18 | .PARAMETER MTPConfigFile 19 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 20 | 21 | .EXAMPLE 22 | Get-MDATPTvmRecommendation 23 | 24 | This command retrieves all TVM security recommendations 25 | 26 | .EXAMPLE 27 | $tvmrecommendations = Get-MDATPTvmRecommendation -MTPConfigFile "C:\Users\Alex\Documents\WindowsPowerShell\Modules\PSMDATP\PoshMTPconfig.json" 28 | 29 | 30 | .NOTES 31 | Version: 1.0 32 | Author: Alex Verboon 33 | Creation Date: 18.07.2020 34 | Purpose/Change: Initial script development 35 | #> 36 | [CmdletBinding()] 37 | Param( 38 | # recommendation Category 39 | [Parameter(Mandatory=$false)] 40 | [ValidateSet('DomainName','Application','OS','Network','Accounts','Security controls')] 41 | [String]$recommendationCategory, 42 | 43 | 44 | # publicexploit 45 | [Parameter(Mandatory=$false)] 46 | [switch]$publicexploit, 47 | 48 | # MDATP configfile 49 | [Parameter(Mandatory=$false)] 50 | [String]$MTPConfigFile 51 | ) 52 | 53 | Begin{ 54 | # Begin Get API Information 55 | If ($MTPConfigFile){ 56 | $PoshMTPconfigFilePath = $MTPConfigFile 57 | Write-Verbose "MTP ConfigFile parameter: $PoshMTPconfigFilePath" 58 | } 59 | Else{ 60 | # If no configfile is defined we use a defined lcoation .\Config\PoshMTPconfig.json 61 | $ConfigFileDir = [IO.Directory]::GetParent($PSScriptRoot) 62 | $PoshMTPconfigFilePath = "$ConfigFileDir\" + "PoshMTPconfig.json" 63 | Write-Verbose "MTP ConfigFile static: $PoshMTPconfigFilePath" 64 | } 65 | 66 | Write-Verbose "Checking for $PoshMTPconfigFilePath" 67 | If (Test-Path -Path $PoshMTPconfigFilePath -PathType Leaf){ 68 | $ConfigSettings = @(Get-Content -Path "$PoshMTPconfigFilePath" | ConvertFrom-Json) 69 | $OAuthUri = $ConfigSettings.API_MDATP.OAuthUri 70 | $ClientID = $ConfigSettings.API_MDATP.ClientID 71 | $ClientSecret = $ConfigSettings.API_MDATP.ClientSecret 72 | } 73 | Else{ 74 | Write-Error "$PoshMTPconfigFilePath not found" 75 | Break 76 | } 77 | # End Get API Information 78 | 79 | # Connect with MDATP API 80 | [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 81 | $Body = @{ 82 | resource = "https://api.securitycenter.windows.com" 83 | client_id = $ClientID 84 | client_secret = $ClientSecret 85 | grant_type = 'client_credentials' 86 | redirectUri = "https://localhost:8000" 87 | } 88 | $Response = Invoke-RestMethod -Method Post -Uri $OAuthUri -Body $Body 89 | 90 | $headers = @{ 91 | 'Content-Type' = 'application/json' 92 | Accept = 'application/json' 93 | Authorization = "Bearer $($Response.access_token)" 94 | } 95 | } 96 | Process{ 97 | Try{ 98 | $tvmuri = "https://api.securitycenter.windows.com/api/recommendations" 99 | $tvmrecommendations = @(Invoke-RestMethod -Uri $tvmuri -Headers $Headers -Body $Body -Method Get -Verbose -ContentType application/json) 100 | 101 | } 102 | Catch{ 103 | $errorMessage = $_.Exception.Message 104 | Write-Error "Error retrieving MDATP TVM security recommendations data [$errorMessage]" 105 | } 106 | 107 | If ($recommendationCategory){ 108 | $Result = $tvmrecommendations.value | Where-Object {$_.recommendationCategory -eq "$recommendationCategory"} 109 | } 110 | Else{ 111 | $Result = $tvmrecommendations.value 112 | } 113 | 114 | If ($publicexploit){ 115 | $Result = $Result | Where-Object {$_.publicExploit -eq $true} 116 | } 117 | 118 | $Result 119 | 120 | 121 | } 122 | End{} 123 | } -------------------------------------------------------------------------------- /src/PSMDATP/Public/Get-MDATPTvmVulnerability.ps1: -------------------------------------------------------------------------------- 1 | function Get-MDATPTvmVulnerability{ 2 | <# 3 | .Synopsis 4 | Get-MDATPTvmVulnerability 5 | 6 | .DESCRIPTION 7 | Get-MDATPTvmVulnerability retrieves Microsoft Defender Advanced Threat Protection Threat and Vulnerability Management 8 | vulnerability informaition 9 | 10 | .PARAMETER Severity 11 | 12 | Severity level assigned to the security vulnerability based on the CVSS score and dynamic factors influenced by the threat landscape 13 | Low, Medium, High, Critical 14 | 15 | .PARAMETER IsExploitAvailable 16 | 17 | Setting this parameter limits the results to vulnerabilities where exploit code for the vulnerability is publicly available 18 | 19 | .PARAMETER MTPConfigFile 20 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 21 | 22 | .EXAMPLE 23 | Get-MDATPTvmVulnerability 24 | 25 | This command retrieves all TVM vulnerability information 26 | 27 | .EXAMPLE 28 | $tvmvulninfo = Get-MDATPTvmVulnerability -MTPConfigFile "C:\Users\Alex\Documents\WindowsPowerShell\Modules\PSMDATP\PoshMTPconfig.json" 29 | 30 | 31 | .NOTES 32 | Version: 1.0 33 | Author: Alex Verboon 34 | Creation Date: 18.07.2020 35 | Purpose/Change: Initial script development 36 | #> 37 | [CmdletBinding()] 38 | Param( 39 | # Severity level 40 | [Parameter(Mandatory=$false)] 41 | [ValidateSet('Low','Medium','High','Critical')] 42 | [String]$SeverityLevel, 43 | 44 | 45 | # publicexploit 46 | [Parameter(Mandatory=$false)] 47 | [switch]$IsExploitAvailable, 48 | 49 | # MDATP configfile 50 | [Parameter(Mandatory=$false)] 51 | [String]$MTPConfigFile 52 | ) 53 | 54 | Begin{ 55 | # Begin Get API Information 56 | If ($MTPConfigFile){ 57 | $PoshMTPconfigFilePath = $MTPConfigFile 58 | Write-Verbose "MTP ConfigFile parameter: $PoshMTPconfigFilePath" 59 | } 60 | Else{ 61 | # If no configfile is defined we use a defined lcoation .\Config\PoshMTPconfig.json 62 | $ConfigFileDir = [IO.Directory]::GetParent($PSScriptRoot) 63 | $PoshMTPconfigFilePath = "$ConfigFileDir\" + "PoshMTPconfig.json" 64 | Write-Verbose "MTP ConfigFile static: $PoshMTPconfigFilePath" 65 | } 66 | 67 | Write-Verbose "Checking for $PoshMTPconfigFilePath" 68 | If (Test-Path -Path $PoshMTPconfigFilePath -PathType Leaf){ 69 | $ConfigSettings = @(Get-Content -Path "$PoshMTPconfigFilePath" | ConvertFrom-Json) 70 | $OAuthUri = $ConfigSettings.API_MDATP.OAuthUri 71 | $ClientID = $ConfigSettings.API_MDATP.ClientID 72 | $ClientSecret = $ConfigSettings.API_MDATP.ClientSecret 73 | } 74 | Else{ 75 | Write-Error "$PoshMTPconfigFilePath not found" 76 | Break 77 | } 78 | # End Get API Information 79 | 80 | # Connect with MDATP API 81 | [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 82 | $Body = @{ 83 | resource = "https://api.securitycenter.windows.com" 84 | client_id = $ClientID 85 | client_secret = $ClientSecret 86 | grant_type = 'client_credentials' 87 | redirectUri = "https://localhost:8000" 88 | } 89 | $Response = Invoke-RestMethod -Method Post -Uri $OAuthUri -Body $Body 90 | 91 | $headers = @{ 92 | 'Content-Type' = 'application/json' 93 | Accept = 'application/json' 94 | Authorization = "Bearer $($Response.access_token)" 95 | } 96 | } 97 | Process{ 98 | Try{ 99 | $tvmuri = "https://api.securitycenter.windows.com/api/vulnerabilities" 100 | $tvmrVulnInfo = @(Invoke-RestMethod -Uri $tvmuri -Headers $Headers -Body $Body -Method Get -Verbose -ContentType application/json) 101 | 102 | } 103 | Catch{ 104 | $errorMessage = $_.Exception.Message 105 | Write-Error "Error retrieving MDATP TVM vulnerability data [$errorMessage]" 106 | } 107 | 108 | If ($Severity){ 109 | $Result = $tvmrVulnInfo.value | Where-Object {$_.VulnerabilitySeverityLevel -eq "$Severity"} 110 | } 111 | Else{ 112 | $Result = $tvmrVulnInfo.value 113 | } 114 | 115 | If ($IsExploitAvailable){ 116 | $Result = $Result | Where-Object {$_.publicExploit -eq $true} 117 | } 118 | 119 | $Result 120 | 121 | 122 | } 123 | End{} 124 | } -------------------------------------------------------------------------------- /src/PSMDATP/Public/Remove-MDATPDevice.ps1: -------------------------------------------------------------------------------- 1 | function Remove-MDATPDevice{ 2 | <# 3 | .Synopsis 4 | Remove-MDATPDevice 5 | 6 | .DESCRIPTION 7 | Remove-MDATPDevice offboards a device from MDATP and adds a tag 'Offboarded' to the device. 8 | 9 | .PARAMETER DeviceName 10 | Computername of the device 11 | 12 | .PARAMETER DeviceID 13 | The unique device ID of the device 14 | 15 | .PARAMETER OffboardReason 16 | Comment to be added to the offboard action, when no value is specified a default comment 'Offobard machine by automation' is added 17 | 18 | .PARAMETER MTPConfigFile 19 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 20 | 21 | .EXAMPLE 22 | Remove-MDATPDevice -DeviceName Computer02 23 | 24 | This command offboards device Computer02 from MDATP 25 | 26 | .NOTES 27 | Version: 1.0 28 | Author: Alex Verboon 29 | Creation Date: 14.03.2020 30 | Purpose/Change: Initial script development 31 | 32 | #> 33 | [CmdletBinding(SupportsShouldProcess)] 34 | Param( 35 | # Computername of the MDATP managed device 36 | [Parameter(Mandatory=$true, 37 | ParameterSetName='DeviceName')] 38 | [ValidateNotNullOrEmpty()] 39 | [String]$DeviceName, 40 | 41 | # Unique device id of the MDATP managed device 42 | [Parameter(Mandatory=$true, 43 | ParameterSetName='DeviceID')] 44 | [ValidateNotNullOrEmpty()] 45 | [String]$DeviceID, 46 | 47 | # Offboard reason 48 | [Parameter(Mandatory=$false)] 49 | [String]$OffboardReason = "Offobard machine by automation", 50 | 51 | # API Configuration 52 | [Parameter(Mandatory=$false)] 53 | [String]$MTPConfigFile 54 | ) 55 | 56 | Begin{ 57 | # Begin Get API Information 58 | If ($MTPConfigFile){ 59 | $PoshMTPconfigFilePath = $MTPConfigFile 60 | Write-Verbose "MTP ConfigFile parameter: $PoshMTPconfigFilePath" 61 | } 62 | Else{ 63 | # If no configfile is defined we use a defined lcoation .\Config\PoshMTPconfig.json 64 | $ConfigFileDir = [IO.Directory]::GetParent($PSScriptRoot) 65 | $PoshMTPconfigFilePath = "$ConfigFileDir\" + "PoshMTPconfig.json" 66 | Write-Verbose "MTP ConfigFile static: $PoshMTPconfigFilePath" 67 | } 68 | 69 | Write-Verbose "Checking for $PoshMTPconfigFilePath" 70 | If (Test-Path -Path $PoshMTPconfigFilePath -PathType Leaf){ 71 | $ConfigSettings = @(Get-Content -Path "$PoshMTPconfigFilePath" | ConvertFrom-Json) 72 | $OAuthUri = $ConfigSettings.API_MDATP.OAuthUri 73 | $ClientID = $ConfigSettings.API_MDATP.ClientID 74 | $ClientSecret = $ConfigSettings.API_MDATP.ClientSecret 75 | } 76 | Else{ 77 | Write-Error "$PoshMTPconfigFilePath not found" 78 | Break 79 | } 80 | # End Get API Information 81 | 82 | # Connect with MDATP API 83 | [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 84 | $Body = @{ 85 | resource = "https://api.securitycenter.windows.com" 86 | client_id = $ClientID 87 | client_secret = $ClientSecret 88 | grant_type = 'client_credentials' 89 | redirectUri = "https://localhost:8000" 90 | } 91 | $Response = Invoke-RestMethod -Method Post -Uri $OAuthUri -Body $Body 92 | #$Authorization = Invoke-RestMethod -Method Post -Uri $OAuthUri -Body $Body -ContentType "application/x-www-form-urlencoded" -UseBasicParsing 93 | #$access_token = $Authorization.access_token 94 | 95 | $headers = @{ 96 | 'Content-Type' = 'application/json' 97 | Accept = 'application/json' 98 | Authorization = "Bearer $($Response.access_token)" 99 | } 100 | } 101 | Process{ 102 | # MDATP API URI 103 | $MDATP_API_URI = "https://api.securitycenter.windows.com/api" 104 | $OffboardingStatus = $false 105 | 106 | # change the devicename to lowercase 107 | $DeviceName = $DeviceName.ToLower() 108 | 109 | # Get the MDATP devices 110 | $MachineAPI = "$MDATP_API_URI/machines" 111 | $Machines = @(Invoke-RestMethod -Uri "$MachineAPI" -Headers $Headers -Method Get -Verbose -ContentType application/json) 112 | If ($DeviceName){ 113 | $ActionDevice = @($machines.value | Select-Object * | Where-Object {$_.computerDnsName -like "$DeviceName"}) 114 | } 115 | Elseif ($DeviceID){ 116 | $ActionDevice = @($machines.value | Select-Object * | Where-Object {$_.id -like "$DeviceID"}) 117 | } 118 | 119 | If($ActionDevice.count -gt 1){ 120 | Write-Warning "There are multiple device records with this computername, please specify the MDATP device id" 121 | $ActionDevice | Select-Object computerDnsName, id 122 | Break 123 | } 124 | Elseif($ActionDevice.count -eq 0){ 125 | Write-Warning "No device records found that match DeviceName $DeviceName" 126 | Break 127 | } 128 | Elseif($ActionDevice.count -eq 1){ 129 | $MDATPDeviceID = $ActionDevice.id 130 | # set offboarding comment 131 | $OffboardReasonInput = @{"Comment" = "$OffboardReason"} | ConvertTo-Json 132 | if ($pscmdlet.ShouldProcess("$DeviceName", "offobarding device from MDATP")){ 133 | $Offboarduri = "$MachineAPI/$MDATPDeviceID/offboard" 134 | Try{ 135 | $OffboardAction =Invoke-WebRequest -Uri $Offboarduri -Headers $Headers -Method Post -Body $OffboardReasonInput 136 | If ($OffboardAction.StatusCode -eq 201){ 137 | Write-Verbose "Offboarding device $DeviceName completed successfully" 138 | # Tag machine 139 | $offboardTag = @{"Value" = "Offboarded"; "Action"= "Add"} | ConvertTo-Json 140 | $Taguri = "$MachineAPI/$MDATPDeviceID/tags" 141 | Invoke-WebRequest -Uri $Taguri -Headers $Headers -Method Post -Body $offboardTag 142 | $OffboardingStatus = $true 143 | # end tag machine 144 | $True 145 | } 146 | Else{ 147 | Write-Warning "Offboarding device $DeviceName failed!" 148 | Write-Error "StatusCode: $($OffboardAction.StatusCode)" 149 | $OffboardingStatus = $false 150 | } 151 | } 152 | Catch{ 153 | $ex = $_.Exception 154 | $errorResponse = $ex.Response.GetResponseStream() 155 | $reader = New-Object System.IO.StreamReader($errorResponse) 156 | $reader.BaseStream.Position = 0 157 | $reader.DiscardBufferedData() 158 | $responseBody = $reader.ReadToEnd(); 159 | Write-Verbose "Response content:`n$responseBody" 160 | Write-Error "Request to $Uri failed with HTTP Status $($ex.Response.StatusCode) $($ex.Response.StatusDescription)" 161 | } 162 | } 163 | } 164 | } 165 | End{ 166 | Write-Verbose "Device: $DeviceName" 167 | Write-Verbose "DeviceID: $MDATPDeviceID" 168 | Write-Verbose "Reason: $OffboardReason" 169 | Write-Verbose "Offboardingstatus: $OffboardingStatus" 170 | Write-Verbose "StatusCode: $($response.statuscode)" 171 | Write-Verbose "StatusDescription: $($response.StatusDescription)" 172 | } 173 | } -------------------------------------------------------------------------------- /src/PSMDATP/Public/Remove-MDATPDeviceTag.ps1: -------------------------------------------------------------------------------- 1 | function Remove-MDATPDeviceTag{ 2 | <# 3 | .Synopsis 4 | Remove-MDATPDeviceTag 5 | 6 | .Description 7 | Remove-MDATPDeviceTag removes the specified Tag to the MDATP device. 8 | 9 | .PARAMETER DeviceName 10 | Computername of the device 11 | 12 | .PARAMETER DeviceID 13 | The unique device ID of the device 14 | 15 | .PARAMETER Tag 16 | The value of the tag to be removed 17 | 18 | .PARAMETER MTPConfigFile 19 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 20 | 21 | 22 | .EXAMPLE 23 | Remove-MDATPDeviceTag -DeviceName computer02 -Tag 'Testing' -verbose 24 | 25 | This command removes the tag 'testing' from device 'computer02' 26 | 27 | .NOTES 28 | Version: 1.0 29 | Author: Alex Verboon 30 | Creation Date: 16.03.2020 31 | Purpose/Change: Initial script development 32 | #> 33 | 34 | [CmdletBinding(SupportsShouldProcess)] 35 | Param( 36 | 37 | # Computername of the MDATP managed device 38 | [Parameter(Mandatory=$true, 39 | ParameterSetName='DeviceName')] 40 | [ValidateNotNullOrEmpty()] 41 | [String]$DeviceName, 42 | 43 | # Unique device id of the MDATP managed device 44 | [Parameter(Mandatory=$true, 45 | ParameterSetName='DeviceID')] 46 | [ValidateNotNullOrEmpty()] 47 | [String]$DeviceID, 48 | 49 | # Tag to be removed from the device 50 | [Parameter(Mandatory=$true)] 51 | [String]$Tag, 52 | 53 | # API Configuration file 54 | [Parameter(Mandatory=$false)] 55 | [String]$MTPConfigFile 56 | ) 57 | Begin{ 58 | # Begin Get API Information 59 | If ($MTPConfigFile){ 60 | $PoshMTPconfigFilePath = $MTPConfigFile 61 | Write-Verbose "MTP ConfigFile parameter: $PoshMTPconfigFilePath" 62 | } 63 | Else{ 64 | # If no configfile is defined we use a defined lcoation .\Config\PoshMTPconfig.json 65 | $ConfigFileDir = [IO.Directory]::GetParent($PSScriptRoot) 66 | $PoshMTPconfigFilePath = "$ConfigFileDir\" + "PoshMTPconfig.json" 67 | Write-Verbose "MTP ConfigFile static: $PoshMTPconfigFilePath" 68 | } 69 | 70 | Write-Verbose "Checking for $PoshMTPconfigFilePath" 71 | If (Test-Path -Path $PoshMTPconfigFilePath -PathType Leaf){ 72 | $ConfigSettings = @(Get-Content -Path "$PoshMTPconfigFilePath" | ConvertFrom-Json) 73 | $OAuthUri = $ConfigSettings.API_MDATP.OAuthUri 74 | $ClientID = $ConfigSettings.API_MDATP.ClientID 75 | $ClientSecret = $ConfigSettings.API_MDATP.ClientSecret 76 | } 77 | Else{ 78 | Write-Error "$PoshMTPconfigFilePath not found" 79 | Break 80 | } 81 | # End Get API Information 82 | 83 | # Connect with MDATP API 84 | [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 85 | $Body = @{ 86 | resource = "https://api.securitycenter.windows.com" 87 | client_id = $ClientID 88 | client_secret = $ClientSecret 89 | grant_type = 'client_credentials' 90 | redirectUri = "https://localhost:8000" 91 | } 92 | $Response = Invoke-RestMethod -Method Post -Uri $OAuthUri -Body $Body 93 | #$Authorization = Invoke-RestMethod -Method Post -Uri $OAuthUri -Body $Body -ContentType "application/x-www-form-urlencoded" -UseBasicParsing 94 | #$access_token = $Authorization.access_token 95 | 96 | $headers = @{ 97 | 'Content-Type' = 'application/json' 98 | Accept = 'application/json' 99 | Authorization = "Bearer $($Response.access_token)" 100 | } 101 | } 102 | Process{ 103 | # MDATP API URI 104 | $MDATP_API_URI = "https://api.securitycenter.windows.com/api" 105 | 106 | # change the devicename to lowercase 107 | $DeviceName = $DeviceName.ToLower() 108 | 109 | # Get the MDATP devices 110 | $MachineAPI = "$MDATP_API_URI/machines" 111 | $Machines = @(Invoke-RestMethod -Uri "$MachineAPI" -Headers $Headers -Method Get -Verbose -ContentType application/json) 112 | If ($DeviceName){ 113 | $ActionDevice = @($machines.value | Select-Object * | Where-Object {$_.computerDnsName -like "$DeviceName"}) 114 | } 115 | Elseif ($DeviceID){ 116 | $ActionDevice = @($machines.value | Select-Object * | Where-Object {$_.id -like "$DeviceID"}) 117 | } 118 | 119 | If($ActionDevice.count -gt 1){ 120 | Write-Warning "There are multiple device records with this computername, please specify the MDATP device id" 121 | $ActionDevice | Select-Object computerDnsName, id 122 | Break 123 | } 124 | Elseif($ActionDevice.count -eq 0){ 125 | Write-Warning "No device records found that match DeviceName $DeviceName" 126 | Break 127 | } 128 | Elseif($ActionDevice.count -eq 1){ 129 | $MDATPDeviceID = $ActionDevice.id 130 | if ($pscmdlet.ShouldProcess("$DeviceName", "Remvoing tag: $Tag")){ 131 | Try{ 132 | # Tag machine 133 | $AddTag = @{"Value" = "$Tag"; "Action"= "Remove"} | ConvertTo-Json 134 | $Taguri = "$MachineAPI/$MDATPDeviceID/tags" 135 | $response =Invoke-WebRequest -Uri $Taguri -Headers $Headers -Method Post -Body $AddTag 136 | # end tag machine 137 | If ($response.StatusCode -eq 200){ 138 | Write-Verbose "Tag: $Tag was successfully removed from device $DeviceName" 139 | $True 140 | } 141 | Else{ 142 | Write-Warning "Removing tag $Tag from device $DeviceName failed!" 143 | Write-Error "StatusCode: $($response.StatusCode)" 144 | $false 145 | } 146 | } 147 | Catch{ 148 | $ex = $_.Exception 149 | $errorResponse = $ex.Response.GetResponseStream() 150 | $reader = New-Object System.IO.StreamReader($errorResponse) 151 | $reader.BaseStream.Position = 0 152 | $reader.DiscardBufferedData() 153 | $responseBody = $reader.ReadToEnd(); 154 | Write-Verbose "Response content:`n$responseBody" 155 | Write-Error "Request to $Uri failed with HTTP Status $($ex.Response.StatusCode) $($ex.Response.StatusDescription)" 156 | } 157 | } 158 | } 159 | } 160 | End{ 161 | Write-Verbose "Device: $DeviceName" 162 | Write-Verbose "DeviceID: $MDATPDeviceID" 163 | Write-Verbose "Removed tag: $Tag" 164 | Write-Verbose "StatusCode: $($response.statuscode)" 165 | Write-Verbose "StatusDescription: $($response.StatusDescription)" 166 | } 167 | } -------------------------------------------------------------------------------- /src/PSMDATP/Public/Remove-MDATPIndicator.ps1: -------------------------------------------------------------------------------- 1 | function Remove-MDATPIndicator{ 2 | <# 3 | .Synopsis 4 | Remove-MDATPIndicator 5 | 6 | .DESCRIPTION 7 | Remove-MDATPIndicator removes a custom indicator from the Microsoft Defender ATP 8 | instance 9 | 10 | .PARAMETER IndicatorID 11 | The unique custom indicator ID 12 | 13 | .PARAMETER MTPConfigFile 14 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 15 | 16 | .EXAMPLE 17 | Remove-MDATPIndicator -IndicatorID 25 18 | 19 | This command removes the custom indicator with id 25 20 | 21 | .NOTES 22 | Version: 1.0 23 | Author: Alex Verboon 24 | Creation Date: 05.05.2020 25 | Purpose/Change: Initial script development 26 | 27 | #> 28 | [CmdletBinding(SupportsShouldProcess)] 29 | Param( 30 | # Unique custom indicator ID 31 | [Parameter(Mandatory=$true)] 32 | [ValidateNotNullOrEmpty()] 33 | [ValidateRange(1,150000)] 34 | [int]$IndicatorID, 35 | 36 | # API Configuration 37 | [Parameter(Mandatory=$false)] 38 | [String]$MTPConfigFile 39 | ) 40 | 41 | Begin{ 42 | # Begin Get API Information 43 | If ($MTPConfigFile){ 44 | $PoshMTPconfigFilePath = $MTPConfigFile 45 | Write-Verbose "MTP ConfigFile parameter: $PoshMTPconfigFilePath" 46 | } 47 | Else{ 48 | # If no configfile is defined we use a defined lcoation .\Config\PoshMTPconfig.json 49 | $ConfigFileDir = [IO.Directory]::GetParent($PSScriptRoot) 50 | $PoshMTPconfigFilePath = "$ConfigFileDir\" + "PoshMTPconfig.json" 51 | Write-Verbose "MTP ConfigFile static: $PoshMTPconfigFilePath" 52 | } 53 | 54 | Write-Verbose "Checking for $PoshMTPconfigFilePath" 55 | If (Test-Path -Path $PoshMTPconfigFilePath -PathType Leaf){ 56 | $ConfigSettings = @(Get-Content -Path "$PoshMTPconfigFilePath" | ConvertFrom-Json) 57 | $OAuthUri = $ConfigSettings.API_MDATP.OAuthUri 58 | $ClientID = $ConfigSettings.API_MDATP.ClientID 59 | $ClientSecret = $ConfigSettings.API_MDATP.ClientSecret 60 | } 61 | Else{ 62 | Write-Error "$PoshMTPconfigFilePath not found" 63 | Break 64 | } 65 | # End Get API Information 66 | 67 | # Connect with MDATP API 68 | [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 69 | $Body = @{ 70 | resource = "https://api.securitycenter.windows.com" 71 | client_id = $ClientID 72 | client_secret = $ClientSecret 73 | grant_type = 'client_credentials' 74 | redirectUri = "https://localhost:8000" 75 | } 76 | $Response = Invoke-RestMethod -Method Post -Uri $OAuthUri -Body $Body 77 | 78 | $headers = @{ 79 | 'Content-Type' = 'application/json' 80 | Accept = 'application/json' 81 | Authorization = "Bearer $($Response.access_token)" 82 | } 83 | } 84 | Process{ 85 | Try{ 86 | $indicatorsuri = "https://api.securitycenter.windows.com/api/indicators" 87 | $indicators = @(Invoke-RestMethod -Uri $indicatorsuri -Headers $Headers -Body $Body -Method Get -ContentType application/json) 88 | } 89 | Catch{ 90 | $errorMessage = $_.Exception.Message 91 | Write-Error "Error retrieving MDATP TI indicators data [$errorMessage]" 92 | } 93 | 94 | $IndicatorInfo = $indicators.value | Where-Object {$_.id -eq $IndicatorID} 95 | $RemoveIndicatorsuri = "https://api.securitycenter.windows.com/api/indicators/$IndicatorID" 96 | 97 | if ($pscmdlet.ShouldProcess("$IndicatorID", "Remvoing Indicator - $($IndicatorInfo.IndicatorType) - $($IndicatorInfo.indicatorvalue)")){ 98 | Try{ 99 | $response = Invoke-WebRequest -Uri $RemoveIndicatorsuri -Headers $Headers -Method Delete 100 | If ($response.StatusCode -eq 204){ 101 | Write-Verbose "Indicator: $IndicatorID - $($IndicatorInfo.IndicatorType) - $($IndicatorInfo.indicatorvalue) was successfully removed" 102 | $True 103 | } 104 | Else{ 105 | Write-Warning "Removing Indicator: $IndicatorID failed" 106 | Write-Error "StatusCode: $($response.StatusCode)" 107 | $False 108 | } 109 | } 110 | Catch{ 111 | $ex = $_.Exception 112 | $errorResponse = $ex.Response.GetResponseStream() 113 | $reader = New-Object System.IO.StreamReader($errorResponse) 114 | $reader.BaseStream.Position = 0 115 | $reader.DiscardBufferedData() 116 | $responseBody = $reader.ReadToEnd(); 117 | Write-Verbose "Response content:`n$responseBody" 118 | Write-Error "Request to $Uri failed with HTTP Status $($ex.Response.StatusCode) $($ex.Response.StatusDescription)" 119 | } 120 | } 121 | } 122 | End{ 123 | Write-Verbose "IndicatorID: $IndicatorID" 124 | Write-Verbose "IndicatorType: $($IndicatorInfo.indicatorType)" 125 | Write-Verbose "Indicatorvalue: $($IndicatorInfo.indicatorValue)" 126 | Write-Verbose "StatusCode: $($response.statuscode)" 127 | Write-Verbose "StatusDescription: $($response.StatusDescription)" 128 | } 129 | } -------------------------------------------------------------------------------- /src/PSMDATP/Public/Set-MDATPAlert.ps1: -------------------------------------------------------------------------------- 1 | function Set-MDATPAlert{ 2 | <# 3 | .Synopsis 4 | Set-MDATPAlert 5 | 6 | .Description 7 | Set-MDATPAlert updates a Microsoft Defender Advanced Threat Protection alert through the Microsoft Defender Advanced Threat Protection Alerts Rest API. 8 | 9 | .PARAMETER AlertID 10 | Identity of the Indicator entity. Required 11 | 12 | .PARAMETER status 13 | The status that will be set for the alert in the organization. Possible values are: "New", "InProgress", and "Resolved". Optional 14 | 15 | .PARAMETER assignedTo 16 | The userid that will be set for assigned to field for the the alert in the organization. Example: secop2@contoso.com. Optional 17 | 18 | .PARAMETER classification 19 | The classification that will be set for the alert in the organization. Possible values are: "Unknown", "FalsePositive", and "TruePositive". Optional 20 | 21 | .PARAMETER determination 22 | The determination that will be set for the alert in the organization. Possible values are: "NotAvailable", "Apt", "Malware", "SecurityPersonnel", "SecurityTesting", "UnwantedSoftware", and "Other". Optional 23 | 24 | .PARAMETER comments 25 | The comment field that will be set for the the alert in the organization. Optional 26 | 27 | .PARAMETER MTPConfigFile 28 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 29 | 30 | .EXAMPLE 31 | Set-WDATPAlert -AlertID 121688558380765161_2136280442 -status Resolved -assignedTo secop2@contoso.com -classification FalsePositive -determination Malware -comments "Resolve my alert and assign to secop2 32 | 33 | .NOTES 34 | Version: 1.0 35 | Author: Daniel Lacher 36 | Creation Date: 02.11.2020 37 | Purpose/Change: Initial pass at creation of function to allow for update to MDATP Alerts via API and PSMDATP framework. 38 | 39 | #> 40 | [CmdletBinding(SupportsShouldProcess=$true)] 41 | Param( 42 | # MDATP Alert ID. 43 | [Parameter(Mandatory=$true)] 44 | [ValidateNotNullorEmpty()] 45 | [String]$AlertID, 46 | 47 | # Specifies the current status of the alert. The property values are: 'New', 'InProgress' and 'Resolved'. 48 | [Parameter(Mandatory=$false)] 49 | [ValidateSet('New', 'InProgress','Resolved')] 50 | [String]$status, 51 | 52 | # Owner of the alert. 53 | [Parameter(Mandatory=$false)] 54 | [ValidateNotNullorEmpty()] 55 | [String]$assignedTo, 56 | 57 | # Specifies the specification of the alert. The property values are: 'Unknown', 'FalsePositive', 'TruePositive'. 58 | [Parameter(Mandatory=$false)] 59 | [ValidateSet('Unknown', 'FalsePositive', 'TruePositive')] 60 | [String]$classification, 61 | 62 | # Specifies the determination of the alert. The property values are: 'NotAvailable', 'Apt', 'Malware', 'SecurityPersonnel', 'SecurityTesting', 'UnwantedSoftware', 'Other'. 63 | [Parameter(Mandatory=$false)] 64 | [ValidateSet('NotAvailable', 'Apt', 'Malware', 'SecurityPersonnel', 'SecurityTesting', 'UnwantedSoftware', 'Other')] 65 | [String]$determination, 66 | 67 | # Comment to be added to the alert. 68 | [Parameter(Mandatory=$false)] 69 | [ValidateNotNullorEmpty()] 70 | [String]$comments, 71 | 72 | # API Configuration file 73 | [Parameter(Mandatory=$false)] 74 | [String]$MTPConfigFile 75 | ) 76 | 77 | Begin{ 78 | # Begin Get API Information 79 | If ($MTPConfigFile){ 80 | $PoshMTPconfigFilePath = $MTPConfigFile 81 | Write-Verbose "MTP ConfigFile parameter: $PoshMTPconfigFilePath" 82 | } 83 | Else{ 84 | # If no configfile is defined we use a defined lcoation .\PoshMTPconfig.json 85 | $ConfigFileDir = [IO.Directory]::GetParent($PSScriptRoot) 86 | $PoshMTPconfigFilePath = "$ConfigFileDir\" + "PoshMTPconfig.json" 87 | Write-Verbose "MTP ConfigFile static: $PoshMTPconfigFilePath" 88 | } 89 | 90 | Write-Verbose "Checking for $PoshMTPconfigFilePath" 91 | If (Test-Path -Path $PoshMTPconfigFilePath -PathType Leaf){ 92 | $ConfigSettings = @(Get-Content -Path "$PoshMTPconfigFilePath" | ConvertFrom-Json) 93 | $OAuthUri = $ConfigSettings.API_MDATP.OAuthUri 94 | $ClientID = $ConfigSettings.API_MDATP.ClientID 95 | $ClientSecret = $ConfigSettings.API_MDATP.ClientSecret 96 | } 97 | Else{ 98 | Write-Error "$PoshMTPconfigFilePath not found" 99 | Break 100 | } 101 | # End Get API Information 102 | 103 | # Connect with MDATP API 104 | [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 105 | $Body = @{ 106 | resource = "https://api.securitycenter.windows.com" 107 | client_id = "$ClientID" 108 | client_secret = "$ClientSecret" 109 | grant_type = 'client_credentials' 110 | redirectUri = "https://localhost:8000" 111 | } 112 | $Response = Invoke-RestMethod -Method Post -Uri $OAuthUri -Body $Body 113 | 114 | 115 | $headers = @{ 116 | 'Content-Type' = 'application/json' 117 | Accept = 'application/json' 118 | Authorization = "Bearer $($Response.access_token)" 119 | } 120 | } 121 | 122 | Process{ 123 | 124 | $alertsuri = "https://api.securitycenter.windows.com/api/alerts/$AlertID" 125 | $UpdateAlert = @{ 126 | "status" = "$status" 127 | "assignedTo" = "$assignedTo" 128 | "classification" = "$classification" 129 | "determination" = "$determination" 130 | "comment" = "$comments" 131 | } 132 | 133 | $UpdateAlert = $UpdateAlert | ConvertTo-Json 134 | Write-Verbose "Request body: $UpdateAlert" 135 | 136 | if ($pscmdlet.ShouldProcess("$AlertID", "Updating Alert: $AlertID")){ 137 | Try{ 138 | $response = Invoke-WebRequest -Uri $alertsuri -Headers $Headers -Method Patch -Body $UpdateAlert 139 | If ($response.StatusCode -eq 200){ 140 | Write-Verbose "Alert: $AlertID - was successfully updated " 141 | $True 142 | } 143 | Else{ 144 | Write-Warning "Alert: $AlertID - update failed" 145 | Write-Error "StatusCode: $($response.StatusCode)" 146 | $False 147 | } 148 | } 149 | Catch{ 150 | $ex = $_.Exception 151 | $errorResponse = $ex.Response.GetResponseStream() 152 | $reader = New-Object System.IO.StreamReader($errorResponse) 153 | $reader.BaseStream.Position = 0 154 | $reader.DiscardBufferedData() 155 | $responseBody = $reader.ReadToEnd(); 156 | Write-Verbose "Response content:`n$responseBody" 157 | Write-Error "Request to $Uri failed with HTTP Status $($ex.Response.StatusCode) $($ex.Response.StatusDescription)" 158 | } 159 | } 160 | } 161 | End{ 162 | Write-Verbose "AlertID: $AlertID"; 163 | Write-Verbose "Status: $status"; 164 | Write-Verbose "AssignedTo:$assignedTo"; 165 | Write-Verbose "Classification: $classification"; 166 | Write-Verbose "Determination: $determination"; 167 | Write-Verbose "Comments: $comments" 168 | } 169 | } -------------------------------------------------------------------------------- /src/PSMDATP/Public/Start-MDATPAppRestriction.ps1: -------------------------------------------------------------------------------- 1 | function Start-MDATPAppRestriction{ 2 | <# 3 | .Synopsis 4 | Start-MDATPAppRestriction 5 | 6 | .DESCRIPTION 7 | Start-MDATPAppRestriction restricts execution of all applications on the machine. 8 | 9 | .PARAMETER DeviceName 10 | Computername of the device 11 | 12 | .PARAMETER DeviceID 13 | The unique device ID of the device 14 | 15 | .PARAMETER Comment 16 | Comment that is added to the request, if no comment is provided the default commment 'submitted by automation' is used. 17 | 18 | .PARAMETER MTPConfigFile 19 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 20 | 21 | .EXAMPLE 22 | Start-MDATPAppRestriction -DeviceName computer02 -Comment "incident1973" 23 | 24 | This command restricts application execution on device computer02 25 | 26 | .NOTES 27 | Version: 1.0 28 | Author: Alex Verboon 29 | Creation Date: 12.04.2020 30 | Purpose/Change: Initial script development 31 | #> 32 | [CmdletBinding(SupportsShouldProcess)] 33 | Param( 34 | # Computername of the MDATP managed device 35 | [Parameter(Mandatory=$true, 36 | ParameterSetName='DeviceName')] 37 | [ValidateNotNullOrEmpty()] 38 | [String]$DeviceName, 39 | 40 | # Unique device id of the MDATP managed device 41 | [Parameter(Mandatory=$true, 42 | ParameterSetName='DeviceID')] 43 | [ValidateNotNullOrEmpty()] 44 | [String]$DeviceID, 45 | 46 | # Comment for the request 47 | [Parameter(Mandatory=$false)] 48 | [String]$Comment, 49 | 50 | # API Configuration file 51 | [Parameter(Mandatory=$false)] 52 | [String]$MTPConfigFile 53 | ) 54 | 55 | Begin{ 56 | # Begin Get API Information 57 | If ($MTPConfigFile){ 58 | $PoshMTPconfigFilePath = $MTPConfigFile 59 | Write-Verbose "MTP ConfigFile parameter: $PoshMTPconfigFilePath" 60 | } 61 | Else{ 62 | # If no configfile is defined we use a defined lcoation .\Config\PoshMTPconfig.json 63 | $ConfigFileDir = [IO.Directory]::GetParent($PSScriptRoot) 64 | $PoshMTPconfigFilePath = "$ConfigFileDir\" + "PoshMTPconfig.json" 65 | Write-Verbose "MTP ConfigFile static: $PoshMTPconfigFilePath" 66 | } 67 | 68 | Write-Verbose "Checking for $PoshMTPconfigFilePath" 69 | If (Test-Path -Path $PoshMTPconfigFilePath -PathType Leaf){ 70 | $ConfigSettings = @(Get-Content -Path "$PoshMTPconfigFilePath" | ConvertFrom-Json) 71 | $OAuthUri = $ConfigSettings.API_MDATP.OAuthUri 72 | $ClientID = $ConfigSettings.API_MDATP.ClientID 73 | $ClientSecret = $ConfigSettings.API_MDATP.ClientSecret 74 | } 75 | Else{ 76 | Write-Error "$PoshMTPconfigFilePath not found" 77 | Break 78 | } 79 | # End Get API Information 80 | 81 | # Connect with MDATP API 82 | [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 83 | $Body = @{ 84 | resource = "https://api.securitycenter.windows.com" 85 | client_id = $ClientID 86 | client_secret = $ClientSecret 87 | grant_type = 'client_credentials' 88 | redirectUri = "https://localhost:8000" 89 | } 90 | $Response = Invoke-RestMethod -Method Post -Uri $OAuthUri -Body $Body 91 | #$Authorization = Invoke-RestMethod -Method Post -Uri $OAuthUri -Body $Body -ContentType "application/x-www-form-urlencoded" -UseBasicParsing 92 | #$access_token = $Authorization.access_token 93 | 94 | $headers = @{ 95 | 'Content-Type' = 'application/json' 96 | Accept = 'application/json' 97 | Authorization = "Bearer $($Response.access_token)" 98 | } 99 | } 100 | Process{ 101 | # MDATP API URI 102 | $MDATP_API_URI = "https://api.securitycenter.windows.com/api" 103 | 104 | If([string]::IsNullOrEmpty($Comment)){ 105 | $Comment = "submitted by automation" 106 | } 107 | 108 | # change the devicename to lowercase 109 | $DeviceName = $DeviceName.ToLower() 110 | 111 | # Get the MDATP devices 112 | $MachineAPI = "$MDATP_API_URI/machines" 113 | $Machines = @(Invoke-RestMethod -Uri "$MachineAPI" -Headers $Headers -Method Get -Verbose -ContentType application/json) 114 | If ($DeviceName){ 115 | $ActionDevice = @($machines.value | Select-Object * | Where-Object {$_.computerDnsName -like "$DeviceName"}) 116 | } 117 | Elseif ($DeviceID){ 118 | $ActionDevice = @($machines.value | Select-Object * | Where-Object {$_.id -like "$DeviceID"}) 119 | } 120 | 121 | If($ActionDevice.count -gt 1){ 122 | Write-Warning "There are multiple device records with this computername, please specify the MDATP device id" 123 | $ActionDevice | Select-Object computerDnsName, id 124 | Break 125 | } 126 | Elseif($ActionDevice.count -eq 0){ 127 | Write-Warning "No device records found that match DeviceName $DeviceName" 128 | Break 129 | } 130 | Elseif($ActionDevice.count -eq 1){ 131 | $MDATPDeviceID = $ActionDevice.id 132 | 133 | if ($pscmdlet.ShouldProcess("$DeviceName", "Start Isolation: $IsolationType")){ 134 | Try{ 135 | $AppRestrictionInput = @{"Comment" = "$Comment"} | ConvertTo-Json 136 | $AppRestrictionUri = "$MachineAPI/$MDATPDeviceID/restrictCodeExecution " 137 | $AppRestrictionResponse =Invoke-WebRequest -Uri $AppRestrictionUri -Headers $Headers -Method Post -Body $AppRestrictionInput 138 | If ($AppRestrictionResponse.StatusCode -eq 201){ 139 | $ActionID = $AppRestrictionResponse.content | ConvertFrom-Json | Select-Object -ExpandProperty id 140 | Write-Verbose "App restriction was successfully initiated for device $DeviceName -ActionID: $ActionID" 141 | $ActionID 142 | } 143 | Else{ 144 | $ActionID = "0000000-0000-0000-0000-000000000000" 145 | Write-Warning "Initiating app restriction for device $DeviceName failed!" 146 | Write-Error "StatusCode: $($AppRestrictionResponse.StatusCode)" 147 | $ActionID 148 | } 149 | } 150 | Catch{ 151 | $ex = $_.Exception 152 | $errorResponse = $ex.Response.GetResponseStream() 153 | $reader = New-Object System.IO.StreamReader($errorResponse) 154 | $reader.BaseStream.Position = 0 155 | $reader.DiscardBufferedData() 156 | $responseBody = $reader.ReadToEnd(); 157 | Write-Verbose "Response content:`n$responseBody" 158 | Write-Error "Request to $Uri failed with HTTP Status $($ex.Response.StatusCode) $($ex.Response.StatusDescription)" 159 | $ActionID = "0000000-0000-0000-0000-000000000000" 160 | $ActionID 161 | } 162 | } 163 | } 164 | } 165 | End{ 166 | Write-Verbose "Device: $DeviceName" 167 | Write-Verbose "DeviceID: $MDATPDeviceID" 168 | Write-Verbose "Comment: $Comment" 169 | Write-Verbose "ActionID: $($ActionID)" 170 | Write-Verbose "StatusCode: $($IsolateResponse.statuscode)" 171 | Write-Verbose "StatusDescription: $($IsolateResponse.StatusDescription)" 172 | } 173 | } -------------------------------------------------------------------------------- /src/PSMDATP/Public/Stop-MDATPAppRestriction.ps1: -------------------------------------------------------------------------------- 1 | function Stop-MDATPAppRestriction{ 2 | <# 3 | .Synopsis 4 | Stop-MDATPAppRestriction 5 | 6 | .DESCRIPTION 7 | Stop-MDATPAppRestriction removes app execution restrictions on the machine. 8 | 9 | .PARAMETER DeviceName 10 | Computername of the device 11 | 12 | .PARAMETER DeviceID 13 | The unique device ID of the device 14 | 15 | .PARAMETER Comment 16 | Comment that is added to the request, if no comment is provided the default commment 'submitted by automation' is used. 17 | 18 | .PARAMETER MTPConfigFile 19 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 20 | 21 | .EXAMPLE 22 | Stop-MDATPAppRestriction -DeviceName computer02 -Comment "incident1973" 23 | 24 | This command removes app execution restrictions from device computer02 25 | 26 | .NOTES 27 | Version: 1.0 28 | Author: Alex Verboon 29 | Creation Date: 12.04.2020 30 | Purpose/Change: Initial script development 31 | #> 32 | [CmdletBinding(SupportsShouldProcess)] 33 | Param( 34 | # Computername of the MDATP managed device 35 | [Parameter(Mandatory=$true, 36 | ParameterSetName='DeviceName')] 37 | [ValidateNotNullOrEmpty()] 38 | [String]$DeviceName, 39 | 40 | # Unique device id of the MDATP managed device 41 | [Parameter(Mandatory=$true, 42 | ParameterSetName='DeviceID')] 43 | [ValidateNotNullOrEmpty()] 44 | [String]$DeviceID, 45 | 46 | # Comment for the request 47 | [Parameter(Mandatory=$false)] 48 | [String]$Comment, 49 | 50 | # API Configuration file 51 | [Parameter(Mandatory=$false)] 52 | [String]$MTPConfigFile 53 | ) 54 | 55 | Begin{ 56 | # Begin Get API Information 57 | If ($MTPConfigFile){ 58 | $PoshMTPconfigFilePath = $MTPConfigFile 59 | Write-Verbose "MTP ConfigFile parameter: $PoshMTPconfigFilePath" 60 | } 61 | Else{ 62 | # If no configfile is defined we use a defined lcoation .\Config\PoshMTPconfig.json 63 | $ConfigFileDir = [IO.Directory]::GetParent($PSScriptRoot) 64 | $PoshMTPconfigFilePath = "$ConfigFileDir\" + "PoshMTPconfig.json" 65 | Write-Verbose "MTP ConfigFile static: $PoshMTPconfigFilePath" 66 | } 67 | 68 | Write-Verbose "Checking for $PoshMTPconfigFilePath" 69 | If (Test-Path -Path $PoshMTPconfigFilePath -PathType Leaf){ 70 | $ConfigSettings = @(Get-Content -Path "$PoshMTPconfigFilePath" | ConvertFrom-Json) 71 | $OAuthUri = $ConfigSettings.API_MDATP.OAuthUri 72 | $ClientID = $ConfigSettings.API_MDATP.ClientID 73 | $ClientSecret = $ConfigSettings.API_MDATP.ClientSecret 74 | } 75 | Else{ 76 | Write-Error "$PoshMTPconfigFilePath not found" 77 | Break 78 | } 79 | # End Get API Information 80 | 81 | # Connect with MDATP API 82 | [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 83 | $Body = @{ 84 | resource = "https://api.securitycenter.windows.com" 85 | client_id = $ClientID 86 | client_secret = $ClientSecret 87 | grant_type = 'client_credentials' 88 | redirectUri = "https://localhost:8000" 89 | } 90 | $Response = Invoke-RestMethod -Method Post -Uri $OAuthUri -Body $Body 91 | #$Authorization = Invoke-RestMethod -Method Post -Uri $OAuthUri -Body $Body -ContentType "application/x-www-form-urlencoded" -UseBasicParsing 92 | #$access_token = $Authorization.access_token 93 | $headers = @{ 94 | 'Content-Type' = 'application/json' 95 | Accept = 'application/json' 96 | Authorization = "Bearer $($Response.access_token)" 97 | } 98 | } 99 | Process{ 100 | $MDATP_API_URI = "https://api.securitycenter.windows.com/api" 101 | If([string]::IsNullOrEmpty($Comment)){ 102 | $Comment = "submitted by automation" 103 | } 104 | $DeviceName = $DeviceName.ToLower() 105 | # Get the MDATP devices 106 | $MachineAPI = "$MDATP_API_URI/machines" 107 | $Machines = @(Invoke-RestMethod -Uri "$MachineAPI" -Headers $Headers -Method Get -Verbose -ContentType application/json) 108 | If ($DeviceName){ 109 | $ActionDevice = @($machines.value | Select-Object * | Where-Object {$_.computerDnsName -like "$DeviceName"}) 110 | } 111 | Elseif ($DeviceID){ 112 | $ActionDevice = @($machines.value | Select-Object * | Where-Object {$_.id -like "$DeviceID"}) 113 | } 114 | 115 | If($ActionDevice.count -gt 1){ 116 | Write-Warning "There are multiple device records with this computername, please specify the MDATP device id" 117 | $ActionDevice | Select-Object computerDnsName, id 118 | Break 119 | } 120 | Elseif($ActionDevice.count -eq 0){ 121 | Write-Warning "No device records found that match DeviceName $DeviceName" 122 | Break 123 | } 124 | Elseif($ActionDevice.count -eq 1){ 125 | $MDATPDeviceID = $ActionDevice.id 126 | 127 | if ($pscmdlet.ShouldProcess("$DeviceName", "Start Isolation: $IsolationType")){ 128 | Try{ 129 | $UnAppRestrictionInput = @{"Comment" = "$Comment"} | ConvertTo-Json 130 | $UnAppRestrictionUri = "$MachineAPI/$MDATPDeviceID/unrestrictCodeExecution " 131 | $UnAppRestrictionResponse =Invoke-WebRequest -Uri $UnAppRestrictionUri -Headers $Headers -Method Post -Body $UnAppRestrictionInput 132 | If ($UnAppRestrictionResponse.StatusCode -eq 201){ 133 | $ActionID = $UnAppRestrictionResponse.content | ConvertFrom-Json | Select-Object -ExpandProperty id 134 | Write-Verbose "Remove App restriction was successfully initiated for device $DeviceName -ActionID: $ActionID" 135 | $ActionID 136 | } 137 | Else{ 138 | $ActionID = "0000000-0000-0000-0000-000000000000" 139 | Write-Warning "Initiating app restriction for device $DeviceName failed!" 140 | Write-Error "StatusCode: $($UnAppRestrictionResponse.StatusCode)" 141 | $ActionID 142 | } 143 | } 144 | Catch{ 145 | $ex = $_.Exception 146 | $errorResponse = $ex.Response.GetResponseStream() 147 | $reader = New-Object System.IO.StreamReader($errorResponse) 148 | $reader.BaseStream.Position = 0 149 | $reader.DiscardBufferedData() 150 | $responseBody = $reader.ReadToEnd(); 151 | Write-Verbose "Response content:`n$responseBody" 152 | Write-Error "Request to $Uri failed with HTTP Status $($ex.Response.StatusCode) $($ex.Response.StatusDescription)" 153 | $ActionID = "0000000-0000-0000-0000-000000000000" 154 | $ActionID 155 | } 156 | } 157 | } 158 | } 159 | End{ 160 | Write-Verbose "Device: $DeviceName" 161 | Write-Verbose "DeviceID: $MDATPDeviceID" 162 | Write-Verbose "Comment: $Comment" 163 | Write-Verbose "ActionID: $($ActionID)" 164 | Write-Verbose "StatusCode: $($IsolateResponse.statuscode)" 165 | Write-Verbose "StatusDescription: $($IsolateResponse.StatusDescription)" 166 | } 167 | } -------------------------------------------------------------------------------- /src/PSMDATP/Public/Stop-MDATPIsolation.ps1: -------------------------------------------------------------------------------- 1 | function Stop-MDATPIsolation{ 2 | <# 3 | .Synopsis 4 | Stop-MDATPIsolation 5 | 6 | .DESCRIPTION 7 | Stop-MDATPIsolation removes network isolation for the specified device 8 | 9 | .PARAMETER DeviceName 10 | Computername of the device 11 | 12 | .PARAMETER DeviceID 13 | The unique device ID of the device 14 | 15 | .PARAMETER Comment 16 | Comment that is added to the request, if no comment is provided the default commment 'submitted by automation' is used. 17 | 18 | .PARAMETER MTPConfigFile 19 | The MTPConfigFile contains the API connection information, if not specified a default PoshMTPconfig.json is used that must be located in the module folder 20 | 21 | .EXAMPLE 22 | Stop-MDATPIsolation -DeviceName computer02 -Comment "incident1973" 23 | 24 | This command removes network isolation for device computer02 25 | 26 | .NOTES 27 | Version: 1.0 28 | Author: Alex Verboon 29 | Creation Date: 12.04.2020 30 | Purpose/Change: Initial script development 31 | #> 32 | [CmdletBinding(SupportsShouldProcess)] 33 | Param( 34 | # Computername of the MDATP managed device 35 | [Parameter(Mandatory=$true, 36 | ParameterSetName='DeviceName')] 37 | [ValidateNotNullOrEmpty()] 38 | [String]$DeviceName, 39 | 40 | # Unique device id of the MDATP managed device 41 | [Parameter(Mandatory=$true, 42 | ParameterSetName='DeviceID')] 43 | [ValidateNotNullOrEmpty()] 44 | [String]$DeviceID, 45 | 46 | # Comment for the request 47 | [Parameter(Mandatory=$false)] 48 | [String]$Comment, 49 | 50 | # API Configuration file 51 | [Parameter(Mandatory=$false)] 52 | [String]$MTPConfigFile 53 | ) 54 | 55 | Begin{ 56 | # Begin Get API Information 57 | If ($MTPConfigFile){ 58 | $PoshMTPconfigFilePath = $MTPConfigFile 59 | Write-Verbose "MTP ConfigFile parameter: $PoshMTPconfigFilePath" 60 | } 61 | Else{ 62 | # If no configfile is defined we use a defined lcoation .\Config\PoshMTPconfig.json 63 | $ConfigFileDir = [IO.Directory]::GetParent($PSScriptRoot) 64 | $PoshMTPconfigFilePath = "$ConfigFileDir\" + "PoshMTPconfig.json" 65 | Write-Verbose "MTP ConfigFile static: $PoshMTPconfigFilePath" 66 | } 67 | 68 | Write-Verbose "Checking for $PoshMTPconfigFilePath" 69 | If (Test-Path -Path $PoshMTPconfigFilePath -PathType Leaf){ 70 | $ConfigSettings = @(Get-Content -Path "$PoshMTPconfigFilePath" | ConvertFrom-Json) 71 | $OAuthUri = $ConfigSettings.API_MDATP.OAuthUri 72 | $ClientID = $ConfigSettings.API_MDATP.ClientID 73 | $ClientSecret = $ConfigSettings.API_MDATP.ClientSecret 74 | } 75 | Else{ 76 | Write-Error "$PoshMTPconfigFilePath not found" 77 | Break 78 | } 79 | # End Get API Information 80 | 81 | # Connect with MDATP API 82 | [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 83 | $Body = @{ 84 | resource = "https://api.securitycenter.windows.com" 85 | client_id = $ClientID 86 | client_secret = $ClientSecret 87 | grant_type = 'client_credentials' 88 | redirectUri = "https://localhost:8000" 89 | } 90 | $Response = Invoke-RestMethod -Method Post -Uri $OAuthUri -Body $Body 91 | #$Authorization = Invoke-RestMethod -Method Post -Uri $OAuthUri -Body $Body -ContentType "application/x-www-form-urlencoded" -UseBasicParsing 92 | #$access_token = $Authorization.access_token 93 | $headers = @{ 94 | 'Content-Type' = 'application/json' 95 | Accept = 'application/json' 96 | Authorization = "Bearer $($Response.access_token)" 97 | } 98 | } 99 | Process{ 100 | $MDATP_API_URI = "https://api.securitycenter.windows.com/api" 101 | If([string]::IsNullOrEmpty($Comment)){ 102 | $Comment = "submitted by automation" 103 | } 104 | $DeviceName = $DeviceName.ToLower() 105 | 106 | # Get the MDATP devices 107 | $MachineAPI = "$MDATP_API_URI/machines" 108 | $Machines = @(Invoke-RestMethod -Uri "$MachineAPI" -Headers $Headers -Method Get -Verbose -ContentType application/json) 109 | If ($DeviceName){ 110 | $ActionDevice = @($machines.value | Select-Object * | Where-Object {$_.computerDnsName -like "$DeviceName"}) 111 | } 112 | Elseif ($DeviceID){ 113 | $ActionDevice = @($machines.value | Select-Object * | Where-Object {$_.id -like "$DeviceID"}) 114 | } 115 | 116 | If($ActionDevice.count -gt 1){ 117 | Write-Warning "There are multiple device records with this computername, please specify the MDATP device id" 118 | $ActionDevice | Select-Object computerDnsName, id 119 | Break 120 | } 121 | Elseif($ActionDevice.count -eq 0){ 122 | Write-Warning "No device records found that match DeviceName $DeviceName" 123 | Break 124 | } 125 | Elseif($ActionDevice.count -eq 1){ 126 | $MDATPDeviceID = $ActionDevice.id 127 | if ($pscmdlet.ShouldProcess("$DeviceName", "Stop Isolation")){ 128 | Try{ 129 | $UnIsolationInput = @{"Comment" = "$Comment"} | ConvertTo-Json 130 | $UnIsolateUri = "$MachineAPI/$MDATPDeviceID/unisolate " 131 | $UnIsolateResponse =Invoke-WebRequest -Uri $UnIsolateUri -Headers $Headers -Method Post -Body $UnIsolationInput 132 | If ($UnIsolateResponse.StatusCode -eq 201){ 133 | $ActionID = $UnIsolateResponse.content | ConvertFrom-Json | Select-Object -ExpandProperty id 134 | Write-Verbose "Remove isolation was successfully initiated for device $DeviceName -ActionID: $ActionID" 135 | $ActionID 136 | } 137 | Else{ 138 | $ActionID = "0000000-0000-0000-0000-000000000000" 139 | Write-Warning "Removing isolation for device $DeviceName failed!" 140 | Write-Error "StatusCode: $($UnIsolateResponse.StatusCode)" 141 | $ActionID 142 | } 143 | } 144 | Catch{ 145 | $ex = $_.Exception 146 | $errorResponse = $ex.Response.GetResponseStream() 147 | $reader = New-Object System.IO.StreamReader($errorResponse) 148 | $reader.BaseStream.Position = 0 149 | $reader.DiscardBufferedData() 150 | $responseBody = $reader.ReadToEnd(); 151 | Write-Verbose "Response content:`n$responseBody" 152 | Write-Error "Request to $Uri failed with HTTP Status $($ex.Response.StatusCode) $($ex.Response.StatusDescription)" 153 | $ActionID = "0000000-0000-0000-0000-000000000000" 154 | $ActionID 155 | } 156 | } 157 | } 158 | } 159 | End{ 160 | Write-Verbose "Device: $DeviceName" 161 | Write-Verbose "DeviceID: $MDATPDeviceID" 162 | Write-Verbose "Comment: $Comment" 163 | Write-Verbose "ActionID: $($ActionID)" 164 | Write-Verbose "StatusCode: $($UnIsolateResponse.statuscode)" 165 | Write-Verbose "StatusDescription: $($UnIsolateResponse.StatusDescription)" 166 | } 167 | } -------------------------------------------------------------------------------- /src/PSMDATP/TEMPLATE_PoshMTPconfig.json: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/alexverboon/PSMDATP/db3f639d0b7710b63c2ac2951e00d46b30643d80/src/PSMDATP/TEMPLATE_PoshMTPconfig.json -------------------------------------------------------------------------------- /src/PSScriptAnalyzerSettings.psd1: -------------------------------------------------------------------------------- 1 | @{ 2 | #________________________________________ 3 | #IncludeDefaultRules 4 | IncludeDefaultRules = $true 5 | #________________________________________ 6 | #Severity 7 | #Specify Severity when you want to limit generated diagnostic records to a sepecific subset: [ Error | Warning | Information ] 8 | Severity = @('Error', 'Warning') 9 | #________________________________________ 10 | #CustomRulePath 11 | #Specify CustomRulePath when you have a large set of custom rules you'd like to reference 12 | #CustomRulePath = "Module\InjectionHunter\1.0.0\InjectionHunter.psd1" 13 | #________________________________________ 14 | #IncludeRules 15 | #Specify IncludeRules when you only want to run specific subset of rules instead of the default rule set. 16 | #IncludeRules = @('PSShouldProcess', 17 | # 'PSUseApprovedVerbs') 18 | #________________________________________ 19 | #ExcludeRules 20 | #Specify ExcludeRules when you want to exclude a certain rule from the the default set of rules. 21 | ExcludeRules = @( 22 | 'PSUseToExportFieldsInManifest' 23 | ) 24 | # 'PSUseDeclaredVarsMoreThanAssignments' 25 | #________________________________________ 26 | #Rules 27 | #Here you can specify customizations for particular rules. Several examples are included below: 28 | #Rules = @{ 29 | # PSUseCompatibleCmdlets = @{ 30 | # compatibility = @('core-6.1.0-windows', 'desktop-4.0-windows') 31 | # } 32 | # PSUseCompatibleSyntax = @{ 33 | # Enable = $true 34 | # TargetVersions = @( 35 | # '3.0', 36 | # '5.1', 37 | # '6.2' 38 | # ) 39 | # } 40 | # PSUseCompatibleCommands = @{ 41 | # Enable = $true 42 | # TargetProfiles = @( 43 | # 'win-8_x64_10.0.14393.0_6.1.3_x64_4.0.30319.42000_core', # PS 6.1 on WinServer-2019 44 | # 'win-8_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework', # PS 5.1 on WinServer-2019 45 | # 'win-8_x64_6.2.9200.0_3.0_x64_4.0.30319.42000_framework' # PS 3 on WinServer-2012 46 | # ) 47 | # } 48 | # PSUseCompatibleTypes = @{ 49 | # Enable = $true 50 | # TargetProfiles = @( 51 | # 'ubuntu_x64_18.04_6.1.3_x64_4.0.30319.42000_core', 52 | # 'win-48_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework' 53 | # ) 54 | # # You can specify types to not check like this, which will also ignore methods and members on it: 55 | # IgnoreTypes = @( 56 | # 'System.IO.Compression.ZipFile' 57 | # ) 58 | # } 59 | #} 60 | #________________________________________ 61 | } 62 | -------------------------------------------------------------------------------- /src/Tests/Infrastructure/SampleInfraTest.Tests.ps1: -------------------------------------------------------------------------------- 1 | # #------------------------------------------------------------------------- 2 | # Set-Location -Path $PSScriptRoot 3 | # #------------------------------------------------------------------------- 4 | # $ModuleName = 'PSMDATP' 5 | # #------------------------------------------------------------------------- 6 | # #if the module is already in memory, remove it 7 | # Get-Module $ModuleName | Remove-Module -Force 8 | # $PathToManifest = [System.IO.Path]::Combine('..', '..', 'Artifacts', "$ModuleName.psd1") 9 | # #------------------------------------------------------------------------- 10 | # Import-Module $PathToManifest -Force 11 | # #------------------------------------------------------------------------- 12 | # Describe 'Infrastructure Tests' -Tag Infrastructure { 13 | # Context 'First Infra Tests' { 14 | # It 'should pass the first infra test' { 15 | # # test logic 16 | # }#it 17 | # } 18 | # } 19 | -------------------------------------------------------------------------------- /src/Tests/Unit/PSMDATP-Module.Tests.ps1: -------------------------------------------------------------------------------- 1 | #------------------------------------------------------------------------- 2 | Set-Location -Path $PSScriptRoot 3 | #------------------------------------------------------------------------- 4 | $ModuleName = 'PSMDATP' 5 | $PathToManifest = [System.IO.Path]::Combine('..', '..', $ModuleName, "$ModuleName.psd1") 6 | $PathToModule = [System.IO.Path]::Combine('..', '..', $ModuleName, "$ModuleName.psm1") 7 | #------------------------------------------------------------------------- 8 | Describe 'Module Tests' -Tag Unit { 9 | Context "Module Tests" { 10 | It 'Passes Test-ModuleManifest' { 11 | Test-ModuleManifest -Path $PathToManifest | Should Not BeNullOrEmpty 12 | $? | Should Be $true 13 | }#manifestTest 14 | It 'root module PSMDATP.psm1 should exist' { 15 | $PathToModule | Should Exist 16 | $? | Should Be $true 17 | }#psm1Exists 18 | It 'manifest should contain PSMDATP.psm1' { 19 | $PathToManifest | 20 | Should -FileContentMatchExactly "PSMDATP.psm1" 21 | }#validPSM1 22 | }#context_ModuleTests 23 | }#describe_ModuleTests 24 | --------------------------------------------------------------------------------