Skip to content

MSDefenderEndpoints#

README

Cortex responder for Microsoft Defender for Endpoints (formerly know as Microsoft ATP)#

With this responder you can#

  • Isolate machine
  • Unisolate machine
  • Restrict App Execution on a machine
  • Remove app restriction on a machine
  • Run full antivirus scan
  • Run an automated scan
  • Push IoC to Microsoft defender
  • Alert
  • BlockAndAlert
  • (future: Collect investigation package)

NOTE: Microsft API for finding machines via IP-addresses is little bit limited "Find Machines seen with the requested internal IP in the time range of 15 minutes prior and after a given timestamp.", because of this "hostname" is preferable observable type"

Responder needs one of the following licenses:

  • Windows 10 Enterprise E5
  • Microsoft 365 E5 (M365 E5) which includes Windows 10 Enterprise E5
  • Microsoft 365 E5 Security
In general, you’ll need to take the following steps to use the responder#
  • Create an Azure AD application
  • Grant permissions to App
Steps#

With your Global administrator credentials, login to the Azure portal.
* Azure Active Directory > App registrations > New registration.

In the registration form:

  • Name - Name your application.
  • Supported account type – leave the default setting.
  • Redirect Uri – leave empty.
API permission#

On your new application page, click API Permissions > Add permission > APIs my organization uses > type WindowsDefenderATP and click on WindowsDefenderATP Choose Application permissions, select Alert.Read.All AND TI.ReadWrite.All AND Machine.ReadAll AND Machine.Isolate AND Machine.Scan AND Machine.RestrictExecution > Click on Add permissions.

After clicking the Add Permissions button, on the next screen we need to grant consent for the permission to take effect. Press the "Grant admin consent for {your tenant name}" button.

To get client credentials:

  • In your application page, Click Certificate & Secrets
  • Specify a key description and set an expiration for 1 year.
  • Click Add and the application key will appear.

IMPORTANT: Copy and store this key in a safe place. Treat it like a password.

Detailed permissions:#

Permissions

How to create Azure App (link to MS blog)

MSDefender-PushIOC-Alert#

Author: Keijo Korte, Louis-Maximilien Dupouy
License: AGPL-V3
Version: 2.0
Supported data types:
- thehive:case_artifact
Registration required: True
Subscription required: True
Free subscription: False
Third party service: https://securitycenter.windows.com

Description#

Push IOC to Defender client. Alert mode

Configuration#

tenantId Azure tenant ID
Default value if not configured abcdef12-ab12-abc12-ab12-abcdef123456
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
appId Azure app ID
Default value if not configured abcdef12-ab12-abc12-ab12-abcdef123456
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
appSecret Azure app secret
Default value if not configured ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890=
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
resourceAppIdUri Security Center URI, usually doens't need to change
Default value if not configured https://api.securitycenter.windows.com
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
oAuthUri Azure oAuth2 authentication endpoint
Default value if not configured https://login.microsoftonline.com
Type of the configuration item string
The configuration item can contain multiple values False
Is required True

MSDefender-UnRestrictAppExecution#

Author: Keijo Korte, Louis-Maximilien Dupouy
License: AGPL-V3
Version: 1.0
Supported data types:
- thehive:case_artifact
Registration required: True
Subscription required: True
Free subscription: False
Third party service: https://securitycenter.windows.com

Description#

Enable execution of any application on the device

Configuration#

tenantId Azure tenant ID
Default value if not configured abcdef12-ab12-abc12-ab12-abcdef123456
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
appId Azure app ID
Default value if not configured abcdef12-ab12-abc12-ab12-abcdef123456
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
appSecret Azure app secret
Default value if not configured ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890=
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
resourceAppIdUri Security Center URI, usually doens't need to change
Default value if not configured https://api.securitycenter.windows.com
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
oAuthUri Azure oAuth2 authentication endpoint
Default value if not configured https://login.microsoftonline.com
Type of the configuration item string
The configuration item can contain multiple values False
Is required True

MSDefender-AutoInvestigation#

Author: Keijo Korte, Louis-Maximilien Dupouy
License: AGPL-V3
Version: 1.0
Supported data types:
- thehive:case_artifact
Registration required: True
Subscription required: True
Free subscription: False
Third party service: https://securitycenter.windows.com

Description#

Start an automated investigation on a device

Configuration#

tenantId Azure tenant ID
Default value if not configured abcdef12-ab12-abc12-ab12-abcdef123456
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
appId Azure app ID
Default value if not configured abcdef12-ab12-abc12-ab12-abcdef123456
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
appSecret Azure app secret
Default value if not configured ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890=
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
resourceAppIdUri Security Center URI, usually doens't need to change
Default value if not configured https://api.securitycenter.windows.com
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
oAuthUri Azure oAuth2 authentication endpoint
Default value if not configured https://login.microsoftonline.com
Type of the configuration item string
The configuration item can contain multiple values False
Is required True

