MDATPQuery.ipynb

Kernel: Python 3

Querying MDATP Data

MSTICpy versions > 0.3.0

Description

This Notebook provides details and examples of how to connect to and query data from the MDATP Advanced Hunting API.

Installation

%pip install --upgrade msticpy

Authentication

Authentication for the MDATP Advanced Hunting API is handled via an Azure AD application. Before you can authenticate you will need to register an application and provide it with the required permissions. MSTICpy supports Application Context authentication to the API. Detailed instructions on registering an application can be found here: https://docs.microsoft.com/windows/security/threat-protection/microsoft-defender-atp/exposed-apis-create-app-webapp

Once created you will require the following details:

• Application (client) ID

• Directory (tenant) ID

• Client secret

These details can be found in the Azure Portal under Azure Active Directory > App Registrations.

Once collected the easiest way to manage these details is via msticpyconfig.yaml - simply add them to the file in the following format:

'''
MDATPApp:
  Args:
    clientId: "{Application (client) ID}"
    clientSecret: "{Client Secret}"
    tenantId: "{Directory (tenant) ID}"
'''

You can then initialize a data provider for MDATP and connect the provider:

from msticpy.data.data_providers import QueryProvider
mdatp_prov = QueryProvider('MDATP')
#app_name is the value of the heading in msticpyconfig.yaml that the app details are stored under.
mdatp_prov.connect(app_name="MDATPApp")

Connected.

{'token_type': 'Bearer',
 'expires_in': '3599',
 'ext_expires_in': '3599',
 'expires_on': '1578009447',
 'not_before': '1578005547',
 'resource': 'https://api.securitycenter.windows.com',
 'access_token': None}

Once connected the MDATP data connector functions in a similar manner to other data connectors. You can list queries:

mdatp_prov.list_queries()

['MDATP.file_path',
 'MDATP.host_alerts',
 'MDATP.host_connections',
 'MDATP.ip_alerts',
 'MDATP.ip_connections',
 'MDATP.list_alerts',
 'MDATP.list_connections',
 'MDATP.list_filehash',
 'MDATP.list_files',
 'MDATP.list_host_processes',
 'MDATP.process_cmd_line',
 'MDATP.process_creations',
 'MDATP.process_paths',
 'MDATP.protocol_connections',
 'MDATP.sha1_alerts',
 'MDATP.url_alerts',
 'MDATP.url_connections',
 'MDATP.user_files',
 'MDATP.user_logons',
 'MDATP.user_network',
 'MDATP.user_processes',
 'MDATPHunting.accessibility_persistence',
 'MDATPHunting.av_sites',
 'MDATPHunting.b64_pe',
 'MDATPHunting.brute_force',
 'MDATPHunting.cve_2018_1000006l',
 'MDATPHunting.cve_2018_1111',
 'MDATPHunting.cve_2018_4878',
 'MDATPHunting.doc_with_link',
 'MDATPHunting.dropbox_link',
 'MDATPHunting.email_link',
 'MDATPHunting.email_smartscreen',
 'MDATPHunting.malware_recycle',
 'MDATPHunting.network_scans',
 'MDATPHunting.powershell_downloads',
 'MDATPHunting.service_account_powershell',
 'MDATPHunting.smartscreen_ignored',
 'MDATPHunting.smb_discovery',
 'MDATPHunting.tor',
 'MDATPHunting.uncommon_powershell',
 'MDATPHunting.user_enumeration']

Get details about avaliable queries:

mdatp_prov.MDATP.list_alerts('?')

Query:  list_connections
Data source:  MDATP
Retrieves list of network connections for a host

Parameters
----------
add_query_items: str (optional)
    Additional query clauses
end: datetime (optional)
    Query end time
start: datetime (optional)
    Query start time
    (default value is: -30)
table: str (optional)
    Table name
    (default value is: NetworkCommunicationEvents  )
Query:
 {table} | where EventTime >= datetime({start}) | where EventTime <= datetime({end}) {add_query_items}

Execute queries with default parameters:

mdatp_prov.MDATP.list_alerts()

Execute queries with custom parameters:

mdatp_prov.MDATP.list_alerts(start="-30", add_query_items="| summarize count() by Severity")

Print a fully constructed query for debug purposes:

mdatp_prov.MDATP.list_alerts("print", start="-30", add_query_items="| summarize count() by Severity")

' AlertEvents | where EventTime >= datetime(2019-12-03T23:24:40.794583Z) | where EventTime <= datetime(2020-01-02T23:24:40.794583Z) | summarize count() by Severity'

Execute a custom query:

query = "AlertEvents | sample 10"
mdatp_prov.exec_query(query)