added samples

Author: nathanfalke

sdk/easm/azure-defender-easm/samples/README.md

@@ -0,0 +1,3 @@
+# Azure EASM samples for Python client
+
+The sample programs here demonstrate some common use case scenarios for the Azure EASM Python SDK Client.

sdk/easm/azure-defender-easm/samples/sample1_managing_discovery_runs.py

@@ -0,0 +1,41 @@
+'''
+This sample demonstrates how to create and manage discovery runs in a workspace using the discovery_groups module of the EasmClient
+'''
+import itertools
+from azure.identity import InteractiveBrowserCredential
+from azure.defender.easm import EasmClient
+
+
+#To create an EasmClient, you need your subscription ID, region, and some sort of credential.
+sub_id = '<your subscription ID here>'
+workspace_name = '<your workspace name here>'
+resource_group = '<your resource group here>'
+region = '<your region here>'
+
+endpoint = f'{region}.easm.defender.microsoft.com'
+
+# For the purposes of this demo, I've chosen the InteractiveBrowserCredential but any credential will work.
+browser_credential = InteractiveBrowserCredential()
+client = EasmClient(endpoint, resource_group, sub_id, workspace_name, browser_credential)
+
+# in order to start discovery runs, we must first create a discovery group, which is a collection of known assets that we can pivot off of. these are created using the `discovery_groups.put` method
+name = '<your discovery group name here>'
+assets = [
+    {'kind': 'domain', 'name': '<a domain you want to run discovery against>'},
+    {'kind': 'host', 'name': '<a host you want to run discovery against>'}
+]
+request = {
+	'description': '<a description for your discovery group>',
+	'seeds': assets
+}
+
+response = client.discovery_groups.put(name, request)
+
+# Discovery groups created through the API's `put` method aren't run automatically, so we need to start the run ourselves.
+client.discovery_groups.run(name)
+
+for group in client.discovery_groups.list():
+    print(group['name'])
+    runs = client.discovery_groups.list_runs(group['name'])
+    for run in itertools.islice(runs, 5):
+        print(f" - started: {run['startedDate']}, finished: {run['completedDate']}, assets found: {run['totalAssetsFoundCount']}")

sdk/easm/azure-defender-easm/samples/sample2_create_disco_group_from_template.py

@@ -0,0 +1,45 @@
+'''
+This sample shows you how to use the discovery_groups module to create discovery groups using templates provided by the discovery_templates module of the EasmClient
+'''
+from azure.identity import InteractiveBrowserCredential
+from azure.defender.easm import EasmClient
+
+
+#To create an EasmClient, you need your subscription ID, region, and some sort of credential.
+sub_id = '<your subscription ID here>'
+workspace_name = '<your workspace name here>'
+resource_group = '<your resource group here>'
+region = '<your region here>'
+
+endpoint = f'{region}.easm.defender.microsoft.com'
+
+# For the purposes of this demo, I've chosen the InteractiveBrowserCredential but any credential will work.
+browser_credential = InteractiveBrowserCredential()
+client = EasmClient(endpoint, resource_group, sub_id, workspace_name, browser_credential)
+
+# The discovery_templates.list method can be used to find a discovery template using a filter.
+# The endpoint will return templates based on a partial match on the name field.
+partial_name = 'taco'
+templates = client.discovery_templates.list(filter=partial_name)
+
+for template in templates:
+    print(f'{template["id"]}: {template["displayName"]}')
+
+# To get more detail about a disco template, we can use the discovery_templates.get method.
+# From here, we can see the names and seeds which would be used in a discovery run.
+template_id = '<your chosen template id>'
+template = client.discovery_templates.get(template_id)
+
+for name in template['names']:
+    print(name)
+
+for seed in template['seeds']:
+    print(f'{seed["kind"]}, {seed["name"]}')
+
+#The discovery template can be used to create a discovery group with using a DiscoGroupRequest and the EasmClient's discovery_groups.put method. Don't forget to run your new disco group with discovery_groups.run
+group_name = '<your group name here>'
+
+request = {'templateId': template_id}
+response = client.discovery_groups.put(group_name, body=request)
+
+client.discovery_groups.run(group_name)

sdk/easm/azure-defender-easm/samples/sample3_use_saved_filters.py