MSDefender-UnisolateMachine#

Author: Keijo Korte
License: AGPL-V3
Version: 1.0
Supported data types:
- thehive:case_artifact
Registration required: True
Subscription required: True
Free subscription: False
Third party service: https://securitycenter.windows.com

Description#

Unisolate machine with Microsoft Defender for Endpoints

Configuration#

tenantId Azure tenant ID
Default value if not configured abcdef12-ab12-abc12-ab12-abcdef123456
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
appId Azure app ID
Default value if not configured abcdef12-ab12-abc12-ab12-abcdef123456
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
appSecret Azure app secret
Default value if not configured ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890=
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
resourceAppIdUri Security Center URI, usually doens't need to change
Default value if not configured https://api.securitycenter.windows.com
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
oAuthUri Azure oAuth2 authentication endpoint
Default value if not configured https://login.microsoftonline.com
Type of the configuration item string
The configuration item can contain multiple values False
Is required True

MSDefender-FullVirusscan#

Author: Keijo Korte
License: AGPL-V3
Version: 1.0
Supported data types:
- thehive:case_artifact
Registration required: True
Subscription required: True
Free subscription: False
Third party service: https://securitycenter.windows.com

Description#

Run full virus scan to machine with Microsoft Defender for Endpoints

Configuration#

tenantId Azure tenant ID
Default value if not configured abcdef12-ab12-abc12-ab12-abcdef123456
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
appId Azure app ID
Default value if not configured abcdef12-ab12-abc12-ab12-abcdef123456
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
appSecret Azure app secret
Default value if not configured ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890=
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
resourceAppIdUri Security Center URI, usually doens't need to change
Default value if not configured https://api.securitycenter.windows.com
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
oAuthUri Azure oAuth2 authentication endpoint
Default value if not configured https://login.microsoftonline.com
Type of the configuration item string
The configuration item can contain multiple values False
Is required True

MSDefender-IsolateMachine#

Author: Keijo Korte
License: AGPL-V3
Version: 1.0
Supported data types:
- thehive:case_artifact
Registration required: True
Subscription required: True
Free subscription: False
Third party service: https://securitycenter.windows.com

Description#

Isolate machine with Microsoft Defender for Endpoints

Configuration#

tenantId Azure tenant ID
Default value if not configured abcdef12-ab12-abc12-ab12-abcdef123456
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
appId Azure app ID
Default value if not configured abcdef12-ab12-abc12-ab12-abcdef123456
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
appSecret Azure app secret
Default value if not configured ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890=
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
resourceAppIdUri Security Center URI, usually doens't need to change
Default value if not configured https://api.securitycenter.windows.com
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
oAuthUri Azure oAuth2 authentication endpoint
Default value if not configured https://login.microsoftonline.com
Type of the configuration item string
The configuration item can contain multiple values False
Is required True

MSDefender-PushIOC-Block#

Author: Keijo Korte, Louis-Maximilien Dupouy
License: AGPL-V3
Version: 2.0
Supported data types:
- thehive:case_artifact
Registration required: True
Subscription required: True
Free subscription: False
Third party service: https://securitycenter.windows.com

Description#

Push IOC to Defender client. Blocking mode

Configuration#

tenantId Azure tenant ID
Default value if not configured abcdef12-ab12-abc12-ab12-abcdef123456
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
appId Azure app ID
Default value if not configured abcdef12-ab12-abc12-ab12-abcdef123456
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
appSecret Azure app secret
Default value if not configured ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890=
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
resourceAppIdUri Security Center URI, usually doens't need to change
Default value if not configured https://api.securitycenter.windows.com
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
oAuthUri Azure oAuth2 authentication endpoint
Default value if not configured https://login.microsoftonline.com
Type of the configuration item string
The configuration item can contain multiple values False
Is required True

MSDefender-RestrictAppExecution#

Author: Keijo Korte, Louis-Maximilien Dupouy
License: AGPL-V3
Version: 1.0
Supported data types:
- thehive:case_artifact
Registration required: True
Subscription required: True
Free subscription: False
Third party service: https://securitycenter.windows.com

Description#

Restrict execution of all applications on the device except a predefined set

Configuration#

tenantId Azure tenant ID
Default value if not configured abcdef12-ab12-abc12-ab12-abcdef123456
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
appId Azure app ID
Default value if not configured abcdef12-ab12-abc12-ab12-abcdef123456
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
appSecret Azure app secret
Default value if not configured ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890=
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
resourceAppIdUri Security Center URI, usually doens't need to change
Default value if not configured https://api.securitycenter.windows.com
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
oAuthUri Azure oAuth2 authentication endpoint
Default value if not configured https://login.microsoftonline.com
Type of the configuration item string
The configuration item can contain multiple values False
Is required True