@@ -0,0 +1,50 @@
+'''
+Saved Filters are used to store a query within EASM, these saved queries can be used to synchronize exact queries across multiple scripts, or to ensure a team is looking at the same assets
+In this example, we'll go over how a saved filter could be used to synchronize the a query across multiple scripts
+'''
+from azure.identity import InteractiveBrowserCredential
+from azure.defender.easm import EasmClient
+
+sub_id = '<your subscription ID here>'
+workspace_name = '<your workspace name here>'
+resource_group = '<your resource group here>'
+region = '<your region here>'
+
+endpoint = f'{region}.easm.defender.microsoft.com'
+
+browser_credential = InteractiveBrowserCredential()
+client = EasmClient(endpoint, resource_group, sub_id, workspace_name, browser_credential)
+
+# To create a Saved Filter, we need to send a filter, name, and description to the `saved_filters.put` endpoint
+saved_filter_name = '<your saved filter name here>'
+request = {
+	'filter': 'IP Address = 151.101.192.67',
+	'description': 'Monitored Addresses',
+}
+client.saved_filters.put(saved_filter_name, body=request)
+
+# The saved filter can now be used in scripts to monitor the assets
+# First, retrieve the saved filter by name, then use it in an asset list or update call
+
+# A sample asset list call that could be used to monitor the assets:
+def monitor(asset):
+	pass #your monitor logic here
+
+monitor_filter = client.saved_filters.get(saved_filter_name)['filter']
+
+for asset in client.assets.list(filter=monitor_filter):
+	monitor(asset)
+
+# A sample asset update call, which could be used to update the monitored assets:
+monitor_filter = client.saved_filters.get(saved_filter_name)['filter']
+
+body = {
+	#your asset update request body here
+}
+
+client.assets.update(body, filter=asset_filter)
+
+# Should your needs change, the filter can be updated with no need to update the scripts it's used in
+# Simply submit a new `saved_filters.put` request to replace the old description and filter with a new set
+request = {'filter': 'IP Address = 0.0.0.0', 'description': 'Monitored Addresses'}
+client.saved_filters.put(saved_filter_name, body=request)

sdk/easm/azure-defender-easm/samples/sample4_managing_external_ids.py

@@ -0,0 +1,62 @@
+'''
+External IDs can be a useful method of keeping track of assets in multiple systems, but it can be time consuming to manually tag each asset. In this example, we'll take a look at how you can, with a map of name/kind/external id, tag each asset in your inventory with an external id automatically using the SDK
+'''
+from azure.identity import InteractiveBrowserCredential
+from azure.defender.easm import EasmClient
+
+#To create an EasmClient, you need your subscription ID, region, and some sort of credential.
+sub_id = '<your subscription ID here>'
+workspace_name = '<your workspace name here>'
+resource_group = '<your resource group here>'
+region = '<your region here>'
+
+endpoint = f'{region}.easm.defender.microsoft.com'
+
+# For the purposes of this demo, I've chosen the InteractiveBrowserCredential but any credential will work.
+browser_credential = InteractiveBrowserCredential()
+client = EasmClient(endpoint, resource_group, sub_id, workspace_name, browser_credential)
+
+# Assets in EASM can be uniquely distinguished by `name` and `kind`, so we can create a simple dictionary containing `name`, `kind`, and `external_id`. In a more realistic case, this could be generated using an export from the external system we're using for tagging, but for our purposes, we can manually write it out
+external_id_mapping = [
+    {
+        'name': 'example.com',
+        'kind': 'host',
+        'external_id': 'EXT040'
+    },
+    {
+        'name': 'example.com',
+        'kind': 'domain',
+        'external_id': 'EXT041'
+    },
+    {
+        'name': '93.184.216.34',
+        'kind': 'ipAddress',
+        'external_id': 'EXT042'
+    },
+    {
+        'name': 'example.org',
+        'kind': 'host',
+        'external_id': 'EXT050'
+    },
+]
+# Using the `assets` client, we can update each asset and append the tracking id of the update to our update ID list, so that we can keep track of the progress on each update later
+update_ids = []
+
+for asset in external_id_mapping:
+    update_request = {'external_id': asset['external_id']}
+    asset_filter = f"kind = {asset['kind']} AND name = {asset['name']}"
+    update = client.assets.update(body=update_request, filter=asset_filter)
+    update_ids.append(update['id'])
+
+# Using the `tasks` client, we can view the progress of each update using the `get` method
+for update_id in update_ids:
+    update = client.tasks.get(update_id)
+    print(f'{update["id"]}: {update["state"]}')
+
+# The updates can be viewed using the `assets.list` method by creating a filter that matches on each external id using an `in` query
+ids = ', '.join([f'"{asset["external_id"]}"' for asset in external_id_mapping])
+asset_filter = f'External ID in ({ids})'
+
+for asset in client.assets.list(filter=asset_filter):
+    print(f'{asset["externalId"]}, {asset["name"]}')
+